MongoDB

Cómo usar MongoDB en una aplicación Laravel. Cubrimos la instalación del driver, la configuración, los modelos Eloquent, el query builder y el uso como driver de caché y de colas.

​

Introducción

MongoDB es una de las bases de datos NoSQL orientadas a documentos más populares. Destaca por su alto rendimiento de escritura (ideal para analítica e IoT), alta disponibilidad (failover automático con réplicas), escalado horizontal (sharding) y un potente lenguaje de consulta (agregaciones, búsqueda de texto completo y consultas geoespaciales).

A diferencia del formato filas/columnas de una base de datos SQL, cada registro en MongoDB es un documento en formato BSON (JSON binario). La aplicación puede recuperar estos datos en formato JSON.

Para usar MongoDB con Laravel, se recomienda el paquete mongodb/laravel-mongodb, mantenido oficialmente por MongoDB. Ofrece una integración muy completa con Eloquent y con las distintas funcionalidades de Laravel.

​

Instalación

​

Driver PHP de MongoDB

Para conectarte a MongoDB necesitas la extensión de PHP mongodb. Con Laravel Herd o php.new ya viene instalada. Si la instalas manualmente, usa PECL.

pecl install mongodb

Consulta la guía de instalación de la extensión PHP MongoDB para más detalles.

Comprueba que la extensión PHP mongodb esté activa tanto en CLI como en el servidor web. Las configuraciones pueden diferir.

​

Arrancar el servidor MongoDB

Puedes usar MongoDB Community Server para desarrollo local. Consulta la guía de instalación oficial para Windows, macOS, Linux y Docker.

Con Docker:

# docker-compose.yml
services:
  mongodb:
    image: mongo:8
    ports:
      - "27017:27017"
    environment:
      MONGO_INITDB_ROOT_USERNAME: root
      MONGO_INITDB_ROOT_PASSWORD: password
      MONGO_INITDB_DATABASE: laravel_app
    volumes:
      - mongodb_data:/data/db

volumes:
  mongodb_data:

docker compose up -d

Para hosting en la nube puedes usar MongoDB Atlas. Para acceder a un cluster de Atlas desde local necesitas añadir tu IP a la lista de acceso del proyecto.

​

Instalación del paquete laravel-mongodb

Instala el paquete mongodb/laravel-mongodb con Composer.

composer require mongodb/laravel-mongodb

​

Configuración

​

Variables de entorno

Añade la información de conexión a MongoDB en .env.

MONGODB_URI="mongodb://localhost:27017"
MONGODB_DATABASE="laravel_app"

Si utilizas MongoDB Atlas, cambia la cadena de conexión a la de Atlas.

MONGODB_URI="mongodb+srv://<username>:<password>@<cluster>.mongodb.net/<dbname>?retryWrites=true&w=majority"
MONGODB_DATABASE="laravel_app"

​

config/database.php

Añade la conexión mongodb al array connections en config/database.php.

'connections' => [

    // ... conexiones existentes ...

    'mongodb' => [
        'driver' => 'mongodb',
        'dsn' => env('MONGODB_URI', 'mongodb://localhost:27017'),
        'database' => env('MONGODB_DATABASE', 'laravel_app'),
    ],

],

Si combinas una base de datos relacional como MySQL con MongoDB, deja default como está y añade simplemente la conexión mongodb. Podrás cambiar de conexión por modelo.

​

Funcionalidades principales

​

Modelos Eloquent

Extendiendo MongoDB\Laravel\Eloquent\Model puedes trabajar con MongoDB de forma casi idéntica a un modelo Eloquent normal.

<?php

namespace App\Models;

use MongoDB\Laravel\Eloquent\Model;

class Article extends Model
{
    protected $connection = 'mongodb';
    protected $collection = 'articles'; // Nombre de la colección (se deduce del nombre de clase si se omite)

    protected $fillable = [
        'title',
        'body',
        'tags',
        'published_at',
    ];
}

MongoDB no tiene esquema fijo, por lo que no hacen falta migraciones. Al guardar un documento se crea automáticamente la colección.

​

Operaciones CRUD básicas

Se opera con la misma API que Eloquent normal.

use App\Models\Article;

