Skip to main content

​
Overview

Prisma Engines uses a modular connector architecture to support multiple database systems. Connectors abstract database-specific operations for both query execution and schema management.

​
Core Architecture

​
Query Engine Connectors

Query engine connectors implement the data access layer for executing CRUD operations, aggregations, and transactions.

​
Main Traits

Connector Trait (query-engine/connectors/query-connector/src/interface.rs) 
pub trait Connector {
    async fn get_connection(&self) -> Result<Box<dyn Connection + Send + Sync>>;
    fn name(&self) -> &'static str;
    fn should_retry_on_transient_error(&self) -> bool;
}
The Connector trait provides:
  • Connection pooling and management
  • Database system identification for telemetry (OTEL spec compliant)
  • Transient error retry logic (MongoDB-specific)
Connection Trait 
pub trait Connection: ConnectionLike {
    async fn start_transaction(
        &mut self,
        isolation_level: Option<String>,
    ) -> Result<Box<dyn Transaction>>;
    async fn version(&self) -> Option<String>;
    fn as_connection_like(&mut self) -> &mut dyn ConnectionLike;
}
Transaction Trait 
pub trait Transaction: ConnectionLike {
    async fn commit(&mut self) -> Result<()>;
    async fn rollback(&mut self) -> Result<()>;
    async fn version(&self) -> Option<String>;
    fn as_connection_like(&mut self) -> &mut dyn ConnectionLike;
}
ConnectionLike Marker 
pub trait ConnectionLike: ReadOperations + WriteOperations + Send + Sync {}

​
Schema Engine Connectors

Schema engine connectors handle migrations, introspection, and schema validation.

​
SchemaConnector Trait

Location: schema-engine/connectors/schema-connector/src/schema_connector.rs Key responsibilities:
  • Migration management: Create, apply, and validate migrations
  • Introspection: Generate Prisma schema from existing databases
  • Schema operations: Create/drop databases, reset schemas
  • Version compatibility: Check database version support
pub trait SchemaConnector: Send + Sync + 'static {
    fn schema_dialect(&self) -> Box<dyn SchemaDialect>;
    fn acquire_lock(&mut self) -> BoxFuture<'_, ConnectorResult<()>>;
    fn apply_migration(&mut self, migration: &Migration) -> BoxFuture<'_, ConnectorResult<u32>>;
    fn connector_type(&self) -> &'static str;
    fn introspect(&mut self, ctx: &IntrospectionContext) -> BoxFuture<'_, ConnectorResult<IntrospectionResult>>;
    // ... additional methods
}

​
SchemaDialect Trait

Abstracts database-specific migration rendering and schema diffing: 
pub trait SchemaDialect: Send + Sync + 'static {
    fn diff(&self, from: DatabaseSchema, to: DatabaseSchema, filter: &SchemaFilter) -> Migration;
    fn render_script(&self, migration: &Migration, diagnostics: &DestructiveChangeDiagnostics) -> ConnectorResult<String>;
    fn migration_file_extension(&self) -> &'static str;
    fn migration_len(&self, migration: &Migration) -> usize;
    fn schema_from_datamodel(&self, sources: Vec<(String, SourceFile)>) -> ConnectorResult<DatabaseSchema>;
}

​
Operations

​
Read Operations

All connectors implement the ReadOperations trait:
  • get_single_record: Fetch one record by filter
  • get_many_records: Fetch multiple records with query arguments
  • get_related_m2m_record_ids: Fetch IDs from join tables for M2M relations
  • aggregate_records: Execute aggregation queries (count, sum, avg, min, max)

​
Write Operations

  • create_record: Insert single record
  • create_records: Bulk insert (with skip duplicates support)
  • create_records_returning: Bulk insert with returned data
  • update_records: Update multiple records
  • update_record: Update single record
  • native_upsert_record: Database-native upsert
  • delete_records: Delete multiple records
  • delete_record: Delete single record with returned data
  • m2m_connect / m2m_disconnect: Manage M2M join tables
  • execute_raw / query_raw: Raw SQL/query execution

​
Schema Operations

  • Migration: Create migrations by diffing schemas, render to SQL/scripts, apply to database
  • Introspection: Scan database structure, generate Prisma schema
  • Validation: Check migration compatibility, validate connection
  • Database lifecycle: Create, drop, reset databases

​
Connector Capabilities

Connectors expose capabilities through ConnectorCapabilities bitflags:
  • CreateMany: Bulk insert support
  • CreateSkipDuplicates: Skip duplicate rows on insert
  • InsertReturning / UpdateReturning / DeleteReturning: Return affected rows
  • NativeUpsert: Database-native upsert
  • JsonFiltering: JSON field filtering
  • FullTextSearch: Native full-text search

​
Supported Databases

Prisma Engines currently supports:
DatabaseProviderSchema ConnectorQuery Connector
PostgreSQLpostgresql✅ SqlSchemaConnectorVia Query Compiler
MySQLmysql✅ SqlSchemaConnectorVia Query Compiler
SQLitesqlite✅ SqlSchemaConnectorVia Query Compiler
SQL Serversqlserver✅ SqlSchemaConnectorVia Query Compiler
CockroachDBcockroachdb✅ SqlSchemaConnectorVia Query Compiler
MongoDBmongodb✅ MongoDbSchemaConnectorLegacy (QC planned)
Query Compiler Architecture: Prisma 7+ uses the Query Compiler (QC) architecture where query planning happens in Rust and execution runs in TypeScript using driver adapters. The native Rust query engine has been removed.

​
Migration Table

SQL connectors store migration history in the _prisma_migrations table:
  • id: Migration UUID
  • checksum: Migration content hash
  • finished_at: Completion timestamp
  • migration_name: Migration directory name
  • logs: Execution logs
  • rolled_back_at: Rollback timestamp
  • started_at: Start timestamp
  • applied_steps_count: Number of migration steps

​
Error Handling

Connectors translate database errors to user-facing errors:
  • SQL: Quaint errors mapped to ConnectorError with user-facing messages
  • MongoDB: MongoDB errors converted via mongo_error_to_connector_error
  • Version incompatibility: DatabaseVersionIncompatibility errors

​
Next Steps

SQL Connectors

Learn about SQL connector implementation

MongoDB Connector

Explore MongoDB connector specifics

Build docs developers (and LLMs) love

Get started for freeTalk to us