MongoDB Connector

Overview

The MongoDB schema connector provides migration and introspection support for MongoDB databases. It follows the same SchemaConnector abstraction as SQL connectors but with MongoDB-specific implementation details. Location: schema-engine/connectors/mongodb-schema-connector/

Query Compiler Status: MongoDB support in the Query Compiler (QC) is not yet implemented. Prisma 7 ships without MongoDB support initially; it will be added once a driver adapter implementation is available.

Architecture

MongoDbSchemaConnector

pub struct MongoDbSchemaConnector {
    connection_string: String,
    client: OnceCell<Client>,
    preview_features: BitFlags<PreviewFeature>,
    host: Arc<dyn ConnectorHost>,
}

Key characteristics:

Lazy connection initialization via OnceCell
No connection pooling (MongoDB driver handles internally)
Supports preview features for experimental functionality

MongoDbSchemaDialect

pub struct MongoDbSchemaDialect;

impl SchemaDialect for MongoDbSchemaDialect {
    fn diff(&self, from: DatabaseSchema, to: DatabaseSchema) -> Migration;
    fn migration_len(&self, migration: &Migration) -> usize;
    fn migration_summary(&self, migration: &Migration) -> String;
    // ...
}

Supported MongoDB Versions

Provider: mongodb Supported Versions: MongoDB 4.0+, MongoDB 5.0+, MongoDB 6.0+ Deployment Types:

Standalone servers
Replica sets (recommended for transactions)
Sharded clusters
MongoDB Atlas

Connection String Format

MongoDB uses the standard MongoDB connection URI:

mongodb://[username:password@]host1[:port1][,...hostN[:portN]][/[database][?options]]
mongodb+srv://[username:password@]host[/[database][?options]]

Examples

Standard
MongoDB Atlas
With Options

mongodb://localhost:27017/myapp
mongodb://user:password@localhost:27017/myapp
mongodb://localhost:27017,localhost:27018/myapp?replicaSet=rs0

mongodb+srv://username:[email protected]/myapp
mongodb+srv://username:[email protected]/myapp?retryWrites=true&w=majority

mongodb://localhost:27017/myapp?authSource=admin
mongodb://localhost:27017/myapp?maxPoolSize=50&w=majority
mongodb://localhost:27017/myapp?readPreference=secondary

Connection Parameters

authSource: Authentication database (default: database in URI)
replicaSet: Replica set name
ssl / tls: Enable TLS/SSL
retryWrites: Enable retryable writes
w: Write concern (e.g., majority)
maxPoolSize: Maximum connection pool size
minPoolSize: Minimum connection pool size
maxIdleTimeMS: Max time connections can remain idle
serverSelectionTimeoutMS: Server selection timeout
readPreference: Read preference (primary, secondary, etc.)

Capabilities

MongoDB connector capabilities:

Document model: Store data as BSON documents
Embedded documents: Nested composite types
Arrays: Native array support for all types
Transactions: Multi-document ACID transactions (replica sets/sharded clusters)
Flexible schema: Schema validation at application level
Indexes: Single field, compound, multikey, text, geospatial

Limitations:

No native enums (stored as strings)
No JOIN operations (handled via application-level aggregation)
No foreign key constraints (referential integrity at application level)
No migration scripts (schema is application-defined)

MongoDB-Specific Features

Composite Types

MongoDB excels at embedded documents:

type Address {
  street String
  city   String
  zip    String
}

model User {
  id      String  @id @default(auto()) @map("_id") @db.ObjectId
  name    String
  address Address
}

Stored as:

{
  "_id": ObjectId("..."),
  "name": "John Doe",
  "address": {
    "street": "123 Main St",
    "city": "Springfield",
    "zip": "12345"
  }
}

Arrays

Native array support for primitives and composite types:

model Post {
  id      String   @id @default(auto()) @map("_id") @db.ObjectId
  title   String
  tags    String[]
  authors User[]
}

ObjectId

MongoDB’s native identifier type:

model User {
  id String @id @default(auto()) @map("_id") @db.ObjectId
}

The @db.ObjectId attribute maps to MongoDB’s 12-byte BSON ObjectId.

Schema Operations

Database Lifecycle

Create Database:

connector.create_database().await?;