// Crear
$article = Article::create([
    'title' => 'Introducción a MongoDB',
    'body' => 'MongoDB es una base de datos orientada a documentos.',
    'tags' => ['nosql', 'mongodb', 'laravel'],
    'published_at' => now(),
]);

// Obtener
$article = Article::find('64f1a2b3c4d5e6f7a8b9c0d1');
$articles = Article::where('tags', 'nosql')->get();

// Actualizar
$article->update(['title' => 'Introducción a MongoDB (revisada)']);

// Eliminar
$article->delete();

​

Arrays y documentos embebidos

Puedes trabajar directamente con arrays y documentos embebidos, uno de los puntos fuertes de MongoDB.

// Push a un campo array
$article->push('tags', 'database');

// Pull desde un campo array
$article->pull('tags', 'nosql');

// Consulta sobre documentos embebidos
$articles = Article::where('meta.author', 'Taylor')->get();

​

Query Builder

Con el query builder de MongoDB puedes escribir consultas complejas. Consulta la documentación del query builder de laravel-mongodb para más detalles.

use Illuminate\Support\Facades\DB;

// Consulta básica
$articles = DB::connection('mongodb')
    ->collection('articles')
    ->where('tags', 'laravel')
    ->orderBy('published_at', 'desc')
    ->limit(10)
    ->get();

// Pipeline de agregación
$stats = DB::connection('mongodb')
    ->collection('orders')
    ->raw(function ($collection) {
        return $collection->aggregate([
            ['$group' => ['_id' => '$status', 'total' => ['$sum' => '$amount']]],
            ['$sort' => ['total' => -1]],
        ]);
    });

​

Driver de caché

El driver de caché de MongoDB elimina automáticamente las entradas caducadas usando índices TTL. Consulta la documentación del driver de caché.

Añade el store en config/cache.php.

'stores' => [

    'mongodb' => [
        'driver' => 'mongodb',
        'connection' => 'mongodb',
        'collection' => 'cache',
    ],

],

Cambia el driver de caché a MongoDB en .env.

CACHE_STORE=mongodb

​

Driver de colas

MongoDB puede usarse como driver de colas. Consulta la documentación del driver de colas.

Añade la conexión en config/queue.php.

'connections' => [

    'mongodb' => [
        'driver' => 'mongodb',
        'connection' => 'mongodb',
        'collection' => 'jobs',
        'queue' => env('MONGODB_QUEUE', 'default'),
        'retry_after' => (int) env('MONGODB_QUEUE_RETRY_AFTER', 90),
        'after_commit' => false,
    ],

],

Cambia la conexión de colas a MongoDB en .env.

QUEUE_CONNECTION=mongodb

​

Almacenamiento de archivos con GridFS

Con GridFS de MongoDB puedes almacenar archivos usando el adaptador GridFS para Flysystem. Consulta la documentación de GridFS.

composer require league/flysystem-gridfs

Añade el disco en config/filesystems.php.

'disks' => [

    'gridfs' => [
        'driver' => 'gridfs',
        'connection' => 'mongodb',
        'database' => env('MONGODB_DATABASE', 'laravel_app'),
    ],

],

use Illuminate\Support\Facades\Storage;

// Subir archivo
Storage::disk('gridfs')->put('file.pdf', $contents);

// Recuperar archivo
$contents = Storage::disk('gridfs')->get('file.pdf');

​

Búsqueda vectorial (Vector Search)

Con MongoDB Atlas Vector Search puedes hacer búsquedas por similitud mediante embeddings vectoriales. Se vectorizan datos (texto, imagen, audio…) y se guardan; luego se recuperan los documentos más cercanos al vector de consulta. Es una función pensada para IA / machine learning.

La búsqueda vectorial solo está disponible en MongoDB Atlas. No funciona con MongoDB Community Server local ni con entornos auto-hospedados. Debes crear previamente un índice de Vector Search en la consola de Atlas.

El método vectorSearch está disponible en el query builder.

use App\Models\Article;

// Genera el embedding desde una cadena de consulta (por ejemplo, con la API de OpenAI)
$queryVector = getEmbedding('¿Qué es MongoDB?'); // array float[]

