MongoDB

Wie Sie MongoDB in einer Laravel-Anwendung einsetzen. Von der Treiber-Installation über die Konfiguration bis zu Eloquent-Modellen, dem Query Builder sowie der Nutzung als Cache- und Queue-Treiber.

​

Einführung

MongoDB ist eine der beliebtesten NoSQL-Dokumentendatenbanken. Sie zeichnet sich durch hohe Schreibleistung (ideal für Analytics und IoT), hohe Verfügbarkeit (automatisches Failover per Replica Set), horizontale Skalierung (Sharding) und eine leistungsstarke Query-Sprache (Aggregation, Volltextsuche, Geo-Abfragen) aus.

Anders als das Zeilen-/Spalten-Modell in SQL-Datenbanken ist jeder Datensatz in MongoDB ein Dokument im BSON-Format (binäres JSON). Die Anwendung kann diese Daten im JSON-Format lesen.

Für den Einsatz von MongoDB mit Laravel empfehlen wir das offizielle, von MongoDB gepflegte Paket mongodb/laravel-mongodb. Es bietet eine umfassende Integration mit Eloquent und weiteren Laravel-Funktionen.

​

Installation

​

MongoDB PHP-Treiber

Um sich mit MongoDB zu verbinden, benötigen Sie die PHP-Erweiterung mongodb. Bei Nutzung von Laravel Herd oder php.new ist sie bereits installiert. Für die manuelle Installation verwenden Sie PECL.

pecl install mongodb

Details zur Installation finden Sie im Installations-Leitfaden der MongoDB-PHP-Erweiterung.

Stellen Sie sicher, dass die PHP-Erweiterung mongodb sowohl für die CLI als auch für den Webserver aktiviert ist. Die Konfigurationen können sich unterscheiden.

​

MongoDB-Server starten

Für die lokale Entwicklung eignet sich der MongoDB Community Server. Installationshinweise für Windows, macOS, Linux und Docker finden Sie im offiziellen Installationshandbuch.

Mit 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

Für Cloud-Hosting steht MongoDB Atlas zur Verfügung. Um von lokal auf einen Atlas-Cluster zuzugreifen, müssen Sie Ihre IP-Adresse in die IP-Zugriffsliste des Projekts aufnehmen.

​

Das Paket laravel-mongodb installieren

Installieren Sie das Paket mongodb/laravel-mongodb mit Composer.

composer require mongodb/laravel-mongodb

​

Konfiguration

​

Umgebungsvariablen

Ergänzen Sie in der .env-Datei die Verbindungsdaten für MongoDB.

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

Wenn Sie MongoDB Atlas verwenden, ersetzen Sie den Connection-String durch den von Atlas.

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

​

config/database.php

Fügen Sie im Array connections in config/database.php eine mongodb-Verbindung hinzu.

'connections' => [

    // ... bestehende Verbindungen ...

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

],

Wenn Sie MySQL o. Ä. gemeinsam mit MongoDB einsetzen, lassen Sie default unverändert und fügen einfach die mongodb-Verbindung hinzu. Sie können die Verbindung je Modell wechseln.

​

Kernfunktionen

​

Eloquent-Modelle

Indem Sie von MongoDB\Laravel\Eloquent\Model erben, können Sie MongoDB nahezu genauso bedienen wie normale Eloquent-Modelle.

<?php

namespace App\Models;

use MongoDB\Laravel\Eloquent\Model;