MongoDB creates databases lazily on first write:

tracing::warn!("MongoDB database will be created on first use.");

Drop Database:

connector.drop_database().await?;

Drops the entire database and all collections. Reset:

connector.reset(soft, namespaces, filter).await?;

For MongoDB, reset always drops the database (soft reset not supported).

Migration

MongoDB migrations differ from SQL:

connector.apply_migration(&migration).await?;

Migration Steps:

CreateCollection: Create new collection
DropCollection: Drop collection
CreateIndex: Create index on collection
DropIndex: Drop index
UpdateValidator: Update schema validation rules

No SQL Scripts:

fn render_script(&self, _migration: &Migration) -> ConnectorResult<String> {
    Err(ConnectorError::from_msg(
        "Rendering to a script is not supported on MongoDB."
    ))
}

MongoDB migrations are applied directly via the driver; there’s no SQL-like script format.

Introspection

MongoDB introspection uses sampling to infer schema:

let result = connector.introspect(&ctx, extension_types).await?;

Sampling Process:

Describe collections: List all collections in database
Sample documents: Read sample documents from each collection
Infer schema: Analyze document structure to determine field types
Detect composite types: Identify embedded documents
Find indexes: Read index definitions
Generate model: Create Prisma schema from inferred structure

Implementation:

let schema = client.describe().await?;
sampler::sample(client.database(), schema, ctx).await

Challenges:

Schema inference: MongoDB is schemaless; inference based on samples may not capture all variations
Type ambiguity: BSON type mapping to Prisma types requires heuristics
Optional fields: Determining which fields are optional requires statistical analysis

Migration Persistence

MongoDB stores migration records in a collection (equivalent to SQL _prisma_migrations table):

impl MigrationPersistence for MongoDbSchemaConnector {
    // Migration tracking implementation
}

The collection stores:

Migration ID
Migration name
Checksum
Applied timestamp
Status

Transient Errors

MongoDB has specific retry logic for transient errors:

fn should_retry_on_transient_error(&self) -> bool {
    true
}

Transient errors occur due to:

Replica set elections
Network hiccups
Lock contention

Prisma automatically retries transactions when these occur.

Destructive Change Checking

MongoDB destructive change checker warns about:

impl DestructiveChangeChecker for MongoDbSchemaConnector {
    // Check for destructive changes
}

Warnings:

Dropping collections (data loss)
Dropping indexes (performance impact)
Changing field types (potential data loss)
Adding required fields to existing documents

Limitations

Unsupported Commands

Some schema engine commands are not supported:

fn apply_script(&mut self, _migration_name: &str, _script: &str) -> BoxFuture<'_, ConnectorResult<()>> {
    Box::pin(future::ready(Err(unsupported_command_error())))
}

fn db_execute(&mut self, _script: String) -> BoxFuture<'_, ConnectorResult<()>> {
    Box::pin(future::ready(Err(ConnectorError::from_msg(
        "dbExecute is not supported on MongoDB"
    ))))
}

These return:

The "mongodb" provider is not supported with this command.
For more info see https://www.prisma.io/docs/concepts/database-connectors/mongodb

Schema Validation

MongoDB supports JSON schema validation at the database level:

db.createCollection("users", {
  validator: {
    $jsonSchema: {
      bsonType: "object",
      required: ["name", "email"],
      properties: {
        name: { bsonType: "string" },
        email: { bsonType: "string" }
      }
    }
  }
})

Prisma can update validators during migrations but does not generate them from schema by default.

Relations in MongoDB

MongoDB handles relations differently than SQL:

Embedded Relations

One-to-many via embedded arrays:

model User {
  id    String @id @default(auto()) @map("_id") @db.ObjectId
  posts Post[]
}

type Post {
  title String
  body  String
}

Referenced Relations

One-to-many via references:

model User {
  id    String @id @default(auto()) @map("_id") @db.ObjectId
  posts Post[]
}

model Post {
  id       String @id @default(auto()) @map("_id") @db.ObjectId
  userId   String @db.ObjectId
  user     User   @relation(fields: [userId], references: [id])
}

Many-to-Many

Stored as arrays of IDs:

model Post {
  id         String   @id @default(auto()) @map("_id") @db.ObjectId
  categoryIds String[] @db.ObjectId
  categories Category[] @relation(fields: [categoryIds], references: [id])
}