$results = Article::query()->vectorSearch(
    index: 'vector_index',   // Nombre del índice Vector Search de Atlas
    path: 'embedding',       // Nombre del campo que contiene el vector
    queryVector: $queryVector,
    limit: 10,               // Número de documentos a devolver
    numCandidates: 100,      // Número de candidatos (para búsqueda ANN)
);

// Cada documento incluye vectorSearchScore
foreach ($results as $result) {
    echo $result->title . ': ' . $result->vectorSearchScore;
}

​

Búsqueda de texto completo (motor Scout)

Puedes usar el motor Scout mongodb para aprovechar la búsqueda de texto completo de Laravel Scout con MongoDB. Internamente usa MongoDB Atlas Search y admite búsquedas difusas y con comodines. Consulta la documentación del motor Scout.

El motor Scout de MongoDB también requiere MongoDB Atlas. La colección del índice de Scout debe ser distinta de la del modelo. Se aplica automáticamente el prefix de config/scout.php (por defecto, el nombre de la aplicación).

Configura el driver de Scout como mongodb en .env.

SCOUT_DRIVER=mongodb

Añade el trait Searchable al modelo.

use Laravel\Scout\Searchable;
use MongoDB\Laravel\Eloquent\Model;

class Article extends Model
{
    use Searchable;

    // Indica qué campos se incluyen en el índice
    public function toSearchableArray(): array
    {
        return [
            'title' => $this->title,
            'body'  => $this->body,
            'tags'  => $this->tags,
        ];
    }
}

Crea el índice de Scout e importa los datos existentes.

php artisan scout:index articles
php artisan scout:import "App\Models\Article"

Realiza búsquedas con la API estándar de Scout.

// Búsqueda de texto completo
$results = Article::search('MongoDB Laravel')->get();

// Búsqueda con filtros
$results = Article::search('query builder')
    ->where('status', 'published')
    ->paginate(15);

​

Uso combinado con MySQL

En Laravel puedes usar MySQL y MongoDB a la vez. Indica la conexión con la propiedad $connection en cada modelo.

// Modelo Eloquent normal que usa MySQL
class User extends \Illuminate\Database\Eloquent\Model
{
    protected $connection = 'mysql';
}

// Modelo que usa MongoDB
class Article extends \MongoDB\Laravel\Eloquent\Model
{
    protected $connection = 'mongodb';
}

Si quieres definir relaciones entre modelos de MySQL y de MongoDB, consulta las relaciones híbridas.

​

Resumen

Lista de comprobación de instalación

1. Instala la extensión de PHP con pecl install mongodb
2. Arranca el servidor MongoDB (local, Docker o Atlas)
3. Instala el paquete con composer require mongodb/laravel-mongodb
4. Configura MONGODB_URI y MONGODB_DATABASE en .env
5. Añade la conexión mongodb en config/database.php

Cuándo usar MongoDB o MySQL

Característica	MongoDB	MySQL
Modelo de datos	Documento (JSON/BSON)	Tabla (filas y columnas)
Esquema	Sin esquema (flexible)	Esquema fijo
Escalado	Fácil escalado horizontal	Predominantemente vertical
Transacciones	Multi-documento (v4+)	ACID completo
Casos ideales	Logs, analítica, IoT, datos de estructura flexible	Datos estructurados, relaciones complejas

Uso por funcionalidad

Funcionalidad	Configuración
Modelo Eloquent	Extender MongoDB\Laravel\Eloquent\Model
Query builder	DB::connection('mongodb')->collection(...)
Caché	config/cache.php + CACHE_STORE=mongodb
Colas	config/queue.php + QUEUE_CONNECTION=mongodb
Almacenamiento de archivos	config/filesystems.php + adaptador GridFS
Búsqueda vectorial	Model::query()->vectorSearch(...) (Atlas obligatorio)
Búsqueda de texto	SCOUT_DRIVER=mongodb + trait Searchable (Atlas obligatorio)

​

Próximos pasos

Documentación oficial de laravel-mongodb

Referencia detallada de todas las funciones: Eloquent, query builder, relaciones, etc.

Guía rápida

Aprende rápidamente el uso básico de MongoDB con Laravel

Configuración de base de datos

Bases de la configuración de conexiones a base de datos en Laravel

Introducción a Eloquent

Uso básico del ORM Eloquent