class Article extends Model
{
    protected $connection = 'mongodb';
    protected $collection = 'articles'; // Collection-Name (wenn weggelassen, aus dem Klassennamen abgeleitet)

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

Da MongoDB schemalos ist, sind keine Migrationen nötig. Beim Speichern eines Dokuments wird die Collection automatisch angelegt.

​

Grundlegende CRUD-Operationen

Sie verwenden dieselbe API wie beim normalen Eloquent.

use App\Models\Article;

// Anlegen
$article = Article::create([
    'title' => 'Einführung in MongoDB',
    'body' => 'MongoDB ist eine dokumentenorientierte Datenbank.',
    'tags' => ['nosql', 'mongodb', 'laravel'],
    'published_at' => now(),
]);

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

// Aktualisieren
$article->update(['title' => 'Einführung in MongoDB (überarbeitet)']);

// Löschen
$article->delete();

​

Arrays und eingebettete Dokumente

Sie können Arrays und eingebettete Dokumente – eine Stärke von MongoDB – direkt verwenden.

// Wert an ein Array-Feld anhängen
$article->push('tags', 'database');

// Wert aus einem Array-Feld entfernen
$article->pull('tags', 'nosql');

// Abfrage auf einem eingebetteten Dokument
$articles = Article::where('meta.author', 'Taylor')->get();

​

Query Builder

Mit dem Query Builder von MongoDB lassen sich komplexe Abfragen formulieren. Details finden Sie in der Query-Builder-Dokumentation von laravel-mongodb.

use Illuminate\Support\Facades\DB;

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

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

​

Cache-Treiber

Der MongoDB-Cache-Treiber nutzt TTL-Indizes und entfernt abgelaufene Einträge automatisch. Siehe die Cache-Treiber-Dokumentation für Details.

Fügen Sie in config/cache.php einen Store hinzu.

'stores' => [

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

],

Stellen Sie in der .env den Cache-Treiber auf MongoDB.

CACHE_STORE=mongodb

​

Queue-Treiber

Sie können MongoDB als Queue-Treiber verwenden. Details finden Sie in der Queue-Treiber-Dokumentation.

Fügen Sie in config/queue.php die Verbindung hinzu.

'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,
    ],

],

Setzen Sie die Queue-Verbindung in der .env auf MongoDB.

QUEUE_CONNECTION=mongodb

​

Dateispeicherung mit GridFS

Mit GridFS von MongoDB können Sie Dateien speichern. Verwendet wird der GridFS-Adapter für Flysystem. Details siehe GridFS-Dokumentation.

composer require league/flysystem-gridfs

Fügen Sie in config/filesystems.php einen Disk hinzu.

'disks' => [

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

],

use Illuminate\Support\Facades\Storage;

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

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

​

Vektorsuche (Vector Search)

Mit MongoDB Atlas Vector Search können Sie Ähnlichkeitssuchen über Vektor-Embeddings durchführen. Sie speichern zum Beispiel Text-, Bild- oder Audio-Daten als Vektoren und finden die dem Query-Vektor am nächsten liegenden Dokumente – ein Suchfeature für KI und Machine Learning.

Die Vektorsuche ist ausschließlich auf MongoDB Atlas verfügbar. In einem lokalen MongoDB Community Server oder in selbst gehosteten Umgebungen lässt sie sich nicht verwenden. Sie müssen vorab in der Atlas-Konsole einen Vector-Search-Index anlegen.

Die Methode vectorSearch steht am Query Builder zur Verfügung.

use App\Models\Article;

// Embedding aus einem Query-String erzeugen (z. B. per OpenAI API)
$queryVector = getEmbedding('Was ist MongoDB'); // float[]-Array

$results = Article::query()->vectorSearch(
    index: 'vector_index',   // Name des Atlas-Vector-Search-Index
    path: 'embedding',       // Feld, in dem der Vektor gespeichert ist
    queryVector: $queryVector,
    limit: 10,               // Anzahl zurückgegebener Dokumente
    numCandidates: 100,      // Anzahl der Kandidaten (für ANN-Suche)
);

// Jedes Dokument erhält einen vectorSearchScore
foreach ($results as $result) {
    echo $result->title . ': ' . $result->vectorSearchScore;
}

​

Volltextsuche (Scout-Engine)