model Category {
  id    String @id @default(auto()) @map("_id") @db.ObjectId
  posts Post[]
}

Native Types

MongoDB BSON types mapped in Prisma:

Prisma Type	MongoDB Type	Annotation
String	String	`@db.String`
Int	Int32	`@db.Int`
BigInt	Int64	`@db.Long`
Float	Double	`@db.Double`
Decimal	Decimal128	`@db.Decimal`
Boolean	Bool	`@db.Bool`
DateTime	Date	`@db.Date` / `@db.Timestamp`
Bytes	BinData	`@db.BinData`
Json	Object/Array	`@db.Object` / `@db.Array`
String (ID)	ObjectId	`@db.ObjectId`

Client Wrapper

The MongoDB connector uses a client wrapper (client_wrapper.rs):

pub struct Client {
    client: mongodb::Client,
    database_name: String,
    preview_features: BitFlags<PreviewFeature>,
}

impl Client {
    pub async fn connect(connection_string: &str, preview_features: BitFlags<PreviewFeature>) -> ConnectorResult<Self>;
    pub async fn describe(&self) -> ConnectorResult<MongoSchema>;
    pub fn database(&self) -> mongodb::Database;
    pub fn db_name(&self) -> &str;
    pub async fn drop_database(&self) -> ConnectorResult<()>;
}

Error conversion:

pub fn mongo_error_to_connector_error(error: mongodb::error::Error) -> ConnectorError {
    ConnectorError::from_msg(error.to_string())
}

Future: Query Compiler Support

Planned MongoDB Query Compiler implementation will require:

Driver adapter: JavaScript/TypeScript adapter for MongoDB Node.js driver
Query translation: Prisma query AST to MongoDB aggregation pipeline
Type mapping: Prisma types to BSON types
Relation resolution: Application-level joins via aggregation $lookup
Transaction support: Multi-document transactions on replica sets

Until then, MongoDB uses the legacy connector architecture.

Next Steps

Connector Overview

Return to connector architecture overview

SQL Connectors

Explore SQL connector implementation

Libraries

Binaries

Connectors

Overview

Architecture

MongoDbSchemaConnector

MongoDbSchemaDialect

Supported MongoDB Versions

Connection String Format

Examples

Connection Parameters

Capabilities

MongoDB-Specific Features

Composite Types

Arrays

ObjectId

Schema Operations

Database Lifecycle

Migration

Introspection

Migration Persistence

Transient Errors

Destructive Change Checking

Limitations

Unsupported Commands

Schema Validation

Relations in MongoDB

Embedded Relations

Referenced Relations

Many-to-Many

Native Types

Client Wrapper

Future: Query Compiler Support

Next Steps

Connector Overview

SQL Connectors

Build docs developers (and LLMs) love

Libraries

Binaries

Connectors

​Overview

​Architecture

​MongoDbSchemaConnector

​MongoDbSchemaDialect

​Supported MongoDB Versions

​Connection String Format

​Examples

​Connection Parameters

​Capabilities

​MongoDB-Specific Features

​Composite Types

​Arrays

​ObjectId

​Schema Operations

​Database Lifecycle

​Migration

​Introspection

​Migration Persistence

​Transient Errors

​Destructive Change Checking

​Limitations

​Unsupported Commands

​Schema Validation

​Relations in MongoDB

​Embedded Relations

​Referenced Relations

​Many-to-Many

​Native Types

​Client Wrapper

​Future: Query Compiler Support

​Next Steps

Connector Overview

SQL Connectors

Build docs developers (and LLMs) love

Overview

Architecture

MongoDbSchemaConnector

MongoDbSchemaDialect

Supported MongoDB Versions

Connection String Format

Examples

Connection Parameters

Capabilities

MongoDB-Specific Features

Composite Types

Arrays

ObjectId

Schema Operations

Database Lifecycle

Migration

Introspection

Migration Persistence

Transient Errors

Destructive Change Checking

Limitations

Unsupported Commands

Schema Validation

Relations in MongoDB

Embedded Relations

Referenced Relations

Many-to-Many

Native Types

Client Wrapper

Future: Query Compiler Support

Next Steps