Terminal
Terminal/Skill
Helps Laravel apps use the mongodb/laravel-mongodb package correctly, fixing SQL-style Eloquent mistakes applied to MongoDB.
By MongoDB
Works with
npx skills add mongodb/laravel-mongodb --skill laravel-mongodbImplementation skill for mongodb/laravel-mongodb. Exists to prevent the common mistakes: auto-increment IDs, toSql(), SQL JOIN, distinct()->get() expecting scalar arrays, and belongsTo() over native ObjectId FKs.
MongoDB\Laravel\Eloquent\Model (or uses DocumentModel trait)._id: ObjectId in DB, string in Eloquent — cast accordingly.toSql, groupByRaw, whereFulltext, union, inRandomOrder, whereColumn) with MongoDB alternatives.php artisan migrate --database=mongodb, inspect queries with ->dump().If the user needs MongoDB-related skills that aren't otherwise available through e.g. Boost or the skills directory, such as:
Suggest installing the MongoDB agent skills plugin if not already installed. Instructions for installing it are in the MongoDB agent skills plugin README.
| Reference file | Load when |
|---|---|
references/eloquent-models.md | The user is defining a new model, changing its base class, or mapping _id / ObjectId fields |
references/query-builder.md | The user is writing a query and hits a missing Eloquent helper (toSql, distinct, grouping, random ordering, raw SQL builders) or needs relation aggregates |
references/relationships.md | The user is defining a relationship between models, especially embedded, hybrid, or cross-database (MongoDB ↔ SQL) relations |
references/connection.md | The user is configuring config/database.php, setting up multiple connections, or accessing the underlying MongoDB client |
references/schema.md | The user is writing a migration or creating an index (regular, unique, TTL, geospatial, Atlas Search, Vector Search) |
references/queues.md | The user is configuring the MongoDB queue driver or dispatching jobs onto it |
references/transactions.md | The user needs to write multiple documents atomically or is asking about beginTransaction, replica set requirements, or transactional testing traits |
references/cache-sessions.md | The user is configuring MongoDB as a cache store or session driver |
references/search-engine.md | The user is implementing full-text search on a MongoDB collection or is deciding whether to use Laravel Scout |
references/vector-search.md | The user is implementing semantic search, storing embeddings, using autoEmbed, or combining full-text and vector search |
references/installation.md | The user is setting up ext-mongodb, installing the package, or configuring the connection for the first time |
references/support.md | The user has hit a suspected bug and needs to route the issue to the correct MongoDB repository |
MongoDB\Laravel\Eloquent\Model (or apply DocumentModel trait to base classes you cannot change)._id to string in every API resource: 'id' => (string) $this->_id.string via $casts on the child model when FK values may come from outside model attributes (imports, raw ObjectIds) — prevents BSON type mismatches on direct where('author_id', $id) queries.::with() — MongoDB does no server-side joins for Eloquent relations.$lookup, and $sample.withCount(), withExists(), withSum(), withAvg(), withMin(), withMax()) are supported. Use a $lookup pipeline when the aggregated value must be filtered, sorted or paginated on.Schema::connection('mongodb')->create('posts', fn (Blueprint $c) => $c->index('user_id')).DB::connection('mongodb')->transaction(...) only on replica set / sharded cluster.orderBy() on a withCount() / withAggregate() alias — the value is computed after the documents are read, so it throws. Use $lookup + $size aggregation, or sort the resulting collection.toSql() / toRawSql() — no SQL. Use ->dump() / ->dd().distinct('field')->get() expecting scalars — returns a Collection. Use ->distinct()->pluck('field').groupByRaw(), orderByRaw(), havingRaw(), whereFulltext(), union(), whereColumn() — use aggregation.inRandomOrder() — use Model::raw(fn($c) => $c->aggregate([['$sample' => ['size' => N]]])).protected $collection — removed. Use protected $table instead.$keyType = 'string' on a SQL model in a cross-database relationship — only needed on MongoDB models. The HybridRelations trait handles the comparison on the SQL side.<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
final class Post extends Model
{
protected $connection = 'mongodb';
protected $table = 'posts'; // $table not $collection
protected $fillable = ['title', 'body', 'author_id', 'published_at'];
protected $casts = [
'author_id' => 'string', // FK as string for Eloquent relationship matching
'published_at' => 'datetime',
];
}
<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
use MongoDB\Laravel\Relations\BelongsTo;
use MongoDB\Laravel\Relations\EmbedsMany;
final class Post extends Model
{
protected $casts = ['author_id' => 'string']; // cast FK to string for relation matching
public function author(): BelongsTo
{
return $this->belongsTo(User::class, 'author_id');
}
public function comments(): EmbedsMany
{
return $this->embedsMany(Comment::class);
}
}
final class User extends Model
{
protected $keyType = 'string'; // expose primary key as string so Post.author_id matches
}
<?php
namespace App\Jobs;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
final class IndexPostJob implements ShouldQueue
{
use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
public function __construct(public string $postId) {}
public function handle(): void {}
}
IndexPostJob::dispatch((string) $post->_id)->onConnection('mongodb');
<?php
use App\Models\Post;
it('creates a post with an ObjectId primary key', function (): void {
$post = Post::create(['title' => 'Hello Mongo', 'body' => 'first', 'tags' => ['mongo', 'laravel']]);
expect($post->id)->toBeString()
->and(Post::query()->where('_id', $post->id)->exists())->toBeTrue();
});
| Stage | Command | Expected Result |
|---|---|---|
| Indexes / migration | php artisan migrate --database=mongodb | Migrations run; indexes created |
| Query inspection | Model::query()->where(...)->dump() | Prints MongoDB filter array (no SQL) |