Mit der Scout-Engine mongodb können Sie die Volltextsuche von Laravel Scout mit MongoDB nutzen. Intern wird MongoDB Atlas Search verwendet – inklusive Unterstützung für Fuzzy- und Wildcard-Suche. Details finden Sie in der Scout-Engine-Dokumentation.

Auch die MongoDB-Scout-Engine ist nur auf MongoDB Atlas verfügbar. Die Scout-Index-Collection muss eine andere Collection sein als die des Modells. Die Einstellung prefix in config/scout.php (standardmäßig der App-Name) wird automatisch angewendet.

Stellen Sie den Scout-Treiber in der .env auf mongodb.

SCOUT_DRIVER=mongodb

Fügen Sie dem Modell das Trait Searchable hinzu.

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

class Article extends Model
{
    use Searchable;

    // Legt die Felder fest, die in den Suchindex aufgenommen werden
    public function toSearchableArray(): array
    {
        return [
            'title' => $this->title,
            'body'  => $this->body,
            'tags'  => $this->tags,
        ];
    }
}

Legen Sie den Scout-Index an und importieren Sie die vorhandenen Daten.

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

Suchen können Sie mit der Standard-API von Scout.

// Volltextsuche
$results = Article::search('MongoDB Laravel')->get();

// Suche mit Filter
$results = Article::search('Query Builder')
    ->where('status', 'published')
    ->paginate(15);

​

Zusammen mit MySQL nutzen

In Laravel können MySQL und MongoDB parallel verwendet werden. Pro Modell geben Sie die Verbindung über die Eigenschaft $connection an.

// Reguläres Eloquent-Modell mit MySQL
class User extends \Illuminate\Database\Eloquent\Model
{
    protected $connection = 'mysql';
}

// Modell mit MongoDB
class Article extends \MongoDB\Laravel\Eloquent\Model
{
    protected $connection = 'mongodb';
}

Wenn Sie Beziehungen zwischen MySQL- und MongoDB-Modellen abbilden möchten, siehe Hybride Beziehungen.

​

Zusammenfassung

Installations-Checkliste

1. PHP-Erweiterung mit pecl install mongodb installieren
2. MongoDB-Server starten (lokal, per Docker oder Atlas)
3. Paket mit composer require mongodb/laravel-mongodb installieren
4. MONGODB_URI und MONGODB_DATABASE in der .env setzen
5. mongodb-Verbindung in config/database.php hinzufügen

MongoDB vs. MySQL

Merkmal	MongoDB	MySQL
Datenmodell	Dokumente (JSON/BSON)	Tabellen (Zeilen/Spalten)
Schema	Schemalos (flexibel)	Festes Schema
Skalierung	Horizontale Skalierung einfach	Meist vertikale Skalierung
Transaktionen	Multi-Document (ab v4)	Vollständig ACID
Typische Anwendung	Logs, Analytics, IoT, flexible Datenstrukturen	Strukturierte Daten, komplexe Beziehungen

Funktionsübersicht

Funktion	Konfigurationsort
Eloquent-Modelle	MongoDB\Laravel\Eloquent\Model erweitern
Query Builder	DB::connection('mongodb')->collection(...)
Cache	config/cache.php + CACHE_STORE=mongodb
Queue	config/queue.php + QUEUE_CONNECTION=mongodb
Dateispeicher	config/filesystems.php + GridFS-Adapter
Vektorsuche	Model::query()->vectorSearch(...) (Atlas erforderlich)
Volltextsuche	SCOUT_DRIVER=mongodb + Searchable-Trait (Atlas erforderlich)

​

Nächste Schritte

Offizielle Dokumentation von laravel-mongodb

Vollständige Referenz zu Eloquent, Query Builder, Beziehungen und mehr

Schnellstart

Die Grundlagen von MongoDB mit Laravel schnell lernen

Datenbank-Konfiguration

Grundlagen zur Konfiguration von Datenbankverbindungen in Laravel

Einführung in Eloquent

Grundlegende Nutzung des Eloquent ORM