# blade47/drizzle-orm Wiki ## Technical docs: Overview URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/getting-started/overview
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-kit/src/api.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/api.ts) - [drizzle-orm/package.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/package.json) - [drizzle-kit/src/serializer/studio.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/studio.ts) - [drizzle-kit/src/cli/connections.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/connections.ts) - [drizzle-orm/src/libsql/http/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/http/index.ts) - [drizzle-orm/src/gel/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel/driver.ts) - [drizzle-orm/src/pglite/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pglite/driver.ts) - [drizzle-orm/src/libsql/node/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/node/index.ts) - [drizzle-orm/src/durable-sqlite/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/durable-sqlite/driver.ts) - [drizzle-orm/src/libsql/sqlite3/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/sqlite3/index.ts) - [drizzle-kit/src/cli/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/index.ts) - [drizzle-orm/src/libsql/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/driver.ts) - [drizzle-orm/src/libsql/web/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/web/index.ts) - [drizzle-orm/src/libsql/wasm/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/wasm/index.ts) - [drizzle-orm/src/libsql/ws/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/ws/index.ts) - [drizzle-orm/src/netlify-db/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/driver.ts) - [pnpm-workspace.yaml](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/pnpm-workspace.yaml) - [drizzle-orm/src/neon-serverless/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-serverless/driver.ts) - [drizzle-orm/src/bun-sqlite/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/bun-sqlite/driver.ts) - [drizzle-kit/src/cli/schema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/schema.ts) - [drizzle-orm/src/bun-sql/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/bun-sql/driver.ts) - [drizzle-orm/type-tests/sqlite/db.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/sqlite/db.ts) - [drizzle-orm/src/neon-http/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-http/driver.ts) - [drizzle-orm/src/mysql2/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql2/driver.ts) - [drizzle-orm/src/postgres-js/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/postgres-js/driver.ts) - [drizzle-orm/src/vercel-postgres/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/vercel-postgres/driver.ts) - [drizzle-orm/src/singlestore/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore/driver.ts) - [drizzle-orm/type-tests/geldb/db.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/db.ts) - [turbo.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/turbo.json) - [drizzle-orm/src/d1/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/d1/index.ts)
## Overview Drizzle ORM is a lightweight, high-performance, TypeScript-first database toolkit engineered with a headless architecture that decouples declarative schema definitions and query building logic from underlying database driver implementations. Operating across a diverse ecosystem of relational database engines including PostgreSQL, MySQL, SQLite, and Gel, the toolkit targets modern serverless, edge, and containerized runtime environments without imposing heavy runtime abstractions or native dependency bloat. Sources: [drizzle-orm/package.json:4-41](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/package.json#L4-L41), [drizzle-orm/src/singlestore/driver.ts:1-184](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore/driver.ts#L1-L184) The architecture supports varied execution targets spanning standard Node.js database pools, HTTP and WebSocket-based serverless protocols, and specialized embedded environments such as Cloudflare D1 workers, Durable Objects storage, and native SQLite bindings. Through tight integration with [CLI Command Architecture](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/cli-command-architecture) and validation utilities, Drizzle coordinates schema management, migration diffing, and type-safe query compilation across a unified monorepo workspace structure. Sources: [drizzle-kit/src/cli/index.ts:1-46](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/index.ts#L1-L46), [pnpm-workspace.yaml:1-10](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/pnpm-workspace.yaml#L1-L10) ## Headless Design and Monorepo Philosophy ### Workspace Structure and Package Boundaries The project organizes its codebase within a multi-package pnpm workspace coordinated by `pnpm-workspace.yaml`. The workspace decouples core ORM functionality, migration tooling, seed services, and schema validation wrappers into dedicated packages. Sources: [pnpm-workspace.yaml:1-10](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/pnpm-workspace.yaml#L1-L10) | Workspace Package | Directory | Role and Responsibility | | :--- | :--- | :--- | | `drizzle-orm` | `drizzle-orm` | Core query builder, table/column models, dialects, and session abstractions | | `drizzle-kit` | `drizzle-kit` | CLI command architecture, [database introspection](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/database-introspection), migrations, and [Studio Server Bridge](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/studio-server-bridge) | | `drizzle-zod` | `drizzle-zod` | Automatic generation of Zod validation schemas from table definitions | | `drizzle-typebox` | `drizzle-typebox` | JSON Schema generation via Sinclair's TypeBox library | | `drizzle-valibot` | `drizzle-valibot` | Lightweight Valibot validation schema generator | | `drizzle-arktype` | `drizzle-arktype` | Runtime validation definitions inferred via ArkType | | `drizzle-seed` | `drizzle-seed` | Mock data generation and foreign key topological insertion ordering | | `integration-tests` | `integration-tests` | Cross-dialect test suite executed against containerized database fixtures | | `eslint-plugin-drizzle` | `eslint-plugin-drizzle` | AST lint rules enforcing safe delete and update query constraints | Sources: [pnpm-workspace.yaml:1-10](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/pnpm-workspace.yaml#L1-L10) > [!NOTE] > Workspace packages maintain strict separation of concerns, allowing runtime validation libraries (`drizzle-zod`, `drizzle-typebox`, `drizzle-valibot`, `drizzle-arktype`) to operate independently as optional peer or downstream dependencies atop the core `drizzle-orm` engine. ### Driver Decoupling and Peer Dependencies The core `drizzle-orm` package enforces a headless design by isolating native database client runtimes into optional peer dependencies. Rather than bundling heavy native binaries or tight vendor connections directly into the bundle, `drizzle-orm` declares drivers via `peerDependencies` combined with `peerDependenciesMeta` set to optional. Sources: [drizzle-orm/package.json:47-169](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/package.json#L47-L169) ```json "peerDependenciesMeta": { "mysql2": { "optional": true }, "@vercel/postgres": { "optional": true }, "@xata.io/client": { "optional": true }, "better-sqlite3": { "optional": true }, "@types/better-sqlite3": { "optional": true }, "sqlite3": { "optional": true }, "sql.js": { "optional": true }, "@types/sql.js": { "optional": true }, "@cloudflare/workers-types": { "optional": true }, "pg": { "optional": true }, "@types/pg": { "optional": true }, "postgres": { "optional": true }, "@neondatabase/serverless": { "optional": true }, "@netlify/db": { "optional": true }, "bun-types": { "optional": true }, "@aws-sdk/client-rds-data": { "optional": true }, "@planetscale/database": { "optional": true }, "knex": { "optional": true }, "kysely": { "optional": true }, "@libsql/client": { "optional": true }, "@libsql/client-wasm": { "optional": true }, "@opentelemetry/api": { "optional": true }, "expo-sqlite": { "optional": true }, "gel": { "optional": true }, "@op-engineering/op-sqlite": { "optional": true }, "@electric-sql/pglite": { "optional": true }, "@tidbcloud/serverless": { ``` Sources: [drizzle-orm/package.json:78-169](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/package.json#L78-L169) > [!IMPORTANT] > Because drivers such as `pg`, `mysql2`, `better-sqlite3`, and `@neondatabase/serverless` are marked as optional peer dependencies, consumers load only the specific client required by their target runtime, keeping bundle footprints minimal across serverless and edge deployments. ## Database Engine and Dialect Support ### PostgreSQL, PGlite, and Postgres-js Drivers Drizzle ORM provides first-class support for PostgreSQL through specialized dialect compilation in `PgDialect` and dedicated session handlers. The `postgres-js` driver connects via the `postgres` package, configuring transparent parsers for PostgreSQL data types (such as OIDs `1184`, `1082`, `1083`, `1114`, `1182`, `1185`, `1115`, `1231`, `114`, and `3802`) to bypass unexpected transformations on dates and JSON fields. Sources: [drizzle-orm/src/postgres-js/driver.ts:1-38](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/postgres-js/driver.ts#L1-L38) ```typescript const transparentParser = (val: any) => val; // Override postgres.js default date parsers: https://github.com/porsager/postgres/discussions/761 for (const type of ['1184', '1082', '1083', '1114', '1182', '1185', '1115', '1231']) { client.options.parsers[type as any] = transparentParser; client.options.serializers[type as any] = transparentParser; } client.options.serializers['114'] = transparentParser; client.options.serializers['3802'] = transparentParser; ``` Sources: [drizzle-orm/src/postgres-js/driver.ts:28-36](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/postgres-js/driver.ts#L28-L36) Additionally, embedded PostgreSQL is supported via PGlite through `@electric-sql/pglite`, handling local data directories and client instances within `PgliteDriver` and `PgliteDatabase`. Sources: [drizzle-orm/src/pglite/driver.ts:1-47](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pglite/driver.ts#L1-L47) > [!NOTE] > The `postgres-js` driver explicitly overrides default date and json parsers by assigning a transparent identity parser (`val => val`) to ensure raw wire formats pass directly into Drizzle's type casting layer without premature serialization. ### MySQL2 and SQLite Engine Adaptations For MySQL environments, the `mysql2` driver abstracts connection pools and individual client connections using `MySql2Driver` and `MySql2Database`. It inspects client instances to verify whether they provide a callback or promise interface, automatically invoking `.promise()` on callback-based clients to normalize asynchronous execution. Sources: [drizzle-orm/src/mysql2/driver.ts:1-120](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql2/driver.ts#L1-L120) ```typescript const clientForInstance = isCallbackClient(client) ? client.promise() : client; ``` Sources: [drizzle-orm/src/mysql2/driver.ts:77-77](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql2/driver.ts#L77-L77) SQLite dialects target diverse runtimes, ranging from Node.js bindings like `better-sqlite3` and Bun's built-in `bun:sqlite` to edge-native targets such as Cloudflare D1 databases (`D1Database`) and Cloudflare Durable Objects storage (`DurableObjectStorage`). Sources: [drizzle-orm/type-tests/sqlite/db.ts:1-16](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/sqlite/db.ts#L1-L16) > [!WARNING] > When providing a schema configuration alongside the `mysql2` driver, you must explicitly specify the `mode` property as either `'planetscale'` or `'default'` to avoid runtime configuration errors. Sources: [drizzle-orm/src/mysql2/driver.ts:80-86](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql2/driver.ts#L80-L86) ### Gel Database Integration Drizzle extends its dialect breadth to Gel via `GelDialect`, `GelDriver`, and `GelJsDatabase`, bridging the Gel client ecosystem (`gel`) into standard Drizzle query building and relational session semantics. Sources: [drizzle-orm/src/gel/driver.ts:1-47](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel/driver.ts#L1-L47) | Driver Module | Target Engine / Client | Primary Artifacts | | :--- | :--- | :--- | | `postgres-js` | PostgreSQL (`postgres`) | `PostgresJsDatabase`, `PostgresJsSession`, `postgres` client | | `pglite` | Embedded PostgreSQL (`@electric-sql/pglite`) | `PgliteDatabase`, `PgliteSession`, `PGlite` client | | `mysql2` | MySQL / PlanetScale (`mysql2`) | `MySql2Database`, `MySql2Session`, Pool/Connection | | `better-sqlite3` / `bun-sqlite` | SQLite (Node / Bun) | `BetterSQLite3Database`, `BunSQLiteDatabase` | | `d1` / `durable-sqlite` | Cloudflare Workers & Durable Objects | `D1Database`, `DurableObjectStorage` wrappers | | `gel` | Gel DB (`gel`) | `GelJsDatabase`, `GelDriver`, `GelClient` | Sources: [drizzle-orm/src/gel/driver.ts:1-47](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel/driver.ts#L1-L47), [drizzle-orm/src/mysql2/driver.ts:1-68](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql2/driver.ts#L1-L68), [drizzle-orm/src/pglite/driver.ts:1-47](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pglite/driver.ts#L1-L47), [drizzle-orm/src/postgres-js/driver.ts:1-38](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/postgres-js/driver.ts#L1-L38), [drizzle-orm/type-tests/sqlite/db.ts:1-16](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/sqlite/db.ts#L1-L16) > [!CAUTION] > Calling `drizzle.mock()` on dialect drivers returns a mock database instance where `$client` is either uninitialized or set to a placeholder string (e.g. `'$client is not available on drizzle.mock()'`), preventing accidental production queries from executing against stubbed connections. Sources: [drizzle-orm/src/gel/driver.ts:131-138](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel/driver.ts#L131-L138), [drizzle-orm/src/pglite/driver.ts:153-160](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pglite/driver.ts#L153-L160), [drizzle-orm/src/postgres-js/driver.ts:120-132](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/postgres-js/driver.ts#L120-L132) ## Serverless and Edge Runtimes ### Cloudflare Durable Objects and Bun Integrations Drizzle provides dedicated database driver modules tailored for modern serverless and edge computing environments, including Cloudflare Durable Objects and the Bun runtime. For Cloudflare Durable Objects, the `durable-sqlite` driver exports `DrizzleSqliteDODatabase` alongside a `drizzle` initialization function that accepts a `DurableObjectStorage` client instance and a `DrizzleConfig` object, configuring a synchronous SQLite dialect (`SQLiteSyncDialect`) and a `SQLiteDOSession` without requiring manual polling or network roundtrips. Sources: [drizzle-orm/src/durable-sqlite/driver.ts:16-60](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/durable-sqlite/driver.ts#L16-L60) Similarly, the Bun ecosystem is supported through two specialized driver packages: `bun-sqlite` and `bun-sql`. The `bun-sqlite` driver builds upon Bun's native `bun:sqlite` engine by wrapping `Database` instances into `BunSQLiteDatabase`, supporting flexible connection options such as `readonly`, `create`, and `readwrite` flags. The `bun-sql` driver targets Bun's PostgreSQL capabilities, instantiating `BunSQLDatabase` instances over Bun's native `SQL` client and automatically wiring query parsers, serializers, and caching hooks. Sources: [drizzle-orm/src/bun-sqlite/driver.ts:17-152](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/bun-sqlite/driver.ts#L17-L152), [drizzle-orm/src/bun-sql/driver.ts:19-125](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/bun-sql/driver.ts#L19-L125) > [!NOTE] > When initializing `drizzle` with `bun-sqlite` or `bun-sql`, invoking `drizzle.mock()` constructs a stubbed database instance where the `$client` property is assigned either a placeholder object with empty option maps or an uninitialized handle, keeping test mocks completely isolated from native runtime bindings. Sources: [drizzle-orm/src/bun-sqlite/driver.ts:145-152](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/bun-sqlite/driver.ts#L145-L152), [drizzle-orm/src/bun-sql/driver.ts:113-125](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/bun-sql/driver.ts#L113-L125) ### Neon Serverless and Vercel Postgres Protocols Serverless PostgreSQL deployments across Neon and Vercel Postgres rely on lightweight HTTP and WebSocket connection managers that bypass traditional persistent connection pools. The Neon serverless driver package provides two distinct client modes: WebSocket-driven connection pooling via `NeonDriver` and `Pool` configurations from `@neondatabase/serverless`, and HTTP-based stateless querying via `NeonHttpDriver` and `neon()` query functions. The HTTP driver initializes explicit type parsers for PostgreSQL temporal and geometric types—such as `TIMESTAMPTZ`, `TIMESTAMP`, `DATE`, and `INTERVAL`—ensuring raw string representations are preserved across serverless boundaries. Sources: [drizzle-orm/src/neon-serverless/driver.ts:18-41](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-serverless/driver.ts#L18-L41), [drizzle-orm/src/neon-http/driver.ts:15-51](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-http/driver.ts#L15-L51) Vercel Postgres integrates similarly through the `vercel-postgres` driver, which wraps the `@vercel/postgres` `sql` client into `VercelPgDatabase` instances and supports optional caching layers and custom logging through `VercelPgDriver`. Both Neon HTTP and Vercel Postgres driver configurations accept schema definitions, extraction helpers, and custom cache invalidation callbacks (`onMutate`) directly within their initialization objects. Sources: [drizzle-orm/src/vercel-postgres/driver.ts:17-85](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/vercel-postgres/driver.ts#L17-L85), [drizzle-orm/src/neon-http/driver.ts:124-169](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-http/driver.ts#L124-L169) > [!IMPORTANT] > The `NeonHttpDatabase` class exposes a `$withAuth(token)` method that returns a proxied database instance intercepting query execution and `with` clauses to dynamically inject fine-grained authentication tokens into Neon HTTP requests. Sources: [drizzle-orm/src/neon-http/driver.ts:80-112](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-http/driver.ts#L80-L112) | Serverless Driver Module | Target Protocol / Client SDK | Primary Database Class | Key Configuration Options | | :--- | :--- | :--- | :--- | | `durable-sqlite` | Cloudflare Durable Objects (`DurableObjectStorage`) | `DrizzleSqliteDODatabase` | `client`, `schema`, `casing`, `logger` | | `bun-sqlite` | Bun Native SQLite (`bun:sqlite`) | `BunSQLiteDatabase` | `connection` (string/object with `readonly`, `create`, `readwrite`), `client`, `schema` | | `bun-sql` | Bun Native PostgreSQL (`bun`) | `BunSQLDatabase` | `connection` (string/object with URL & `SQLOptions`), `client`, `schema` | | `neon-serverless` | Neon WebSocket / Pool (`@neondatabase/serverless`) | `NeonDatabase` | `connection` (string/`PoolConfig`), `client`, `ws`, `cache`, `logger` | | `neon-http` | Neon HTTP Query (`@neondatabase/serverless`) | `NeonHttpDatabase` | `connection` (string/`HTTPTransactionOptions`), `client`, `cache`, `logger` | | `vercel-postgres` | Vercel Postgres (`@vercel/postgres`) | `VercelPgDatabase` | `client`, `cache`, `logger`, `casing` | Sources: [drizzle-orm/src/durable-sqlite/driver.ts:16-55](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/durable-sqlite/driver.ts#L16-L55), [drizzle-orm/src/bun-sqlite/driver.ts:17-124](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/bun-sqlite/driver.ts#L17-L124), [drizzle-orm/src/bun-sql/driver.ts:19-95](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/bun-sql/driver.ts#L19-L95), [drizzle-orm/src/neon-serverless/driver.ts:43-111](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-serverless/driver.ts#L43-L111), [drizzle-orm/src/neon-http/driver.ts:80-208](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-http/driver.ts#L80-L208), [drizzle-orm/src/vercel-postgres/driver.ts:42-108](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/vercel-postgres/driver.ts#L42-L108) > [!CAUTION] > When configuring the Neon serverless driver via an options object, providing a `ws` property automatically overrides the global `neonConfig.webSocketConstructor` constructor for all underlying WebSocket connections. Sources: [drizzle-orm/src/neon-serverless/driver.ts:124-134](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-serverless/driver.ts#L124-L134) ## Unified LibSQL Transport Adapters ### LibSQL Driver Modularity Drizzle ORM provides a modular set of entrypoints for LibSQL, decoupling database operations from specific client bindings across seven dedicated transport packages. Each entrypoint exports a specialized `drizzle` initialization function that accepts either a connection string, a pre-configured client instance, or a unified configuration object containing connection parameters and schema definitions. ```typescript export function drizzle< TSchema extends Record = Record, TClient extends Client = Client, >( ...params: [ TClient | string, ] | [ TClient | string, DrizzleConfig, ] | [ ( & DrizzleConfig & ({ connection: string | Config; } | { client: TClient; }) ), ] ): LibSQLDatabase & { ``` Sources: [drizzle-orm/src/libsql/driver.ts:7-26](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/driver.ts#L7-L26) The initialization function handles three distinct parameter signatures: passing a connection string directly, passing a configuration object with a `connection` string or `Config` object or an existing `client` instance, or passing a pre-instantiated client directly alongside an optional `DrizzleConfig` object. ```typescript if (typeof params[0] === 'string') { const instance = createClient({ url: params[0], }); return construct(instance, params[1]) as any; } if (isConfig(params[0])) { const { connection, client, ...drizzleConfig } = params[0] as & { connection?: Config; client?: TClient } & DrizzleConfig; if (client) return construct(client, drizzleConfig) as any; const instance = typeof connection === 'string' ? createClient({ url: connection }) : createClient(connection!); return construct(instance, drizzleConfig) as any; } return construct(params[0] as TClient, params[1] as DrizzleConfig | undefined) as any; } ``` Sources: [drizzle-orm/src/libsql/http/index.ts:27-48](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/http/index.ts#L27-L48) > [!NOTE] > All LibSQL driver entrypoints export a static `drizzle.mock()` helper method that constructs a type-safe `LibSQLDatabase` instance without binding to a live client, assigning `$client` the literal type string `'$client is not available on drizzle.mock()'`. Sources: [drizzle-orm/src/libsql/http/index.ts:50-57](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/http/index.ts#L50-L57), [drizzle-orm/src/libsql/node/index.ts:50-57](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/node/index.ts#L50-L57), [drizzle-orm/src/libsql/sqlite3/index.ts:50-57](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/sqlite3/index.ts#L50-L57), [drizzle-orm/src/libsql/driver.ts:52-59](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/driver.ts#L52-L59), [drizzle-orm/src/libsql/web/index.ts:50-57](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/web/index.ts#L50-L57), [drizzle-orm/src/libsql/wasm/index.ts:50-57](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/wasm/index.ts#L50-L57), [drizzle-orm/src/libsql/ws/index.ts:50-57](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/ws/index.ts#L50-L57) | Transport Module Path | Underlying Package Import | Target Environment / Protocol | | :--- | :--- | :--- | | `drizzle-orm/libsql` | `@libsql/client` | Default / Generic LibSQL Client | | `drizzle-orm/libsql/node` | `@libsql/client/node` | Node.js native bindings | | `drizzle-orm/libsql/http` | `@libsql/client/http` | HTTP protocol serverless transport | | `drizzle-orm/libsql/ws` | `@libsql/client/ws` | WebSocket protocol serverless transport | | `drizzle-orm/libsql/web` | `@libsql/client/web` | Web standard fetch environments | | `drizzle-orm/libsql/wasm` | `@libsql/client-wasm` | WebAssembly SQLite runtime | | `drizzle-orm/libsql/sqlite3` | `@libsql/client/sqlite3` | Native `sqlite3` driver bindings | Sources: [drizzle-orm/src/libsql/http/index.ts:1](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/http/index.ts#L1), [drizzle-orm/src/libsql/node/index.ts:1](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/node/index.ts#L1), [drizzle-orm/src/libsql/sqlite3/index.ts:1](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/sqlite3/index.ts#L1), [drizzle-orm/src/libsql/driver.ts:1](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/driver.ts#L1), [drizzle-orm/src/libsql/web/index.ts:1](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/web/index.ts#L1), [drizzle-orm/src/libsql/wasm/index.ts:1](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/wasm/index.ts#L1), [drizzle-orm/src/libsql/ws/index.ts:1](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/ws/index.ts#L1) ## Tooling Ecosystem and Schema Coordination ### CLI Commands and Schema Management Drizzle Kit orchestrates schema generation, migration lifecycle management, database inspection, and local studio hosting through a set of CLI commands defined using `@drizzle-team/brocli`. Each command validates inputs, enforces version compatibility with `drizzle-orm`, and dispatches dialect-specific handlers across PostgreSQL, MySQL, SQLite, Turso, SingleStore, and Gel. | CLI Command | Description / Action | Target Dialects / Handlers | | :--- | :--- | :--- | | `generate` | Prepares migration files and differential schemas | `postgresql`, `mysql`, `sqlite`, `turso`, `singlestore` | | `drop` | Removes the most recent migration file from the output folder | Validated against V1 output directory layout | | `studio` | Launches local Drizzle Studio server with TLS certificates | `postgresql`, `mysql`, `sqlite`, `turso`, `singlestore` (Gel throws error) | | `export` | Generates a raw SQL diff between the current and empty state | `postgresql`, `mysql`, `sqlite`, `turso`, `singlestore` | Sources: [drizzle-kit/src/cli/schema.ts:50-67](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/schema.ts#L50-L67), [drizzle-kit/src/cli/schema.ts:633-650](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/schema.ts#L633-L650), [drizzle-kit/src/cli/schema.ts:652-805](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/schema.ts#L652-L805), [drizzle-kit/src/cli/schema.ts:807-856](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/schema.ts#L807-L856) > [!WARNING] > Attempting to execute the `studio` or `export` commands with the `gel` dialect will cause the CLI to log an error message via `error()` and immediately terminate process execution with `process.exit(1)`. Sources: [drizzle-kit/src/cli/schema.ts:743-750](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/schema.ts#L743-L750), [drizzle-kit/src/cli/schema.ts:845-852](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/schema.ts#L845-L852) ### Driver Interoperability and Runtime Checks The tooling and runtime packages coordinate closely to ensure proper driver wiring. For example, Netlify DB initialization inspects connection parameters to select between serverless Neon HTTP/Pool configurations and native Node.js Postgres pools, automatically mapping built-in types such as `TIMESTAMPTZ`, `TIMESTAMP`, `DATE`, and `INTERVAL`. ```typescript initMappers() { types.setTypeParser(types.builtins.TIMESTAMPTZ, (val: any) => val); types.setTypeParser(types.builtins.TIMESTAMP, (val: any) => val); types.setTypeParser(types.builtins.DATE, (val: any) => val); types.setTypeParser(types.builtins.INTERVAL, (val: any) => val); types.setTypeParser(1231, (val: any) => val); types.setTypeParser(1115, (val: any) => val); types.setTypeParser(1185, (val: any) => val); types.setTypeParser(1187, (val: any) => val); types.setTypeParser(1182, (val: any) => val); } } ``` Sources: [drizzle-orm/src/netlify-db/driver.ts:58-69](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/driver.ts#L58-L69) > [!NOTE] > When starting Drizzle Studio with specific underlying drivers such as `aws-data-api` or `pglite`, the CLI verifies that the installed `drizzle-orm` package meets minimum version thresholds (`> 0.30.10` and `> 0.30.6` respectively) before allowing the server to start. Sources: [drizzle-kit/src/cli/schema.ts:691-712](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/schema.ts#L691-L712) ## Where to go next | I want to… | Read | | --- | --- | | Walk through minimal, copy-pasteable examples to declare schemas, establish a connection with popular drivers, execute type-safe queries, and apply migrations. | [Quick Start](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/getting-started/quick-start) | | Navigate the monorepo directory layout, understanding the boundary and responsibility of drizzle-orm, drizzle-kit, drizzle-seed, validation wrappers, and integration tests. | [Project Structure](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/getting-started/project-structure) | | How raw SQL expressions, parameterized chunks, dialect-aware operators, condition trees, and SQL functions are constructed and safely parameterized. | [SQL Template Engine](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/sql-template-engine) | | How table definitions, column builder abstractions, primary keys, indexes, foreign keys, aliases, and naming conventions are implemented and inferred across dialects. | [Table and Column Models](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/table-and-column-models) | | How the Relational Query Builder (RQB) parses declarative relation definitions (1:1, 1:N, M:N), models nested graph queries, and builds consolidated execution payloads. | [Relational Query Engine](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/relational-query-engine) | | How core query builders, Select/Insert/Update/Delete base abstractions, thenable query promises, and subquery wrappers compile high-level operations into executable ASTs. | [Query Builder Foundation](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/query-builder-foundation) | | How database sessions, driver connection wrappers, transaction semantics, savepoints, batch execution, and migration runners coordinate across asynchronous runtimes. | [Sessions and Transactions](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/sessions-and-transactions) | | How query result caching interfaces are structured and integrated with external distributed cache stores such as Upstash Redis. | [Query Caching](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/query-caching) | | How query execution logging, OpenTelemetry-compatible spans, tracer hooks, and diagnostic telemetry are wired through internal query execution paths. | [Logging and Tracing](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/logging-and-tracing) | | How to define schemas, tables, standard columns, PostGIS geometry, pgvector types, sequences, check constraints, indexes, unique constraints, and row-level security policies in PostgreSQL. | [Dialects And Schema Schema Definition](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/dialects-and-schema/dialects-and-schema-schema-definition) | | How PostgreSQL-specific dialect compilation, select/insert/update/delete operations, returning clauses, conflict resolution (upsert), and materialized view refreshes are implemented. | [Dialects And Schema Query Builders](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/dialects-and-schema/dialects-and-schema-query-builders) | | How HTTP and WebSocket-based serverless PostgreSQL clients (Neon HTTP/Serverless, Supabase, Vercel Postgres, AWS Data API, Netlify DB, and Xata HTTP) maintain connectionless or pooled execution. | [Drivers And Runtimes](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/drivers-and-runtimes/drivers-and-runtimes) | | How Drizzle operates inside Cloudflare D1 workers, Durable Objects storage, Expo SQLite mobile environments, and OP-SQLite on React Native. | [Edge and Mobile SQLite](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/drivers-and-runtimes/edge-and-mobile-sqlite) | | How Drizzle schemas and sessions integrate with Prisma client instances, Knex query runners, and Kysely adapters for incremental migrations. | [Knex Kysely and Prisma Interop](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/drivers-and-runtimes/knex-kysely-and-prisma-interop) | | How drizzle-kit parses CLI arguments, dispatches migrate, check, drop, and up commands, prompts interactive choices, and displays formatted terminal output. | [CLI Command Architecture](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/cli-command-architecture) | | How TypeScript schema definitions are serialized into normalized JSON migration snapshots and journals across PostgreSQL, MySQL, SQLite, SingleStore, and Gel. | [Migration Toolkit Schema](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/migration-toolkit-schema) | | How live database catalogs (information schema, system tables, pragma statements) are inspected to reverse-engineer Drizzle schema code for all supported engines. | [Database Introspection](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/database-introspection) | | How drizzle-kit serves Drizzle Studio locally, provisions TLS certificates, exposes schema metadata, and proxies query inspection over a local HTTP server. | [Studio Server Bridge](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/studio-server-bridge) | | How drizzle.config.ts files are parsed, validated, and normalized for dialect options, connection parameters, extensions, and schema glob paths. | [Configuration and Validations](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/configuration-and-validations) | | How to automatically generate Zod schemas from Drizzle table definitions, customize insert/select schemas, refine constraints, and validate forms. | [Drizzle Zod Integration](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/ecosystem-packages/drizzle-zod-integration) | | How JSON Schema validation objects are derived from Drizzle column types using Sinclair's TypeBox library. | [Drizzle TypeBox Integration](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/ecosystem-packages/drizzle-typebox-integration) | | How modular and lightweight Valibot validation schemas are automatically generated from Drizzle ORM table definitions. | [Drizzle Valibot Integration](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/ecosystem-packages/drizzle-valibot-integration) | | How ArkType runtime validation definitions are inferred from database table schemas. | [Drizzle ArkType Integration](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/ecosystem-packages/drizzle-arktype-integration) | | How drizzle-seed inspects database schemas, orders insertion sequences respecting foreign key topological dependencies, and seeds mock records. | [Seed Service Engine](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/ecosystem-packages/seed-service-engine) | | How realistic mock data (names, addresses, jobs, lorem ipsum, phone numbers) and weighted distribution generators produce mock values for column types. | [Seed Data Generators](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/ecosystem-packages/seed-data-generators) | | How AST lint rules enforce safety practices, such as requiring WHERE clauses on delete and update queries to avoid accidental whole-table wipes. | [ESLint Plugin Drizzle](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/ecosystem-packages/eslint-plugin-drizzle) | | How Turborepo, Rollup, tsup, and custom fix-imports scripts coordinate package bundling, ESM/CJS exports, and bundle size constraints. | [Monorepo Build Pipeline](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/testing-and-tooling/monorepo-build-pipeline) | | How Vitest, Docker containers, SST cloud fixtures, and real database drivers run cross-dialect integration tests across MySQL, PostgreSQL, SQLite, and SingleStore. | [Integration Test Harness](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/testing-and-tooling/integration-test-harness) | | How Drizzle ORM verifies compile-time type inference, relational join typing, strict-null checks, and prevents regressions across TypeScript versions. | [Type System Verification](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/testing-and-tooling/type-system-verification) | ## Related - [Quick Start](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/getting-started/quick-start) - [Project Structure](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/getting-started/project-structure) - [SQL Template Engine](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/sql-template-engine) --- ## Technical docs: Database Migration Query Merger URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/how-it-works/database-migration-query-merger
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-orm/src/netlify-db/migrator.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/migrator.ts) - [drizzle-orm/src/node-postgres/migrator.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/node-postgres/migrator.ts) - [drizzle-orm/src/pg-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/dialect.ts) - [drizzle-orm/src/pg-core/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/session.ts) - [drizzle-orm/src/sql/sql.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts)
## Overview ### Introduction The **Migrate -> MergeQueries** execution flow represents the end-to-end lifecycle of schema migration execution within Drizzle ORM's PostgreSQL and Netlify Database adapters. When a user triggers database migrations, migration files are parsed, converted into executable `SQL` templates, compiled into database-ready query strings with parameterized values, and finally merged into cohesive query batches executed via a database session transaction. Sources: [drizzle-orm/src/netlify-db/migrator.ts:8-18](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/migrator.ts#L8-L18), [drizzle-orm/src/node-postgres/migrator.ts:5-11](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/node-postgres/migrator.ts#L5-L11), [drizzle-orm/src/pg-core/dialect.ts:73-112](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/dialect.ts#L73-L112) --- ## Step-by-Step Execution Trace ### Step 1: Netlify-DB Migration Entrypoint The migration process can initiate from the Netlify Database adapter's `migrate` function. It checks whether the provided database instance is an instance of `NodePgDatabase`. If so, it delegates execution directly to the Node-Postgres migrator; otherwise, it reads migration files from disk/configuration and passes them to the underlying database session dialect. Sources: [drizzle-orm/src/netlify-db/migrator.ts:8-18](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/migrator.ts#L8-L18) ### Step 2: Node-Postgres Migration Entrypoint For standard Node-Postgres setups, the `migrate` function loads the migration metadata using `readMigrationFiles(config)` and invokes `db.dialect.migrate(...)` with the parsed migrations, database session, and configuration. Sources: [drizzle-orm/src/node-postgres/migrator.ts:5-11](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/node-postgres/migrator.ts#L5-L11) ### Step 3: PostgreSQL Dialect Migration Handler The `PgDialect.migrate` method sets up the migrations tracking table (`__drizzle_migrations`), checks existing records in the database, opens a transaction, and loops through unapplied migration scripts, executing individual statements inside a transaction block. Sources: [drizzle-orm/src/pg-core/dialect.ts:73-112](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/dialect.ts#L73-L112) ### Step 4: Session Execution & Query Preparation When `tx.execute(...)` is called with an `SQL` template object, the `PgSession` wraps the operation inside active telemetry spans, turning the raw `SQL` object into a prepared query via `this.dialect.sqlToQuery(query)`. Sources: [drizzle-orm/src/pg-core/session.ts:190-207](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/session.ts#L190-L207) ### Step 5: Dialect SQL-to-Query Conversion `PgDialect.sqlToQuery` acts as a bridge, invoking `sql.toQuery(...)` with dialect-specific configurations such as custom casing rules, parameter escaping, and typing functions. Sources: [drizzle-orm/src/pg-core/dialect.ts:609-618](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/dialect.ts#L609-L618) ### Step 6: SQL Object Query Compilation `SQL.toQuery` initiates an active OpenTelemetry tracing span (`drizzle.buildSQL`) and invokes `buildQueryFromSourceParams` over the internal query chunks to compile textual SQL and parameter lists. Sources: [drizzle-orm/src/sql/sql.ts:137-146](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts#L137-L146) ### Step 7: Building Query from Source Parameters `buildQueryFromSourceParams` iterates through every `SQLChunk` inside the expression tree—handling strings, names, identifiers, tables, parameters, and nested `SQL` objects—producing a list of partial `QueryWithTypings` objects. Sources: [drizzle-orm/src/sql/sql.ts:148-300](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts#L148-L300) ### Step 8: Merging Queries `mergeQueries` aggregates an array of `QueryWithTypings` chunks into a single, unified `QueryWithTypings` result object by concatenating SQL strings, accumulating parameter arrays, and merging type definitions. Sources: [drizzle-orm/src/sql/sql.ts:74-87](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts#L74-L87) --- ## Architecture Diagrams ### Sequence Diagram ```mermaid sequenceDiagram autonumber participant NetlifyMigrator as netlify-db/migrator.ts participant NodePgMigrator as node-postgres/migrator.ts participant PgDialect as pg-core/dialect.ts participant PgSession as pg-core/session.ts participant SQLObj as sql/sql.ts (SQL) alt Netlify DB (Non-NodePg) NetlifyMigrator->>PgDialect: migrate(migrations, session, config) else Node-Postgres / NodePg fallback NetlifyMigrator->>NodePgMigrator: migrate(db, config) NodePgMigrator->>PgDialect: migrate(migrations, session, config) end loop For each unapplied migration statement PgDialect->>PgSession: tx.execute(sql) PgSession->>PgDialect: sqlToQuery(query) PgDialect->>SQLObj: sql.toQuery(config) SQLObj->>SQLObj: buildQueryFromSourceParams(chunks, config) SQLObj->>SQLObj: mergeQueries(queries) SQLObj-->>PgDialect: QueryWithTypings PgDialect-->>PgSession: Executed query result end ``` Sources: [drizzle-orm/src/netlify-db/migrator.ts:8-18](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/migrator.ts#L8-L18), [drizzle-orm/src/node-postgres/migrator.ts:5-11](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/node-postgres/migrator.ts#L5-L11), [drizzle-orm/src/pg-core/dialect.ts:73-112](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/dialect.ts#L73-L112), [drizzle-orm/src/pg-core/session.ts:190-207](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/session.ts#L190-L207), [drizzle-orm/src/sql/sql.ts:74-146](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts#L74-L146) ### Flowchart ```mermaid flowchart TD A[Migrate Entrypoint] --> B{Is NodePgDatabase?} B -- Yes --> C[NodePg Migrate] B -- No --> D[Read Migration Files] C --> D D --> E[PgDialect.migrate] E --> F[Execute Migration Statements] F --> G[PgSession.execute] G --> H[PgDialect.sqlToQuery] H --> I[SQL.toQuery] I --> J[buildQueryFromSourceParams] J --> K[mergeQueries] K --> L[Database Transaction Execution] ``` Sources: [drizzle-orm/src/netlify-db/migrator.ts:8-18](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/migrator.ts#L8-L18), [drizzle-orm/src/node-postgres/migrator.ts:5-11](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/node-postgres/migrator.ts#L5-L11), [drizzle-orm/src/pg-core/dialect.ts:73-112](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/dialect.ts#L73-L112), [drizzle-orm/src/pg-core/session.ts:190-207](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/session.ts#L190-L207), [drizzle-orm/src/sql/sql.ts:74-146](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts#L74-L146) --- ## Key Observations - **Cross-Module Boundaries:** The execution flow seamlessly traverses driver-specific migrators (`netlify-db`, `node-postgres`), core database dialects (`pg-core`), active session managers, and core SQL query construction primitives (`sql/sql.ts`). - **Transaction Safety:** Migration scripts are executed sequentially inside a database transaction (`session.transaction`), ensuring that schema updates are atomic and rolling back if any statement fails. - **Telemetry & Tracing:** OpenTelemetry spans (`drizzle.operation`, `drizzle.prepareQuery`, `drizzle.buildSQL`) wrap query preparation and execution phases to monitor performance overhead. Sources: [drizzle-orm/src/netlify-db/migrator.ts:8-18](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/migrator.ts#L8-L18), [drizzle-orm/src/pg-core/dialect.ts:95-111](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/dialect.ts#L95-L111), [drizzle-orm/src/pg-core/session.ts:195-206](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/session.ts#L195-L206), [drizzle-orm/src/sql/sql.ts:138-146](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts#L138-L146) --- ## Technical docs: Quick Start URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/getting-started/quick-start
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-orm/type-tests/pg/tables.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/tables.ts) - [drizzle-orm/type-tests/mysql/tables.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/tables.ts) - [drizzle-orm/type-tests/geldb/tables.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/tables.ts) - [drizzle-orm/type-tests/singlestore/db.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/db.ts) - [drizzle-orm/type-tests/sqlite/tables.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/sqlite/tables.ts) - [drizzle-kit/src/api.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/api.ts) - [drizzle-kit/src/cli/connections.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/connections.ts) - [drizzle-orm/type-tests/singlestore/tables.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/tables.ts) - [drizzle-orm/type-tests/pg/select.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/select.ts) - [drizzle-orm/type-tests/kysely/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/kysely/index.ts) - [drizzle-orm/type-tests/pg/db.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/db.ts) - [drizzle-orm/src/mysql2/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql2/driver.ts) - [drizzle-orm/src/postgres-js/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/postgres-js/driver.ts) - [drizzle-orm/type-tests/mysql/db.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/db.ts) - [drizzle-orm/type-tests/geldb/select.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/select.ts) - [drizzle-orm/type-tests/mysql/select.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/select.ts) - [drizzle-orm/src/node-postgres/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/node-postgres/driver.ts) - [drizzle-orm/type-tests/mysql/db-rel.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/db-rel.ts) - [drizzle-orm/type-tests/singlestore/select.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/select.ts) - [drizzle-orm/type-tests/sqlite/select.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/sqlite/select.ts) - [drizzle-orm/type-tests/geldb/db.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/db.ts) - [drizzle-orm/type-tests/pg/db-rel.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/db-rel.ts) - [drizzle-orm/type-tests/sqlite/db.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/sqlite/db.ts) - [drizzle-kit/src/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/index.ts) - [drizzle-orm/src/better-sqlite3/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/better-sqlite3/index.ts) - [drizzle-orm/src/node-postgres/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/node-postgres/index.ts)
## Overview Get up and running with Drizzle ORM [Overview](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/getting-started/overview) by connecting schema definitions, driver initialization, and query execution across multiple database engines. This guide provides a foundational walkthrough to help developers define type-safe database tables [Type System Verification](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/testing-and-tooling/type-system-verification), establish client connections using drivers like node-postgres [Drivers And Runtimes](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/drivers-and-runtimes/drivers-and-runtimes) or mysql2, and execute complex queries with type-safe selection operators. Sources: [drizzle-orm/src/node-postgres/driver.ts:1-140](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/node-postgres/driver.ts#L1-L140), [drizzle-orm/src/mysql2/driver.ts:1-183](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql2/driver.ts#L1-L183), [drizzle-orm/type-tests/pg/tables.ts:963-1054](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/tables.ts#L963-L1054) ## Declaring Tables Across Dialects ### Dialect Table APIs Drizzle ORM provides dialect-specific table builder functions—such as `pgTable`, `mysqlTable`, `sqliteTable`, `singlestoreTable`, and `gelTable`—to define schema structures with precise compile-time type verification [Type System Verification](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/testing-and-tooling/type-system-verification). Each table builder accepts a table name, a column mapping object (or a callback builder function returning column definitions), and an optional extra-config callback for defining table-level constraints, primary keys, and unique indexes. Table definitions can be specified using a direct column object or a getter function callback across all supported storage engines. Column configurations support modifiers such as `.primaryKey()`, `.notNull()`, `.default()`, and dialect-specific type constraints. ```typescript const cities1 = pgTable('cities_table', { id: serial('id').primaryKey(), name: text('name').notNull().primaryKey(), role: text('role', { enum: ['admin', 'user'] }).default('user').notNull(), population: integer('population').default(0), }); const cities2 = pgTable('cities_table', ({ serial, text, integer }) => ({ id: serial('id').primaryKey(), name: text('name').notNull().primaryKey(), role: text('role', { enum: ['admin', 'user'] }).default('user').notNull(), population: integer('population').default(0), })); ``` Sources: [drizzle-orm/type-tests/pg/tables.ts:963-974](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/tables.ts#L963-L974) Similarly, SQLite and SingleStore support builders with advanced column mapping configurations, including explicit length constraints, enums, and generated expressions [Dialects And Schema Schema Definition](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/dialects-and-schema/dialects-and-schema-schema-definition). ```typescript const test = sqliteTable('test', { test1: text('test', { length: 255, enum: ['a', 'b', 'c'] as const }).notNull(), test2: text('test', { length: 255, enum: ['a', 'b', 'c'] }).notNull(), test3: text('test', { enum: ['a', 'b', 'c'] as const }).notNull(), test4: text('test', { enum: ['a', 'b', 'c'] }).notNull(), }); ``` Sources: [drizzle-orm/type-tests/sqlite/tables.ts:450-455](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/sqlite/tables.ts#L450-L455) ```typescript const emailLog = singlestoreTable( 'email_log', { id: int('id', { unsigned: true }).autoincrement().notNull(), clientId: int('id_client', { unsigned: true }), receiverEmail: varchar('receiver_email', { length: 255 }).notNull(), messageId: varchar('message_id', { length: 255 }), contextId: int('context_id', { unsigned: true }), contextType: singlestoreEnum('context_type', ['test']).$type<['test']>(), action: varchar('action', { length: 80 }).$type<['test']>(), events: json('events').$type<{ t: 'test' }[]>(), createdAt: timestamp('created_at', { mode: 'string' }).defaultNow().notNull(), updatedAt: timestamp('updated_at', { mode: 'string' }).defaultNow().onUpdateNow(), }, (table) => { return { emailLogId: primaryKey({ columns: [table.id], name: 'email_log_id' }), emailLogMessageIdUnique: unique('email_log_message_id_unique').on(table.messageId), }; }, ); ``` Sources: [drizzle-orm/type-tests/singlestore/tables.ts:737-757](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/tables.ts#L737-L757) ### Custom Types and Schema Scoping Schema scoping functions such as `pgSchema`, `mysqlSchema`, and `singlestoreSchema` isolate tables within named database namespaces. Custom column types can be constructed using `customType`, specifying data types, driver transformations, and required configuration parameters. > [!NOTE] > Custom type definitions require explicitly declaring whether configuration options are mandatory via `configRequired: true` or optional in the generic configuration structure. ```typescript const getUsersTable = (schemaName: TSchema) => { return pgSchema(schemaName).table('users', { id: integer('id').primaryKey(), name: text('name').notNull(), }); }; ``` Sources: [drizzle-orm/type-tests/pg/tables.ts:1088-1093](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/tables.ts#L1088-L1093) ```typescript const customTextRequired = customType<{ data: string; driverData: string; config: { length: number }; configRequired: true; }>({ dataType(config) { Expect>; return `varchar(${config.length})`; }, toDriver(value) { Expect>(); return value; }, fromDriver(value) { Expect>(); return value; }, }); ``` Sources: [drizzle-orm/type-tests/pg/tables.ts:904-924](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/tables.ts#L904-L924) ## Initializing PostgreSQL and MySQL Clients ### PostgreSQL Client Initialization Establishing connections to PostgreSQL and MySQL databases requires instantiating the appropriate driver client and passing it to the dialect initialization function. Drizzle supports multiple initialization signatures for both Node.js `pg`, `postgres-js`, and `mysql2` clients, accepting direct client instances, connection strings, or configuration objects containing `client`, `connection`, `schema`, `casing`, `logger`, `cache`, and driver-specific options. The PostgreSQL driver supports connection setup via `node-postgres` and `postgres-js`. For `node-postgres`, the `drizzle` entrypoint accepts either a `Pool` or `Client` instance, a raw connection string, or a configuration object with `connection` or `client` keys [drizzle-orm/src/node-postgres/driver.ts:91-140](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/node-postgres/driver.ts#L91-L140). Similarly, `postgres-js` accepts an `Sql` instance, a connection URL string, or a configuration object [drizzle-orm/src/postgres-js/driver.ts:70-118](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/postgres-js/driver.ts#L70-L118). ```typescript import pg from 'pg'; import { drizzle } from '~/node-postgres/index.ts'; const { Client } = pg; export const db = drizzle(new Client()); ``` Sources: [drizzle-orm/type-tests/pg/db.ts:1-6](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/db.ts#L1-L6) > [!NOTE] > When initializing `postgres-js`, Drizzle automatically overrides default date, JSON, and binary parsers (`1184`, `1082`, `1083`, `1114`, `1182`, `1185`, `1115`, `1231`, `114`, `3802`) with transparent identity parsers to prevent unwanted timezone transformations [drizzle-orm/src/postgres-js/driver.ts:28-36](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/postgres-js/driver.ts#L28-L36). Sources: [drizzle-orm/src/postgres-js/driver.ts:28-36](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/postgres-js/driver.ts#L28-L36) ### MySQL Client Initialization MySQL configurations use the `mysql2` driver, accepting callback or promise-based pools and connections. Callback pools passed to `drizzle` are automatically wrapped with `.promise()` to support async query execution [drizzle-orm/src/mysql2/driver.ts:77](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql2/driver.ts#L77). ```typescript import { createPool } from 'mysql2/promise'; import { drizzle } from '~/mysql2/index.ts'; const pool = createPool({}); export const db = drizzle(pool); ``` Sources: [drizzle-orm/type-tests/mysql/db.ts:1-6](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/db.ts#L1-L6) > [!WARNING] > When providing a relational `schema` object to MySQL `drizzle` configuration, you must explicitly specify a `mode` property set to either `'default'` or `'planetscale'`. Omitting the mode when a schema is present throws a runtime `DrizzleError`. Sources: [drizzle-orm/src/mysql2/driver.ts:80-86](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql2/driver.ts#L80-L86) ## Configuring Embedded and Alternative Engines ### SQLite and Serverless Drivers Embedded databases and alternative engines such as SQLite variants, SingleStore, and Gel use specialized driver initialization entrypoints. SQLite supports multiple runtimes including `better-sqlite3`, Bun's native SQLite, Cloudflare D1, and Durable Object storage. Each runtime requires its respective driver instance initialized before passing to the dialect-specific `drizzle` function. ```typescript import Database from 'better-sqlite3'; import { Database as BunDatabase } from 'bun:sqlite'; import { drizzle as drizzleBetterSqlite3 } from '~/better-sqlite3/index.ts'; import { drizzle as drizzleBun } from '~/bun-sqlite/index.ts'; import { drizzle as drizzleD1 } from '~/d1/index.ts'; import { drizzle as durableSqlite } from '~/durable-sqlite/index.ts'; const client = new Database(':memory:'); const bunClient = new BunDatabase(':memory:'); declare const d1: D1Database; declare const durableSql: DurableObjectStorage; export const db = drizzleBetterSqlite3(client); export const bunDb = drizzleBun(bunClient); export const d1Db = drizzleD1(d1); export const durableSqliteDb = durableSqlite(durableSql); ``` Sources: [drizzle-orm/type-tests/sqlite/db.ts:1-16](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/sqlite/db.ts#L1-L16) > [!NOTE] > SQLite initialization functions accept either a direct client instance or configuration objects, allowing memory-backed databases or persistent storage bindings like Cloudflare D1 and Durable Objects to operate transparently within type definitions. Sources: [drizzle-orm/type-tests/sqlite/db.ts:8-16](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/sqlite/db.ts#L8-L16) ### Alternative Database Dialects SingleStore and Gel use independent driver connectors and initialization modules. SingleStore integrates through `mysql2/promise` connection pools, accepting optional configuration objects with schema definitions. Gel connects via the official `gel` package client instance. ```typescript import { createPool } from 'mysql2/promise'; import { drizzle } from '~/singlestore/index.ts'; const pool = createPool({}); export const db = drizzle(pool); { drizzle(pool); drizzle(pool, { schema: {} }); drizzle(pool, { schema: {} }); drizzle(pool, {}); } ``` Sources: [drizzle-orm/type-tests/singlestore/db.ts:1-13](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/db.ts#L1-L13) ```typescript import * as gel from 'gel'; import { drizzle } from '~/gel/index.ts'; export const db = drizzle(gel.createClient()); ``` Sources: [drizzle-orm/type-tests/geldb/db.ts:1-4](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/db.ts#L1-L4) > [!TIP] > SingleStore initialization permits passing an empty or populated schema object alongside the connection pool during setup, matching the configuration patterns used across relational database drivers. Sources: [drizzle-orm/type-tests/singlestore/db.ts:8-13](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/db.ts#L8-L13) ## Executing Queries with Selection Operators ### Query Construction and Joins Selection queries start from a database table using `.select()` combined with `.from()`, and can be extended with inner joins, left joins, or full outer joins to combine related entities. Operators such as `eq`, `and`, and raw SQL fragments via the `sql` template tag define join conditions and filter predicates. ```typescript const join4 = await db .select({ user: { id: users.id, }, city: { id: cities.id, }, class: classes, friend: friends, }) .from(users) .innerJoin(cities, sql`${users.id} = ${cities.id}`) .innerJoin(classes, sql`${cities.id} = ${classes.id}`) .innerJoin(friends, sql`${friends.id} = ${users.id}`) .where(sql`${users.age1} > 0`); ``` Sources: [drizzle-orm/type-tests/geldb/select.ts:817-832](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/select.ts#L817-L832), [drizzle-orm/type-tests/singlestore/select.ts:548-563](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/select.ts#L548-L563) > [!WARNING] > Attempting to chain multiple `.where()` clauses on the same select statement triggers a TypeScript compilation error because query builders restrict filtering to a single invocation per statement. Sources: [drizzle-orm/type-tests/geldb/select.ts:923-943](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/select.ts#L923-L943), [drizzle-orm/type-tests/singlestore/select.ts:657-677](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/select.ts#L657-L677) ### Row Locking and Modifiers Queries support row-level locking modifiers via the `.for()` method to handle concurrent transactions. Depending on the dialect and requirements, locking strategies can specify exclusivity, wait behavior, or lock skipping. ```typescript await db.select().from(users).for('update'); await db.select().from(users).for('no key update', { of: users }); await db.select().from(users).for('no key update', { of: users, skipLocked: true }); await db.select().from(users).for('share', { of: users, noWait: true }); ``` Sources: [drizzle-orm/type-tests/geldb/select.ts:885-904](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/select.ts#L885-L904), [drizzle-orm/type-tests/singlestore/select.ts:615-617](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/select.ts#L615-L617) > [!CAUTION] > Combining both `skipLocked: true` and `noWait: true` in the same `.for()` options object causes a TypeScript type error and is disallowed by locking constraint rules. Sources: [drizzle-orm/type-tests/geldb/select.ts:905-910](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/select.ts#L905-L910), [drizzle-orm/type-tests/singlestore/select.ts:619-623](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/select.ts#L619-L623) ## Querying Relational Schemas with Relations ### Relational Queries and Schema Definition Relational queries access structured graphs of data via `db.query..findMany()` by bundling schema definitions directly into client initialization. When configuring a PostgreSQL or MySQL client via `drizzle(client, { schema })`, `extractTablesRelationalConfig` and `createTableRelationsHelpers` process the passed schema object to map relationships, table configurations, and name lookups. ```typescript import pg from 'pg'; import { drizzle } from '~/node-postgres/index.ts'; import * as schema from './tables-rel.ts'; const { Pool } = pg; const pdb = new Pool({ connectionString: process.env['PG_CONNECTION_STRING'] }); const db = drizzle(pdb, { schema }); ``` Sources: [drizzle-orm/src/node-postgres/driver.ts:67-77](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/node-postgres/driver.ts#L67-L77), [drizzle-orm/type-tests/pg/db-rel.ts:1-10](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/db-rel.ts#L1-L10) > [!NOTE] > MySQL2 database instances require `config.mode` to be explicitly set to either `'planetscale'` or `'default'` when a schema is provided, otherwise an error is thrown during initialization. > > Sources: [drizzle-orm/src/mysql2/driver.ts:80-86](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql2/driver.ts#L80-L86) ### Filtering, Pagination, and Column Selection The relational query builder accepts `where`, `limit`, `orderBy`, `columns`, and `with` options to filter records and shape nested tree structures. The `columns` configuration object supports boolean values or `undefined` / `false` flags to include or exclude specific fields. ```typescript const result = await db.query.users.findMany({ where: (users, { sql }) => sql`char_length(${users.name} > 1)`, limit: sql.placeholder('l'), orderBy: (users, { asc, desc }) => [asc(users.name), desc(users.id)], with: { posts: { columns: { id: false, title: undefined, }, extras: { lower: sql`lower(${schema.posts.title})`.as('lower_name'), }, }, }, }); ``` Sources: [drizzle-orm/type-tests/pg/db-rel.ts:13-24](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/db-rel.ts#L13-L24), [drizzle-orm/type-tests/pg/db-rel.ts:92-107](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/db-rel.ts#L92-L107) > [!TIP] > The `extras` property allows appending computed SQL expressions and custom aliases to query selections without modifying the underlying table schema definition. Sources: [drizzle-orm/type-tests/pg/db-rel.ts:99-104](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/db-rel.ts#L99-L104), [drizzle-orm/type-tests/mysql/db-rel.ts:99-101](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/db-rel.ts#L99-L101) ## Applying Migrations with Kit Entrypoints ### Configuration and DefineConfig The `drizzle-kit` entrypoint provides the `defineConfig` utility to validate and structure options for schema management, migrations, and [database introspection](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/database-introspection) [Configuration and Validations](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/configuration-and-validations). The configuration object governs dialect selection, schema paths, migration output directories, and driver-specific credentials across multiple engines. ```typescript import { defineConfig } from 'drizzle-kit'; export default defineConfig({ dialect: 'postgresql', schema: './src/schema.ts', out: './drizzle', breakpoints: true, strict: true, verbose: true, }); ``` Sources: [drizzle-kit/src/index.ts:109-132](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/index.ts#L109-L132), [drizzle-kit/src/index.ts:347-349](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/index.ts#L347-L349) ### Dialect Support and Driver Options Drizzle-kit supports distinct database dialects alongside specialized driver integrations. The configuration schema enforces valid option combinations for connection parameters, SSL settings, and migration metadata tables. | Dialect | Required Credentials / URL | Supported Drivers / Options | | :--- | :--- | :--- | | `postgresql` | `url` or `host`, `database`, optional `ssl` | `aws-data-api`, `pglite` | | `mysql` | `url` or `host`, `database`, optional `ssl` | — | | `sqlite` | `url` | `d1-http`, `expo`, `durable-sqlite` | | `turso` | `url`, optional `authToken` | — | | `singlestore` | `url` or `host`, `database`, optional `ssl` | — | | `gel` | optional `url` or host fields, `tlsSecurity` | — | Sources: [drizzle-kit/src/index.ts:133-255](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/index.ts#L133-L255) > [!NOTE] > The `breakpoints` option defaults to `true` and inserts SQL statement breakpoints into generated migrations. This is required for engines like MySQL, SQLite, and SingleStore that do not support multiple DDL alteration statements within a single transaction. Sources: [drizzle-kit/src/index.ts:65-71](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/index.ts#L65-L71), [drizzle-kit/src/index.ts:113](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/index.ts#L113) ## Related - [Overview](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/getting-started/overview) - [Dialects And Schema Schema Definition](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/dialects-and-schema/dialects-and-schema-schema-definition) - [CLI Command Architecture](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/cli-command-architecture) --- ## Technical docs: Project Structure URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/getting-started/project-structure
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-kit/src/api.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/api.ts) - [turbo.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/turbo.json) - [drizzle-kit/src/utils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/utils.ts) - [drizzle-orm/src/d1/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/d1/index.ts) - [pnpm-workspace.yaml](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/pnpm-workspace.yaml) - [drizzle-kit/src/serializer/studio.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/studio.ts) - [drizzle-orm/src/neon/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon/index.ts) - [package.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/package.json) - [drizzle-seed/src/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts) - [drizzle-orm/src/gel-core/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/index.ts) - [drizzle-kit/src/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/index.ts) - [drizzle-orm/src/singlestore-core/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/index.ts) - [drizzle-kit/package.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/package.json) - [drizzle-orm/src/singlestore/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore/index.ts) - [drizzle-orm/src/gel/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel/index.ts) - [drizzle-orm/src/durable-sqlite/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/durable-sqlite/index.ts) - [drizzle-orm/src/libsql/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/index.ts) - [drizzle-seed/package.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/package.json) - [drizzle-orm/src/pg-core/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/index.ts) - [drizzle-kit/src/serializer/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/index.ts) - [drizzle-orm/src/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/index.ts) - [drizzle-orm/src/mysql-proxy/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-proxy/index.ts) - [drizzle-orm/src/prisma/sqlite/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/sqlite/index.ts) - [drizzle-orm/src/prisma/pg/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/pg/index.ts) - [drizzle-orm/src/sqlite-proxy/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-proxy/index.ts) - [drizzle-orm/src/pglite/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pglite/index.ts) - [drizzle-orm/src/pg-proxy/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-proxy/index.ts) - [drizzle-orm/src/singlestore-proxy/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-proxy/index.ts) - [drizzle-orm/src/mysql-core/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/index.ts) - [drizzle-orm/src/op-sqlite/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/op-sqlite/index.ts)
## Overview Drizzle ORM and its tooling ecosystem are structured as an integrated monorepo workspace containing packages such as `drizzle-orm`, `drizzle-kit`, validation companions (`drizzle-zod`, `drizzle-typebox`, `drizzle-valibot`, `drizzle-arktype`), seeding engines (`drizzle-seed`), and internal development utilities. Managed through a Turborepo build pipeline and pnpm workspaces, the repository enforces strict dependency isolation and build ordering between core relational abstractions, engine-specific dialect modules, and runtime drivers. Sources: [turbo.json:1-210](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/turbo.json#L1-L210), [pnpm-workspace.yaml:1-11](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/pnpm-workspace.yaml#L1-L11), [package.json:1-42](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/package.json#L1-L42) ## Monorepo Workspace Organization ### Workspace Members and Configuration The repository uses `pnpm` workspaces to govern ten distinct packages under a private root manifest named `drizzle-root` with `pnpm@10.6.3`. The workspace layout includes core database relational abstractions, migration CLI infrastructure, schema validation generators, mock data seeding utilities, integration test suites, and internal linting plugins. ```yaml packages: - drizzle-orm - drizzle-kit - drizzle-zod - drizzle-typebox - drizzle-valibot - drizzle-arktype - drizzle-seed - integration-tests - eslint-plugin-drizzle onlyBuiltDependencies: ``` Sources: [pnpm-workspace.yaml:1-11](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/pnpm-workspace.yaml#L1-L11) | Workspace Member | Description | | :--- | :--- | | `drizzle-orm` | Core ORM runtime and query builder library | | `drizzle-kit` | Migration CLI and tooling suite | | `drizzle-zod` | Zod schema generation companion | | `drizzle-typebox` | TypeBox schema generation companion | | `drizzle-valibot` | Valibot schema generation companion | | `drizzle-arktype` | ArkType schema generation companion | | `drizzle-seed` | Database mock seeding engine | | `integration-tests` | Comprehensive database integration tests | | `eslint-plugin-drizzle` | Custom ESLint rules for Drizzle codebases | Sources: [pnpm-workspace.yaml:1-10](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/pnpm-workspace.yaml#L1-L10) > [!NOTE] > The root `package.json` configures development dependencies including `typescript` (5.6.3), `tsup` (8.3.5), `turbo` (2.2.3), and `dprint` (0.46.2), while defining workspace aliases such as `drizzle-orm` pointing directly to its distribution output (`workspace:./drizzle-orm/dist`). Sources: [package.json:1-42](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/package.json#L1-L42) ### Build and Test Scripts Orchestration tasks are driven by Turborepo filters and root scripts defined in the root configuration. These tasks coordinate type-checking, builds, formatting, and test execution across workspace boundaries. ```json "scripts": { "build:orm": "turbo run build --filter drizzle-orm --color", "build": "turbo run build test:types //#lint --color", "b": "pnpm build", "pack": "turbo run pack --color", "test": "turbo run test --color", "t": "pnpm test", "test:types": "turbo run test:types --color", "lint": "dprint check --list-different", "lint:fix": "dprint fmt" }, ``` Sources: [package.json:4-14](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/package.json#L4-L14) | Script Name | Command | Purpose | | :--- | :--- | :--- | | `build:orm` | `turbo run build --filter drizzle-orm --color` | Builds only the core `drizzle-orm` package via Turbo | | `build` | `turbo run build test:types //#lint --color` | Executes full monorepo build, type tests, and linting | | `b` | `pnpm build` | Shorthand alias for full monorepo build | | `pack` | `turbo run pack --color` | Packs workspace packages into distributable archives | | `test` | `turbo run test --color` | Runs test suites across all workspace members | | `t` | `pnpm test` | Shorthand alias for test execution | | `test:types` | `turbo run test:types --color` | Executes type-checking across workspace packages | | `lint` | `dprint check --list-different` | Checks code formatting using dprint | | `lint:fix` | `dprint fmt` | Auto-formats codebase files using dprint | Sources: [package.json:4-14](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/package.json#L4-L14) > [!IMPORTANT] > The root `pnpm-workspace.yaml` specifies an explicit `onlyBuiltDependencies` array to restrict native compilation during dependency installation, isolating binary packages such as `better-sqlite3`, `esbuild`, `prisma`, `sqlite3`, and `workerd`. Sources: [pnpm-workspace.yaml:11-27](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/pnpm-workspace.yaml#L11-L27) ### Package Isolation and Entry Points Individual workspace packages enforce strict encapsulation via targeted `package.json` configurations, declaring precise exports maps for CommonJS and ESM consumers, as well as peer dependency constraints. ```json "exports": { ".": { "import": { "types": "./index.d.mts", "default": "./index.mjs" }, "require": { "types": "./index.d.ts", "default": "./index.js" }, "types": "./index.d.mts", "default": "./index.mjs" }, "./api": { "import": { "types": "./api.d.mts", "default": "./api.mjs" }, "require": { "types": "./api.d.ts", "default": "./api.js" }, "types": "./api.d.mts", "default": "./api.mjs" } } ``` Sources: [drizzle-kit/package.json:118-143](https://github.com/blade47/drizzle-kit/package.json#L118-L143) > [!WARNING] > Packages like `drizzle-seed` declare `drizzle-orm` as an optional peer dependency (`>=0.36.4`) while consuming workspace references during development builds (`workspace:./drizzle-orm/dist`), requiring correct build ordering enforced by Turborepo pipelines. Sources: [drizzle-seed/package.json:67-74](https://github.com/blade47/drizzle-seed/package.json#L67-L74), [drizzle-seed/package.json:90-90](https://github.com/blade47/drizzle-seed/package.json#L90-L90) ## Drizzle ORM Core Subsystem ### Core Subsystem Module Exports The core query builder library exports its primary abstractions and runtime modules from the entry point `drizzle-orm/src/index.ts`. These modules provide the foundational contracts for schema definition, column construction, expression handling, and query execution. | Export Module | Source File | Purpose | | :--- | :--- | :--- | | Table alias definitions | `./alias.ts` | Provides mechanisms for aliasing database tables and relational expressions | | Column builders | `./column-builder.ts` | Defines fluent builders and configuration APIs for table columns | | Column primitives | `./column.ts` | Implements core column properties, data types, and mapping logic | | Entity abstractions | `./entity.ts` | Base definitions for relational entities and schema components | | Error handling | `./errors.ts` | Core library exceptions and runtime error types | | Logging infrastructure | `./logger.ts` | Query logging abstractions and formatting interfaces | | Query operations | `./operations.ts` | Universal operator contracts and filter expression builders | | Query promises | `./query-promise.ts` | Thenable query objects supporting async execution and chaining | | Relations mapping | `./relations.ts` | Relational schema definitions, foreign key links, and relation helpers | | SQL AST subsystem | `./sql/index.ts` | Abstract syntax tree nodes, SQL template literal tags, and token serialization | | Subqueries | `./subquery.ts` | Derived table wrappers and subquery construction contracts | | Table primitives | `./table.ts` | Core table definition structures and schema metadata containers | | Utilities | `./utils.ts` | Internal helper functions and shared type utilities | | View abstractions | `./view-common.ts` | Common interfaces for database views and materialized representations | Sources: [drizzle-orm/src/index.ts:1-14](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/index.ts#L1-L14) > [!NOTE] > The core subsystem operates as a zero-dependency headless library, relying entirely on exported TypeScript modules to build AST representations that are later translated into engine-specific SQL by dialect drivers. Sources: [drizzle-orm/src/index.ts:1-14](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/index.ts#L1-L14) ## Dialect Specialization Boundaries ### Engine-Specific Core Modules Dialect specialization directories organize engine-specific primitives, mapping abstractions, and query structures across supported database backends. PostgreSQL, MySQL, SingleStore, and Gel maintain isolated core index entry points under their respective directories in `drizzle-orm/src/`. | Core Module Export | PostgreSQL (`pg-core`) | MySQL (`mysql-core`) | SingleStore (`singlestore-core`) | Gel (`gel-core`) | | :--- | :--- | :--- | :--- | :--- | | Table alias | `export * from './alias.ts'` | `export * from './alias.ts'` | `export * from './alias.ts'` | `export * from './alias.ts'` | | Check constraints | `export * from './checks.ts'` | `export * from './checks.ts'` | — | `export * from './checks.ts'` | | Column definitions | `export * from './columns/index.ts'` | `export * from './columns/index.ts'` | `export * from './columns/index.ts'` | `export * from './columns/index.ts'` | | Database instance | `export * from './db.ts'` | `export * from './db.ts'` | `export * from './db.ts'` | `export * from './db.ts'` | | Dialect implementation | `export * from './dialect.ts'` | `export * from './dialect.ts'` | `export * from './dialect.ts'` | `export * from './dialect.ts'` | | Foreign keys | `export * from './foreign-keys.ts'` | `export * from './foreign-keys.ts'` | — | `export * from './foreign-keys.ts'` | | Index definitions | `export * from './indexes.ts'` | `export * from './indexes.ts'` | `export * from './indexes.ts'` | `export * from './indexes.ts'` | | Access policies | `export * from './policies.ts'` | — | — | `export * from './policies.ts'` | | Primary keys | `export * from './primary-keys.ts'` | `export * from './primary-keys.ts'` | `export * from './primary-keys.ts'` | `export * from './primary-keys.ts'` | | Query builders | `export * from './query-builders/index.ts'` | `export * from './query-builders/index.ts'` | `export * from './query-builders/index.ts'` | `export * from './query-builders/index.ts'` | | Roles | `export * from './roles.ts'` | — | — | `export * from './roles.ts'` | | Schema container | `export * from './schema.ts'` | `export * from './schema.ts'` | `export * from './schema.ts'` | `export * from './schema.ts'` | | Sequences | `export * from './sequence.ts'` | — | — | `export * from './sequence.ts'` | | Session interface | `export * from './session.ts'` | `export * from './session.ts'` | `export * from './session.ts'` | `export * from './session.ts'` | | Subqueries | `export * from './subquery.ts'` | `export * from './subquery.ts'` | `export * from './subquery.ts'` | `export * from './subquery.ts'` | | Table structures | `export * from './table.ts'` | `export * from './table.ts'` | `export * from './table.ts'` | `export * from './table.ts'` | | Unique constraints | `export * from './unique-constraint.ts'` | `export * from './unique-constraint.ts'` | `export * from './unique-constraint.ts'` | `export * from './unique-constraint.ts'` | | Utilities | `export * from './utils.ts'`, `export * from './utils/index.ts'` | `export * from './utils.ts'` | `export * from './utils.ts'` | `export * from './utils.ts'` | | Views and common view types | `export * from './view-common.ts'`, `export * from './view.ts'` | `export * from './view-common.ts'`, `export * from './view.ts'` | Commented out / disabled | `export * from './view-common.ts'`, `export * from './view.ts'` | Sources: [drizzle-orm/src/pg-core/index.ts:1-21](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/index.ts#L1-L21), [drizzle-orm/src/mysql-core/index.ts:1-17](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/index.ts#L1-L17), [drizzle-orm/src/singlestore-core/index.ts:1-14](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/index.ts#L1-L14), [drizzle-orm/src/gel-core/index.ts:1-20](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/index.ts#L1-L20) > [!CAUTION] > SingleStore core explicitly disables view exports via block comments inside `drizzle-orm/src/singlestore-core/index.ts`, omitting view-common and view modules from its public dialect API surface. Sources: [drizzle-orm/src/singlestore-core/index.ts:14-14](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/index.ts#L14-L14) > [!NOTE] > PostgreSQL (`pg-core`) maintains an additional internal utility sub-index (`export * from './utils/index.ts'`) alongside its root `utils.ts` module to handle advanced PostgreSQL-specific type and expression helpers. Sources: [drizzle-orm/src/pg-core/index.ts:18-19](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/index.ts#L18-L19) ## Runtime Driver Bindings ### LibSQL Driver and Session Exports ```typescript export * from './driver.ts'; export * from './session.ts'; ``` Sources: [drizzle-orm/src/libsql/index.ts:1-2](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/index.ts#L1-L2) The LibSQL runtime integration layer re-exports all binding declarations from its constituent driver and session modules. ```typescript export * from './driver.ts'; export * from './session.ts'; ``` Sources: [drizzle-orm/src/libsql/index.ts:1-2](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/index.ts#L1-L2) > [!NOTE] > LibSQL driver bindings maintain a strict separation between connection initialization logic in `driver.ts` and execution context management in `session.ts`. Sources: [drizzle-orm/src/libsql/index.ts:1-2](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/index.ts#L1-L2) ### PGlite Driver and Session Exports ```typescript export * from './driver.ts'; export * from './session.ts'; ``` Sources: [drizzle-orm/src/pglite/index.ts:1-2](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pglite/index.ts#L1-L2) Similarly, the PGlite in-memory and embedded PostgreSQL runtime integration aggregates its entry point by consuming module exports from local driver and session sources. ```typescript export * from './driver.ts'; export * from './session.ts'; ``` Sources: [drizzle-orm/src/pglite/index.ts:1-2](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pglite/index.ts#L1-L2) > [!TIP] > Both LibSQL and PGlite package entry points intentionally expose flat module namespaces via star-export declarations to streamline consumer imports across diverse serverless and edge targets. Sources: [drizzle-orm/src/libsql/index.ts:1-2](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/index.ts#L1-L2), [drizzle-orm/src/pglite/index.ts:1-2](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pglite/index.ts#L1-L2) ## Tooling and Utility Infrastructure ### CLI Validation Layers and Migration Utilities ```typescript const validatorForDialect = (dialect: Dialect) => { switch (dialect) { case 'postgresql': return { validator: backwardCompatiblePgSchema, version: 7 }; case 'sqlite': return { validator: backwardCompatibleSqliteSchema, version: 6 }; case 'turso': return { validator: backwardCompatibleSqliteSchema, version: 6 }; case 'mysql': return { validator: backwardCompatibleMysqlSchema, version: 5 }; case 'singlestore': return { validator: backwardCompatibleSingleStoreSchema, version: 1 }; case 'gel': return { validator: backwardCompatibleGelSchema, version: 1 }; } }; ``` Sources: [drizzle-kit/src/utils.ts:115-130](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/utils.ts#L115-L130) The `drizzle-kit` utility infrastructure inspects and validates database schemas across various SQL dialects by mapping each dialect to a compatible schema validator and expected version number. The `validatorForDialect` helper function evaluates the target dialect and returns the corresponding parser alongside its required schema version integer. | Dialect | Validator Function | Version | Sources | | :--- | :--- | :---: | :--- | | `postgresql` | `backwardCompatiblePgSchema` | 7 | [drizzle-kit/src/utils.ts:117-118](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/utils.ts#L117-L118) | | `sqlite` | `backwardCompatibleSqliteSchema` | 6 | [drizzle-kit/src/utils.ts:119-120](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/utils.ts#L119-L120) | | `turso` | `backwardCompatibleSqliteSchema` | 6 | [drizzle-kit/src/utils.ts:121-122](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/utils.ts#L121-L122) | | `mysql` | `backwardCompatibleMysqlSchema` | 5 | [drizzle-kit/src/utils.ts:123-124](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/utils.ts#L123-L124) | | `singlestore` | `backwardCompatibleSingleStoreSchema` | 1 | [drizzle-kit/src/utils.ts:125-126](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/utils.ts#L125-L126) | | `gel` | `backwardCompatibleGelSchema` | 1 | [drizzle-kit/src/utils.ts:127-128](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/utils.ts#L127-L128) | Sources: [drizzle-kit/src/utils.ts:115-130](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/utils.ts#L115-L130) > [!WARNING] > If a snapshot file specifies a version number exceeding the validator's configured version threshold, `validateWithReport` logs an unsupported version message and terminates execution via `process.exit(0)`. Sources: [drizzle-kit/src/utils.ts:145-152](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/utils.ts#L145-L152) ### Shared Runtime Configuration Boundaries ```typescript export type Config = & { dialect: Dialect; out?: string; breakpoints?: boolean; tablesFilter?: string | string[]; extensionsFilters?: 'postgis'[]; schemaFilter?: string | string[]; schema?: string | string[]; verbose?: boolean; strict?: boolean; casing?: 'camelCase' | 'snake_case'; migrations?: { table?: string; schema?: string; prefix?: Prefix; }; introspect?: { casing: 'camel' | 'preserve'; }; entities?: { roles?: boolean | { provider?: 'supabase' | 'neon' | string & {}; exclude?: string[]; include?: string[] }; }; } ``` Sources: [drizzle-kit/src/index.ts:109-132](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/index.ts#L109-L132) Configuration definitions for `drizzle-kit` establish strict typing boundaries across options such as `dialect`, `out`, `breakpoints`, `tablesFilter`, `extensionsFilters`, `schemaFilter`, `schema`, `verbose`, `strict`, `casing`, `migrations`, `introspect`, and `entities`. Connection parameters enforce disjoint credentials based on the selected database dialect, requiring specific credential shapes for engines like Turso, SQLite, PostgreSQL, and MySQL. > [!NOTE] > The `breakpoints` configuration parameter defaults to true and controls whether SQL statement breakpoints are embedded in generated migration files to support sequential execution on engines lacking multi-statement transaction DDL. Sources: [drizzle-kit/src/index.ts:65-70](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/index.ts#L65-L70), [drizzle-kit/src/index.ts:113](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/index.ts#L113) ## Related - [Overview](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/getting-started/overview) - [Monorepo Build Pipeline](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/testing-and-tooling/monorepo-build-pipeline) --- ## Technical docs: SQL Template Engine URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/sql-template-engine
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-orm/src/sql/sql.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts) - [drizzle-orm/src/gel-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/dialect.ts) - [drizzle-orm/src/singlestore-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/dialect.ts) - [drizzle-orm/src/sql/expressions/conditions.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/expressions/conditions.ts) - [drizzle-orm/src/pg-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/dialect.ts) - [drizzle-orm/src/sqlite-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/dialect.ts) - [drizzle-orm/src/gel-core/expressions.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/expressions.ts) - [drizzle-orm/src/singlestore-core/expressions.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/expressions.ts) - [drizzle-orm/src/mysql-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/dialect.ts) - [drizzle-orm/src/gel-core/query-builders/select.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/select.ts) - [drizzle-orm/src/gel-core/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/session.ts) - [drizzle-orm/type-tests/sqlite/select.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/sqlite/select.ts) - [drizzle-orm/type-tests/geldb/select.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/select.ts) - [drizzle-orm/src/sql/expressions/select.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/expressions/select.ts) - [drizzle-orm/src/sql/functions/aggregate.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/functions/aggregate.ts) - [drizzle-orm/src/sql/functions/vector.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/functions/vector.ts) - [drizzle-orm/src/d1/migrator.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/d1/migrator.ts) - [drizzle-orm/src/durable-sqlite/migrator.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/durable-sqlite/migrator.ts) - [drizzle-orm/src/libsql/migrator.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/migrator.ts)
## Overview The SQL template engine in Drizzle ORM provides a powerful programmatic foundation for constructing typesafe SQL queries, expressions, and database operations through tagged template literals and abstract syntax tree (AST) nodes. It solves the complexity of dynamic query composition by turning nested SQL chunks, parameters, tables, columns, and subqueries into structured trees that compile cleanly into driver-ready queries with proper parameter binding and escaping. Core classes like `SQL`, `StringChunk`, and `Param` manage query structures, while helper functions for conditions, aggregates, and vector operations enable expressive query building across dialects. Sources: [drizzle-orm/src/sql/sql.ts:1-73](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts#L1-L73), [drizzle-orm/src/sql/sql.ts:89-130](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts#L89-L130), [drizzle-orm/src/sql/expressions/conditions.ts:1-35](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/expressions/conditions.ts#L1-L35), [drizzle-orm/src/sql/functions/aggregate.ts:1-21](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/functions/aggregate.ts#L1-L21), [drizzle-orm/src/sql/functions/vector.ts:1-39](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/functions/vector.ts#L1-L39) ## SQL Chunks and AST Structure ### Chunk Union and AST Node Types The core AST representation revolves around the `Chunk` union type and the `SQL` class, which hold fragments, metadata, and nested child nodes. Every part of a compiled query starts as a chunk or a wrapper implementing the `SQLWrapper` interface. The `Chunk` type defines all valid nodes that can be assembled inside an `SQL` statement tree. These include raw string pieces, database tables, views, columns, raw name identifiers, parameters, placeholders, and nested `SQL` instances. ```typescript export type Chunk = | string | Table | View | AnyColumn | Name | Param | Placeholder | SQL; ``` Sources: [drizzle-orm/src/sql/sql.ts:22-30](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts#L22-L30) Any value or schema model implementing the `getSQL()` method satisfies the `SQLWrapper` interface, allowing custom builders and database constructs to integrate directly into query compilation trees. ```typescript export interface SQLWrapper { getSQL(): SQL; shouldOmitSQLParens?(): boolean; } ``` Sources: [drizzle-orm/src/sql/sql.ts:65-68](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts#L65-L68) The table below lists the core AST classes and wrappers, their entity kinds, and their runtime roles during query generation. | Class / Interface | Entity Kind | Role in AST | | :--- | :--- | :--- | | `SQL` | `'SQL'` | Root or nested container holding an array of `SQLChunk` instances, track-used tables, and driver encoders. | | `StringChunk` | `'StringChunk'` | Holds raw literal SQL string arrays that require no escaping or parameterization. | | `SQLWrapper` | N/A (Interface) | Protocol implemented by entities capable of returning an internal `SQL` AST via `getSQL()`. | | `FakePrimitiveParam` | `'FakePrimitiveParam'` | Type-level marker indicating a primitive parameter used in templates; never instantiated at runtime. | Sources: [drizzle-orm/src/sql/sql.ts:18-20](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts#L18-L20), [drizzle-orm/src/sql/sql.ts:89-96](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts#L89-L96), [drizzle-orm/src/sql/sql.ts:103-110](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts#L103-L110) > [!NOTE] > `FakePrimitiveParam` exists strictly at the TypeScript type level to represent primitive parameter values within `sql` template tags, remaining completely uninstantiated during runtime execution. Sources: [drizzle-orm/src/sql/sql.ts:13-17](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts#L13-L17) ### SQL Container and Used Tables Tracking The `SQL` class manages an array of query chunks (`queryChunks: SQLChunk[]`). Upon instantiation, the constructor inspects each chunk; if the chunk is a `Table` instance, it extracts schema prefixes and table names, registering them in the `usedTables` array for reference tracking. ```typescript constructor(readonly queryChunks: SQLChunk[]) { for (const chunk of queryChunks) { if (is(chunk, Table)) { const schemaName = chunk[Table.Symbol.Schema]; this.usedTables.push( schemaName === undefined ? chunk[Table.Symbol.Name] : schemaName + '.' + chunk[Table.Symbol.Name], ); } } } ``` Sources: [drizzle-orm/src/sql/sql.ts:118-130](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts#L118-L130) > [!IMPORTANT] > When compiling subqueries or nested expressions, `SQL` instances propagate their `shouldInlineParams` flag down the tree during recursive query building to override default parameter placeholder behavior. Sources: [drizzle-orm/src/sql/sql.ts:188-193](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts#L188-L193) ## Template Tag and Parameter Binding ### Query Configuration and Typings Values Query building configurations dictate how placeholders, parameters, escape sequences, and casing rules are processed during AST compilation. The `BuildQueryConfig` interface provides the required callbacks and state containers for name escaping, parameter formatting, string literals, casing caches, and index generation contexts. ```typescript export interface BuildQueryConfig { casing: CasingCache; escapeName(name: string): string; escapeParam(num: number, value: unknown): string; escapeString(str: string): string; prepareTyping?: (encoder: DriverValueEncoder) => QueryTypingsValue; paramStartIndex?: { value: number }; inlineParams?: boolean; invokeSource?: 'indexes' | undefined; } ``` Sources: [drizzle-orm/src/sql/sql.ts:32-41](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts#L32-L41) Supported driver typing annotations determine how database parameter values are serialized or cast across driver boundaries. The table below outlines every allowed `QueryTypingsValue` constant recognized by the query compiler. | Query Typing Value | Description / Driver Mapping | | :--- | :--- | | `'json'` | Indicates JSON-encoded columns or payload structures. | | `'decimal'` | Represents arbitrary-precision numeric decimal types. | | `'time'` | Designates time-of-day temporal values. | | `'timestamp'` | Represents combined date and time stamps. | | `'uuid'` | Designates universally unique identifier types. | | `'date'` | Represents calendar date values. | | `'none'` | Default untyped driver parameter binding. | Sources: [drizzle-orm/src/sql/sql.ts:43-43](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts#L43-L43) > [!NOTE] > `FakePrimitiveParam` serves as a type-level marker representing primitive parameters inside template string literals without incurring runtime instantiation overhead. Sources: [drizzle-orm/src/sql/sql.ts:13-17](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts#L13-L17) ### Parameter Binding and Inline Mapping Parameter processing inspects chunks during query building to determine whether values should be bound via driver parameters or serialized directly into the SQL text string. When `inlineParams` is active, or when dealing with unmapped parameters, values are converted via `mapInlineParam`. ```typescript private mapInlineParam( chunk: unknown, { escapeString }: BuildQueryConfig, ): string { if (chunk === null) { return 'null'; } if (typeof chunk === 'number' || typeof chunk === 'boolean') { return chunk.toString(); } if (typeof chunk === 'string') { return escapeString(chunk); } if (typeof chunk === 'object') { const mappedValueAsString = chunk.toString(); if (mappedValueAsString === '[object Object]') { return escapeString(JSON.stringify(chunk)); } return escapeString(mappedValueAsString); } throw new Error('Unexpected param value: ' + chunk); } ``` Sources: [drizzle-orm/src/sql/sql.ts:302-323](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts#L302-L323) > [!WARNING] > Object parameters whose `toString()` representation evaluates to `[object Object]` are automatically serialized via `JSON.stringify` before string escaping when parameter inlining is enabled. Sources: [drizzle-orm/src/sql/sql.ts:315-321](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts#L315-L321) ## Query Resolution and Placeholder Substitution ### Query Building Control Flow The `buildQueryFromSourceParams` method processes arrays of query chunks recursively, dispatching each node type through specialized serialization branches. Telemetry spans wrap query generation via `tracer.startActiveSpan`, emitting query text and parameters to tracing diagnostics. ```typescript toQuery(config: BuildQueryConfig): QueryWithTypings { return tracer.startActiveSpan('drizzle.buildSQL', (span) => { const query = this.buildQueryFromSourceParams(this.queryChunks, config); span?.setAttributes({ 'drizzle.query.text': query.sql, 'drizzle.query.params': JSON.stringify(query.params), }); return query; }); } ``` Sources: [drizzle-orm/src/sql/sql.ts:137-146](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts#L137-L146) > [!IMPORTANT] > When query chunks contain arrays, the compiler automatically parenthesizes the items and joins them with commas, constructing an expanded chunk array before re-invoking `buildQueryFromSourceParams`. Sources: [drizzle-orm/src/sql/sql.ts:176-186](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts#L176-L186) ### Chunk Serialization Handlers Different AST chunk types trigger distinct formatting rules during query generation, handling identifiers, schemas, parameters, and wrapper structures. | Chunk Type | Serialization Behavior | | :--- | :--- | | `StringChunk` | Concatenates literal string segments with empty parameter arrays. | | `Name` | Escapes identifier names using `escapeName`. | | `Table` | Formats schema-qualified table names or bare names when aliased. | | `Column` | Resolves column casing via `casing.getColumnCasing` and prefixes table identifiers unless queried within `indexes`. | | `View` | Formats schema-qualified view identifiers or alias names. | | `Param` | Binds parameters through `escapeParam`, tracking parameter indices and driver encoders. | | `Placeholder` | Generates parameter placeholders using the active `paramStartIndex`. | | `Subquery` | Formats inline subqueries with parentheses and aliases, or referenced CTE names when `isWith` is set. | Sources: [drizzle-orm/src/sql/sql.ts:164-282](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts#L164-L282) > [!NOTE] > If a `Param` chunk contains a nested `SQL` instance after encoder mapping, the compiler unwraps and processes it recursively via `buildQueryFromSourceParams`. Sources: [drizzle-orm/src/sql/sql.ts:238-242](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts#L238-L242) ## Comparison and Logical Expressions ### Parameter Binding and Condition Operators Condition tree constructors leverage template literals and helper functions defined in `drizzle-orm/src/sql/expressions/conditions.ts` to build SQL AST nodes. The `bindIfParam` function inspects values against column encoders, wrapping raw values into `Param` instances when appropriate while leaving columns, tables, views, placeholders, parameters, and SQL wrappers unhindered. ```typescript export function bindIfParam(value: unknown, column: SQLWrapper): SQLChunk { if ( isDriverValueEncoder(column) && !isSQLWrapper(value) && !is(value, Param) && !is(value, Placeholder) && !is(value, Column) && !is(value, Table) && !is(value, View) ) { return new Param(value, column); } return value as SQLChunk; } ``` Sources: [drizzle-orm/src/sql/expressions/conditions.ts:17-30](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/expressions/conditions.ts#L17-L30) Binary operators construct equality, inequality, and directional comparisons using `sql`` template tags combined with `bindIfParam`. | Operator Function | SQL Expression Generated | Description | | :--- | :--- | :--- | | `eq` | `${left} = ${bindIfParam(right, left)}` | Tests equality between two expressions. | | `ne` | `${left} <> ${bindIfParam(right, left)}` | Tests inequality between two expressions. | | `gt` | `${left} > ${bindIfParam(right, left)}` | Tests strictly greater-than. | | `gte` | `${left} >= ${bindIfParam(right, left)}` | Tests greater-than or equal-to. | | `lt` | `${left} < ${bindIfParam(right, left)}` | Tests strictly less-than. | | `lte` | `${left} <= ${bindIfParam(right, left)}` | Tests less-than or equal-to. | Sources: [drizzle-orm/src/sql/expressions/conditions.ts:62-86](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/expressions/conditions.ts#L62-L86), [drizzle-orm/src/sql/expressions/conditions.ts:195-253](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/expressions/conditions.ts#L195-L253) > [!WARNING] > The SQL standard specifies that two `NULL` values are not equal. To check for `NULL` values, developers should use `isNull` instead of `eq(column, null)`. Sources: [drizzle-orm/src/sql/expressions/conditions.ts:46-51](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/expressions/conditions.ts#L46-L51) ### Logical and Array Membership Combinators Logical combinators filter out `undefined` conditions dynamically before assembling expression trees. If an `and` or `or` call receives an empty list of valid conditions, it returns `undefined`. If it receives a single valid condition, it returns that `SQL` instance directly without wrapping parentheses. ```typescript export function and( ...unfilteredConditions: (SQLWrapper | undefined)[] ): SQL | undefined { const conditions = unfilteredConditions.filter( (c): c is Exclude => c !== undefined, ); if (conditions.length === 0) { return undefined; } if (conditions.length === 1) { return new SQL(conditions); } return new SQL([ new StringChunk('('), sql.join(conditions, new StringChunk(' and ')), new StringChunk(')'), ]); } ``` Sources: [drizzle-orm/src/sql/expressions/conditions.ts:105-125](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/expressions/conditions.ts#L105-L125) Negation, array membership, and null checks complete the condition toolkit. The `not` function prefixes any expression with the `not` keyword. Array checks handle empty arrays specially for `notInArray`, returning a literal `true` expression when no values are provided. ```typescript export function notInArray( column: SQLWrapper, values: (unknown | Placeholder)[] | SQLWrapper, ): SQL { if (Array.isArray(values)) { if (values.length === 0) { return sql`true`; } return sql`${column} not in ${values.map((v) => bindIfParam(v, column))}`; } return sql`${column} not in ${bindIfParam(values, column)}`; } ``` Sources: [drizzle-orm/src/sql/expressions/conditions.ts:322-334](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/expressions/conditions.ts#L322-L334) > [!NOTE] > Passing an empty array to `notInArray` evaluates to `true` to preserve valid SQL syntax when filtering dynamically. Sources: [drizzle-orm/src/sql/expressions/conditions.ts:326-329](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/expressions/conditions.ts#L326-L329) ## Dialect Expressions and String Functions ### Dialect Expression Helpers and String Operations Dialect-specific modules provide specialized string manipulation helpers that integrate driver parameter binding with database-native string syntax. Both the Gel and SingleStore core modules export custom `concat` and `substring` functions that accept column references or aliased fields along with string values, placeholders, or wrapped SQL fragments. ```typescript export function concat(column: GelColumn | SQL.Aliased, value: string | Placeholder | SQLWrapper): SQL { return sql`${column} || ${bindIfParam(value, column)}`; } export function substring( column: GelColumn | SQL.Aliased, { from, for: _for }: { from?: number | Placeholder | SQLWrapper; for?: number | Placeholder | SQLWrapper }, ): SQL { const chunks: SQLChunk[] = [sql`substring(`, column]; if (from !== undefined) { chunks.push(sql` from `, bindIfParam(from, column)); } if (_for !== undefined) { chunks.push(sql` for `, bindIfParam(_for, column)); } chunks.push(sql`)`); return sql.join(chunks); } ``` Sources: [drizzle-orm/src/gel-core/expressions.ts:8-25](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/expressions.ts#L8-L25), [drizzle-orm/src/singlestore-core/expressions.ts:8-25](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/expressions.ts#L8-L25) The `concat` helper utilizes the standard concatenation operator (`||`) and passes the right-hand value through `bindIfParam` to ensure proper encoder mapping and driver parameterization. The `substring` helper constructs dynamic chunk lists for extraction queries, conditionally appending `from` and `for` modifiers when defined. > [!NOTE] > Both Gel and SingleStore implement identical signatures and AST assembly logic for `concat` and `substring`, utilizing `sql.join` to merge fragmented expression chunks into valid parameterized statements. Sources: [drizzle-orm/src/gel-core/expressions.ts:8-25](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/expressions.ts#L8-L25), [drizzle-orm/src/singlestore-core/expressions.ts:8-25](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/expressions.ts#L8-L25) ## Aggregate and Vector Functions ### Standard Aggregate Builders Drizzle provides standard aggregate function wrappers constructed via the `sql` template literal. The `count` function accepts an optional `expression` and defaults to `*` via `sql.raw('*')` when omitted, mapping its resulting type to `number`. Distinct variants such as `countDistinct`, `avgDistinct`, and `sumDistinct` prepend the `distinct` keyword inside the expression block. ```typescript export function count(expression?: SQLWrapper): SQL { return sql`count(${expression || sql.raw('*')})`.mapWith(Number); } export function countDistinct(expression: SQLWrapper): SQL { return sql`count(distinct ${expression})`.mapWith(Number); } ``` Sources: [drizzle-orm/src/sql/functions/aggregate.ts:19-37](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/functions/aggregate.ts#L19-L37) The following table summarizes the available aggregate functions, their SQL template structures, and their return type mappings: | Function | Template Expression | Return Type | Source Lines | | :--- | :--- | :--- | :--- | | `count` | `count(${expression \|\| sql.raw('*')})` | `number` | [aggregate.ts:19-21](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/functions/aggregate.ts#L19-L21) | | `countDistinct` | `count(distinct ${expression})` | `number` | [aggregate.ts:35-37](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/functions/aggregate.ts#L35-L37) | | `avg` | `avg(${expression})` | `string \| null` | [aggregate.ts:51-53](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/functions/aggregate.ts#L51-L53) | | `avgDistinct` | `avg(distinct ${expression})` | `string \| null` | [aggregate.ts:67-69](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/functions/aggregate.ts#L67-L69) | | `sum` | `sum(${expression})` | `string \| null` | [aggregate.ts:83-85](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/functions/aggregate.ts#L83-L85) | | `sumDistinct` | `sum(distinct ${expression})` | `string \| null` | [aggregate.ts:99-101](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/functions/aggregate.ts#L99-L101) | | `max` | `max(${expression})` | Column data type or `string \| null` | [aggregate.ts:113-115](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/functions/aggregate.ts#L113-L115) | | `min` | `min(${expression})` | Column data type or `string \| null` | [aggregate.ts:127-129](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/functions/aggregate.ts#L127-L129) | > [!NOTE] > Functions like `max` and `min` dynamically inspect whether the passed expression is an instance of `Column`. If so, they map the result to the column's native data type; otherwise, they fall back to `String`. Sources: [drizzle-orm/src/sql/functions/aggregate.ts:113-115](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/functions/aggregate.ts#L113-L115), [drizzle-orm/src/sql/functions/aggregate.ts:127-129](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/functions/aggregate.ts#L127-L129) ### Vector Distance Operator Abstractions Vector distance operations combine column references or SQL wrappers with distance operators and target values. The internal helper `toSql` serializes array inputs via `JSON.stringify`, while non-array inputs are embedded directly into the template string. ```typescript function toSql(value: number[] | string[]): string { return JSON.stringify(value); } export function l2Distance( column: SQLWrapper | AnyColumn, value: number[] | string[] | TypedQueryBuilder | string, ): SQL { if (Array.isArray(value)) { return sql`${column} <-> ${toSql(value)}`; } return sql`${column} <-> ${value}`; } ``` Sources: [drizzle-orm/src/sql/functions/vector.ts:5-39](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/functions/vector.ts#L5-L39) The vector distance helpers and their corresponding operators are mapped below: | Function Name | Operator | Description | Source Lines | | :--- | :--- | :--- | :--- | | `l2Distance` | `<->` | Euclidean (L2) distance | [vector.ts:31-39](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/functions/vector.ts#L31-L39) | | `l1Distance` | `<+>` | Taxicab (L1) distance | [vector.ts:61-69](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/functions/vector.ts#L61-L69) | | `innerProduct` | `<#>` | Negative inner product | [vector.ts:93-101](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/functions/vector.ts#L93-L101) | | `cosineDistance` | `<=>` | Cosine distance | [vector.ts:125-133](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/functions/vector.ts#L125-L133) | | `hammingDistance` | `<~>` | Hamming distance | [vector.ts:150-158](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/functions/vector.ts#L150-L158) | | `jaccardDistance` | `<%>` | Jaccard distance | [vector.ts:170-178](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/functions/vector.ts#L170-L178) | > [!WARNING] > Passing raw JavaScript arrays to vector distance functions triggers `JSON.stringify` serialization via `toSql`, whereas passing query builders or string expressions embeds them directly into the generated AST without JSON wrapping. Sources: [drizzle-orm/src/sql/functions/vector.ts:5-39](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/functions/vector.ts#L5-L39) ## Related - [Query Builder Foundation](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/query-builder-foundation) - [Table and Column Models](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/table-and-column-models) --- ## Technical docs: Table and Column Models URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/table-and-column-models
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-orm/src/sqlite-core/columns/common.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/columns/common.ts) - [drizzle-kit/src/introspect-pg.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-pg.ts) - [drizzle-orm/type-tests/sqlite/tables.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/sqlite/tables.ts) - [drizzle-orm/src/sqlite-core/table.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/table.ts) - [drizzle-kit/src/introspect-gel.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-gel.ts) - [drizzle-orm/src/column-builder.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/column-builder.ts) - [drizzle-orm/src/pg-core/indexes.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/indexes.ts) - [drizzle-kit/src/introspect-singlestore.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-singlestore.ts) - [drizzle-kit/src/introspect-mysql.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-mysql.ts) - [drizzle-kit/src/sqlgenerator.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/sqlgenerator.ts) - [drizzle-orm/src/gel-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/dialect.ts) - [drizzle-orm/src/sqlite-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/dialect.ts) - [drizzle-orm/src/singlestore-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/dialect.ts) - [drizzle-orm/src/gel-core/columns/common.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/columns/common.ts) - [drizzle-orm/src/sqlite-core/primary-keys.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/primary-keys.ts) - [drizzle-orm/src/table.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/table.ts) - [drizzle-orm/src/gel-core/indexes.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/indexes.ts) - [drizzle-orm/src/pg-core/columns/common.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/columns/common.ts) - [drizzle-kit/src/introspect-sqlite.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-sqlite.ts) - [drizzle-orm/src/sqlite-core/indexes.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/indexes.ts) - [drizzle-orm/src/pg-core/table.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/table.ts) - [drizzle-orm/src/mysql-core/columns/common.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/columns/common.ts) - [drizzle-orm/src/alias.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/alias.ts) - [drizzle-orm/src/sqlite-core/db.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/db.ts) - [drizzle-orm/src/sqlite-core/columns/integer.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/columns/integer.ts) - [drizzle-orm/src/mysql-core/table.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/table.ts) - [drizzle-orm/src/gel-core/table.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/table.ts) - [drizzle-orm/src/sqlite-core/foreign-keys.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/foreign-keys.ts) - [drizzle-orm/src/mysql-core/indexes.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/indexes.ts) - [drizzle-orm/src/sqlite-core/utils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/utils.ts)
## Overview Table and Column Models supply the core structural foundation for defining database entities, column definitions, and schema metadata across all supported dialects. They provide the base abstractions and symbol branding needed to construct typed tables, configure column builders, establish foreign keys, and map driver values. Sources: [drizzle-orm/src/table.ts:42-118](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/table.ts#L42-L118) By combining declarative TypeScript types with runtime column transformers and table proxy handlers, this system bridges high-level schema definitions with low-level SQL query generation and relational query execution. Sources: [drizzle-orm/src/alias.ts:10-75](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/alias.ts#L10-L75), [drizzle-orm/src/column-builder.ts:11-26](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/column-builder.ts#L11-L26) ## Core Table Architecture and Invariants ### Base Table Class and Symbol Branding The `Table` class serves as the root abstraction for all schema entities, implementing `SQLWrapper` and carrying static metadata alongside internal symbol properties. Each table instance is branded at runtime using `IsDrizzleTable` and maintains configuration traits through TypeScript mapped types (`TableConfig`, `InferSelectModel`, and `InferInsertModel`). Internal state tracking relies on a set of exported symbols located on `Table.Symbol`. These symbols isolate metadata properties from user-defined column names, preserving clean namespace separation for table names, schemas, and alias mapping flags. ```typescript export class Table implements SQLWrapper { static readonly [entityKind]: string = 'Table'; declare readonly _: { readonly brand: 'Table'; readonly config: T; readonly name: T['name']; readonly schema: T['schema']; readonly columns: T['columns']; readonly inferSelect: InferSelectModel>; readonly inferInsert: InferInsertModel>; }; ... ``` Sources: [drizzle-orm/src/table.ts:42-60](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/table.ts#L42-L60) | Symbol Name | Runtime Symbol Key | Purpose | | :--- | :--- | :--- | | `Name` | `drizzle:TableName` | Stores the active table name (modifiable during aliasing). | | `Schema` | `drizzle:Schema` | Stores the optional database schema identifier. | | `OriginalName` | `drizzle:OriginalName` | Preserves the initial unaliased table name. | | `Columns` | `drizzle:Columns` | Holds the record mapping column keys to column definitions. | | `ExtraConfigColumns` | `drizzle:ExtraConfigColumns` | Stores extra configuration columns during table building. | | `BaseName` | `drizzle:BaseName` | Preserves the pre-transformation name before `tableCreator` hooks. | | `IsAlias` | `drizzle:IsAlias` | Boolean flag indicating whether the table instance is an alias. | | `ExtraConfigBuilder` | `drizzle:ExtraConfigBuilder` | Callback reference for evaluating extra table constraints and indexes. | Sources: [drizzle-orm/src/table.ts:20-40](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/table.ts#L20-L40), [drizzle-orm/src/table.ts:65-112](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/table.ts#L65-L112) > [!NOTE] > The `isTable` runtime check validates table instances exclusively by inspecting whether `IsDrizzleTable` exists on the target object, ensuring fast identification without relying on `instanceof` checks that can fail across module boundary versions. > > Sources: [drizzle-orm/src/table.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/table.ts#L120-L122) ### Entity Metadata and Relational Inference Tables expose inference utilities (`$inferSelect` and `$inferInsert`) that evaluate column definitions to construct strict TypeScript models. The `InferModelFromColumns` type maps column configurations, handling database column name remapping when `dbColumnNames` is enabled and distinguishing required versus optional insert keys using column operation markers (`RequiredKeyOnly` and `OptionalKeyOnly`). ```typescript export type InferModelFromColumns< TColumns extends Record, TInferMode extends 'select' | 'insert' = 'select', TConfig extends { dbColumnNames: boolean; override?: boolean } = { dbColumnNames: false; override: false }, > = Simplify< TInferMode extends 'insert' ? & { [ Key in keyof TColumns & string as RequiredKeyOnly< MapColumnName, TColumns[Key] > ]: GetColumnData; } & { [ Key in keyof TColumns & string as OptionalKeyOnly< MapColumnName, TColumns[Key], TConfig['override'] > ]?: GetColumnData | undefined; } : { [ Key in keyof TColumns & string as MapColumnName< Key, TColumns[Key], TConfig['dbColumnNames'] > ]: GetColumnData; } >; ``` Sources: [drizzle-orm/src/table.ts:155-187](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/table.ts#L155-L187) Functions such as `getTableName` and `getTableUniqueName` extract structural metadata directly from table symbols, providing fully qualified namespace strings (`schema.tablename`) for query builders and the [relational query engine](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/relational-query-engine). ```typescript export function getTableName(table: T): T['_']['name'] { return table[TableName]; } export function getTableUniqueName(table: T): `${T['_']['schema']}.${T['_']['name']}` { return `${table[Schema] ?? 'public'}.${table[TableName]}`; } ``` Sources: [drizzle-orm/src/table.ts:143-149](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/table.ts#L143-L149) ## Column Builder Lifecycle and Configuration ### Configuration Contracts and Type Mapping Column builders manage the definition and serialization attributes of database columns before they are materialized into table columns. The core configuration contract relies on `ColumnBuilderBaseConfig`, which enforces properties such as column name, data type, column type, driver parameters, and enumerated values. The `MakeColumnConfig` utility type processes these base configurations to determine nullability, default presence, primary key status, autoincrement flags, and generated identity configurations across table columns. ```typescript export interface ColumnBuilderBaseConfig { name: string; dataType: TDataType; columnType: TColumnType; data: unknown; driverParam: unknown; enumValues: string[] | undefined; } export type MakeColumnConfig< T extends ColumnBuilderBaseConfig, TTableName extends string, TData = T extends { $type: infer U } ? U : T['data'], > = { name: T['name']; tableName: TTableName; dataType: T['dataType']; columnType: T['columnType']; data: TData; driverParam: T['driverParam']; notNull: T extends { notNull: true } ? true : false; hasDefault: T extends { hasDefault: true } ? true : false; isPrimaryKey: T extends { isPrimaryKey: true } ? true : false; isAutoincrement: T extends { isAutoincrement: true } ? true : false; hasRuntimeDefault: T extends { hasRuntimeDefault: true } ? true : false; enumValues: T['enumValues']; baseColumn: T extends { baseBuilder: infer U extends ColumnBuilderBase } ? BuildColumn : never; identity: T extends { identity: 'always' } ? 'always' : T extends { identity: 'byDefault' } ? 'byDefault' : undefined; generated: T extends { generated: infer G } ? unknown extends G ? undefined : G extends undefined ? undefined : G : undefined; } & {}; ``` Sources: [drizzle-orm/src/column-builder.ts:46-79](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/column-builder.ts#L46-L79) Supported primitive data types span string, number, boolean, array, json, date, bigint, custom, buffer, dateDuration, duration, relDuration, localTime, localDate, and localDateTime. Dialect targets are explicitly restricted to pg, mysql, sqlite, singlestore, common, and gel. ```typescript export type ColumnDataType = | 'string' | 'number' | 'boolean' | 'array' | 'json' | 'date' | 'bigint' | 'custom' | 'buffer' | 'dateDuration' | 'duration' | 'relDuration' | 'localTime' | 'localDate' | 'localDateTime'; export type Dialect = 'pg' | 'mysql' | 'sqlite' | 'singlestore' | 'common' | 'gel'; ``` Sources: [drizzle-orm/src/column-builder.ts:11-28](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/column-builder.ts#L11-L28) > [!NOTE] > `ColumnBuilderRuntimeConfig` stores active runtime flags such as `keyAsName`, `notNull`, `hasDefault`, `default`, `defaultFn`, and `onUpdateFn` to evaluate column behaviors during schema building and statement generation. > > Sources: [drizzle-orm/src/column-builder.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/column-builder.ts#L102-L109) ### SQLite Integer, Timestamp, and Boolean Builders SQLite columns demonstrate specialized builder lifecycles and driver value transformations through `SQLiteBaseIntegerBuilder` and its concrete extensions. The `integer` factory function parses optional names and configurations, branching to construct `SQLiteIntegerBuilder`, `SQLiteTimestampBuilder`, or `SQLiteBooleanBuilder` depending on the selected mode. ```typescript export interface IntegerConfig< TMode extends 'number' | 'timestamp' | 'timestamp_ms' | 'boolean' = | 'number' | 'timestamp' | 'timestamp_ms' | 'boolean', > { mode: TMode; } export function integer(): SQLiteIntegerBuilderInitial<''>; export function integer( config?: IntegerConfig, ): Or, Equal> extends true ? SQLiteTimestampBuilderInitial<''> : Equal extends true ? SQLiteBooleanBuilderInitial<''> : SQLiteIntegerBuilderInitial<''>; export function integer( name: TName, config?: IntegerConfig, ): Or, Equal> extends true ? SQLiteTimestampBuilderInitial : Equal extends true ? SQLiteBooleanBuilderInitial : SQLiteIntegerBuilderInitial; export function integer(a?: string | IntegerConfig, b?: IntegerConfig) { const { name, config } = getColumnNameAndConfig(a, b); if (config?.mode === 'timestamp' || config?.mode === 'timestamp_ms') { return new SQLiteTimestampBuilder(name, config.mode); } if (config?.mode === 'boolean') { return new SQLiteBooleanBuilder(name, config.mode); } return new SQLiteIntegerBuilder(name); } export const int = integer; ``` Sources: [drizzle-orm/src/sqlite-core/columns/integer.ts:204-237](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/columns/integer.ts#L204-L237) | Column Type | Mode Parameter | Driver Parameter Type | Mapped JavaScript Type | Driver Mapping Logic | | :--- | :--- | :--- | :--- | :--- | | `SQLiteInteger` | `number` (default) | `number` | `number` | Direct integer storage. | | `SQLiteTimestamp` | `timestamp` | `number` | `Date` | Multiplies or divides by `1000` for epoch seconds. | | `SQLiteTimestamp` | `timestamp_ms` | `number` | `Date` | Preserves millisecond epoch numbers directly. | | `SQLiteBoolean` | `boolean` | `number` | `boolean` | Translates integer `1` and `0` to boolean values. | Sources: [drizzle-orm/src/sqlite-core/columns/integer.ts:66-202](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/columns/integer.ts#L66-L202) ```mermaid flowchart TD A["integer(name, config)"] --> B{config?.mode} B -->|timestamp / timestamp_ms| C["SQLiteTimestampBuilder"] B -->|boolean| D["SQLiteBooleanBuilder"] B -->|undefined / number| E["SQLiteIntegerBuilder"] C --> F["SQLiteTimestamp.mapFromDriverValue / mapToDriverValue"] D --> G["SQLiteBoolean.mapFromDriverValue / mapToDriverValue"] E --> H["SQLiteInteger"] ``` Sources: [drizzle-orm/src/sqlite-core/columns/integer.ts:143-202](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/columns/integer.ts#L143-L202), [drizzle-orm/src/sqlite-core/columns/integer.ts:228-235](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/columns/integer.ts#L228-L235) > [!CAUTION] > Calling `defaultNow()` on a `SQLiteTimestampBuilder` is deprecated; column defaults should be assigned using `.default()` with custom SQL expressions instead. > > Sources: [drizzle-orm/src/sqlite-core/columns/integer.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/columns/integer.ts#L117-L124) ## Dialect Table Instantiation and Normalization ### Table Creation Functions and Schemas Table instantiation across database engines relies on dialect-specific table classes that extend the core `Table` abstraction while managing engine-specific symbols and configuration types. The `SQLiteTable` class defines `InlineForeignKeys` symbol branding to track foreign keys declared within column definitions SQLiteTable: ```typescript export const InlineForeignKeys = Symbol.for('drizzle:SQLiteInlineForeignKeys'); export class SQLiteTable extends Table { static override readonly [entityKind]: string = 'SQLiteTable'; /** @internal */ static override readonly Symbol = Object.assign({}, Table.Symbol, { InlineForeignKeys: InlineForeignKeys as typeof InlineForeignKeys, }); /** @internal */ override [Table.Symbol.Columns]!: NonNullable; /** @internal */ [InlineForeignKeys]: ForeignKey[] = []; /** @internal */ override [Table.Symbol.ExtraConfigBuilder]: | ((self: Record) => SQLiteTableExtraConfig) | undefined = undefined; } ``` Sources: [drizzle-orm/src/sqlite-core/table.ts:27-47](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/table.ts#L27-L47) Similarly, `PgTable` in PostgreSQL and `GelTable` in Gel introduce both `InlineForeignKeys` and `EnableRLS` symbols to support row-level security policy toggles and inline constraints PgTable, GelTable: ```typescript /** @internal */ export const InlineForeignKeys = Symbol.for('drizzle:PgInlineForeignKeys'); /** @internal */ export const EnableRLS = Symbol.for('drizzle:EnableRLS'); export class PgTable extends Table { static override readonly [entityKind]: string = 'PgTable'; /** @internal */ static override readonly Symbol = Object.assign({}, Table.Symbol, { InlineForeignKeys: InlineForeignKeys as typeof InlineForeignKeys, EnableRLS: EnableRLS as typeof EnableRLS, }); /**@internal */ [InlineForeignKeys]: ForeignKey[] = []; /** @internal */ [EnableRLS]: boolean = false; /** @internal */ override [Table.Symbol.ExtraConfigBuilder]: ((self: Record) => PgTableExtraConfig) | undefined = undefined; /** @internal */ override [Table.Symbol.ExtraConfigColumns]: Record = {}; } ``` Sources: [drizzle-orm/src/pg-core/table.ts:28-54](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/table.ts#L28-L54) ```typescript /** @internal */ export const InlineForeignKeys = Symbol.for('drizzle:GelInlineForeignKeys'); /** @internal */ export const EnableRLS = Symbol.for('drizzle:EnableRLS'); export class GelTable extends Table { static override readonly [entityKind]: string = 'GelTable'; /** @internal */ static override readonly Symbol = Object.assign({}, Table.Symbol, { InlineForeignKeys: InlineForeignKeys as typeof InlineForeignKeys, EnableRLS: EnableRLS as typeof EnableRLS, }); /**@internal */ [InlineForeignKeys]: ForeignKey[] = []; /** @internal */ [EnableRLS]: boolean = false; /** @internal */ override [Table.Symbol.ExtraConfigBuilder]: ((self: Record) => GelTableExtraConfig) | undefined = undefined; /** @internal */ override [Table.Symbol.ExtraConfigColumns]: Record = {}; } ``` Sources: [drizzle-orm/src/gel-core/table.ts:28-54](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/table.ts#L28-L54) `MySqlTable` implements equivalent symbol tracking for MySQL environments MySqlTable: ```typescript /** @internal */ export const InlineForeignKeys = Symbol.for('drizzle:MySqlInlineForeignKeys'); export class MySqlTable extends Table { static override readonly [entityKind]: string = 'MySqlTable'; declare protected $columns: T['columns']; /** @internal */ static override readonly Symbol = Object.assign({}, Table.Symbol, { InlineForeignKeys: InlineForeignKeys as typeof InlineForeignKeys, }); /** @internal */ override [Table.Symbol.Columns]!: NonNullable; /** @internal */ [InlineForeignKeys]: ForeignKey[] = []; /** @internal */ override [Table.Symbol.ExtraConfigBuilder]: | ((self: Record) => MySqlTableExtraConfig) | undefined = undefined; } ``` Sources: [drizzle-orm/src/mysql-core/table.ts:26-49](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/table.ts#L26-L49) ### Column Builder Parsing and Normalization During table construction, column definitions can be provided either as a static record map or via a callback function receiving engine-specific column builders (`SQLiteColumnBuilders`, `PgColumnsBuilders`, `MySqlColumnBuilders`, or `GelColumnsBuilders`). The normalization routine resolves these definitions, sets column names, and instantiates the underlying column objects pgTableWithSchema, mysqlTableWithSchema, gelTableWithSchema: ```typescript export function pgTableWithSchema< TTableName extends string, TSchemaName extends string | undefined, TColumnsMap extends Record, >( name: TTableName, columns: TColumnsMap | ((columnTypes: PgColumnsBuilders) => TColumnsMap), extraConfig: | ((self: BuildExtraConfigColumns) => PgTableExtraConfig | PgTableExtraConfigValue[]) | undefined, schema: TSchemaName, baseName = name, ): PgTableWithColumns<{ name: TTableName; schema: TSchemaName; columns: BuildColumns; dialect: 'pg'; }> { const rawTable = new PgTable<{ name: TTableName; schema: TSchemaName; columns: BuildColumns; dialect: 'pg'; }>(name, schema, baseName); const parsedColumns: TColumnsMap = typeof columns === 'function' ? columns(getPgColumnBuilders()) : columns; const builtColumns = Object.fromEntries( Object.entries(parsedColumns).map(([name, colBuilderBase]) => { const colBuilder = colBuilderBase as PgColumnBuilder; colBuilder.setName(name); const column = colBuilder.build(rawTable); rawTable[InlineForeignKeys].push(...colBuilder.buildForeignKeys(column, rawTable)); return [name, column]; }), ) as unknown as BuildColumns; const builtColumnsForExtraConfig = Object.fromEntries( Object.entries(parsedColumns).map(([name, colBuilderBase]) => { const colBuilder = colBuilderBase as PgColumnBuilder; colBuilder.setName(name); const column = colBuilder.buildExtraConfigColumn(rawTable); return [name, column]; }), ) as unknown as BuildExtraConfigColumns; const table = Object.assign(rawTable, builtColumns); table[Table.Symbol.Columns] = builtColumns; table[Table.Symbol.ExtraConfigColumns] = builtColumnsForExtraConfig; if (extraConfig) { table[PgTable.Symbol.ExtraConfigBuilder] = extraConfig as any; } return Object.assign(table, { enableRLS: () => { table[PgTable.Symbol.EnableRLS] = true; return table as PgTableWithColumns<{ name: TTableName; schema: TSchemaName; columns: BuildColumns; dialect: 'pg'; }>; }, }); } ``` Sources: [drizzle-orm/src/pg-core/table.ts:71-137](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/table.ts#L71-L137) ```typescript export function mysqlTableWithSchema< TTableName extends string, TSchemaName extends string | undefined, TColumnsMap extends Record, >( name: TTableName, columns: TColumnsMap | ((columnTypes: MySqlColumnBuilders) => TColumnsMap), extraConfig: | (( self: BuildColumns, ) => MySqlTableExtraConfig | MySqlTableExtraConfigValue[]) | undefined, schema: TSchemaName, baseName = name, ): MySqlTableWithColumns<{ name: TTableName; schema: TSchemaName; columns: BuildColumns; dialect: 'mysql'; }> { const rawTable = new MySqlTable<{ name: TTableName; schema: TSchemaName; columns: BuildColumns; dialect: 'mysql'; }>(name, schema, baseName); const parsedColumns: TColumnsMap = typeof columns === 'function' ? columns(getMySqlColumnBuilders()) : columns; const builtColumns = Object.fromEntries( Object.entries(parsedColumns).map(([name, colBuilderBase]) => { const colBuilder = colBuilderBase as MySqlColumnBuilder; colBuilder.setName(name); const column = colBuilder.build(rawTable); rawTable[InlineForeignKeys].push(...colBuilder.buildForeignKeys(column, rawTable)); return [name, column]; }), ) as unknown as BuildColumns; const table = Object.assign(rawTable, builtColumns); table[Table.Symbol.Columns] = builtColumns; table[Table.Symbol.ExtraConfigColumns] = builtColumns as unknown as BuildExtraConfigColumns< TTableName, TColumnsMap, 'mysql' >; if (extraConfig) { table[MySqlTable.Symbol.ExtraConfigBuilder] = extraConfig as unknown as ( self: Record, ) => MySqlTableExtraConfig; } return table; } ``` Sources: [drizzle-orm/src/mysql-core/table.ts:61-116](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/table.ts#L61-L116) ```typescript export function gelTableWithSchema< TTableName extends string, TSchemaName extends string | undefined, TColumnsMap extends Record, >( name: TTableName, columns: TColumnsMap | ((columnTypes: GelColumnsBuilders) => TColumnsMap), extraConfig: | (( self: BuildExtraConfigColumns, ) => GelTableExtraConfig | GelTableExtraConfigValue[]) | undefined, schema: TSchemaName, baseName = name, ): GelTableWithColumns<{ name: TTableName; schema: TSchemaName; columns: BuildColumns; dialect: 'gel'; }> { const rawTable = new GelTable<{ name: TTableName; schema: TSchemaName; columns: BuildColumns; dialect: 'gel'; }>(name, schema, baseName); const parsedColumns: TColumnsMap = typeof columns === 'function' ? columns(getGelColumnBuilders()) : columns; const builtColumns = Object.fromEntries( Object.entries(parsedColumns).map(([name, colBuilderBase]) => { const colBuilder = colBuilderBase as GelColumnBuilder; colBuilder.setName(name); const column = colBuilder.build(rawTable); rawTable[InlineForeignKeys].push(...colBuilder.buildForeignKeys(column, rawTable)); return [name, column]; }), ) as unknown as BuildColumns; const builtColumnsForExtraConfig = Object.fromEntries( Object.entries(parsedColumns).map(([name, colBuilderBase]) => { const colBuilder = colBuilderBase as GelColumnBuilder; colBuilder.setName(name); const column = colBuilder.buildExtraConfigColumn(rawTable); return [name, column]; }), ) as unknown as BuildExtraConfigColumns; const table = Object.assign(rawTable, builtColumns); table[Table.Symbol.Columns] = builtColumns; table[Table.Symbol.ExtraConfigColumns] = builtColumnsForExtraConfig; if (extraConfig) { table[GelTable.Symbol.ExtraConfigBuilder] = extraConfig as any; } return Object.assign(table, { enableRLS: () => { table[GelTable.Symbol.EnableRLS] = true; return table as GelTableWithColumns<{ name: TTableName; schema: TSchemaName; columns: BuildColumns; dialect: 'gel'; }>; }, }); } ``` Sources: [drizzle-orm/src/gel-core/table.ts:73-141](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/table.ts#L73-L141) > [!NOTE] > PostgreSQL and Gel table factories build both standard columns and extra config columns (`buildExtraConfigColumn`), enabling table-level constraints to reference column metadata prior to schema serialization. > > Sources: [drizzle-orm/src/pg-core/table.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/table.ts#L98-L120), [drizzle-orm/src/gel-core/table.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/table.ts#L102-L124) > [!WARNING] > Passing an object instead of an array as the third parameter (`extraConfig`) to table builder functions is deprecated and will be removed in future releases across SQLite, MySQL, and Gel. > > Sources: [drizzle-orm/src/sqlite-core/table.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/table.ts#L89-L110), [drizzle-orm/src/mysql-core/table.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/table.ts#L148-L169), [drizzle-orm/src/gel-core/table.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/table.ts#L143-L165) ## Table Proxies and Alias Remapping ### Proxy Handlers and Identifier Aliasing Table and column aliasing leverage JavaScript `Proxy` objects to intercept property access, symbol evaluation, and schema traversal across query builders and dialect runtimes. The `TableAliasProxyHandler` intercepts core table symbols such as `Table.Symbol.IsAlias`, `Table.Symbol.Name`, and `Table.Symbol.OriginalName` to substitute alias strings while mapping column property accesses through `ColumnAliasProxyHandler` drizzle-orm/src/alias.ts. ```typescript export class TableAliasProxyHandler implements ProxyHandler { static readonly [entityKind]: string = 'TableAliasProxyHandler'; constructor(private alias: string, private replaceOriginalName: boolean) {} get(target: T, prop: string | symbol): any { if (prop === Table.Symbol.IsAlias) { return true; } if (prop === Table.Symbol.Name) { return this.alias; } if (this.replaceOriginalName && prop === Table.Symbol.OriginalName) { return this.alias; } if (prop === ViewBaseConfig) { return { ...target[ViewBaseConfig as keyof typeof target], name: this.alias, isAlias: true, }; } if (prop === Table.Symbol.Columns) { const columns = (target as Table)[Table.Symbol.Columns]; if (!columns) { return columns; } const proxiedColumns: { [key: string]: any } = {}; Object.keys(columns).map((key) => { proxiedColumns[key] = new Proxy( columns[key]!, new ColumnAliasProxyHandler(new Proxy(target, this)), ); }); return proxiedColumns; } const value = target[prop as keyof typeof target]; if (is(value, Column)) { return new Proxy(value as AnyColumn, new ColumnAliasProxyHandler(new Proxy(target, this))); } return value; } } ``` Sources: [drizzle-orm/src/alias.ts:24-75](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/alias.ts#L24-L75) The proxy mechanism ensures that references to columns or nested relations inherit the modified table context without mutating the underlying schema definitions. Dialect query builders such as SQLiteDialect incorporate these proxy utilities to handle self-joins, derived tables, and subquery projections drizzle-orm/src/sqlite-core/dialect.ts, drizzle-orm/src/singlestore-core/dialect.ts. ```typescript export function aliasedTable( table: T, tableAlias: string, ): T { return new Proxy(table, new TableAliasProxyHandler(tableAlias, false)) as any; } export function aliasedRelation(relation: T, tableAlias: string): T { return new Proxy(relation, new RelationTableAliasProxyHandler(tableAlias)); } export function aliasedTableColumn(column: T, tableAlias: string): T { return new Proxy( column, new ColumnAliasProxyHandler(new Proxy(column.table, new TableAliasProxyHandler(tableAlias, false))), ); } ``` Sources: [drizzle-orm/src/alias.ts:91-108](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/alias.ts#L91-L108) > [!NOTE] > `TableAliasProxyHandler` conditionally overrides `Table.Symbol.OriginalName` based on the boolean flag `replaceOriginalName`, allowing subqueries to retain or overwrite their underlying table identifier during compilation. > > Sources: [drizzle-orm/src/alias.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/alias.ts#L27-L40) ### SQL Expression Rewrites When queries contain nested expressions, subqueries, or aliased chunks, column references within the AST must be recursively updated to match the active table alias. The `mapColumnsInSQLToAlias` function inspects query chunks and wraps columns and subqueries with the designated alias proxy drizzle-orm/src/alias.ts. ```typescript export function mapColumnsInSQLToAlias(query: SQL, alias: string): SQL { return sql.join(query.queryChunks.map((c) => { if (is(c, Column)) { return aliasedTableColumn(c, alias); } if (is(c, SQL)) { return mapColumnsInSQLToAlias(c, alias); } if (is(c, SQL.Aliased)) { return mapColumnsInAliasedSQLToAlias(c, alias); } return c; })); } ``` Sources: [drizzle-orm/src/alias.ts:113-126](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/alias.ts#L113-L126) | Proxy Handler | Target Entity | Intercepted Symbols / Properties | Purpose | | --- | --- | --- | --- | | `ColumnAliasProxyHandler` | `Column` | `'table'` | Binds column references to the aliased table or view container. | | `TableAliasProxyHandler` | `Table` \| `View` | `IsAlias`, `Name`, `OriginalName`, `Columns`, `ViewBaseConfig` | Remaps table identifiers, flags, and column maps to use alias names. | | `RelationTableAliasProxyHandler` | `Relation` | `'sourceTable'` | Recursively proxies relation source tables for relational graph queries. | Sources: [drizzle-orm/src/alias.ts:10-89](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/alias.ts#L10-L89) ## Constraint Resolution and Schema Utilities ### Runtime Table Configuration and Entity Inspection Table configurations, schema constraints, and builder metadata are inspected and resolved at runtime via utility functions like `getTableConfig`. For SQLite tables, this function iterates over column definitions, inline foreign keys, and extra configuration builders, instantiating and categorizing indexes, checks, unique constraints, primary keys, and foreign keys into a unified configuration object drizzle-orm/src/sqlite-core/utils.ts. ```typescript export function getTableConfig(table: TTable) { const columns = Object.values(table[SQLiteTable.Symbol.Columns]); const indexes: Index[] = []; const checks: Check[] = []; const primaryKeys: PrimaryKey[] = []; const uniqueConstraints: UniqueConstraint[] = []; const foreignKeys: ForeignKey[] = Object.values(table[SQLiteTable.Symbol.InlineForeignKeys]); const name = table[Table.Symbol.Name]; const extraConfigBuilder = table[SQLiteTable.Symbol.ExtraConfigBuilder]; if (extraConfigBuilder !== undefined) { const extraConfig = extraConfigBuilder(table[SQLiteTable.Symbol.Columns]); const extraValues = Array.isArray(extraConfig) ? extraConfig.flat(1) as any[] : Object.values(extraConfig); for (const builder of Object.values(extraValues)) { if (is(builder, IndexBuilder)) { indexes.push(builder.build(table)); } else if (is(builder, CheckBuilder)) { checks.push(builder.build(table)); } else if (is(builder, UniqueConstraintBuilder)) { uniqueConstraints.push(builder.build(table)); } else if (is(builder, PrimaryKeyBuilder)) { primaryKeys.push(builder.build(table)); } else if (is(builder, ForeignKeyBuilder)) { foreignKeys.push(builder.build(table)); } } } return { columns, indexes, foreignKeys, checks, primaryKeys, uniqueConstraints, name, }; } ``` Sources: [drizzle-orm/src/sqlite-core/utils.ts:19-57](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/utils.ts#L19-L57) Entity resolution checks use type guards to differentiate builder instances such as `IndexBuilder`, `CheckBuilder`, `UniqueConstraintBuilder`, `PrimaryKeyBuilder`, and `ForeignKeyBuilder`, ensuring each constraint is correctly built against the target table instance prior to AST compilation drizzle-orm/src/sqlite-core/utils.ts. ```typescript for (const builder of Object.values(extraValues)) { if (is(builder, IndexBuilder)) { indexes.push(builder.build(table)); } else if (is(builder, CheckBuilder)) { checks.push(builder.build(table)); } else if (is(builder, UniqueConstraintBuilder)) { uniqueConstraints.push(builder.build(table)); } else if (is(builder, PrimaryKeyBuilder)) { primaryKeys.push(builder.build(table)); } else if (is(builder, ForeignKeyBuilder)) { foreignKeys.push(builder.build(table)); } } ``` Sources: [drizzle-orm/src/sqlite-core/utils.ts:33-45](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/utils.ts#L33-L45) > [!NOTE] > `extractUsedTable` evaluates table inputs across `SQLiteTable`, `Subquery`, `SQLiteViewBase`, and `SQL` expression instances to resolve base table names and used table arrays during AST traversal. > > Sources: [drizzle-orm/src/sqlite-core/utils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/utils.ts#L59-L70) ### Index Builders and Dialect-Specific Options Index configuration differs across dialects to accommodate specialized storage parameters, concurrency flags, and locking algorithms. PostgreSQL index builders support partial index conditions via `where`, storage options via `with`, access methods, and concurrency modifiers via `concurrently` and `only` drizzle-orm/src/pg-core/indexes.ts. ```typescript interface IndexConfig { name?: string; columns: Partial[]; /** * If true, the index will be created as `create unique index` instead of `create index`. */ unique: boolean; /** * If true, the index will be created as `create index concurrently` instead of `create index`. */ concurrently?: boolean; /** * If true, the index will be created as `create index ... on only ` instead of `create index ... on
`. */ only: boolean; /** * Condition for partial index. */ where?: SQL; /** * The optional WITH clause specifies storage parameters for the index */ with?: Record; /** * The optional WITH clause method for the index */ method?: 'btree' | string; } ``` Sources: [drizzle-orm/src/pg-core/indexes.ts:8-42](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/indexes.ts#L8-L42) MySQL index builders manage index construction algorithms and locks directly within their configuration contracts drizzle-orm/src/mysql-core/indexes.ts. ```typescript interface IndexConfig { name: string; columns: IndexColumn[]; /** * If true, the index will be created as `create unique index` instead of `create index`. */ unique?: boolean; /** * If set, the index will be created as `create index ... using { 'btree' | 'hash' }`. */ using?: 'btree' | 'hash'; /** * If set, the index will be created as `create index ... algorithm { 'default' | 'inplace' | 'copy' }`. */ algorithm?: 'default' | 'inplace' | 'copy'; /** * If set, adds locks to the index creation. */ lock?: 'default' | 'none' | 'shared' | 'exclusive'; } ``` Sources: [drizzle-orm/src/mysql-core/indexes.ts:6-30](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/indexes.ts#L6-L30) | Index Configuration Property | Dialects Supported | Purpose / Values | | --- | --- | --- | | `name` | PostgreSQL, MySQL | Optional or required string identifier for the index. | | `columns` | PostgreSQL, MySQL | Array of indexed columns or raw `SQL` expressions. | | `unique` | PostgreSQL, MySQL | Boolean flag creating a unique index. | | `concurrently` | PostgreSQL | Creates the index without locking concurrent writes (`create index concurrently`). | | `only` | PostgreSQL | Restricts index creation to the specified table without inheritance children. | | `where` | PostgreSQL | Defines a partial index condition using a `SQL` expression. | | `method` | PostgreSQL, MySQL | Index access method (e.g., `'btree'`, `'hash'`, `'gist'`, `'gin'`, `'brin'`, `'hnsw'`, `'ivfflat'`). | | `algorithm` | MySQL | Specifies index creation algorithm: `'default'`, `'inplace'`, `'copy'`. | | `lock` | MySQL | Adds concurrency locks during index creation: `'default'`, `'none'`, `'shared'`, `'exclusive'`. | Sources: [drizzle-orm/src/pg-core/indexes.ts:8-42](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/indexes.ts#L8-L42), [drizzle-orm/src/mysql-core/indexes.ts:6-30](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/indexes.ts#L6-L30) ## Related - [Dialects And Schema Schema Definition](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/dialects-and-schema/dialects-and-schema-schema-definition) - [Relational Query Engine](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/relational-query-engine) --- ## Technical docs: Column Types URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/database-schema/column-types
Relevant source files The following files were used as context for generating this wiki page: * [drizzle-kit/src/introspect-mysql.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-kit/src/introspect-mysql.ts) * [drizzle-kit/src/introspect-gel.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-kit/src/introspect-gel.ts) * [drizzle-kit/src/introspect-singlestore.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-kit/src/introspect-singlestore.ts) * [drizzle-orm/src/pg-core/columns/common.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/pg-core/columns/common.ts) * [drizzle-orm/src/pg-core/columns/numeric.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/pg-core/columns/numeric.ts) * [drizzle-orm/src/singlestore-core/columns/decimal.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/singlestore-core/columns/decimal.ts) * [drizzle-orm/src/column-builder.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/column-builder.ts) * [drizzle-orm/src/sqlite-core/columns/numeric.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/sqlite-core/columns/numeric.ts) * [drizzle-orm/src/sqlite-core/columns/blob.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/sqlite-core/columns/blob.ts) * [drizzle-orm/src/sqlite-core/columns/integer.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/sqlite-core/columns/integer.ts) * [drizzle-orm/src/singlestore-core/columns/datetime.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/singlestore-core/columns/datetime.ts) * [drizzle-orm/src/singlestore-core/columns/custom.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/singlestore-core/columns/custom.ts) * [drizzle-orm/src/gel-core/columns/custom.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/gel-core/columns/custom.ts) * [drizzle-orm/src/sqlite-core/columns/custom.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/sqlite-core/columns/custom.ts)
Column Types in Drizzle provide a robust, type-safe interface for mapping database schemas to TypeScript objects. By defining a set of core builders and runtime definitions, Drizzle ensures that every column in a table can be accurately queried, validated, and serialized to the underlying database dialect, whether it is PostgreSQL, MySQL, SQLite, Gel, or SingleStore. The system is architected around a separation between the build phase and the runtime phase. Builder classes, such as those derived from `PgColumnBuilder` or `SQLiteColumnBuilder`, manage configurations—such as nullability, default values, and primary key constraints—during the schema definition phase. When a table is built, these builders transition into runtime column instances, which hold the logic for data transformation between the driver's raw output and the application's domain types. Design decisions within this subsystem prioritize type inference and dialect-specific abstraction. Builders use generics to track data types (e.g., `'string'`, `'number'`, `'boolean'`), while the column classes handle dialect-specific serialization quirks, such as different integer representations or JSON/Blob handling. This layered design allows Drizzle to expose a unified API surface while maintaining the performance and flexibility required for cross-dialect database management. ## Core Builder Infrastructure The `PgColumnBuilder` or `SQLiteColumnBuilder` classes (and their equivalents) are the roots for column definitions in their respective dialects. Their primary purpose is to collect configuration metadata before a table is fully realized. They implement the chainable API used in table definitions, such as `.notNull()`, `.default()`, and `.primaryKey()`. Internally, the `config` object acts as a state container. When you call `.notNull()`, the builder simply sets `this.config.notNull = true` and returns `this` cast to a specific type, ensuring the TypeScript compiler reflects this state change for subsequent chain calls. Sources: [drizzle-orm/src/pg-core/columns/common.ts:38-43](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/pg-core/columns/common.ts#L38-L43), [drizzle-orm/src/sqlite-core/columns/common.ts:6](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/sqlite-core/columns/common.ts#L6) ## Dialect-Specific Column Implementations While building interfaces share commonality, actual data type implementation is split by dialect. For example, `PgNumericBuilder` and `SQLiteNumericBuilder` both offer numeric column support but handle the mapping logic to their respective driver's outputs differently. In the `PgNumeric` implementation, the `mapFromDriverValue` function is designed to handle `unknown` inputs, converting them to `string` if they are not already, ensuring consistent behavior despite database variability. Conversely, the `SQLiteNumericNumber` implementation specifically maps its inputs to `number` type, demonstrating how builders and runtime definitions tailor the interface based on the requested `mode`. Sources: [drizzle-orm/src/pg-core/columns/numeric.ts:40-67](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/pg-core/columns/numeric.ts#L40-L67), [drizzle-orm/src/sqlite-core/columns/numeric.ts:37-49](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/sqlite-core/columns/numeric.ts#L37-L49), [drizzle-orm/src/sqlite-core/columns/numeric.ts:80-94](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/sqlite-core/columns/numeric.ts#L80-L94) ## Custom Type Support Drizzle provides a `customType` function for each dialect to support proprietary or complex database types that are not explicitly covered by the core library. This subsystem allows developers to specify the underlying SQL data type via a `dataType` function and provide custom `toDriver` and `fromDriver` mapping functions. When a column is defined via `customType`, the builder instance (e.g., `SingleStoreCustomColumnBuilder` or `SQLiteCustomColumnBuilder`) holds the configuration, while the resulting column class instance encapsulates the mapping logic. This architecture prevents core code from needing awareness of every possible niche database type while still providing seamless integration. Sources: [drizzle-orm/src/singlestore-core/columns/custom.ts:26-59](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/singlestore-core/columns/custom.ts#L26-L59), [drizzle-orm/src/sqlite-core/columns/custom.ts:25-58](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/sqlite-core/columns/custom.ts#L25-L58) ## Lifecycle and Initialization Flow The transition from a definition to a concrete database object involves a specific initialization sequence. When a table is declared, the framework instantiates the builder classes. The `build()` method is then invoked, which consumes the `config` object from the builder and initializes the runtime column class. For example, when constructing an array column in PostgreSQL: 1. `PgArrayBuilder` is initialized with a base builder. 2. The user calls `.build(table)`. 3. `PgArrayBuilder` instantiates the base column and passes it to the `PgArray` constructor. 4. The `PgArray` constructor sets the array-specific SQL type, such as `integer[]`. Sources: [drizzle-orm/src/pg-core/columns/common.ts:260-307](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/pg-core/columns/common.ts#L260-L307) ## Serialization and Introspection Logic Drizzle Kit performs introspection to convert raw database schema data back into Drizzle ORM TypeScript code. This involves mapping raw column types back to Drizzle function calls. The `schemaToTypeScript` function in the MySQL introspector, for instance, iterates over table columns, patches type strings using a lookup table (`importsPatch`), and then dispatches the result to a `column()` function. This function acts as a factory, matching the string type to a constructor for the correct builder, and generating the necessary `.default()` or `.primaryKey()` chain calls. Sources: [drizzle-kit/src/introspect-mysql.ts:133-195](https://github.com/blade47/drizzle-orm/blob/main/drizzle-kit/src/introspect-mysql.ts#L133-L195), [drizzle-kit/src/introspect-mysql.ts:386-416](https://github.com/blade47/drizzle-orm/blob/main/drizzle-kit/src/introspect-mysql.ts#L386-L416) > [!NOTE] > When introspecting columns, the framework maps "int unsigned" types to standard integer builders and applies an `{ unsigned: true }` parameter in the generated code. ## Data Mapping Mechanisms Each column type contains logic to bridge the gap between driver data and application data. `mapFromDriverValue` and `mapToDriverValue` are the primary lifecycle hooks for this conversion. For instance, the `SQLiteBlobJson` column type defines how it handles raw binary data: ```typescript override mapFromDriverValue(value: Buffer | Uint8Array | ArrayBuffer): T['data'] { // ... decoding logic return JSON.parse(buf.toString('utf8')); } ``` This is critical because SQLite doesn't have a native JSON type; it forces developers to store JSON objects in `blob` or `text` columns, and this mapping function abstracts that limitation entirely away from the developer. Sources: [drizzle-orm/src/sqlite-core/columns/blob.ts:100-114](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/sqlite-core/columns/blob.ts#L100-L114) ## Design Trade-offs | Design Choice | Benefit | Cost | | ----------------------------- | -------------------------------------------------- | ---------------------------------------------------------- | | **Separate Builder Class** | Decouples runtime logic from schema configuration. | Requires double instantiation (builder → column instance). | | **Dialect-specific Builders** | Allows for exact SQL feature mapping per database. | Increased codebase size through specialized classes. | | **Type-safe Mapper** | Prevents runtime data corruption at the boundary. | Performance overhead during heavy read/write operations. | Sources: [drizzle-orm/src/column-builder.ts:185-317](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/column-builder.ts#L185-L317), [drizzle-orm/src/pg-core/columns/numeric.ts:17-38](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/pg-core/columns/numeric.ts#L17-L38) ## Related * \[\[Schema Declarations]] --- ## Technical docs: Relational Query Engine URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/relational-query-engine
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-orm/src/gel-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/dialect.ts) - [drizzle-orm/src/mysql-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/dialect.ts) - [drizzle-orm/src/pg-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/dialect.ts) - [drizzle-orm/src/singlestore-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/dialect.ts) - [drizzle-orm/src/sqlite-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/dialect.ts) - [drizzle-orm/src/relations.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/relations.ts) - [drizzle-kit/src/introspect-pg.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-pg.ts) - [drizzle-orm/src/pg-core/query-builders/query.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/query.ts) - [drizzle-orm/src/mysql-core/query-builders/query.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/query-builders/query.ts) - [drizzle-orm/src/gel-core/query-builders/query.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/query.ts) - [drizzle-orm/src/singlestore-core/query-builders/query.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/query-builders/query.ts) - [drizzle-orm/src/sqlite-core/query-builders/query.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/query.ts) - [drizzle-kit/src/serializer/studio.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/studio.ts) - [drizzle-orm/type-tests/geldb/db-rel.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/db-rel.ts) - [drizzle-orm/type-tests/mysql/db-rel.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/db-rel.ts) - [drizzle-orm/type-tests/pg/db-rel.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/db-rel.ts) - [drizzle-orm/src/operations.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/operations.ts) - [drizzle-orm/src/selection-proxy.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/selection-proxy.ts)
## Overview The Relational Query Engine serves as Drizzle's high-level declarative query layer, translating nested TypeScript query definitions into optimized, dialect-specific SQL execution plans across multiple database engines. It solves the complexity of querying graph-shaped relational data structures by bridging typed schema definitions with underlying driver sessions through dedicated query builder classes like `PgRelationalQuery`, `MySqlRelationalQuery`, `GelRelationalQuery`, `SingleStoreRelationalQuery`, and `SQLiteRelationalQuery`. Key architectural decisions include encapsulating query promises and execution lifecycles, supporting nested filtering, pagination, and sorting via `findMany` and `findFirst`, and normalizing graph relations across primary and non-primary key constraints. It interacts closely with underlying database dialects to construct lateral subqueries, manage table aliases, apply selection masks, and execute row-mapping transformations on fetched database records. Sources: [drizzle-orm/src/pg-core/query-builders/query.ts:19-110](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/query.ts#L19-L110), [drizzle-orm/src/mysql-core/query-builders/query.ts:23-74](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/query-builders/query.ts#L23-L74), [drizzle-orm/src/gel-core/query-builders/query.ts:19-63](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/query.ts#L19-L63), [drizzle-orm/src/singlestore-core/query-builders/query.ts:22-70](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/query-builders/query.ts#L22-L70), [drizzle-orm/src/sqlite-core/query-builders/query.ts:22-96](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/query.ts#L22-L96) ## Relation Declarations and Metadata Modeling ### Schema Definition and Helpers The relational metadata layer begins with public schema definition helpers and typed relation descriptors. The `relations` function accepts a table and a callback yielding a record of `Relation` objects, automatically binding each entry to its field name via `value.withFieldName(key)`. The helpers `createOne` and `createMany` construct `One` and `Many` relation descriptors respectively, where `createOne` evaluates nullability by inspecting whether all component fields have `notNull: true`. ```typescript export function relations< TTableName extends string, TRelations extends Record>, >( table: AnyTable<{ name: TTableName }>, relations: (helpers: TableRelationsHelpers) => TRelations, ): Relations { return new Relations( table, (helpers: TableRelationsHelpers) => Object.fromEntries( Object.entries(relations(helpers)).map(([key, value]) => [ key, value.withFieldName(key), ]), ) as TRelations, ); } ``` Sources: [drizzle-orm/src/relations.ts:502-519](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/relations.ts#L502-L519) The engine extracts complete relational schemas using `extractTablesRelationalConfig`, which iterates over raw schema entries, normalizes single-default schema wrappers, and resolves forward references through `relationsBuffer` when relations are declared before their target tables. | Configuration Field | Type | Purpose | | :--- | :--- | :--- | | `tsName` | `string` | TypeScript schema object key for the table | | `dbName` | `string` | Physical database table identifier name | | `schema` | `string \| undefined` | Optional database schema namespace | | `columns` | `Record` | Mapped column definitions | | `relations` | `Record` | Registered table relations | | `primaryKey` | `AnyColumn[]` | Resolved primary key column array | Sources: [drizzle-orm/src/relations.ts:416-500](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/relations.ts#L416-L500) > [!NOTE] > When schema entries contain a single `'default'` property holding a nested record, `extractTablesRelationalConfig` automatically unwraps it before iterating over table and relation definitions. > Sources: [drizzle-orm/src/relations.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/relations.ts#L422-L428) ### Graph Relation Normalization Relation graph normalization resolves mapping fields between source and target tables when explicit join configurations are omitted. The `normalizeRelation` function inspects whether a relation is an instance of `One` containing an explicit `RelationConfig`. If explicit fields and references are present, they are returned directly. Otherwise, the engine looks up the referenced table configuration in the schema and searches for matching reverse relations. ```typescript export function normalizeRelation( schema: TablesRelationalConfig, tableNamesMap: Record, relation: Relation, ): NormalizedRelation { if (is(relation, One) && relation.config) { return { fields: relation.config.fields, references: relation.config.references, }; } ... ``` Sources: [drizzle-orm/src/relations.ts:559-569](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/relations.ts#L559-L569) Reverse relation matching evaluates either matching explicit `relationName` properties or linking back via `referencedTable === relation.sourceTable`. If multiple reverse relations match without a disambiguating name, an error is thrown. When a single reverse `One` relation is found, its fields and references are inverted to establish the normalized connection path. > [!WARNING] > Omitting an explicit `relationName` when multiple bidirectional relations exist between the same two tables causes `normalizeRelation` to throw an ambiguous match error. > Sources: [drizzle-orm/src/relations.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/relations.ts#L608-L618) ## Relational Query Builder Classes ### Relational Query Builder Construction and Methods Dialect-specific relational query builders coordinate schema definitions, table mappings, and session handlers to instantiate executable queries. Each dialect exports a `RelationalQueryBuilder` class that exposes `findMany` and `findFirst` methods accepting type-safe configuration objects restricted by `KnownKeysOnly`. The `findFirst` method wraps the query configuration by setting `limit: 1` and marks the internal execution mode as `'first'`, whereas `findMany` defaults to `'many'`. | Dialect Module | Builder Class Name | Query Runner Class Name | Session Type | | :--- | :--- | :--- | :--- | | PostgreSQL (`pg-core`) | `RelationalQueryBuilder` | `PgRelationalQuery` | `PgSession` | | MySQL (`mysql-core`) | `RelationalQueryBuilder` | `MySqlRelationalQuery` | `MySqlSession` | | Gel (`gel-core`) | `RelationalQueryBuilder` | `GelRelationalQuery` | `GelSession` | | SingleStore (`singlestore-core`) | `RelationalQueryBuilder` | `SingleStoreRelationalQuery` | `SingleStoreSession` | | SQLite (`sqlite-core`) | `RelationalQueryBuilder` | `SQLiteRelationalQuery` / `SQLiteSyncRelationalQuery` | `SQLiteSession` | Sources: [drizzle-orm/src/pg-core/query-builders/query.ts:19-63](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/query.ts#L19-L63), [drizzle-orm/src/mysql-core/query-builders/query.ts:23-74](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/query-builders/query.ts#L23-L74), [drizzle-orm/src/gel-core/query-builders/query.ts:19-63](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/query.ts#L19-L63), [drizzle-orm/src/singlestore-core/query-builders/query.ts:22-70](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/query-builders/query.ts#L22-L70), [drizzle-orm/src/sqlite-core/query-builders/query.ts:22-96](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/query.ts#L22-L96) ```typescript findMany>( config?: KnownKeysOnly>, ): PgRelationalQuery[]> { return new PgRelationalQuery( this.fullSchema, this.schema, this.tableNamesMap, this.table, this.tableConfig, this.dialect, this.session, config ? (config as DBQueryConfig<'many', true>) : {}, 'many', ); } findFirst, 'limit'>>( config?: KnownKeysOnly, 'limit'>>, ): PgRelationalQuery | undefined> { return new PgRelationalQuery( this.fullSchema, this.schema, this.tableNamesMap, this.table, this.tableConfig, this.dialect, this.session, config ? { ...(config as DBQueryConfig<'many', true> | undefined), limit: 1 } : { limit: 1 }, 'first', ); } ``` Sources: [drizzle-orm/src/pg-core/query-builders/query.ts:32-62](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/query.ts#L32-L62) > [!NOTE] > In MySQL and SingleStore builders, relational query classes are parameterized by higher-kinded types (`PreparedQueryHKTBase`) to allow engines to generate dialect-specific prepared query handles. > Sources: [drizzle-orm/src/mysql-core/query-builders/query.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/query-builders/query.ts#L23-L43), [drizzle-orm/src/singlestore-core/query-builders/query.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/query-builders/query.ts#L22-L41) ### Execution Lifecycle and Query Compilation Relational query runner classes inherit from `QueryPromise` and implement query compilation, statement preparation, and row mapping. When `.execute()` or `.prepare()` is invoked, the runner calls an internal compilation method such as `_toSQL()` or `_getQuery()` which delegates to the dialect to build the underlying SQL abstract syntax tree (AST). For instance, PostgreSQL and Gel invoke `dialect.buildRelationalQueryWithoutPK`, whereas MySQL checks the connection mode (`planetscale`) to determine whether to build queries without lateral subqueries. ```typescript private _getQuery() { const query = this.mode === 'planetscale' ? this.dialect.buildRelationalQueryWithoutLateralSubqueries({ fullSchema: this.fullSchema, schema: this.schema, tableNamesMap: this.tableNamesMap, table: this.table, tableConfig: this.tableConfig, queryConfig: this.config, tableAlias: this.tableConfig.tsName, }) : this.dialect.buildRelationalQuery({ fullSchema: this.fullSchema, schema: this.schema, tableNamesMap: this.tableNamesMap, table: this.table, tableConfig: this.tableConfig, queryConfig: this.config, tableAlias: this.tableConfig.tsName, }); return query; } ``` Sources: [drizzle-orm/src/mysql-core/query-builders/query.ts:114-135](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/query-builders/query.ts#L114-L135) Once compiled into SQL, the query is passed to the session via `prepareQuery` (or `prepareOneTimeQuery` in SQLite). The session callback processes raw database rows by executing `mapRelationalRow`, passing the schema table configuration, row selection mask, and column mapping utility. If the query execution mode is set to `'first'`, the result mapper extracts and returns the first element (`rows[0]`), otherwise returning the full array. ```typescript (rawRows, mapColumnValue) => { const rows = rawRows.map((row) => mapRelationalRow(this.schema, this.tableConfig, row, query.selection, mapColumnValue) ); if (this.mode === 'first') { return rows[0] as TResult; } return rows as TResult; }, ); ``` Sources: [drizzle-orm/src/pg-core/query-builders/query.ts:99-108](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/query.ts#L99-L108) > [!WARNING] > SQLite provides separate asynchronous (`SQLiteRelationalQuery`) and synchronous (`SQLiteSyncRelationalQuery`) classes where synchronous executions bypass promises and immediately invoke `.get()` or `.all()` through `executeRaw()`. > Sources: [drizzle-orm/src/sqlite-core/query-builders/query.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/query.ts#L98-L207) ## Lateral Joins and Subquery Compilation ### Dialect-Specific Subquery Strategies Different database engines impose distinct constraints on how relational joins and nested subqueries are compiled. Drizzle accommodates these engine-specific capabilities by delegating query construction to dialect methods tailored to each backend's support for lateral subqueries, correlated references, and table primary key requirements. ```typescript private _getQuery() { const query = this.mode === 'planetscale' ? this.dialect.buildRelationalQueryWithoutLateralSubqueries({ fullSchema: this.fullSchema, schema: this.schema, tableNamesMap: this.tableNamesMap, table: this.table, tableConfig: this.tableConfig, queryConfig: this.config, tableAlias: this.tableConfig.tsName, }) : this.dialect.buildRelationalQuery({ fullSchema: this.fullSchema, schema: this.schema, tableNamesMap: this.tableNamesMap, table: this.table, tableConfig: this.tableConfig, queryConfig: this.config, tableAlias: this.tableConfig.tsName, }); return query; } ``` Sources: [drizzle-orm/src/mysql-core/query-builders/query.ts:114-135](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/query-builders/query.ts#L114-L135) As shown in the MySQL relational query builder, the dialect branch inspection explicitly checks whether the execution target is running under PlanetScale mode. When `this.mode === 'planetscale'`, the query builder invokes `buildRelationalQueryWithoutLateralSubqueries` instead of standard `buildRelationalQuery`. This branching is required because serverless MySQL hosting environments often lack full lateral join support or enforce restrictions on correlated subquery constructs. ### Keyless and Specialized Compilation Methods Beyond MySQL's conditional dispatch, PostgreSQL and Gel employ `buildRelationalQueryWithoutPK` to handle relational queries where primary key assumptions or table structures require specialized AST generation. ```typescript private _getQuery() { return this.dialect.buildRelationalQueryWithoutPK({ fullSchema: this.fullSchema, schema: this.schema, tableNamesMap: this.tableNamesMap, table: this.table, tableConfig: this.tableConfig, queryConfig: this.config, tableAlias: this.tableConfig.tsName, }); } ``` Sources: [drizzle-orm/src/pg-core/query-builders/query.ts:116-126](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/query.ts#L116-L126) | Dialect / Core | Target Method | Branch Condition / Purpose | | --- | --- | --- | | PostgreSQL (`pg-core`) | `buildRelationalQueryWithoutPK` | Compiles relational queries without relying on explicit primary key column lookups in subquery correlations. | | MySQL (`mysql-core`) | `buildRelationalQueryWithoutLateralSubqueries` | Executed when `mode === 'planetscale'` to avoid lateral join features unsupported by PlanetScale. | | MySQL (`mysql-core`) | `buildRelationalQuery` | Standard MySQL path utilizing lateral subqueries and advanced join syntax. | | SingleStore (`singlestore-core`) | `buildRelationalQuery` | Standard SingleStore path for relational query compilation. | | SQLite (`sqlite-core`) | `buildRelationalQuery` | Standard SQLite path compiling relational selections into AST structures. | Sources: [drizzle-orm/src/pg-core/query-builders/query.ts:116-126](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/query.ts#L116-L126), [drizzle-orm/src/mysql-core/query-builders/query.ts:114-135](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/query-builders/query.ts#L114-L135), [drizzle-orm/src/gel-core/query-builders/query.ts:116-126](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/query.ts#L116-L126), [drizzle-orm/src/singlestore-core/query-builders/query.ts:109-119](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/query-builders/query.ts#L109-L119), [drizzle-orm/src/sqlite-core/query-builders/query.ts:129-138](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/query.ts#L129-L138) > [!CAUTION] > Attempting to execute standard lateral-join-based relational queries against a PlanetScale MySQL instance will fail at runtime unless the engine mode is explicitly configured to `'planetscale'`, which triggers `buildRelationalQueryWithoutLateralSubqueries`. > Sources: [drizzle-orm/src/mysql-core/query-builders/query.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/query-builders/query.ts#L114-L135) ## Selection Masking and Dynamic Aliasing ### Selection Proxy Wrapping and Proxy Handlers Selection masking and dynamic aliasing in Drizzle are governed by `SelectionProxyHandler`, which implements the JavaScript `ProxyHandler` interface across subqueries, record sets, and database views. When properties are accessed on a selection proxy, the handler intercepts symbol and string lookups to manage `_` metadata configurations, view configurations, and column selections. ```typescript get(subquery: T, prop: string | symbol): any { if (prop === '_') { return { ...subquery['_' as keyof typeof subquery], selectedFields: new Proxy( (subquery as Subquery)._.selectedFields, this as ProxyHandler>, ), }; } if (prop === ViewBaseConfig) { return { ...subquery[ViewBaseConfig as keyof typeof subquery], selectedFields: new Proxy( (subquery as View)[ViewBaseConfig].selectedFields, this as ProxyHandler>, ), }; } ``` Sources: [drizzle-orm/src/selection-proxy.ts:47-66](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/selection-proxy.ts#L47-L66) The proxy handler evaluates accessed properties to determine whether they represent stored columns, raw SQL expressions, aliased SQL chunks, or nested objects. When a column is encountered and an alias is configured, the handler wraps the column and its underlying table within `ColumnAliasProxyHandler` and `TableAliasProxyHandler` respectively. ```typescript if (is(value, Column)) { if (this.config.alias) { return new Proxy( value, new ColumnAliasProxyHandler( new Proxy( value.table, new TableAliasProxyHandler(this.config.alias, this.config.replaceOriginalName ?? false), ), ), ); } return value; } ``` Sources: [drizzle-orm/src/selection-proxy.ts:100-113](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/selection-proxy.ts#L100-L113) ### Column Projection Scoping and SQL Behavior The configuration options accepted by `SelectionProxyHandler` control how raw SQL expressions and aliased fields behave during query building and view generation. | Configuration Key | Type | Default / Options | Purpose | | --- | --- | --- | --- | | `alias` | `string` | `undefined` | Table alias applied to intercepted columns during proxy wrapping. | | `sqlAliasedBehavior` | `'sql' \| 'alias'` | Required | Determines whether `SQL.Aliased` returns the underlying expression (`'sql'`) or the field alias (`'alias'`). | | `sqlBehavior` | `'sql' \| 'error'` | Required | Determines whether unaliased raw `SQL` expressions return the expression or throw a type/runtime error. | | `replaceOriginalName` | `boolean` | `false` | Replaces the original column name with its alias, primarily used when creating database views. | Sources: [drizzle-orm/src/selection-proxy.ts:13-41](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/selection-proxy.ts#L13-L41) > [!WARNING] > Accessing a raw SQL field from a subquery that lacks an explicit alias will throw an error at runtime and evaluate to a Drizzle type-level error when `sqlBehavior` is set to `'error'`. > Sources: [drizzle-orm/src/selection-proxy.ts:90-98](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/selection-proxy.ts#L90-L98) > [!NOTE] > `SQL.Aliased` instances that originated inside a prior subquery carry `isSelectionField: true`, preventing the proxy handler from mistakenly returning raw underlying SQL expressions when `sqlAliasedBehavior` is set to `'sql'`. > Sources: [drizzle-orm/src/selection-proxy.ts:79-88](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/selection-proxy.ts#L79-L88) ## Result Hydration and Row Mapping ### Relational Row Transformation and Mapping Lifecycles After database sessions execute compiled relational queries, raw tabular rows returned by drivers require structural reshaping into nested object graphs matching the user's schema and selection configuration. Across PostgreSQL, MySQL, SQLite, SingleStore, and Gel dialects, this post-query phase is driven by `mapRelationalRow`, which processes raw row data and column value mappers provided by underlying database drivers. ```typescript (rawRows, mapColumnValue) => { const rows = rawRows.map((row) => mapRelationalRow(this.schema, this.tableConfig, row, query.selection, mapColumnValue) ); if (this.mode === 'first') { return rows[0] as TResult; } return rows as TResult; }, ``` Sources: [drizzle-orm/src/pg-core/query-builders/query.ts:99-107](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/query.ts#L99-L107) For asynchronous and synchronous session configurations, the execution pipeline wraps the raw rows mapper inside prepared query definitions. Depending on whether the query mode is configured as `'many'` or `'first'`, the result handler returns either an array of fully hydrated entities or extracts the initial index element. ```typescript (rawRows, mapColumnValue) => { const rows = rawRows.map((row) => mapRelationalRow(this.schema, this.tableConfig, row, query.selection, mapColumnValue) ); if (this.mode === 'first') { return rows[0] as TResult; } return rows as TResult; }, ``` Sources: [drizzle-orm/src/sqlite-core/query-builders/query.ts:152-160](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/query.ts#L152-L160) ### Execution and Preparation Modalities Different query runner implementations manage row mapping through dialect-specific prepared statements and query promises. | Dialect Runner Class | Method / Hook | Mode Parameter | Return Processing | | --- | --- | --- | --- | | `PgRelationalQuery` | `_prepare` | `'many'` \| `'first'` | Maps raw rows with `mapRelationalRow`, slicing index `0` for `'first'`. | | `MySqlRelationalQuery` | `prepare` | `'many'` \| `'first'` | Iterates over `rawRows` via `mapRelationalRow` without column value mappers. | | `SQLiteRelationalQuery` | `_prepare` | `'many'` \| `'first'` | Dispatches to session `prepareQuery` or `prepareOneTimeQuery` with driver mappers. | | `GelRelationalQuery` | `_prepare` | `'many'` \| `'first'` | Executes via Gel session wrapper, applying active telemetry span tracing. | | `SingleStoreRelationalQuery` | `prepare` | `'many'` \| `'first'` | Processes result sets via SingleStore session query preparation layer. | Sources: [drizzle-orm/src/pg-core/query-builders/query.ts:90-108](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/query.ts#L90-L108), [drizzle-orm/src/mysql-core/query-builders/query.ts:99-111](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/query-builders/query.ts#L99-L111), [drizzle-orm/src/sqlite-core/query-builders/query.ts:142-161](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/query.ts#L142-L161), [drizzle-orm/src/gel-core/query-builders/query.ts:90-108](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/query.ts#L90-L108), [drizzle-orm/src/singlestore-core/query-builders/query.ts:94-106](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/query-builders/query.ts#L94-L106) > [!NOTE] > PostgreSQL, Gel, and SQLite sessions pass a secondary `mapColumnValue` callback into `mapRelationalRow`, enabling custom type decoding per column during row deserialization. > Sources: [drizzle-orm/src/pg-core/query-builders/query.ts:99-102](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/query.ts#L99-L102), [drizzle-orm/src/gel-core/query-builders/query.ts:99-102](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/query.ts#L99-L102), [drizzle-orm/src/sqlite-core/query-builders/query.ts:152-155](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/query.ts#L152-L155) > [!WARNING] > Selecting `findFirst` on any relational query builder forces the row transformation pipeline to truncate the hydrated array output, returning `undefined` if no records match the criteria. > Sources: [drizzle-orm/src/pg-core/query-builders/query.ts:48-62](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/query.ts#L48-L62), [drizzle-orm/src/sqlite-core/query-builders/query.ts:69-95](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/query.ts#L69-L95) ## Related - [Table and Column Models](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/table-and-column-models) - [Query Builder Foundation](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/query-builder-foundation) --- ## Technical docs: Query Builder Foundation URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/query-builder-foundation
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-orm/src/gel-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/dialect.ts) - [drizzle-orm/src/sqlite-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/dialect.ts) - [drizzle-orm/src/gel-core/query-builders/select.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/select.ts) - [drizzle-orm/src/mysql-core/query-builders/select.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/query-builders/select.ts) - [drizzle-orm/src/sqlite-core/query-builders/select.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/select.ts) - [drizzle-orm/src/singlestore-core/query-builders/select.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/query-builders/select.ts) - [drizzle-orm/src/pg-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/dialect.ts) - [drizzle-orm/src/mysql-core/query-builders/query.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/query-builders/query.ts) - [drizzle-orm/src/gel-core/query-builders/query-builder.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/query-builder.ts) - [drizzle-orm/src/pg-core/query-builders/select.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/select.ts) - [drizzle-orm/src/mysql-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/dialect.ts) - [drizzle-orm/src/gel-core/db.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/db.ts) - [drizzle-orm/src/sql/sql.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql/sql.ts) - [drizzle-orm/src/singlestore-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/dialect.ts) - [drizzle-orm/src/pg-core/query-builders/query-builder.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/query-builder.ts) - [drizzle-orm/src/gel-core/query-builders/query.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/query.ts) - [drizzle-orm/src/pg-core/query-builders/query.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/query.ts) - [drizzle-orm/src/sqlite-core/query-builders/query.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/query.ts) - [drizzle-orm/src/gel-core/query-builders/insert.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/insert.ts) - [drizzle-orm/src/sqlite-core/query-builders/query-builder.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/query-builder.ts) - [drizzle-orm/type-tests/geldb/select.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/select.ts) - [drizzle-orm/src/sqlite-core/db.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/db.ts) - [drizzle-orm/src/singlestore-core/query-builders/query-builder.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/query-builders/query-builder.ts) - [drizzle-orm/src/sqlite-core/query-builders/update.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/update.ts) - [drizzle-orm/src/mysql-core/query-builders/query-builder.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/query-builders/query-builder.ts) - [drizzle-orm/src/sqlite-core/query-builders/count.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/count.ts) - [drizzle-orm/src/sqlite-core/query-builders/raw.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/raw.ts) - [drizzle-orm/src/gel-core/query-builders/raw.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/raw.ts) - [drizzle-orm/src/query-builders/query-builder.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/query-builders/query-builder.ts) - [drizzle-orm/src/query-builders/select.types.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/query-builders/select.types.ts)
## Overview The Query Builder Foundation defines the architectural and type-level framework for constructing, composing, and executing declarative SQL queries across all supported database dialects. It centers on foundational base classes such as `TypedQueryBuilder` and `QueryPromise` that standardize asynchronous execution, thenable resolutions, and fluent method chaining across select, insert, update, and count operations. By pairing abstract query specifications with concrete dialect implementations, the foundation enables type-safe schema selection, join nullability mapping, and expression compilation without relying on pre-instantiated database connections. Sources: [drizzle-orm/src/query-builders/query-builder.ts:4-18](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/query-builders/query-builder.ts#L4-L18), [drizzle-orm/src/gel-core/query-builders/select.ts:1013-1060](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/select.ts#L1013-L1060), [drizzle-orm/src/sqlite-core/query-builders/select.ts:129-160](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/select.ts#L129-L160), [drizzle-orm/src/singlestore-core/query-builders/select.ts:133-160](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/query-builders/select.ts#L133-L160) ## Core Query Builder Abstractions ### Core Query Base Abstractions ### TypedQueryBuilder and Selection Contracts The foundational contract for all query builders is established by the `TypedQueryBuilder` abstract class. It implements the `SQLWrapper` interface and exposes structural type generics for the selected fields, result shape, and builder configuration. The class defines an internal `_` property structure alongside helper methods for extracting selected fields and enforcing SQL compilation. ```typescript export abstract class TypedQueryBuilder implements SQLWrapper { static readonly [entityKind]: string = 'TypedQueryBuilder'; declare _: { selectedFields: TSelection; result: TResult; config?: TConfig; }; /** @internal */ getSelectedFields(): TSelection { return this._.selectedFields; } abstract getSQL(): SQL; } ``` Sources: [drizzle-orm/src/query-builders/query-builder.ts:4-18](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/query-builders/query-builder.ts#L4-L18) Type-level calculations for queries rely on structural mapping utilities defined across select operations. These type definitions govern join semantics, result flattening, and subquery validation. | Type Identifier | Parameters | Purpose | | :--- | :--- | :--- | | `JoinType` | none | Defines accepted join variations (`inner`, `left`, `right`, `full`, `cross`) | | `JoinNullability` | none | Specifies row presence nullability (`nullable`, `not-null`) | | `SelectMode` | none | Controls result shape categorization (`partial`, `single`, `multiple`) | | `SetOperator` | none | Specifies set operation types (`union`, `intersect`, `except`) | Sources: [drizzle-orm/src/query-builders/select.types.ts:9-11](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/query-builders/select.types.ts#L9-L11), [drizzle-orm/src/query-builders/select.types.ts:37-37](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/query-builders/select.types.ts#L37-L37), [drizzle-orm/src/query-builders/select.types.ts:175-175](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/query-builders/select.types.ts#L175-L175) > [!NOTE] > `TypedQueryBuilder` does not manage database connections or session execution directly. Concrete subclasses must implement `getSQL()` to translate internal configuration trees into parameterized `SQL` instances that drivers can execute. ## Standalone Query Builder Instantiation ### Dialect Query Builder Classes and Entity Kinds Each database dialect provides a standalone `QueryBuilder` class that enables constructing queries without an active database session or connection pool. These classes hold an internal entity kind identifier and support lazy loading of their respective dialect instances to prevent circular dependencies during module initialization. | Module Path | Entity Kind Identifier | Dialect Class | Config Type | | :--- | :--- | :--- | :--- | | `drizzle-orm/src/gel-core/query-builders/query-builder.ts` | `GelQueryBuilder` | `GelDialect` | `GelDialectConfig` | | `drizzle-orm/src/pg-core/query-builders/query-builder.ts` | `PgQueryBuilder` | `PgDialect` | `PgDialectConfig` | | `drizzle-orm/src/sqlite-core/query-builders/query-builder.ts` | `SQLiteQueryBuilder` | `SQLiteDialect`, `SQLiteSyncDialect` | `SQLiteDialectConfig` | | `drizzle-orm/src/singlestore-core/query-builders/query-builder.ts` | `SingleStoreQueryBuilder` | `SingleStoreDialect` | `SingleStoreDialectConfig` | | `drizzle-orm/src/mysql-core/query-builders/query-builder.ts` | `MySqlQueryBuilder` | `MySqlDialect` | `MySqlDialectConfig` | Sources: [drizzle-orm/src/gel-core/query-builders/query-builder.ts:13-17](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/query-builder.ts#L13-L17), [drizzle-orm/src/pg-core/query-builders/query-builder.ts:13-17](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/query-builder.ts#L13-L17), [drizzle-orm/src/sqlite-core/query-builders/query-builder.ts:12-16](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/query-builder.ts#L12-L16), [drizzle-orm/src/singlestore-core/query-builders/query-builder.ts:12-16](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/query-builders/query-builder.ts#L12-L16), [drizzle-orm/src/mysql-core/query-builders/query-builder.ts:12-16](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/query-builders/query-builder.ts#L12-L16) > [!NOTE] > The constructor accepts either an instantiated dialect instance or a dialect configuration object, resolving and storing them conditionally via the `is()` helper check. Sources: [drizzle-orm/src/gel-core/query-builders/query-builder.ts:19-22](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/query-builder.ts#L19-L22), [drizzle-orm/src/pg-core/query-builders/query-builder.ts:19-22](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/query-builder.ts#L19-L22) ### Proxy Initialization and Subquery Aliasing The query builder provides `$with` and `with()` methods to construct Common Table Expressions (CTEs) and subqueries. When a subquery builder or callback is passed to `$with`, it wraps the resulting `WithSubquery` instance in a JavaScript `Proxy` managed by `SelectionProxyHandler`. ```typescript return new Proxy( new WithSubquery( qb.getSQL(), selection ?? ('getSelectedFields' in qb ? qb.getSelectedFields() ?? {} : {}) as SelectedFields, alias, true, ), new SelectionProxyHandler({ alias, sqlAliasedBehavior: 'alias', sqlBehavior: 'error' }), ) as any; ``` Sources: [drizzle-orm/src/pg-core/query-builders/query-builder.ts:36-44](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/query-builder.ts#L36-L44), [drizzle-orm/src/sqlite-core/query-builders/query-builder.ts:35-43](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/query-builder.ts#L35-L43), [drizzle-orm/src/singlestore-core/query-builders/query-builder.ts:35-43](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/query-builders/query-builder.ts#L35-L43), [drizzle-orm/src/mysql-core/query-builders/query-builder.ts:35-43](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/query-builders/query-builder.ts#L35-L43), [drizzle-orm/src/gel-core/query-builders/query-builder.ts:35-39](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/query-builder.ts#L35-L39) > [!WARNING] > `SelectionProxyHandler` configures `sqlAliasedBehavior` as `'alias'` and `sqlBehavior` as `'error'` for proxying field selections on subqueries, ensuring unaliased column references throw errors during compilation. Sources: [drizzle-orm/src/gel-core/query-builders/query-builder.ts:36-39](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/query-builder.ts#L36-L39), [drizzle-orm/src/pg-core/query-builders/query-builder.ts:36-44](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/query-builder.ts#L36-L44), [drizzle-orm/src/sqlite-core/query-builders/query-builder.ts:35-43](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/query-builder.ts#L35-L43), [drizzle-orm/src/singlestore-core/query-builders/query-builder.ts:35-43](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/query-builders/query-builder.ts#L35-L43), [drizzle-orm/src/mysql-core/query-builders/query-builder.ts:35-43](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/query-builders/query-builder.ts#L35-L43) ## Thenable Execution via QueryPromise ### Relational and Raw Query Execution Lifecycle Relational query builders such as `MySqlRelationalQuery`, `GelRelationalQuery`, `PgRelationalQuery`, and `SQLiteRelationalQuery` extend `QueryPromise`, inheriting `then` and `catch` methods that enable them to be awaited directly as asynchronous promises. Each query class implements an `execute()` method that resolves its underlying session execution path. For PostgreSQL and Gel builders, execution wraps the query in an OpenTelemetry active span via `tracer.startActiveSpan('drizzle.operation', ...)` before triggering `_prepare().execute()`. Sources: [drizzle-orm/src/mysql-core/query-builders/query.ts:76-79](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/query-builders/query.ts#L76-L79), [drizzle-orm/src/mysql-core/query-builders/query.ts:154-156](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/query-builders/query.ts#L154-L156), [drizzle-orm/src/gel-core/query-builders/query.ts:65-67](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/query.ts#L65-L67), [drizzle-orm/src/gel-core/query-builders/query.ts:145-149](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/query.ts#L145-L149), [drizzle-orm/src/pg-core/query-builders/query.ts:65-67](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/query.ts#L65-L67), [drizzle-orm/src/pg-core/query-builders/query.ts:152-156](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/query.ts#L152-L156), [drizzle-orm/src/sqlite-core/query-builders/query.ts:98-100](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/query.ts#L98-L100), [drizzle-orm/src/sqlite-core/query-builders/query.ts:196-198](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/query.ts#L196-L198) > [!NOTE] > `SQLiteSyncRelationalQuery` subclasses `SQLiteRelationalQuery` to provide a synchronous `.sync()` method alongside standard async promise resolution, dispatching directly to `.executeRaw()` using the driver's synchronous retrieval methods. Sources: [drizzle-orm/src/sqlite-core/query-builders/query.ts:201-206](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/query.ts#L201-L206) ### Raw Execution and Statement Preparation Raw query wrappers like `SQLiteRaw` and `GelRaw` extend `QueryPromise` while implementing `RunnableQuery`, `SQLWrapper`, and `PreparedQuery` simultaneously. They accept an explicit `execute` callback function during construction and supply internal query compilation methods such as `getSQL()`, `getQuery()`, and `mapResult()`. ```typescript export class SQLiteRaw extends QueryPromise implements RunnableQuery, SQLWrapper, PreparedQuery { static override readonly [entityKind]: string = 'SQLiteRaw'; declare readonly _: { readonly dialect: 'sqlite'; readonly result: TResult; }; /** @internal */ config: SQLiteRawConfig; constructor( public execute: () => Promise, /** @internal */ public getSQL: () => SQL, action: SQLiteRawAction, private dialect: SQLiteAsyncDialect, private mapBatchResult: (result: unknown) => unknown, ) { super(); this.config = { action }; } ... ``` Sources: [drizzle-orm/src/sqlite-core/query-builders/raw.ts:15-38](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/raw.ts#L15-L38) | Class Name | Dialect | Implemented Interfaces / Base | Execution Action Methods | | :--- | :--- | :--- | :--- | | `MySqlRelationalQuery` | MySQL | `QueryPromise` | `execute()`, `prepare()` | | `GelRelationalQuery` | Gel | `QueryPromise`, `RunnableQuery`, `SQLWrapper` | `execute()`, `prepare()`, `_prepare()` | | `PgRelationalQuery` | PostgreSQL | `QueryPromise`, `RunnableQuery`, `SQLWrapper` | `execute()`, `prepare()`, `_prepare()` | | `SQLiteRelationalQuery` | SQLite | `QueryPromise`, `RunnableQuery`, `SQLWrapper` | `execute()`, `prepare()`, `executeRaw()` | | `SQLiteSyncRelationalQuery` | SQLite | Extends `SQLiteRelationalQuery` | `sync()`, `executeRaw()` | | `SQLiteRaw` | SQLite | `QueryPromise`, `RunnableQuery`, `SQLWrapper`, `PreparedQuery` | `execute()`, `mapResult()`, `getQuery()` | | `GelRaw` | Gel | `QueryPromise`, `RunnableQuery`, `SQLWrapper`, `PreparedQuery` | `execute()`, `mapResult()`, `getQuery()` | Sources: [drizzle-orm/src/mysql-core/query-builders/query.ts:76-79](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/query-builders/query.ts#L76-L79), [drizzle-orm/src/mysql-core/query-builders/query.ts:99-112](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/query-builders/query.ts#L99-L112), [drizzle-orm/src/gel-core/query-builders/query.ts:65-67](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/query.ts#L65-L67), [drizzle-orm/src/gel-core/query-builders/query.ts:112-114](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/query.ts#L112-L114), [drizzle-orm/src/pg-core/query-builders/query.ts:65-67](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/query.ts#L65-L67), [drizzle-orm/src/pg-core/query-builders/query.ts:112-114](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/query.ts#L112-L114), [drizzle-orm/src/sqlite-core/query-builders/query.ts:98-100](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/query.ts#L98-L100), [drizzle-orm/src/sqlite-core/query-builders/query.ts:164-166](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/query.ts#L164-L166), [drizzle-orm/src/sqlite-core/query-builders/query.ts:201-206](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/query.ts#L201-L206), [drizzle-orm/src/sqlite-core/query-builders/raw.ts:15-17](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/raw.ts#L15-L17), [drizzle-orm/src/sqlite-core/query-builders/raw.ts:40-47](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/raw.ts#L40-L47), [drizzle-orm/src/gel-core/query-builders/raw.ts:9-11](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/raw.ts#L9-L11), [drizzle-orm/src/gel-core/query-builders/raw.ts:33-39](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/raw.ts#L33-L39) ## Count Query Builder Foundation ### SQLWrapper and Promise Integration Mechanics The `SQLiteCountBuilder` class extends `SQL` while implementing both `Promise` and `SQLWrapper`. This dual-contract design enables the builder to function simultaneously as a raw SQL chunk container and as an awaitable promise that resolves directly to a numeric count result via its underlying `SQLiteSession`. ```typescript export class SQLiteCountBuilder< TSession extends SQLiteSession, > extends SQL implements Promise, SQLWrapper { private sql: SQL; static override readonly [entityKind] = 'SQLiteCountBuilderAsync'; [Symbol.toStringTag] = 'SQLiteCountBuilderAsync'; private session: TSession; ``` Sources: [drizzle-orm/src/sqlite-core/query-builders/count.ts:7-16](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/count.ts#L7-L16) The constructor accepts a parameter object containing a table or view source, optional filter expressions, and a session instance. It initializes the superclass `SQL` instance with an embedded count representation using `buildEmbeddedCount`, while storing a separate standalone count statement generated by `buildCount` in a private `sql` property for session execution. ```typescript constructor( readonly params: { source: SQLiteTable | SQLiteView | SQL | SQLWrapper; filters?: SQL; session: TSession; }, ) { super(SQLiteCountBuilder.buildEmbeddedCount(params.source, params.filters).queryChunks); this.session = params.session; this.sql = SQLiteCountBuilder.buildCount( params.source, params.filters, ); } ``` Sources: [drizzle-orm/src/sqlite-core/query-builders/count.ts:31-46](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/count.ts#L31-L46) > [!NOTE] > `SQLiteCountBuilder` maintains two distinct SQL compilation methods: `buildEmbeddedCount` wraps the query inside parentheses for use as an expression, whereas `buildCount` constructs a standalone executable statement. ### Query Compilation Methods and Lifecycle Handlers Query compilation relies on private static helper methods that dynamically inject a `where` clause only when filters are present, leveraging `sql.raw(' where ').if(filters)`. ```typescript private static buildEmbeddedCount( source: SQLiteTable | SQLiteView | SQL | SQLWrapper, filters?: SQL, ): SQL { return sql`(select count(*) from ${source}${sql.raw(' where ').if(filters)}${filters})`; } private static buildCount( source: SQLiteTable | SQLiteView | SQL | SQLWrapper, filters?: SQL, ): SQL { return sql`select count(*) from ${source}${sql.raw(' where ').if(filters)}${filters}`; } ``` Sources: [drizzle-orm/src/sqlite-core/query-builders/count.ts:17-30](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/count.ts#L17-L30) Asynchronous promise resolution is implemented via standard `then`, `catch`, and `finally` methods. The `then` method delegates execution to `this.session.count(this.sql)`, resolving the returned promise with the numeric outcome of the query. ```typescript then( onfulfilled?: ((value: number) => TResult1 | PromiseLike) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike) | null | undefined, ): Promise { return Promise.resolve(this.session.count(this.sql)).then( onfulfilled, onrejected, ); } catch( onRejected?: ((reason: any) => never | PromiseLike) | null | undefined, ): Promise { return this.then(undefined, onRejected); } finally(onFinally?: (() => void) | null | undefined): Promise { return this.then( (value) => { onFinally?.(); return value; }, (reason) => { onFinally?.(); throw reason; }, ); } ``` Sources: [drizzle-orm/src/sqlite-core/query-builders/count.ts:48-75](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/count.ts#L48-L75) | Method Name | Parameters | Return Type | Purpose | | :--- | :--- | :--- | :--- | | `buildEmbeddedCount` | `source`, `filters` | `SQL` | Constructs a parenthesized subquery expression for SQL composition. | | `buildCount` | `source`, `filters` | `SQL` | Constructs an executable standalone `select count(*)` query statement. | | `then` | `onfulfilled`, `onrejected` | `Promise` | Executes session count lookup and hooks promise fulfillment. | | `catch` | `onRejected` | `Promise` | Handles promise rejection flows. | | `finally` | `onFinally` | `Promise` | Executes cleanup callbacks regardless of success or failure. | Sources: [drizzle-orm/src/sqlite-core/query-builders/count.ts:17-30](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/count.ts#L17-L30), [drizzle-orm/src/sqlite-core/query-builders/count.ts:48-75](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/count.ts#L48-L75) ## Update Mutation Query Builders ### Mutation Query Builder Structure and Generic Contracts The SQLite update infrastructure relies on `SQLiteUpdateBase` and the `SQLiteUpdate` interface to define typing boundaries, result configurations, and execution handles. The `SQLiteUpdate` interface extends `SQLWrapper` and `QueryPromise`, resolving to either `TRunResult` when no returning clause is specified, or `TReturning[]` when a returning clause is active. ```typescript TResultType extends 'sync' | 'async' = 'sync' | 'async', TRunResult = unknown, TFrom extends SQLiteTable | Subquery | SQLiteViewBase | SQL | undefined = undefined, TReturning = undefined, TDynamic extends boolean = false, TExcludedMethods extends string = never, > extends SQLWrapper, QueryPromise { readonly _: { readonly dialect: 'sqlite'; readonly table: TTable; readonly resultType: TResultType; readonly runResult: TRunResult; readonly from: TFrom; readonly returning: TReturning; readonly dynamic: TDynamic; readonly excludedMethods: TExcludedMethods; readonly result: TReturning extends undefined ? TRunResult : TReturning[]; }; } ``` Sources: [drizzle-orm/src/sqlite-core/query-builders/update.ts:205-223](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/update.ts#L205-L223) The base implementation class `SQLiteUpdateBase` provides the underlying property structure and initializes the builder configuration via its constructor, storing the target table, update set mapping, session instance, dialect reference, and optional CTE with-list. ```typescript export class SQLiteUpdateBase< TTable extends SQLiteTable = SQLiteTable, // eslint-disable-next-line @typescript-eslint/no-unused-vars TResultType extends 'sync' | 'async' = 'sync' | 'async', TRunResult = unknown, TFrom extends SQLiteTable | Subquery | SQLiteViewBase | SQL | undefined = undefined, TReturning = undefined, // eslint-disable-next-line @typescript-eslint/no-unused-vars TDynamic extends boolean = false, // eslint-disable-next-line @typescript-eslint/no-unused-vars TExcludedMethods extends string = never, > extends QueryPromise implements RunnableQuery, SQLWrapper { static override readonly [entityKind]: string = 'SQLiteUpdate'; /** @internal */ config: SQLiteUpdateConfig; constructor( table: TTable, set: UpdateSet, private session: SQLiteSession, private dialect: SQLiteDialect, withList?: Subquery[], ) { super(); this.config = { set, table, withList, joins: [] }; } ``` Sources: [drizzle-orm/src/sqlite-core/query-builders/update.ts:225-254](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/update.ts#L225-L254) > [!NOTE] > `SQLiteUpdateBase` enforces entity identification by overriding the static `[entityKind]` symbol with the string `'SQLiteUpdate'`. ### Update Set Mapping and Execution Lifecycle Query construction proceeds by capturing mutation fields through the constructor's `set` parameter (`UpdateSet`) and configuring secondary clauses such as source tables via the `from` method, which returns an extended `SQLiteUpdateWithJoins` builder instance. ```typescript from( source: TFrom, ): SQLiteUpdateWithJoins { this.config.from = source; ``` Sources: [drizzle-orm/src/sqlite-core/query-builders/update.ts:255-258](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/update.ts#L255-L258) | Generic Parameter | Default Value | Purpose | | :--- | :--- | :--- | | `TTable` | `SQLiteTable` | Represents the target database table being updated. | | `TResultType` | `'sync' \| 'async'` | Determines whether query resolution is synchronous or asynchronous. | | `TRunResult` | `unknown` | Defines the raw execution result type when no returning clause is used. | | `TFrom` | `undefined` | Models additional source tables, subqueries, views, or raw SQL fragments for joins. | | `TReturning` | `undefined` | Specifies the shape of returned rows if a returning clause is supplied. | | `TDynamic` | `false` | Indicates whether dynamic method chaining restrictions are relaxed. | | `TExcludedMethods` | `never` | Tracks methods that have been disabled via prior builder chains. | Sources: [drizzle-orm/src/sqlite-core/query-builders/update.ts:205-223](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/update.ts#L205-L223) ## Type-Level Query Composition and Typing ### Selection Validation and Nullability Mappings Type-level composition handles join semantics, select modes, and nullability propagation through conditional mapped types. The `JoinType` union specifies supported join categories, while `JoinNullability` and `ApplyNullability` manage column and table row optionality based on join participation. ```typescript export type JoinType = 'inner' | 'left' | 'right' | 'full' | 'cross'; export type JoinNullability = 'nullable' | 'not-null'; export type ApplyNullability = TNullability extends 'nullable' ? T | null : TNullability extends 'null' ? null : T; ``` Sources: [drizzle-orm/src/query-builders/select.types.ts:9-15](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/query-builders/select.types.ts#L9-L15) | Join Type | Nullability Mapping Behavior | | :--- | :--- | | `inner` | Appends `'not-null'` to joined table selection. | | `left` | Appends `'nullable'` to joined table selection. | | `right` | Sets existing nullability map to `'nullable'` and assigns `'not-null'` to the joined table. | | `full` | Sets all existing entries and the joined table to `'nullable'`. | | `cross` | Appends `'not-null'` to joined table selection. | Sources: [drizzle-orm/src/query-builders/select.types.ts:137-147](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/query-builders/select.types.ts#L137-L147) > [!WARNING] > Attempting to reference raw, unaliased `SQL` expressions inside subquery selections triggers a `DrizzleTypeError` requiring an explicit alias assignment via `.as()`. Sources: [drizzle-orm/src/query-builders/select.types.ts:122-124](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/query-builders/select.types.ts#L122-L124) ### Result Inference and Dynamic Builders Select execution results resolve dynamically across `'partial'`, `'single'`, and `'multiple'` modes using `SelectResult`. Type testing frameworks validate these inferences against expected output shapes, ensuring that chained methods like `where`, `having`, `groupBy`, `orderBy`, and `for` respect single-invocation constraints. ```typescript export type SelectMode = 'partial' | 'single' | 'multiple'; export type SelectResult< TResult, TSelectMode extends SelectMode, TNullabilityMap extends Record, > = TSelectMode extends 'partial' ? SelectPartialResult : TSelectMode extends 'single' ? SelectResultFields : ApplyNotNullMapToJoins, TNullabilityMap>; ``` Sources: [drizzle-orm/src/query-builders/select.types.ts:37-45](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/query-builders/select.types.ts#L37-L45) > [!NOTE] > Dynamic query wrappers accept both `GelSelect` and `GelSelectQueryBuilder` instances when enabling runtime flexibility via `$dynamic()`. Sources: [drizzle-orm/type-tests/geldb/select.ts:1004-1020](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/select.ts#L1004-L1020) ## Related - [SQL Template Engine](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/sql-template-engine) - [Sessions and Transactions](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/sessions-and-transactions) --- ## Technical docs: Sessions and Transactions URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/sessions-and-transactions
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-orm/src/libsql/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/session.ts) - [drizzle-orm/src/sqlite-proxy/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-proxy/session.ts) - [drizzle-orm/src/singlestore/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore/session.ts) - [drizzle-orm/src/bun-sql/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/bun-sql/session.ts) - [drizzle-orm/src/netlify-db/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/session.ts) - [drizzle-orm/src/planetscale-serverless/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/planetscale-serverless/session.ts) - [drizzle-orm/src/neon-serverless/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-serverless/session.ts) - [drizzle-orm/src/tidb-serverless/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/tidb-serverless/session.ts) - [drizzle-orm/src/mysql2/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql2/session.ts) - [drizzle-orm/src/pglite/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pglite/session.ts) - [drizzle-orm/src/postgres-js/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/postgres-js/session.ts) - [drizzle-orm/src/node-postgres/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/node-postgres/session.ts) - [drizzle-orm/src/singlestore-core/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/session.ts) - [drizzle-orm/src/aws-data-api/pg/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/aws-data-api/pg/session.ts) - [drizzle-orm/src/gel/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel/session.ts) - [drizzle-orm/src/mysql-core/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/session.ts) - [drizzle-orm/src/op-sqlite/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/op-sqlite/session.ts) - [drizzle-orm/src/vercel-postgres/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/vercel-postgres/session.ts) - [drizzle-orm/src/pg-proxy/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-proxy/session.ts) - [drizzle-orm/src/d1/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/d1/session.ts) - [drizzle-orm/src/neon-http/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-http/session.ts) - [drizzle-orm/src/pg-core/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/session.ts) - [drizzle-orm/src/bun-sqlite/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/bun-sqlite/session.ts) - [drizzle-orm/src/pg-core/db.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/db.ts) - [drizzle-orm/src/sqlite-core/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/session.ts) - [drizzle-orm/src/better-sqlite3/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/better-sqlite3/session.ts) - [drizzle-orm/src/sql-js/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql-js/session.ts) - [drizzle-orm/src/sqlite-core/db.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/db.ts) - [drizzle-orm/src/prisma/sqlite/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/sqlite/session.ts) - [drizzle-orm/src/gel-core/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/session.ts)
## Overview Sessions and transactions form the execution layer that bridges high-level query builders and low-level database drivers across diverse relational dialects and runtimes. By defining unified session abstractions like PostgreSQL Core, MySQL Core, and SQLite Core, the system standardizes statement preparation, execution pipelines, and result mapping regardless of whether queries run synchronously in Node.js or asynchronously across edge and serverless environments. Sources: [drizzle-orm/src/pg-core/session.ts:168-234](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/session.ts#L168-L234), [drizzle-orm/src/mysql-core/session.ts:170-238](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/session.ts#L170-L238), [drizzle-orm/src/sqlite-core/session.ts:212-323](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/session.ts#L212-L323) ## Session Architecture and Prepared Queries ### Statement Execution Methods and Runtimes The execution interface centers around dialect-specific session abstractions—such as `LibSQLSession`, `SQLiteRemoteSession`, `BunSQLSession`, `NeonSession`, `PgliteSession`, `GelDbSession`, `SQLJsSession`, and `PrismaSQLiteSession`—which inherit from shared base classes like `SQLiteSession` and `PgSession`. These sessions encapsulate database clients, configuration options, and telemetry loggers (`NoopLogger` or custom implementations), providing uniform methods for query compilation, statement preparation, and execution dispatch across diverse underlying runtimes. Prepared statements are managed by specialized subclasses including `LibSQLPreparedQuery`, `RemotePreparedQuery`, `BunSQLPreparedQuery`, `NeonPreparedQuery`, `GelDbPreparedQuery`, `PreparedQuery` (for sql.js), and `PrismaSQLitePreparedQuery`. These query objects accept query fragments and parameters, resolve placeholder values via `fillPlaceholders`, record execution metrics through [logging and tracing](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/logging-and-tracing) hooks, and map raw driver outputs into structured domain entities. ```mermaid graph TD S["Session (`LibSQLSession`, `BunSQLSession`, etc.)"] -->|"prepareQuery()"| PQ["Prepared Query (`LibSQLPreparedQuery`, `BunSQLPreparedQuery`, etc.)"] PQ -->|"fillPlaceholders()"| P["Parameterized Query"] P -->|"logQuery()"| L["Logger / Tracer"] P -->|"queryWithCache() / driver execute"| D["Driver Client"] D -->|"Raw Rows"| M["mapResultRow() / customResultMapper"] ``` Sources: [drizzle-orm/src/libsql/session.ts:29-75](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/session.ts#L29-L75), [drizzle-orm/src/sqlite-proxy/session.ts:29-74](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-proxy/session.ts#L29-L74), [drizzle-orm/src/bun-sql/session.ts:19-103](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/bun-sql/session.ts#L19-L103), [drizzle-orm/src/neon-serverless/session.ts:188-233](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-serverless/session.ts#L188-L233), [drizzle-orm/src/pglite/session.ts:165-195](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pglite/session.ts#L165-L195), [drizzle-orm/src/gel/session.ts:17-102](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel/session.ts#L17-L102), [drizzle-orm/src/sql-js/session.ts:24-66](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql-js/session.ts#L24-L66), [drizzle-orm/src/prisma/sqlite/session.ts:62-83](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/sqlite/session.ts#L62-L83) Prepared query contracts support a standard suite of execution methods—`run`, `all`, `get`, `values`, and `execute`—whose availability and return formats vary by driver implementation. For instance, synchronous sql.js prepared queries handle direct statement preparation, step iteration, result object extraction, and explicit resource freeing via `stmt.free()`, whereas asynchronous Bun SQL and Neon queries wrap execution within telemetry spans and cache layers. | Session Class | Driver Client Type | Execution Mode | Supported Query Operations | | :--- | :--- | :--- | :--- | | `LibSQLSession` | `@libsql/client` `Client` | Async | `prepareQuery`, `batch`, `migrate`, `transaction` | | `SQLiteRemoteSession` | `RemoteCallback` | Async | `prepareQuery`, `batch`, `transaction` | | `BunSQLSession` | Bun `SQL` | Async | `prepareQuery`, `query`, `transaction`, `unsafe` | | `NeonSession` | Neon `Pool` / `Client` | Async | `prepareQuery`, `query`, `queryObjects`, `count`, `transaction` | | `PgliteSession` | `PgliteClient` | Async | `prepareQuery`, `transaction`, `count` | | `GelDbSession` | Gel `Client` / `Transaction` | Async | `prepareQuery`, `transaction`, `count` | | `SQLJsSession` | sql.js `Database` | Sync | `prepareQuery`, `transaction` | | `PrismaSQLiteSession` | Prisma Client extension | Async | `prepareQuery`, `transaction` (unimplemented) | Sources: [drizzle-orm/src/libsql/session.ts:29-129](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/session.ts#L29-L129), [drizzle-orm/src/sqlite-proxy/session.ts:29-105](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-proxy/session.ts#L29-L105), [drizzle-orm/src/bun-sql/session.ts:110-188](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/bun-sql/session.ts#L110-L188), [drizzle-orm/src/neon-serverless/session.ts:188-281](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-serverless/session.ts#L188-L281), [drizzle-orm/src/pglite/session.ts:165-195](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pglite/session.ts#L165-L195), [drizzle-orm/src/gel/session.ts:109-168](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel/session.ts#L109-L168), [drizzle-orm/src/sql-js/session.ts:24-66](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql-js/session.ts#L24-L66), [drizzle-orm/src/prisma/sqlite/session.ts:62-89](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/sqlite/session.ts#L62-L89) > [!NOTE] > In sql.js sessions, binary field values (`Uint8Array`) are automatically normalized via `normalizeFieldValue` into Node `Buffer` instances when available, or decoded using `TextDecoder` if `Buffer` is absent. Sources: [drizzle-orm/src/sql-js/session.ts:197-210](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql-js/session.ts#L197-L210) ## Transaction Lifecycles and Rollback Semantics ### Demarcation and Scopes Transaction boundaries are managed via driver-specific demarcation methods wrapped in session abstractions. In `BunSQLSession`, transactions use the native `client.begin()` method, supplying a transaction-scoped client to instantiate `BunSQLTransaction`. Similarly, `PgliteSession` delegates directly to the underlying `client.transaction()` API, while `AwsDataApiSession` explicitly dispatches `BeginTransactionCommand`, `CommitTransactionCommand`, and `RollbackTransactionCommand` via the AWS Data API client. ```typescript override async transaction( transaction: (tx: AwsDataApiTransaction) => Promise, config?: PgTransactionConfig | undefined, ): Promise { const { transactionId } = await this.client.send(new BeginTransactionCommand(this.rawQuery)); const session = new AwsDataApiSession(this.client, this.dialect, this.schema, this.options, transactionId); const tx = new AwsDataApiTransaction(this.dialect, session, this.schema); if (config) { await tx.setTransaction(config); } try { const result = await transaction(tx); await this.client.send(new CommitTransactionCommand({ ...this.rawQuery, transactionId })); return result; } catch (e) { await this.client.send(new RollbackTransactionCommand({ ...this.rawQuery, transactionId })); throw e; } } ``` Sources: [drizzle-orm/src/bun-sql/session.ts:170-187](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/bun-sql/session.ts#L170-L187), [drizzle-orm/src/pglite/session.ts:170-187](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pglite/session.ts#L170-L187), [drizzle-orm/src/aws-data-api/pg/session.ts:238-256](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/aws-data-api/pg/session.ts#L238-L256) Neon and SQL.js sessions handle transaction boundaries by executing explicit raw SQL statements (`begin`, `commit`, and `rollback`) wrapped in `try...catch` blocks. In `NeonSession`, pool connections check whether the client instance is a `Pool` to release the client back to the pool in a `finally` block. ```typescript override async transaction( transaction: (tx: NeonTransaction) => Promise, config: PgTransactionConfig = {}, ): Promise { const session = this.client instanceof Pool // eslint-disable-line no-instanceof/no-instanceof ? new NeonSession(await this.client.connect(), this.dialect, this.schema, this.options) : this; const tx = new NeonTransaction(this.dialect, session, this.schema); await tx.execute(sql`begin ${tx.getTransactionConfigSQL(config)}`); try { const result = await transaction(tx); await tx.execute(sql`commit`); return result; } catch (error) { await tx.execute(sql`rollback`); throw error; } finally { if (this.client instanceof Pool) { // eslint-disable-line no-instanceof/no-instanceof (session.client as PoolClient).release(); } } } ``` Sources: [drizzle-orm/src/neon-serverless/session.ts:260-281](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-serverless/session.ts#L260-L281), [drizzle-orm/src/sql-js/session.ts:51-65](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql-js/session.ts#L51-L65) > [!NOTE] > In `SQLJsSession`, transaction configuration behaviors (such as deferred, immediate, or exclusive) are appended dynamically to the `begin` statement using `config.behavior`. Sources: [drizzle-orm/src/sql-js/session.ts:51-56](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql-js/session.ts#L51-L56) ### Nested Scopes and Savepoints Nested transaction blocks within driver implementations rely on database savepoints rather than multi-tier native transactions. Each nested scope increments `nestedIndex` to generate unique savepoint identifiers matching the pattern `sp1`, `sp2`, and so forth. | Transaction Class | Nested Implementation Mechanism | Savepoint Naming Pattern | Rollback on Error | | :--- | :--- | :--- | :--- | | `BunSQLTransaction` | `client.savepoint()` | Managed by Bun SQL | Automatic via driver block | | `NeonTransaction` | `savepoint` / `rollback to savepoint` | `sp${this.nestedIndex + 1}` | Explicit SQL command | | `TiDBServerlessTransaction` | `savepoint` / `rollback to savepoint` | `sp${this.nestedIndex + 1}` | Explicit SQL command | | `PgliteTransaction` | `savepoint` / `rollback to savepoint` | `sp${this.nestedIndex + 1}` | Explicit SQL command | | `AwsDataApiTransaction` | `savepoint` / `rollback to savepoint` | `sp${this.nestedIndex + 1}` | Explicit SQL command | | `SQLJsTransaction` | `savepoint` / `rollback to savepoint` | `sp${this.nestedIndex + 1}` | Explicit SQL command | Sources: [drizzle-orm/src/bun-sql/session.ts:206-219](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/bun-sql/session.ts#L206-L219), [drizzle-orm/src/neon-serverless/session.ts:290-302](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-serverless/session.ts#L290-L302), [drizzle-orm/src/tidb-serverless/session.ts:209-228](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/tidb-serverless/session.ts#L209-L228), [drizzle-orm/src/pglite/session.ts:203-220](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pglite/session.ts#L203-L220), [drizzle-orm/src/aws-data-api/pg/session.ts:265-284](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/aws-data-api/pg/session.ts#L265-L284), [drizzle-orm/src/sql-js/session.ts:74-86](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql-js/session.ts#L74-L86) > [!CAUTION] > When an error occurs inside a nested transaction block utilizing savepoints, the execution path triggers `rollback to savepoint spN` and releases or throws the error, preserving the outer transaction state. Sources: [drizzle-orm/src/neon-serverless/session.ts:298-301](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-serverless/session.ts#L298-L301), [drizzle-orm/src/sql-js/session.ts:82-85](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql-js/session.ts#L82-L85) ## Driver Connection Wrappers and Execution ### Connection Bridging and Client Execution Drizzle abstracts disparate underlying driver connection interfaces into uniform session and prepared query instances across runtimes. In environments powered by Bun SQL (`BunSQLSession`) and Pglite (`PgliteSession`), queries are dispatched using driver-native `.unsafe()` and `.transaction()` wrappers while capturing telemetry through OpenTelemetry spans. ```typescript async execute(placeholderValues: Record | undefined = {}): Promise { return tracer.startActiveSpan('drizzle.execute', async (span) => { const params = fillPlaceholders(this.params, placeholderValues); span?.setAttributes({ 'drizzle.query.text': this.queryString, 'drizzle.query.params': JSON.stringify(params), }); this.logger.logQuery(this.queryString, params); const { fields, queryString: query, client, joinsNotNullableMap, customResultMapper } = this; if (!fields && !customResultMapper) { return tracer.startActiveSpan('drizzle.driver.execute', async () => { return await this.queryWithCache(query, params, async () => { return await client.unsafe(query, params as any[]); }); }); } ``` Sources: [drizzle-orm/src/bun-sql/session.ts:40-58](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/bun-sql/session.ts#L40-L58), [drizzle-orm/src/pglite/session.ts:165-187](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pglite/session.ts#L165-L187) > [!NOTE] > Client adapters like `PrismaSQLitePreparedQuery` bridge SQLite execution by mapping calls directly to Prisma's `$queryRawUnsafe` API, while throwing unsupported errors for raw value arrays and transaction blocks. Sources: [drizzle-orm/src/prisma/sqlite/session.ts:33-56](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/sqlite/session.ts#L33-L56), [drizzle-orm/src/prisma/sqlite/session.ts:84-90](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/sqlite/session.ts#L84-L90) ### Synchronous and Asynchronous SQLite Execution Pipelines SQLite runtimes split execution semantics between synchronous in-memory drivers like `sql.js` and asynchronous mobile/edge drivers like `OP-SQLite`. `SQLJsSession` utilizes explicit statement preparation, parameter binding via `BindParams`, stepping via `stmt.step()`, and manual resource freeing via `stmt.free()`. ```typescript run(placeholderValues?: Record): void { const stmt = this.client.prepare(this.query.sql); const params = fillPlaceholders(this.query.params, placeholderValues ?? {}); this.logger.logQuery(this.query.sql, params); const result = stmt.run(params as BindParams); stmt.free(); return result; } ``` Sources: [drizzle-orm/src/sql-js/session.ts:106-116](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql-js/session.ts#L106-L116), [drizzle-orm/src/sql-js/session.ts:118-143](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql-js/session.ts#L118-L143) In contrast, `OPSQLiteSession` routes execution methods through asynchronous connection bindings: | Execution Method | OP-SQLite Driver Call | Return Type | | :--- | :--- | :--- | | `run` | `client.executeAsync(query, params)` | `QueryResult` | | `all` | `client.execute(query, params).rows?._array` | `T['all']` | | `values` | `client.executeRawAsync(query, params)` | `T['values']` | Sources: [drizzle-orm/src/op-sqlite/session.ts:135-142](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/op-sqlite/session.ts#L135-L142), [drizzle-orm/src/op-sqlite/session.ts:144-160](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/op-sqlite/session.ts#L144-L160), [drizzle-orm/src/op-sqlite/session.ts:187-193](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/op-sqlite/session.ts#L187-L193) > [!WARNING] > When decoding binary results in `SQLJsSession`, `normalizeFieldValue` checks `Uint8Array` instances and converts them using `Buffer.from()` if available, or `TextDecoder` otherwise, throwing an error if neither polyfill exists. Sources: [drizzle-orm/src/sql-js/session.ts:197-210](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql-js/session.ts#L197-L210) ## HTTP and Serverless Transaction Emulation ### Stateless HTTP Gateways and WebSocket Upgrades Stateless HTTP gateways and serverless environments present distinct coordination challenges for transaction semantics because HTTP protocols do not inherently maintain persistent connection state between requests. Drivers such as Neon HTTP (`NeonHttpSession`) execute queries over stateless HTTPS connections using `@neondatabase/serverless`, which inherently prevents multi-statement transaction execution blocks since each query can hit a different serverless container or worker instance. Consequently, calling `transaction()` on `NeonHttpSession` throws an error explicitly stating that transactions are unsupported in the `neon-http` driver. ```typescript override async transaction( _transaction: (tx: NeonTransaction) => Promise, // eslint-disable-next-line @typescript-eslint/no-unused-vars _config: PgTransactionConfig = {}, ): Promise { throw new Error('No transactions support in neon-http driver'); } ``` Sources: [drizzle-orm/src/neon-http/session.ts:248-254](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-http/session.ts#L248-L254) In contrast, hybrid adapters like Netlify DB (`NetlifyDbSession`) manage this limitation by bridging HTTP and WebSocket protocols. When a transaction is initiated, `NetlifyDbSession` acquires a dedicated `PoolClient` instance from an underlying connection pool, establishes a persistent WebSocket connection, executes `begin` alongside transaction configuration parameters, and executes the transactional callback inside `NetlifyDbTransaction`. ```typescript await tx.execute(sql`begin ${tx.getTransactionConfigSQL(config)}`); try { const result = await transaction(tx); await tx.execute(sql`commit`); return result; } catch (error) { await tx.execute(sql`rollback`); throw error; } finally { poolClient.release(); } } ``` Sources: [drizzle-orm/src/netlify-db/session.ts:168-179](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/session.ts#L168-L179) > [!WARNING] > Netlify DB WebSocket sessions (`NetlifyDbWsSession`) explicitly throw an error if nested `transaction()` calls are invoked directly on the session instance, enforcing that inner scopes route through `NetlifyDbTransaction` savepoint handling instead. Sources: [drizzle-orm/src/netlify-db/session.ts:259-265](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/session.ts#L259-L265) ### Client-Side Transaction Coordination AWS Data API and remote proxy runtimes coordinate transactions by passing explicit transaction identifiers across stateless API requests. `AwsDataApiSession` manages transaction blocks by sending a `BeginTransactionCommand` to the AWS Data API client, receiving a unique `transactionId` string, and injecting that identifier into every subsequent prepared query statement executed within that scope. ```typescript override async transaction( transaction: (tx: AwsDataApiTransaction) => Promise, config?: PgTransactionConfig | undefined, ): Promise { const { transactionId } = await this.client.send(new BeginTransactionCommand(this.rawQuery)); const session = new AwsDataApiSession(this.client, this.dialect, this.schema, this.options, transactionId); const tx = new AwsDataApiTransaction(this.dialect, session, this.schema); if (config) { await tx.setTransaction(config); } try { const result = await transaction(tx); await this.client.send(new CommitTransactionCommand({ ...this.rawQuery, transactionId })); return result; } catch (e) { await this.client.send(new RollbackTransactionCommand({ ...this.rawQuery, transactionId })); throw e; } } ``` Sources: [drizzle-orm/src/aws-data-api/pg/session.ts:238-256](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/aws-data-api/pg/session.ts#L238-L256) Remote proxy drivers (`PgRemoteSession`) bypass transaction handling entirely because the underlying remote callback transport lacks stateful transaction coordination, throwing an error on invocation. | Driver Session Class | Transaction Support Strategy | Behavior on `transaction()` | | :--- | :--- | :--- | | `NeonHttpSession` | None (Stateless HTTP) | Throws `'No transactions support in neon-http driver'` | | `NetlifyDbSession` | WebSocket Pool Client | Acquires `PoolClient`, runs `begin`/`commit`/`rollback`, releases client | | `AwsDataApiSession` | API Transaction ID | Sends `BeginTransactionCommand`, tracks `transactionId`, sends `CommitTransactionCommand` or `RollbackTransactionCommand` | | `PgRemoteSession` | Remote Proxy Callback | Throws `'Transactions are not supported by the Postgres Proxy driver'` | Sources: [drizzle-orm/src/neon-http/session.ts:248-254](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-http/session.ts#L248-L254), [drizzle-orm/src/netlify-db/session.ts:168-179](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/session.ts#L168-L179), [drizzle-orm/src/aws-data-api/pg/session.ts:238-256](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/aws-data-api/pg/session.ts#L238-L256), [drizzle-orm/src/pg-proxy/session.ts:70-75](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-proxy/session.ts#L70-L75) > [!NOTE] > Netlify DB explicitly verifies that a WebSocket constructor is available globally before initializing serverless query execution, assigning `WebSocket` to `neonConfig.webSocketConstructor` if unassigned. Sources: [drizzle-orm/src/netlify-db/session.ts:39-45](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/session.ts#L39-L45) ## Batch Pipelines and Proxy Sessions ### Batch Item Aggregation Batch execution models in Drizzle aggregate arrays of query items into single pipeline requests dispatched to remote drivers or database clients. In `LibSQLSession`, the `batch()` method iterates over incoming `queries`, invokes `_prepare()` on each item to generate a prepared query, extracts the underlying SQL string and parameter arguments via `getQuery()`, and pushes them into an `InStatement` array. ```typescript async batch[] | readonly BatchItem<'sqlite'>[]>(queries: T) { const preparedQueries: PreparedQuery[] = []; const builtQueries: InStatement[] = []; for (const query of queries) { const preparedQuery = query._prepare(); const builtQuery = preparedQuery.getQuery(); preparedQueries.push(preparedQuery); builtQueries.push({ sql: builtQuery.sql, args: builtQuery.params as InArgs }); } ``` Sources: [drizzle-orm/src/libsql/session.ts:77-86](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/session.ts#L77-L86) Once the built statements are assembled, `LibSQLSession` invokes `this.client.batch(builtQueries)` and maps the resulting array of driver outputs back through each individual prepared query's `mapResult()` handler with array mode enabled. ```typescript const batchResults = await this.client.batch(builtQueries); return batchResults.map((result, i) => preparedQueries[i]!.mapResult(result, true)); } ``` Sources: [drizzle-orm/src/libsql/session.ts:88-90](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/session.ts#L88-L90) Similarly, `LibSQLSession` provides a `migrate()` method that mirrors the exact structure of `batch()` but delegates to `this.client.migrate(builtQueries)` for migration-specific pipeline execution. ```typescript async migrate[] | readonly BatchItem<'sqlite'>[]>(queries: T) { const preparedQueries: PreparedQuery[] = []; const builtQueries: InStatement[] = []; for (const query of queries) { const preparedQuery = query._prepare(); const builtQuery = preparedQuery.getQuery(); preparedQueries.push(preparedQuery); builtQueries.push({ sql: builtQuery.sql, args: builtQuery.params as InArgs }); } const batchResults = await this.client.migrate(builtQueries); return batchResults.map((result, i) => preparedQueries[i]!.mapResult(result, true)); } ``` Sources: [drizzle-orm/src/libsql/session.ts:92-105](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/session.ts#L92-L105) ### Remote Proxy Transports Proxy and HTTP-backed drivers implement batch pipelines by marshalling query descriptors across remote transport boundaries. In `NeonHttpSession`, the `batch()` method processes incoming queries by creating `NeonQueryPromise` instances with `fullResults: true` and array mode determined by each prepared query's `isResponseInArrayMode()` configuration. ```typescript async batch, T extends Readonly<[U, ...U[]]>>( queries: T, ) { const preparedQueries: PreparedQuery[] = []; const builtQueries: NeonQueryPromise[] = []; for (const query of queries) { const preparedQuery = query._prepare(); const builtQuery = preparedQuery.getQuery(); preparedQueries.push(preparedQuery); builtQueries.push( this.clientQuery(builtQuery.sql, builtQuery.params, { fullResults: true, arrayMode: preparedQuery.isResponseInArrayMode(), }), ); } ``` Sources: [drizzle-orm/src/neon-http/session.ts:199-214](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-http/session.ts#L199-L214) The collected promises are then dispatched to Neon's HTTP client transaction endpoint using `this.client.transaction(builtQueries, queryConfig)` before mapping the batch results back to their respective prepared queries. ```typescript const batchResults = await this.client.transaction(builtQueries, queryConfig); return batchResults.map((result, i) => preparedQueries[i]!.mapResult(result, true)) as any; ``` Sources: [drizzle-orm/src/neon-http/session.ts:216-218](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-http/session.ts#L216-L218) For SQLite proxy sessions (`SQLiteRemoteSession`), batch aggregation maps query parameters alongside explicit execution methods (`run`, `all`, `values`, or `get`) into remote transport payloads before invoking `this.batchCLient`. ```typescript async batch[] | readonly BatchItem<'sqlite'>[]>(queries: T) { const preparedQueries: PreparedQuery[] = []; const builtQueries: { sql: string; params: any[]; method: 'run' | 'all' | 'values' | 'get' }[] = []; for (const query of queries) { const preparedQuery = query._prepare(); const builtQuery = (preparedQuery as RemotePreparedQuery).getQuery(); preparedQueries.push(preparedQuery); builtQueries.push({ sql: builtQuery.sql, params: builtQuery.params, method: builtQuery.method }); } const batchResults = await (this.batchCLient as AsyncBatchRemoteCallback)(builtQueries); return batchResults.map((result, i) => preparedQueries[i]!.mapResult(result, true)); } ``` Sources: [drizzle-orm/src/sqlite-proxy/session.ts:76-89](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-proxy/session.ts#L76-L89) > [!NOTE] > `SQLiteRemoteSession` extracts raw batch result rows using session-specific helpers like `extractRawAllValueFromBatchResult`, `extractRawGetValueFromBatchResult`, and `extractRawValuesValueFromBatchResult` tailored to `SqliteRemoteResult` structures. Sources: [drizzle-orm/src/sqlite-proxy/session.ts:107-117](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-proxy/session.ts#L107-L117) ## Related - [Query Builder Foundation](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/query-builder-foundation) - [Drivers And Runtimes](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/drivers-and-runtimes/drivers-and-runtimes) --- ## Technical docs: Query Caching URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/query-caching
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-orm/src/cache/upstash/cache.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/cache/upstash/cache.ts) - [drizzle-orm/src/cache/upstash/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/cache/upstash/index.ts) - [drizzle-orm/src/singlestore-core/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/session.ts) - [drizzle-orm/src/singlestore/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore/session.ts) - [drizzle-orm/src/mysql-core/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/session.ts) - [drizzle-orm/src/planetscale-serverless/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/planetscale-serverless/session.ts) - [drizzle-orm/src/sqlite-core/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/session.ts) - [drizzle-orm/src/sqlite-proxy/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-proxy/session.ts) - [drizzle-orm/src/tidb-serverless/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/tidb-serverless/session.ts) - [drizzle-orm/src/gel-core/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/session.ts) - [drizzle-orm/src/neon-serverless/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-serverless/session.ts) - [drizzle-orm/src/mysql2/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql2/session.ts) - [drizzle-orm/src/cache/core/cache.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/cache/core/cache.ts) - [drizzle-orm/src/libsql/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/session.ts) - [drizzle-orm/src/node-postgres/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/node-postgres/session.ts) - [drizzle-orm/src/vercel-postgres/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/vercel-postgres/session.ts) - [drizzle-orm/src/bun-sql/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/bun-sql/session.ts) - [drizzle-orm/src/pg-proxy/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-proxy/session.ts) - [drizzle-orm/src/xata-http/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/xata-http/session.ts) - [drizzle-orm/src/pg-core/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/session.ts) - [drizzle-orm/src/gel/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel/session.ts) - [drizzle-orm/src/pglite/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pglite/session.ts) - [drizzle-orm/src/mysql-proxy/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-proxy/session.ts) - [drizzle-orm/src/op-sqlite/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/op-sqlite/session.ts) - [drizzle-orm/src/neon-http/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-http/session.ts) - [drizzle-orm/src/singlestore-core/db.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/db.ts) - [drizzle-orm/src/cache/core/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/cache/core/index.ts) - [drizzle-orm/src/aws-data-api/pg/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/aws-data-api/pg/session.ts) - [drizzle-orm/src/cache/core/types.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/cache/core/types.ts) - [drizzle-orm/src/durable-sqlite/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/durable-sqlite/session.ts)
## Overview Query caching in Drizzle provides an extensible caching infrastructure designed to intercept database execution, minimize redundant round-trips, and maintain synchronization between cached query results and underlying table mutations. By integrating caching abstractions directly into database sessions and prepared statements across supported SQL dialects, queries can be conditionally cached, retrieved via read-through patterns, and automatically invalidated when related tables undergo changes. Sources: [drizzle-orm/src/cache/core/cache.ts:5-42](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/cache/core/cache.ts#L5-L42), [drizzle-orm/src/singlestore-core/session.ts:68-152](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/session.ts#L68-L152), [drizzle-orm/src/mysql-core/session.ts:70-154](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/session.ts#L70-L154), [drizzle-orm/src/sqlite-core/session.ts:71-155](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/session.ts#L71-L155), [drizzle-orm/src/pg-core/session.ts:64-147](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/session.ts#L64-L147) ## Core Cache Abstractions and Contract ### Base Cache Class and Null Implementation ```typescript export abstract class Cache { static readonly [entityKind]: string = 'Cache'; abstract strategy(): 'explicit' | 'all'; /** * Invoked if we should check cache for cached response * @param sql * @param tables */ abstract get( key: string, tables: string[], isTag: boolean, isAutoInvalidate?: boolean, ): Promise; /** * Invoked if new query should be inserted to cache * @param sql * @param tables */ abstract put( hashedQuery: string, response: any, tables: string[], isTag: boolean, config?: CacheConfig, ): Promise; /** * Invoked if insert, update, delete was invoked * @param tables */ abstract onMutate( params: MutationOption, ): Promise; } export class NoopCache extends Cache { override strategy() { return 'all' as const; } static override readonly [entityKind]: string = 'NoopCache'; override async get(_key: string): Promise { return undefined; } override async put( _hashedQuery: string, _response: any, _tables: string[], _config?: any, ): Promise { // noop } override async onMutate(_params: MutationOption): Promise { // noop } } ``` Sources: [drizzle-orm/src/cache/core/cache.ts:5-65](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/cache/core/cache.ts#L5-L65) > [!NOTE] > `NoopCache` inherits from the abstract `Cache` base class and resolves cache strategies as `'all'` while returning `undefined` for `get` operations, effectively bypassing caching when no active provider is configured. ### Mutation Options and Query Hashing ```typescript export type MutationOption = { tags?: string | string[]; tables?: Table | Table[] | string | string[] }; export async function hashQuery(sql: string, params?: any[]) { const dataToHash = `${sql}-${JSON.stringify(params)}`; const encoder = new TextEncoder(); const data = encoder.encode(dataToHash); const hashBuffer = await crypto.subtle.digest('SHA-256', data); const hashArray = [...new Uint8Array(hashBuffer)]; const hashHex = hashArray.map((b) => b.toString(16).padStart(2, '0')).join(''); return hashHex; } ``` Sources: [drizzle-orm/src/cache/core/cache.ts:67-78](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/cache/core/cache.ts#L67-L78) > [!IMPORTANT] > `hashQuery` serializes the SQL string and parameter array using `JSON.stringify`, encodes the combined payload via `TextEncoder`, and computes a SHA-256 digest using `crypto.subtle.digest`, converting the resulting buffer into a hexadecimal string representation. ### Configuration Interfaces ```typescript export type CacheConfig = { /** * expire time, in seconds (a positive integer) */ ex?: number; /** * expire time, in milliseconds (a positive integer). */ px?: number; /** * Unix time at which the key will expire, in seconds (a positive integer). */ exat?: number; /** * Unix time at which the key will expire, in milliseconds (a positive integer) */ pxat?: number; /** * Retain the time to live associated with the key. */ keepTtl?: boolean; /** * Set an expiration (TTL or time to live) on one or more fields of a given hash key. * Used for HEXPIRE command */ hexOptions?: 'NX' | 'nx' | 'XX' | 'xx' | 'GT' | 'gt' | 'LT' | 'lt'; }; export type WithCacheConfig = { enable: boolean; config?: CacheConfig; tag?: string; autoInvalidate?: boolean }; ``` Sources: [drizzle-orm/src/cache/core/types.ts:1-29](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/cache/core/types.ts#L1-L29) | Configuration Property | Type | Description | | :--- | :--- | :--- | | `ex` | `number` | Expire time in seconds (positive integer) | | `px` | `number` | Expire time in milliseconds (positive integer) | | `exat` | `number` | Unix time at which the key will expire, in seconds | | `pxat` | `number` | Unix time at which the key will expire, in milliseconds | | `keepTtl` | `boolean` | Retain the time to live associated with the key | | `hexOptions` | `'NX' \| 'nx' \| 'XX' \| 'xx' \| 'GT' \| 'gt' \| 'LT' \| 'lt'` | Expiration options used for HEXPIRE commands | | `enable` | `boolean` | Enables or disables query caching | | `config` | `CacheConfig` | Underlying expiration and TTL configuration | | `tag` | `string` | Custom cache tag for group invalidation | | `autoInvalidate` | `boolean` | Automatically invalidate entries upon table mutation | Sources: [drizzle-orm/src/cache/core/types.ts:1-29](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/cache/core/types.ts#L1-L29) ## Upstash Redis Storage Implementation ### UpstashCache Storage Architecture and Key Prefixes The `UpstashCache` class extends the core `Cache` abstraction, utilizing the `@upstash/redis client package to implement distributed query caching with Lua scripting support. It relies on fixed naming prefixes and global key structures to manage cache entries, non-auto-invalidated queries, and relational table mappings. | Constant Name | Value / Prefix | Description | | :--- | :--- | :--- | | `compositeTableSetPrefix` | `'__CTS__'` | Prefix for sets denoting composite table names for unique tables | | `compositeTablePrefix` | `'__CT__'` | Prefix for Redis hashes mapping hash keys or tags to cache values | | `tagsMapKey` | `'__tagsMap__'` | Redis key holding the mapping of tags to composite table names | | `nonAutoInvalidateTablePrefix` | `'__nonAutoInvalidate__'` | Hash prefix storing queries whose auto-invalidation is disabled | Sources: [drizzle-orm/src/cache/upstash/cache.ts:60-95](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/cache/upstash/cache.ts#L60-L95) > [!NOTE] > Queries configured with auto-invalidation disabled bypass composite table hashes entirely, preventing them from being swept away during table mutation triggers and instead residing inside the `__nonAutoInvalidate__` Redis hash. Sources: [drizzle-orm/src/cache/upstash/cache.ts:87-94](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/cache/upstash/cache.ts#L87-L94) ### Lua Scripting for Retrieval and Mutation ```typescript const getByTagScript = ` local tagsMapKey = KEYS[1] -- tags map key local tag = ARGV[1] -- tag local compositeTableName = redis.call('HGET', tagsMapKey, tag) if not compositeTableName then return nil end local value = redis.call('HGET', compositeTableName, tag) return value `; const onMutateScript = ` local tagsMapKey = KEYS[1] -- tags map key local tables = {} -- initialize tables array local tags = ARGV -- tags array for i = 2, #KEYS do tables[#tables + 1] = KEYS[i] -- add all keys except the first one to tables end if #tags > 0 then for _, tag in ipairs(tags) do if tag ~= nil and tag ~= '' then local compositeTableName = redis.call('HGET', tagsMapKey, tag) if compositeTableName then redis.call('HDEL', compositeTableName, tag) end end end redis.call('HDEL', tagsMapKey, unpack(tags)) end local keysToDelete = {} if #tables > 0 then local compositeTableNames = redis.call('SUNION', unpack(tables)) for _, compositeTableName in ipairs(compositeTableNames) do keysToDelete[#keysToDelete + 1] = compositeTableName end for _, table in ipairs(tables) do keysToDelete[#keysToDelete + 1] = table end redis.call('DEL', unpack(keysToDelete)) end `; ``` Sources: [drizzle-orm/src/cache/upstash/cache.ts:8-54](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/cache/upstash/cache.ts#L8-L54) > [!IMPORTANT] > `UpstashCache` registers two compiled Lua scripts during initialization: `getByTagScript` (marked readonly) which looks up tag mappings and fetches cached values in a single atomic round-trip, and `onMutateScript` which executes set unions (`SUNION`), table deletions (`DEL`), and hash field removals (`HDEL`) when database modifications occur. Sources: [drizzle-orm/src/cache/upstash/cache.ts:8-54](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/cache/upstash/cache.ts#L8-L54), [drizzle-orm/src/cache/upstash/cache.ts:106-109](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/cache/upstash/cache.ts#L106-L109) ## Session Cache Lifecycle Coordination ### Execution Interception and Caching Mechanisms Database sessions across SQLite, PostgreSQL, and MySQL proxy implementations coordinate caching through prepared query abstractions. When a query is executed via `SQLiteRemoteSession`, `PgRemoteSession`, or `MySqlRemoteSession`, parameters are filled, queries are logged via `Logger`, and execution flows through read-through wrapper methods like `queryWithCache`. | Session Class | Driver Type | Cache Option Property | Default Cache Implementation | | :--- | :--- | :--- | :--- | | `SQLiteRemoteSession` | SQLite Proxy | `cache` | `NoopCache` | | `PgRemoteSession` | PostgreSQL Proxy | `cache` | `NoopCache` | | `MySqlRemoteSession` | MySQL Proxy | `cache` | `NoopCache` | Sources: [drizzle-orm/src/sqlite-proxy/session.ts:22-41](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-proxy/session.ts#L22-L41), [drizzle-orm/src/pg-proxy/session.ts:18-41](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-proxy/session.ts#L18-L41), [drizzle-orm/src/mysql-proxy/session.ts:27-50](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-proxy/session.ts#L27-L50) > [!NOTE] > Sessions initialize their internal logger and cache instances during construction, falling back to `NoopLogger` and `NoopCache` when options are omitted from the session configuration object. Sources: [drizzle-orm/src/sqlite-proxy/session.ts:38-41](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-proxy/session.ts#L38-L41), [drizzle-orm/src/pg-proxy/session.ts:32-41](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-proxy/session.ts#L32-L41), [drizzle-orm/src/mysql-proxy/session.ts:41-50](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-proxy/session.ts#L41-L50) ### Prepared Query Coordination Prepared query classes wrap execution commands (`run`, `all`, `get`, `values`, `execute`) and interact directly with session-level caching hooks by passing query strings, parameters, and execution callbacks. ```typescript async run(placeholderValues?: Record): Promise { const params = fillPlaceholders(this.query.params, placeholderValues ?? {}); this.logger.logQuery(this.query.sql, params); return await this.queryWithCache(this.query.sql, params, async () => { return await (this.client as AsyncRemoteCallback)(this.query.sql, params, 'run'); }); } ``` Sources: [drizzle-orm/src/sqlite-proxy/session.ts:177-183](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-proxy/session.ts#L177-L183) > [!WARNING] > In `PgRemoteSession`, query execution wrapped with OpenTelemetry spans (`drizzle.execute` and `drizzle.driver.execute`) records query text and parameter payloads as span attributes before delegating to `queryWithCache`. Sources: [drizzle-orm/src/pg-proxy/session.ts:113-154](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-proxy/session.ts#L113-L154) ## Cache Invalidation and Mutation Handling ### Mutation Options and Invalidation Triggers The core cache abstract contract defines the `onMutate` lifecycle hook to handle database modification operations such as inserts, updates, and deletes [[Cache Invalidation and Mutation Handling](#)], accepting a `MutationOption` parameter [[Cache Invalidation and Mutation Handling](#)]. This parameter structure supports optional tags and tables specified as single items or arrays of strings, table objects, or table instances [[Cache Invalidation and Mutation Handling](#)]. ```typescript export type MutationOption = { tags?: string | string[]; tables?: Table | Table[] | string | string[] }; ``` Sources: [drizzle-orm/src/cache/core/cache.ts:67-67](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/cache/core/cache.ts#L67-L67) > [!NOTE] > The `NoopCache` implementation provides an empty implementation for `onMutate`, safely ignoring table mutation events when caching is disabled or unconfigured [[Cache Invalidation and Mutation Handling](#)]. Sources: [drizzle-orm/src/cache/core/cache.ts:62-64](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/cache/core/cache.ts#L62-L64) ### Upstash Mutation Execution via Lua When database modifications trigger cache invalidation in `UpstashCache`, execution delegates to a specialized Lua script (`onMutateScript`) deployed to Redis [[Cache Invalidation and Mutation Handling](#)]. This script evaluates keys and arguments atomically to prune obsolete cache entries across composite table hashes and tag mapping structures [[Cache Invalidation and Mutation Handling](#)]. Sources: [drizzle-orm/src/cache/upstash/cache.ts:21-54](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/cache/upstash/cache.ts#L21-L54) > [!CAUTION] > The `onMutateScript` executes a set union (`SUNION`) across specified table keys to gather all composite table names linked to modified tables, subsequently issuing batch `DEL` commands to purge stale query results from Redis in a single atomic operation [[Cache Invalidation and Mutation Handling](#)]. Sources: [drizzle-orm/src/cache/upstash/cache.ts:42-53](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/cache/upstash/cache.ts#L42-L53) ## Driver and Serverless Runtime Adapters ### Session Options and NoopCache Wiring Serverless and lightweight driver sessions initialize their options by defaulting unconfigured cache properties to `NoopCache`. Across driver implementations including `TiDBServerlessSession`, `NeonSession`, `XataHttpSession`, `GelDbSession`, `PgliteSession`, `OPSQLiteSession`, and `AwsDataApiSession`, the session constructor extracts the optional cache from the session options object or instantiates a fresh `NoopCache` instance. ```typescript private options: TiDBServerlessSessionOptions = {}, ) { super(dialect); this.client = tx ?? baseClient; this.logger = options.logger ?? new NoopLogger(); this.cache = options.cache ?? new NoopCache(); } ``` Sources: [drizzle-orm/src/tidb-serverless/session.ts:124-130](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/tidb-serverless/session.ts#L124-L130) ```typescript constructor( private client: XataHttpClient, dialect: PgDialect, private schema: RelationalSchemaConfig | undefined, private options: XataHttpSessionOptions = {}, ) { super(dialect); this.logger = options.logger ?? new NoopLogger(); this.cache = options.cache ?? new NoopCache(); } ``` Sources: [drizzle-orm/src/xata-http/session.ts:110-119](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/xata-http/session.ts#L110-L119) ```typescript constructor( private client: GelClient, dialect: GelDialect, private schema: RelationalSchemaConfig | undefined, private options: GelSessionOptions = {}, ) { super(dialect); this.logger = options.logger ?? new NoopLogger(); this.cache = options.cache ?? new NoopCache(); } ``` Sources: [drizzle-orm/src/gel/session.ts:117-126](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel/session.ts#L117-L126) ```typescript constructor( private client: PgliteClient | Transaction, dialect: PgDialect, private schema: RelationalSchemaConfig | undefined, private options: PgliteSessionOptions = {}, ) { super(dialect); this.logger = options.logger ?? new NoopLogger(); this.cache = options.cache ?? new NoopCache(); } ``` Sources: [drizzle-orm/src/pglite/session.ts:131-141](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pglite/session.ts#L131-L141) ```typescript constructor( private client: OPSQLiteConnection, dialect: SQLiteAsyncDialect, private schema: RelationalSchemaConfig | undefined, options: OPSQLiteSessionOptions = {}, ) { super(dialect); this.logger = options.logger ?? new NoopLogger(); this.cache = options.cache ?? new NoopCache(); } ``` Sources: [drizzle-orm/src/op-sqlite/session.ts:37-46](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/op-sqlite/session.ts#L37-L46) ```typescript constructor( /** @internal */ readonly client: AwsDataApiClient, dialect: PgDialect, private schema: RelationalSchemaConfig | undefined, private options: AwsDataApiSessionOptions, /** @internal */ readonly transactionId: string | undefined, ) { super(dialect); this.rawQuery = { secretArn: options.secretArn, resourceArn: options.resourceArn, database: options.database, }; this.cache = options.cache ?? new NoopCache(); } ``` Sources: [drizzle-orm/src/aws-data-api/pg/session.ts:175-191](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/aws-data-api/pg/session.ts#L175-L191) ```typescript constructor( public client: TSQL, dialect: PgDialect, private schema: RelationalSchemaConfig | undefined, /** @internal */ readonly options: BunSQLSessionOptions = {}, ) { super(dialect); this.logger = options.logger ?? new NoopLogger(); this.cache = options.cache ?? new NoopCache(); } ``` Sources: [drizzle-orm/src/bun-sql/session.ts:120-130](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/bun-sql/session.ts#L120-L130) > [!NOTE] > Synchronous storage environments such as `SQLiteDOSession` omit cache constructor arguments entirely within their prepared query initializers because synchronous runtime caching is unsupported. Sources: [drizzle-orm/src/durable-sqlite/session.ts:100-111](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/durable-sqlite/session.ts#L100-L111) ### Prepared Query Cache Propagation When sessions instantiate prepared queries, the session-level `cache` reference is passed directly into the query constructor. Prepared query classes such as `TiDBServerlessPreparedQuery`, `NeonPreparedQuery`, `LibSQLPreparedQuery`, `VercelPgPreparedQuery`, `XataHttpPreparedQuery`, `GelDbPreparedQuery`, `PglitePreparedQuery`, `OPSQLitePreparedQuery`, `NeonHttpPreparedQuery`, `AwsDataApiPreparedQuery`, and `BunSQLPreparedQuery` forward the cache instance, query metadata, and cache configuration objects up to base query classes. | Driver Prepared Query | Client / Driver Type | Session Type | Cache Support | | :--- | :--- | :--- | :--- | | `TiDBServerlessPreparedQuery` | `Tx \| Connection` | `TiDBServerlessSession` | Yes | | `NeonPreparedQuery` | `Pool \| PoolClient \| Client` | `NeonSession` | Yes | | `LibSQLPreparedQuery` | `Client` | `LibSQLSession` | Yes | | `VercelPgPreparedQuery` | `VercelPool \| VercelClient \| VercelPoolClient` | `VercelPgSession` | Yes | | `XataHttpPreparedQuery` | `XataHttpClient` | `XataHttpSession` | Yes | | `GelDbPreparedQuery` | `Client \| Transaction` | `GelDbSession` | Yes | | `PglitePreparedQuery` | `PgliteClient \| Transaction` | `PgliteSession` | Yes | | `OPSQLitePreparedQuery` | `OPSQLiteConnection` | `OPSQLiteSession` | Yes | | `NeonHttpPreparedQuery` | `NeonHttpClient` | `NeonHttpSession` | Yes | | `AwsDataApiPreparedQuery` | `AwsDataApiClient` | `AwsDataApiSession` | Yes | | `BunSQLPreparedQuery` | `SQL` | `BunSQLSession` | Yes | | `SQLiteDOPreparedQuery` | `DurableObjectStorage` | `SQLiteDOSession` | No (`undefined`) | Sources: [drizzle-orm/src/tidb-serverless/session.ts:26-48](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/tidb-serverless/session.ts#L26-L48), [drizzle-orm/src/neon-serverless/session.ts:27-49](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-serverless/session.ts#L27-L49), [drizzle-orm/src/libsql/session.ts:165-192](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/session.ts#L165-L192), [drizzle-orm/src/vercel-postgres/session.ts:26-48](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/vercel-postgres/session.ts#L26-L48), [drizzle-orm/src/xata-http/session.ts:27-45](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/xata-http/session.ts#L27-L45), [drizzle-orm/src/gel/session.ts:17-37](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel/session.ts#L17-L37), [drizzle-orm/src/pglite/session.ts:19-42](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pglite/session.ts#L19-L42), [drizzle-orm/src/op-sqlite/session.ts:112-133](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/op-sqlite/session.ts#L112-L133), [drizzle-orm/src/neon-http/session.ts:29-48](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-http/session.ts#L29-L48), [drizzle-orm/src/aws-data-api/pg/session.ts:30-55](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/aws-data-api/pg/session.ts#L30-L55), [drizzle-orm/src/bun-sql/session.ts:19-38](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/bun-sql/session.ts#L19-L38), [drizzle-orm/src/durable-sqlite/session.ts:90-111](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/durable-sqlite/session.ts#L90-L111) > [!WARNING] > When transaction boundaries are opened in serverless sessions—such as `TiDBServerlessSession.transaction`, `GelDbSession.transaction`, `PgliteSession.transaction`, and `AwsDataApiSession.transaction`—new session instances are created with native transaction handles while preserving reference to the parent session's configured `cache` instance. Sources: [drizzle-orm/src/tidb-serverless/session.ts:173-191](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/tidb-serverless/session.ts#L173-L191), [drizzle-orm/src/gel/session.ts:154-162](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel/session.ts#L154-L162), [drizzle-orm/src/pglite/session.ts:170-187](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pglite/session.ts#L170-L187), [drizzle-orm/src/aws-data-api/pg/session.ts:238-256](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/aws-data-api/pg/session.ts#L238-L256) ## Related - [Sessions and Transactions](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/sessions-and-transactions) - [Query Builder Foundation](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/query-builder-foundation) --- ## Technical docs: Logging and Tracing URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/logging-and-tracing
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-orm/src/tracing.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/tracing.ts) - [drizzle-orm/src/sqlite-proxy/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-proxy/session.ts) - [drizzle-orm/src/gel-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/dialect.ts) - [drizzle-orm/src/libsql/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/session.ts) - [drizzle-orm/src/neon-serverless/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-serverless/session.ts) - [drizzle-orm/src/pg-core/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/session.ts) - [drizzle-orm/src/gel-core/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/session.ts) - [drizzle-orm/src/singlestore/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore/session.ts) - [drizzle-orm/src/pg-proxy/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-proxy/session.ts) - [drizzle-orm/src/bun-sql/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/bun-sql/session.ts) - [drizzle-orm/src/node-postgres/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/node-postgres/session.ts) - [drizzle-orm/src/pg-core/query-builders/insert.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/insert.ts) - [drizzle-orm/src/pg-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/dialect.ts) - [drizzle-orm/src/neon-http/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-http/session.ts) - [drizzle-orm/src/planetscale-serverless/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/planetscale-serverless/session.ts) - [drizzle-orm/src/tidb-serverless/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/tidb-serverless/session.ts) - [drizzle-orm/src/aws-data-api/pg/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/aws-data-api/pg/session.ts) - [drizzle-orm/src/mysql2/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql2/session.ts) - [drizzle-orm/src/singlestore-core/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/session.ts) - [drizzle-orm/src/gel-core/query-builders/insert.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/insert.ts) - [drizzle-orm/src/logger.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/logger.ts) - [drizzle-orm/src/tracing-utils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/tracing-utils.ts) - [drizzle-orm/src/op-sqlite/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/op-sqlite/session.ts) - [drizzle-orm/src/singlestore-proxy/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-proxy/session.ts) - [drizzle-orm/src/pg-core/query-builders/query.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/query.ts) - [drizzle-orm/src/sqlite-core/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/session.ts) - [drizzle-orm/src/query-promise.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/query-promise.ts) - [drizzle-orm/src/prisma/pg/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/pg/session.ts) - [drizzle-orm/src/singlestore-core/query-builders/delete.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/query-builders/delete.ts) - [drizzle-orm/src/mysql-core/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/session.ts)
## Overview Drizzle ORM provides an integrated diagnostic infrastructure combining OpenTelemetry tracing and structured query logging to observe and monitor query execution lifecycle events. The tracing subsystem uses the `@opentelemetry/api` package to wrap operations in active spans like `drizzle.operation`, `drizzle.prepareQuery`, `drizzle.buildSQL`, `drizzle.execute`, `drizzle.driver.execute`, and `drizzle.mapResponse`, automatically capturing error statuses and ending spans when execution completes. Concurrently, session-level logging dispatches query strings and parameters through logger implementations such as `DefaultLogger` and `ConsoleLogWriter`, formatting parameters with JSON stringification. This dual architecture allows applications to track performance metrics, inspect parameterized query statements across various driver runtimes, and handle diagnostic errors during failed database interactions. Sources: [drizzle-orm/src/tracing.ts:1-55](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/tracing.ts#L1-L55), [drizzle-orm/src/logger.ts:1-39](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/logger.ts#L1-L39), [drizzle-orm/src/pg-core/session.ts:195-207](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/session.ts#L195-L207), [drizzle-orm/src/pg-proxy/session.ts:114-154](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-proxy/session.ts#L114-L154) ## OpenTelemetry tracing subsystem architecture ### Tracer Configuration and Module Integration The OpenTelemetry tracing integration centers around the internal `tracer` object exported from `drizzle-orm/src/tracing.ts`. The module declares optional references to the `@opentelemetry/api` package and a raw tracer instance. When active spans are requested, the subsystem lazy-loads or references the tracer via `otel.trace.getTracer('drizzle-orm', npmVersion)`, utilizing the package version from `~/version.ts`. If `@opentelemetry/api` is not present in the runtime environment, span wrapping primitives bypass OpenTelemetry entirely and execute the provided callback directly. ```typescript import type { Span, Tracer } from '@opentelemetry/api'; import { iife } from '~/tracing-utils.ts'; import { npmVersion } from '~/version.ts'; let otel: typeof import('@opentelemetry/api') | undefined; let rawTracer: Tracer | undefined; // try { // otel = await import('@opentelemetry/api'); // } catch (err: any) { // if (err.code !== 'MODULE_NOT_FOUND' && err.code !== 'ERR_MODULE_NOT_FOUND') { // throw err; // } // } type SpanName = | 'drizzle.operation' | 'drizzle.prepareQuery' | 'drizzle.buildSQL' | 'drizzle.execute' | 'drizzle.driver.execute' | 'drizzle.mapResponse'; /** @internal */ export const tracer = { startActiveSpan unknown>(name: SpanName, fn: F): ReturnType { if (!otel) { return fn() as ReturnType; } if (!rawTracer) { rawTracer = otel.trace.getTracer('drizzle-orm', npmVersion); } ``` Sources: [drizzle-orm/src/tracing.ts:1-32](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/tracing.ts#L1-L32) > [!NOTE] > If `@opentelemetry/api` is missing from the environment, `tracer.startActiveSpan` skips span creation and transparently executes the workload function without throwing module resolution errors. ### Span Names and Wrapping Primitives The tracing subsystem defines a strict set of permitted operation names managed by the `SpanName` type. These identifiers cover the end-to-end query lifecycle from high-level operations down to driver-specific execution and response mapping. | Span Name | Description | | :--- | :--- | | `drizzle.operation` | Top-level query builder or transactional operation wrapper | | `drizzle.prepareQuery` | Statement preparation and parameter binding compilation | | `drizzle.buildSQL` | SQL string generation and dialect operator construction | | `drizzle.execute` | Query execution boundary across database sessions | | `drizzle.driver.execute` | Low-level driver communication and transport layer invocation | | `drizzle.mapResponse` | Raw database response parsing and entity mapping | ```typescript type SpanName = | 'drizzle.operation' | 'drizzle.prepareQuery' | 'drizzle.buildSQL' | 'drizzle.execute' | 'drizzle.driver.execute' | 'drizzle.mapResponse'; ``` Sources: [drizzle-orm/src/tracing.ts:15-21](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/tracing.ts#L15-L21) Span wrapping is executed via the `startActiveSpan` method, which delegates to an immediately invoked function expression helper (`iife`) defined in `drizzle-orm/src/tracing-utils.ts`. ```typescript export function iife(fn: (...args: T) => U, ...args: T): U { return fn(...args); } ``` Sources: [drizzle-orm/src/tracing-utils.ts:1-3](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/tracing-utils.ts#L1-L3-3) The span wrapper wraps the callback execution inside a `try...catch...finally` block. If an exception occurs, the span status is explicitly set to `otel.SpanStatusCode.ERROR` with the error message extracted from the thrown instance, before rethrowing the error and ending the span. ```typescript return iife( (otel, rawTracer) => rawTracer.startActiveSpan( name, ((span: Span) => { try { return fn(span); } catch (e) { span.setStatus({ code: otel.SpanStatusCode.ERROR, message: e instanceof Error ? e.message : 'Unknown error', // eslint-disable-line no-instanceof/no-instanceof }); throw e; } finally { span.end(); } }) as F, ), otel, rawTracer, ); }, ``` Sources: [drizzle-orm/src/tracing.ts:34-55](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/tracing.ts#L34-L55) ## Query builder span instrumentation ### Relational and Core Query Builder Spans Query builder methods integrate directly with the tracing subsystem by wrapping statement preparation and query execution inside active spans. In PostgreSQL relational query builders (`PgRelationalQuery`), the `_prepare` method wraps statement construction and relational mapping within a `drizzle.prepareQuery` span. ```typescript _prepare(name?: string): PgPreparedQuery { return tracer.startActiveSpan('drizzle.prepareQuery', () => { const { query, builtQuery } = this._toSQL(); return this.session.prepareQuery( builtQuery, undefined, name, true, (rawRows, mapColumnValue) => { const rows = rawRows.map((row) => mapRelationalRow(this.schema, this.tableConfig, row, query.selection, mapColumnValue) ); if (this.mode === 'first') { return rows[0] as TResult; } return rows as TResult; }, ); }); } ``` Sources: [drizzle-orm/src/pg-core/query-builders/query.ts:90-110](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/query.ts#L90-L110) When a relational query is executed via `execute()`, the operation is wrapped inside a `drizzle.operation` span before invoking the underlying prepared statement. ```typescript override execute(): Promise { return tracer.startActiveSpan('drizzle.operation', () => { return this._prepare().execute(undefined, this.authToken); }); } ``` Sources: [drizzle-orm/src/pg-core/query-builders/query.ts:152-156](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/query.ts#L152-L156) > [!NOTE] > Relational execution relies on `_prepare()` internally, causing a nested trace structure where `drizzle.operation` invokes `drizzle.prepareQuery` during statement compilation. ### Dialect Compilation and Execution Flow Query building across different dialects separates syntax compilation from session execution. For instance, SingleStore delete query builders (`SingleStoreDeleteBase`) invoke dialect builders like `buildDeleteQuery` and `sqlToQuery` during `getSQL` and `prepare` calls, passing table metadata and returning clauses directly to the session. ```typescript getSQL(): SQL { return this.dialect.buildDeleteQuery(this.config); } toSQL(): Query { const { typings: _typings, ...rest } = this.dialect.sqlToQuery(this.getSQL()); return rest; } prepare(): SingleStoreDeletePrepare { return this.session.prepareQuery( this.dialect.sqlToQuery(this.getSQL()), this.config.returning, undefined, undefined, undefined, { type: 'delete', tables: extractUsedTable(this.config.table), }, ) as SingleStoreDeletePrepare; } ``` Sources: [drizzle-orm/src/singlestore-core/query-builders/delete.ts:176-197](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/query-builders/delete.ts#L176-L197) ## Logger interface and default writers ### Logger Contracts and Writers The logging subsystem defines two core abstraction contracts: `Logger`, which exposes a `logQuery` method accepting a SQL query string and an array of unknown parameters, and `LogWriter`, which defines a simple `write` method for delivering text messages. ```typescript export interface Logger { logQuery(query: string, params: unknown[]): void; } export interface LogWriter { write(message: string): void; } ``` Sources: [drizzle-orm/src/logger.ts:3-9](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/logger.ts#L3-L9) The built-in output implementation is `ConsoleLogWriter`, which implements `LogWriter` by forwarding messages directly to `console.log`. Both `ConsoleLogWriter` and `DefaultLogger` define static `entityKind` metadata identifiers for runtime type inspection. ```typescript export class ConsoleLogWriter implements LogWriter { static readonly [entityKind]: string = 'ConsoleLogWriter'; write(message: string) { console.log(message); } } ``` Sources: [drizzle-orm/src/logger.ts:11-17](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/logger.ts#L11-L17) ### DefaultLogger and Formatting Logic `DefaultLogger` implements the `Logger` interface and accepts an optional configuration object containing a custom `LogWriter`. If no writer is supplied during instantiation, it defaults to a new instance of `ConsoleLogWriter`. ```typescript export class DefaultLogger implements Logger { static readonly [entityKind]: string = 'DefaultLogger'; readonly writer: LogWriter; constructor(config?: { writer: LogWriter }) { this.writer = config?.writer ?? new ConsoleLogWriter(); } ``` Sources: [drizzle-orm/src/logger.ts:19-26](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/logger.ts#L19-L26) When `logQuery` is invoked, `DefaultLogger` serializes each query parameter into a JSON string using `JSON.stringify`. If serialization fails due to circular references or unsupported types, it falls back to standard `String(p)` coercion. The formatted parameter array is appended to the query string under the suffix `-- params: [...]` only when parameters are present, and the resulting payload is dispatched to the configured writer. ```typescript logQuery(query: string, params: unknown[]): void { const stringifiedParams = params.map((p) => { try { return JSON.stringify(p); } catch { return String(p); } }); const paramsStr = stringifiedParams.length ? ` -- params: [${stringifiedParams.join(', ')}]` : ''; this.writer.write(`Query: ${query}${paramsStr}`); } } ``` Sources: [drizzle-orm/src/logger.ts:28-39](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/logger.ts#L28-L39) > [!TIP] > If `JSON.stringify` throws an error on complex parameter structures inside `DefaultLogger.logQuery`, the parameter falls back to `String(p)` rather than aborting query logging. Additionally, `NoopLogger` provides a null-pattern implementation of `Logger` where `logQuery` performs no operations. ```typescript export class NoopLogger implements Logger { static readonly [entityKind]: string = 'NoopLogger'; logQuery(): void { // noop } } ``` Sources: [drizzle-orm/src/logger.ts:41-47](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/logger.ts#L41-L47) ## Session level query logging integration ### Logger Dispatch Across Drivers Database sessions and prepared query implementations across drivers coordinate with the logging subsystem by invoking `logQuery` on the configured `Logger` instance right before executing any statement. Each driver binds placeholders via `fillPlaceholders` and dispatches the interpolated query text and parameter array. For example, `RemotePreparedQuery` in the SQLite proxy driver invokes `this.logger.logQuery(this.query.sql, params)` across its `run`, `all`, `get`, and `values` execution methods prior to invoking the remote client callback. ```typescript async run(placeholderValues?: Record): Promise { const params = fillPlaceholders(this.query.params, placeholderValues ?? {}); this.logger.logQuery(this.query.sql, params); return await this.queryWithCache(this.query.sql, params, async () => { return await (this.client as AsyncRemoteCallback)(this.query.sql, params, 'run'); }); } ``` Sources: [drizzle-orm/src/sqlite-proxy/session.ts:177-183](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-proxy/session.ts#L177-L183) Similarly, `LibSQLPreparedQuery` dispatches `logger.logQuery(query.sql, params)` across execution branches before executing statements through the underlying LibSQL client or active transaction. ```typescript async run(placeholderValues?: Record): Promise { const params = fillPlaceholders(this.query.params, placeholderValues ?? {}); this.logger.logQuery(this.query.sql, params); return await this.queryWithCache(this.query.sql, params, async () => { const stmt: InStatement = { sql: this.query.sql, args: params as InArgs }; return this.tx ? this.tx.execute(stmt) : this.client.execute(stmt); }); } ``` Sources: [drizzle-orm/src/libsql/session.ts:194-201](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/session.ts#L194-L201) PostgreSQL and MySQL drivers follow the same dispatch contract. In `NeonPreparedQuery`, `BunSQLPreparedQuery`, `NeonHttpPreparedQuery`, `TiDBServerlessPreparedQuery`, and `AwsDataApiPreparedQuery`, parameter binding precedes `logger.logQuery` invocation. `AwsDataApiPreparedQuery` extracts parameters from the raw query configuration input parameters before logging. ```typescript async values(placeholderValues: Record = {}): Promise { const params = fillPlaceholders(this.params, placeholderValues ?? {}); this.rawQuery.input.parameters = params.map((param, index) => ({ name: `${index + 1}`, ...toValueParam(param, this.typings[index]), })); this.options.logger?.logQuery(this.rawQuery.input.sql!, this.rawQuery.input.parameters); ``` Sources: [drizzle-orm/src/aws-data-api/pg/session.ts:110-119](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/aws-data-api/pg/session.ts#L110-L119) Session-level fallback helpers also integrate logging directly. In `TiDBServerlessSession`, direct `all` queries compute the query structure via the dialect, invoke `this.logger.logQuery(querySql.sql, querySql.params)`, and dispatch to the client. ```typescript override all(query: SQL): Promise { const querySql = this.dialect.sqlToQuery(query); this.logger.logQuery(querySql.sql, querySql.params); return this.client.execute(querySql.sql, querySql.params) as Promise; } ``` Sources: [drizzle-orm/src/tidb-serverless/session.ts:159-163](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/tidb-serverless/session.ts#L159-L163) ### Driver Logging Integration Matrix | Driver Module | Prepared Query Class | Session Class | Default Logger Fallback | | :--- | :--- | :--- | :--- | | `sqlite-proxy` | `RemotePreparedQuery` | `SQLiteProxySession` | `NoopLogger` | | `libsql` | `LibSQLPreparedQuery` | `LibSQLSession` | `NoopLogger` | | `neon-serverless` | `NeonPreparedQuery` | `NeonSession` | `NoopLogger` | | `bun-sql` | `BunSQLPreparedQuery` | `BunSQLSession` | `NoopLogger` | | `neon-http` | `NeonHttpPreparedQuery` | `NeonHttpSession` | `NoopLogger` | | `tidb-serverless` | `TiDBServerlessPreparedQuery` | `TiDBServerlessSession` | `NoopLogger` | | `aws-data-api/pg` | `AwsDataApiPreparedQuery` | `AwsDataApiSession` | `NoopLogger` | | `op-sqlite` | `OPSQLitePreparedQuery` | `OPSQLiteSession` | `NoopLogger` | | `singlestore-proxy` | `PreparedQuery` | `SingleStoreRemoteSession` | `NoopLogger` | | `prisma/pg` | `PrismaPgPreparedQuery` | `PrismaPgSession` | `NoopLogger` | Sources: [drizzle-orm/src/sqlite-proxy/session.ts:143-153](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-proxy/session.ts#L143-L153), [drizzle-orm/src/libsql/session.ts:165-174](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/session.ts#L165-L174), [drizzle-orm/src/neon-serverless/session.ts:27-38](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-serverless/session.ts#L27-L38), [drizzle-orm/src/bun-sql/session.ts:19-28](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/bun-sql/session.ts#L19-L28), [drizzle-orm/src/neon-http/session.ts:29-37](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-http/session.ts#L29-L37), [drizzle-orm/src/tidb-serverless/session.ts:26-34](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/tidb-serverless/session.ts#L26-L34), [drizzle-orm/src/aws-data-api/pg/session.ts:30-42](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/aws-data-api/pg/session.ts#L30-L42), [drizzle-orm/src/op-sqlite/session.ts:28-46](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/op-sqlite/session.ts#L28-L46), [drizzle-orm/src/singlestore-proxy/session.ts:29-45](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-proxy/session.ts#L29-L45), [drizzle-orm/src/prisma/pg/session.ts:16-25](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/pg/session.ts#L16-L25) > [!IMPORTANT] > When options omit a logger during session initialization (such as in `BunSQLSession`, `TiDBServerlessSession`, and `OPSQLiteSession`), sessions instantiate a `NoopLogger` to ensure safe method invocation without requiring explicit null checks across prepared queries. Sources: [drizzle-orm/src/bun-sql/session.ts:128-129](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/bun-sql/session.ts#L128-L129), [drizzle-orm/src/tidb-serverless/session.ts:128-129](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/tidb-serverless/session.ts#L128-L129), [drizzle-orm/src/op-sqlite/session.ts:44-45](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/op-sqlite/session.ts#L44-L45) ## Diagnostics and tracing error handling ### Active Span Exception Capture ```typescript startActiveSpan unknown>(name: SpanName, fn: F): ReturnType { if (!otel) { return fn() as ReturnType; } if (!rawTracer) { rawTracer = otel.trace.getTracer('drizzle-orm', npmVersion); } return iife( (otel, rawTracer) => rawTracer.startActiveSpan( name, ((span: Span) => { try { return fn(span); } catch (e) { span.setStatus({ code: otel.SpanStatusCode.ERROR, message: e instanceof Error ? e.message : 'Unknown error', // eslint-disable-line no-instanceof/no-instanceof }); throw e; } finally { span.end(); } }) as F, ), otel, rawTracer, ); }, ``` Sources: [drizzle-orm/src/tracing.ts:25-55](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/tracing.ts#L25-L55) The tracing subsystem intercepts exceptions during active span execution via the `startActiveSpan` wrapper. When an error is thrown within the callback function `fn(span)`, the execution catches the exception in a `try...catch` block, marks the OpenTelemetry span status as an error, and rethrows the original error. > [!WARNING] > If OpenTelemetry (`otel`) is not imported or available in the runtime environment, `startActiveSpan` bypasses span creation entirely and directly executes the callback function without error capture or status reporting. Sources: [drizzle-orm/src/tracing.ts:26-28](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/tracing.ts#L26-L28) ### Span Status and Error Properties | Condition | Span Status Code | Error Message Extraction Strategy | | :--- | :--- | :--- | | Caught value is an `Error` instance | `otel.SpanStatusCode.ERROR` | `e.message` | | Caught value is not an `Error` instance | `otel.SpanStatusCode.ERROR` | `'Unknown error'` | Sources: [drizzle-orm/src/tracing.ts:42-45](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/tracing.ts#L42-L45) > [!IMPORTANT] > The span lifecycle guarantees that `span.end()` is always invoked within a `finally` block, ensuring spans are closed even when query execution or response mapping throws an exception. Sources: [drizzle-orm/src/tracing.ts:47-49](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/tracing.ts#L47-L49) ## Related - [Sessions and Transactions](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/sessions-and-transactions) --- ## Technical docs: Dialects And Schema Schema Definition URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/dialects-and-schema/dialects-and-schema-schema-definition
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-kit/src/introspect-gel.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-gel.ts) - [drizzle-orm/type-tests/pg/tables.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/tables.ts) - [drizzle-kit/src/serializer/pgSerializer.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/pgSerializer.ts) - [drizzle-kit/src/introspect-pg.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-pg.ts) - [drizzle-kit/src/sqlgenerator.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/sqlgenerator.ts) - [drizzle-kit/src/serializer/pgSchema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/pgSchema.ts) - [drizzle-kit/src/serializer/gelSerializer.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/gelSerializer.ts) - [drizzle-orm/type-tests/geldb/tables.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/tables.ts) - [drizzle-kit/src/serializer/gelSchema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/gelSchema.ts) - [drizzle-kit/src/introspect-singlestore.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-singlestore.ts) - [drizzle-orm/src/pg-core/indexes.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/indexes.ts) - [drizzle-orm/src/pg-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/dialect.ts) - [drizzle-orm/src/gel-core/indexes.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/indexes.ts) - [drizzle-orm/src/pg-core/columns/common.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/columns/common.ts) - [drizzle-orm/src/pg-core/table.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/table.ts) - [drizzle-orm/src/pg-core/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/index.ts) - [drizzle-orm/src/gel-core/columns/all.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/columns/all.ts) - [drizzle-orm/src/gel-core/columns/common.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/columns/common.ts) - [drizzle-orm/src/gel-core/schema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/schema.ts) - [drizzle-orm/src/gel-core/table.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/table.ts) - [drizzle-orm/src/mysql-core/columns/all.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/columns/all.ts) - [drizzle-orm/src/mysql-core/columns/common.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/columns/common.ts) - [drizzle-orm/src/mysql-core/foreign-keys.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/foreign-keys.ts) - [drizzle-orm/src/mysql-core/indexes.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/indexes.ts) - [drizzle-orm/src/mysql-core/schema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/schema.ts) - [drizzle-orm/src/mysql-core/table.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/table.ts) - [drizzle-orm/src/pg-core/columns/all.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/columns/all.ts) - [drizzle-orm/src/pg-core/columns/postgis_extension/geometry.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/columns/postgis_extension/geometry.ts) - [drizzle-orm/src/pg-core/columns/vector_extension/vector.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/columns/vector_extension/vector.ts) - [drizzle-orm/src/pg-core/policies.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/policies.ts)
## Overview The schema definition layer in Drizzle ORM provides a type-safe, declarative abstraction for structuring database tables, columns, constraints, indexes, sequences, and security primitives across different database engines (PostgreSQL, MySQL, SQLite, SingleStore, and Gel). By utilizing fluent method chaining and TypeScript type inference, Drizzle core modules allow developers to map database catalogs directly to strongly typed models without sacrificing native SQL control. This architecture bridges the gap between raw DDL statements and application code, powering migration generation via [Migration Toolkit Schema](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/migration-toolkit-schema) and database reverse engineering via [Database Introspection](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/database-introspection). --- ## Gel Schema Definition Gel schema definitions are handled via the `gel-core` package, mimicking PostgreSQL-like semantics while supporting Gel-specific types and structures. Tables are declared using `gelTable` or via `GelSchema.table()` instances, tracking columns, foreign keys, and indexes in a unified metadata structure. Sources: [drizzle-orm/src/gel-core/table.ts:73-141](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/table.ts#L73-L141) The following call chain demonstrates how Gel tables and their columns are initialized and built during schema parsing: `gelTable()` → `gelTableWithSchema()` → `getGelColumnBuilders()` → `columnBuilder.build()` Sources: [drizzle-orm/src/gel-core/columns/all.ts:23-46](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/columns/all.ts#L23-L46) ```mermaid sequenceDiagram participant TableDef as gelTable participant TableWithSchema as gelTableWithSchema participant Builders as getGelColumnBuilders participant ColumnBuilder as GelColumnBuilder participant Column as GelColumn TableDef->>TableWithSchema: gelTable(name, columns, extraConfig) TableWithSchema->>Builders: getGelColumnBuilders() Builders-->>TableWithSchema: Returns column builder map TableWithSchema->>ColumnBuilder: setName(name) ColumnBuilder->>Column: build(rawTable) Column-->>TableWithSchema: Returns built column instance ``` Sources: [drizzle-orm/src/gel-core/table.ts:249-251](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/table.ts#L249-L251) ```typescript import { gelTable, integer, text, index, check } from '~/gel-core/index.ts'; export const users = gelTable( 'users_table', { id: integer('id').primaryKey(), age: integer('age1').notNull(), className: text('class').notNull(), }, (users) => [ index('usersAgeIdx').on(users.age.asc().nullsFirst()), check('legalAge', sql`${users.age} > 18`), ] ); ``` Sources: [drizzle-orm/type-tests/geldb/tables.ts:65-98](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/tables.ts#L65-L98) --- ## MySQL Schema Definition MySQL schema definitions reside in `mysql-core`, offering support for auto-incrementing columns, storage engines, table-level constraints, and character sets. Tables are initialized via `mysqlTable` or `mysqlDatabase().table()`. Sources: [drizzle-orm/src/mysql-core/table.ts:61-116](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/table.ts#L61-L116) Columns supporting auto-increment extend `MySqlColumnBuilderWithAutoIncrement`, enabling the `.autoincrement()` modifier which automatically flags the column as having a default value in the Drizzle type system. Sources: [drizzle-orm/src/mysql-core/columns/common.ts:128-145](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/columns/common.ts#L128-L145) Index configurations for MySQL utilize `IndexBuilderOn` to manage column lists and algorithms. Sources: [drizzle-orm/src/mysql-core/indexes.ts:34-42](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/indexes.ts#L34-L42) ```typescript import { mysqlTable, int, varchar, index } from '~/mysql-core/index.ts'; export const users = mysqlTable( 'users', { id: int('id').primaryKey().autoincrement(), email: varchar('email', { length: 255 }).notNull().unique(), }, (table) => [ index('email_idx').using('btree').on(table.email), ] ); ``` Sources: [drizzle-orm/src/mysql-core/table.ts:119-147](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/table.ts#L119-L147) --- ## PostgreSQL Schema Definition ### Column Builders and Extensions PostgreSQL schema definitions utilize `pg-core` and provide extensive capabilities including standard types, PostGIS extensions, `pgvector` embeddings, sequences, check constraints, unique constraints, and row-level security (RLS) policies. PostgreSQL supports complex structural column builders such as `geometry` for spatial data and `vector` for machine learning embeddings. When defining vectors, specifying an operator class (such as `vector_cosine_ops` or `vector_l2_ops`) during index creation is required by `pgvector`. Sources: [drizzle-orm/src/pg-core/columns/postgis_extension/geometry.ts:105-119](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/columns/postgis_extension/geometry.ts#L105-L119), [drizzle-orm/src/pg-core/columns/vector_extension/vector.ts:70-79](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/columns/vector_extension/vector.ts#L70-L79) ```typescript import { pgTable, serial } from '~/pg-core/index.ts'; import { geometry } from '~/pg-core/columns/postgis_extension/geometry.ts'; import { vector } from '~/pg-core/columns/vector_extension/vector.ts'; export const items = pgTable('items', { id: serial('id').primaryKey(), location: geometry('location', { srid: 4326, mode: 'xy' }), embedding: vector('embedding', { dimensions: 1536 }), }); ``` Sources: [drizzle-orm/type-tests/pg/tables.ts:1312-1335](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/tables.ts#L1312-L1335) ### Indexes and Row-Level Security Row-Level Security (RLS) can be enabled on tables using the `.enableRLS()` method chain, and security policies are attached using `pgPolicy`. Sources: [drizzle-orm/src/pg-core/table.ts:126-136](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/table.ts#L126-L136), [drizzle-orm/src/pg-core/policies.ts:35-52](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/policies.ts#L35-L52) ```typescript import { pgTable, text, integer, index, pgPolicy } from '~/pg-core/index.ts'; import { sql } from '~/sql/sql.ts'; export const documents = pgTable( 'documents', { id: integer('id').primaryKey(), ownerId: text('owner_id').notNull(), }, (table) => [ index('owner_idx').using('btree', table.ownerId.asc()), pgPolicy('user_isolation_policy', { for: 'all', to: 'public', using: sql`owner_id = current_user`, }), ] ).enableRLS(); ``` Sources: [drizzle-orm/src/pg-core/indexes.ts:159-178](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/indexes.ts#L159-L178) --- ## SingleStore Schema Definition SingleStore schemas map distributed relational database capabilities using `singlestoreSchema` and `singlestoreTable`. Sources: [drizzle-kit/src/introspect-singlestore.ts:10-13](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-singlestore.ts#L10-L13) Introspection routines convert database column defaults, JSON types, and indexes into corresponding Drizzle schema declarations. Sources: [drizzle-kit/src/introspect-singlestore.ts:139-156](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-singlestore.ts#L139-L156) ```typescript import { singlestoreTable, int, varchar } from 'drizzle-orm/singlestore-core'; export const storeItems = singlestoreTable('store_items', { id: int('id').primaryKey().autoincrement(), title: varchar('title', { length: 128 }).notNull(), }); ``` Sources: [drizzle-kit/src/introspect-singlestore.ts:19-55](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-singlestore.ts#L19-L55) --- ## SQLite Schema Definition SQLite schema definitions leverage lightweight type mappings suitable for embedded and edge runtimes (such as Cloudflare D1 or Expo SQLite). Sources: [drizzle-kit/src/sqlgenerator.ts:117-124](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/sqlgenerator.ts#L117-L124) They handle primary keys, unique constraints, and foreign key references through `sqlite-core`. Sources: [drizzle-kit/src/sqlgenerator.ts:125-142](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/sqlgenerator.ts#L125-L142) ## Related - [Dialects And Schema Query Builders](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/dialects-and-schema/dialects-and-schema-query-builders) - [Table and Column Models](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/table-and-column-models) - [Drivers And Runtimes](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/drivers-and-runtimes/drivers-and-runtimes) - [Edge and Mobile SQLite](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/drivers-and-runtimes/edge-and-mobile-sqlite) --- ## Technical docs: Dialects And Schema Query Builders URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/dialects-and-schema/dialects-and-schema-query-builders
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-orm/src/pg-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/dialect.ts) - [drizzle-orm/src/gel-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/dialect.ts) - [drizzle-orm/src/pg-core/query-builders/insert.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/insert.ts) - [drizzle-orm/type-tests/pg/tables.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/tables.ts) - [drizzle-orm/src/pg-core/query-builders/refresh-materialized-view.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/refresh-materialized-view.ts) - [drizzle-orm/src/sqlite-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/dialect.ts) - [drizzle-orm/src/singlestore-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/dialect.ts) - [drizzle-orm/src/gel-core/query-builders/refresh-materialized-view.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/refresh-materialized-view.ts) - [drizzle-orm/src/mysql-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/dialect.ts) - [drizzle-orm/src/pg-core/query-builders/update.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/update.ts) - [drizzle-orm/src/pg-core/db.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/db.ts) - [drizzle-orm/src/sqlite-core/query-builders/insert.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/insert.ts) - [drizzle-orm/src/gel-core/query-builders/insert.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/insert.ts) - [drizzle-orm/src/pg-core/query-builders/query.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/query.ts) - [drizzle-orm/src/pg-core/query-builders/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/index.ts) - [drizzle-orm/src/pg-core/query-builders/select.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/select.ts) - [drizzle-orm/src/singlestore-core/query-builders/insert.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/query-builders/insert.ts) - [drizzle-orm/src/pg-core/view.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/view.ts) - [drizzle-orm/src/pg-core/query-builders/delete.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/delete.ts) - [drizzle-orm/type-tests/sqlite/insert.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/sqlite/insert.ts) - [drizzle-orm/type-tests/pg/insert.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/insert.ts) - [drizzle-orm/src/gel-core/query-builders/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/index.ts) - [drizzle-orm/src/gel-core/db.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/db.ts) - [drizzle-orm/src/gel-core/query-builders/select.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/select.ts) - [drizzle-orm/src/gel-core/query-builders/update.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/update.ts)
## Overview The Drizzle ORM query building architecture relies on dialect-specific compiler components coupled with fluent query builder classes to transform high-level method chains into parameterized SQL AST fragments. Each database dialect (PostgreSQL, Gel, SQLite, MySQL, and SingleStore) provides its own dialect driver class that manages identifier escaping, parameter formatting, casing cache transformations, and clause assembly for insert, update, delete, and select operations. Sources: [drizzle-orm/src/pg-core/dialect.ts:609-618](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/dialect.ts#L609-L618) ```mermaid flowchart TD QB["Query Builder API
(.insert(), .select(), .update())"] --> Config["Query Configuration Object"] Config --> Dialect["Dialect Compiler
(PgDialect, SQLiteDialect, etc.)"] Dialect --> SQLAST["SQL AST & Chunks"] SQLAST --> QueryWithTypings["sql.toQuery()"] QueryWithTypings --> PreparedQuery["Prepared Statement / Session Execution"] ``` Sources: [drizzle-orm/src/sqlite-core/dialect.ts:596-604](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/dialect.ts#L596-L604) --- ## Gel Query Builders The Gel query builder subsystem shares architectural lineages with PostgreSQL-core query builders, utilizing `GelDialect`, `GelInsertBase`, `GelSelectBase`, and `GelUpdateBase` to compile queries targeting Gel databases. Insert configurations handle column filtering via `col.shouldDisableInsert()`, fallback to column default functions (`col.defaultFn`) or `onUpdateFn`, and compile `returning` and `on conflict` clauses when present. Sources: [drizzle-orm/src/gel-core/dialect.ts:508-575](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/dialect.ts#L508-L575) ```typescript const inserted = await db.insert(users) .values({ name: 'Gel User' }) .returning(); ``` Sources: [drizzle-orm/src/gel-core/query-builders/insert.ts:220-279](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/insert.ts#L220-L279) The Gel selection framework leverages `GelSelectBuilder` and `GelSelectQueryBuilderBase` to manage complex relation projections, join configurations, and set operators (`union`, `intersect`, `except`) with strict key validation checks. Sources: [drizzle-orm/src/gel-core/query-builders/select.ts:60-145](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/select.ts#L60-L145) > [!NOTE] > Gel query builder methods validate set operator compatibility by inspecting whether left and right selection keys match identically and maintain the same order. Sources: [drizzle-orm/src/gel-core/query-builders/select.ts:515-520](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/select.ts#L515-L520) ```typescript if (!haveSameKeys((leftSelect as any).getSelectedFields(), setOperator.rightSelect.getSelectedFields())) { throw new Error( 'Set operator error (union / intersect / except): selected fields are not the same or are in a different order', ); } ``` Sources: [drizzle-orm/src/gel-core/query-builders/select.ts:1119-1125](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/query-builders/select.ts#L1119-L1125) --- ## MySQL Query Builders MySQL-core query compilation is managed by `MySqlDialect` alongside `MySqlInsertConfig` and related query builders. When compiling insert queries via `buildInsertQuery`, the dialect filters out insert-disabled columns and iterates over input value records. Sources: [drizzle-orm/src/mysql-core/dialect.ts:561-567](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/dialect.ts#L561-L567) ```typescript buildInsertQuery({ table, values: valuesOrSelect, ignore, onConflict, select, }: MySqlInsertConfig): { sql: SQL; generatedIds: Record[] } { ``` Sources: [drizzle-orm/src/mysql-core/dialect.ts:561-567](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/dialect.ts#L561-L567) For each column entry during an insert operation, if a field value is `undefined` or an unassigned `Param`, the dialect checks column defaults (`col.defaultFn`) or update functions (`col.onUpdateFn`), populates generated ID tracking dictionaries, and constructs `ignore` and `on duplicate key` clauses. Sources: [drizzle-orm/src/mysql-core/dialect.ts:586-645](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/dialect.ts#L586-L645) > [!IMPORTANT] > MySQL does not support a native `do nothing` conflict clause directly; developers achieve this behavior by setting a unique column to its own value (e.g., `{ id: sql`id` }`) within `.onDuplicateKeyUpdate()`. Sources: [drizzle-orm/src/singlestore-core/query-builders/insert.ts:246-253](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/query-builders/insert.ts#L246-L253) ```typescript onDuplicateKeyUpdate( config: SingleStoreInsertOnDuplicateKeyUpdateConfig, ): SingleStoreInsertWithout { const setSql = this.dialect.buildUpdateSet(this.config.table, mapUpdateSet(this.config.table, config.set)); this.config.onConflict = sql`update ${setSql}`; return this as any; } ``` Sources: [drizzle-orm/src/singlestore-core/query-builders/insert.ts:246-253](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/query-builders/insert.ts#L246-L253) --- ## PostgreSQL Query Builders PostgreSQL dialect compilation (`PgDialect`) drives advanced clause generation including CTEs (`withList`), column casing identifiers, system value overrides (`overriding system value`), and conflict resolution. Sources: [drizzle-orm/src/pg-core/dialect.ts:513-515](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/dialect.ts#L513-L515) ```typescript buildInsertQuery( { table, values: valuesOrSelect, onConflict, returning, withList, select, overridingSystemValue_ }: PgInsertConfig, ): SQL { ``` Sources: [drizzle-orm/src/pg-core/dialect.ts:513-515](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/dialect.ts#L513-L515) The `PgInsertBase` class provides conflict handling methods `.onConflictDoNothing()` and `.onConflictDoUpdate()`. Sources: [drizzle-orm/src/pg-core/query-builders/insert.ts:369-389](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/insert.ts#L369-L389) ```typescript onConflictDoUpdate( config: PgInsertOnConflictDoUpdateConfig, ): PgInsertWithout { if (config.where && (config.targetWhere || config.setWhere)) { throw new Error( 'You cannot use both "where" and "targetWhere"/"setWhere" at the same time - "where" is deprecated, use "targetWhere" or "setWhere" instead.', ); } const whereSql = config.where ? sql` where ${config.where}` : undefined; const targetWhereSql = config.targetWhere ? sql` where ${config.targetWhere}` : undefined; const setWhereSql = config.setWhere ? sql` where ${config.setWhere}` : undefined; const setSql = this.dialect.buildUpdateSet(this.config.table, mapUpdateSet(this.config.table, config.set)); let targetColumn = ''; targetColumn = Array.isArray(config.target) ? config.target.map((it) => this.dialect.escapeName(this.dialect.casing.getColumnCasing(it))).join(',') : this.dialect.escapeName(this.dialect.casing.getColumnCasing(config.target)); this.config.onConflict = sql`(${ sql.raw(targetColumn) })${targetWhereSql} do update set ${setSql}${whereSql}${setWhereSql}`; return this as any; } ``` Sources: [drizzle-orm/src/pg-core/query-builders/insert.ts:369-389](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/insert.ts#L369-L389) PostgreSQL views and materialized views support execution refreshing via `PgRefreshMaterializedView`. Sources: [drizzle-orm/src/pg-core/query-builders/refresh-materialized-view.ts:30-65](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/refresh-materialized-view.ts#L30-L65) ```typescript export class PgRefreshMaterializedView extends QueryPromise> implements RunnableQuery, 'pg'>, SQLWrapper { static override readonly [entityKind]: string = 'PgRefreshMaterializedView'; private config: { view: PgMaterializedView; concurrently?: boolean; withNoData?: boolean; }; constructor( view: PgMaterializedView, private session: PgSession, private dialect: PgDialect, ) { super(); this.config = { view }; } concurrently(): this { if (this.config.withNoData !== undefined) { throw new Error('Cannot use concurrently and withNoData together'); } this.config.concurrently = true; return this; } withNoData(): this { if (this.config.concurrently !== undefined) { throw new Error('Cannot use concurrently and withNoData together'); } this.config.withNoData = true; return this; } ``` Sources: [drizzle-orm/src/pg-core/query-builders/refresh-materialized-view.ts:30-65](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/refresh-materialized-view.ts#L30-L65) > [!CAUTION] > Attempting to combine `.concurrently()` and `.withNoData()` on a materialized view refresh triggers an explicit error invariant check in both PostgreSQL and Gel implementations. Sources: [drizzle-orm/src/pg-core/query-builders/refresh-materialized-view.ts:51-54](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/refresh-materialized-view.ts#L51-L54) ```typescript if (this.config.withNoData !== undefined) { throw new Error('Cannot use concurrently and withNoData together'); } ``` Sources: [drizzle-orm/src/pg-core/query-builders/refresh-materialized-view.ts:51-54](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/query-builders/refresh-materialized-view.ts#L51-L54) --- ## SingleStore Query Builders SingleStore query building is directed by `SingleStoreDialect` and `SingleStoreInsertBase`. The dialect handles migration bootstrapping by verifying and creating the `__drizzle_migrations` table via `session.execute()`, and executes insert queries supporting `ignore` flags and duplicate key updates. Sources: [drizzle-orm/src/singlestore-core/dialect.ts:53-66](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/dialect.ts#L53-L66) ```typescript buildInsertQuery({ table, values, ignore, onConflict, }: SingleStoreInsertConfig): { sql: SQL; generatedIds: Record[]; } { ``` Sources: [drizzle-orm/src/singlestore-core/dialect.ts:519-527](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/dialect.ts#L519-L527) When executing inserts, SingleStore tracks primary key auto-increment columns to generate response IDs, formatting clauses with `on duplicate key update`. Sources: [drizzle-orm/src/singlestore-core/query-builders/insert.ts:246-253](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/query-builders/insert.ts#L246-L253) ```typescript onDuplicateKeyUpdate( config: SingleStoreInsertOnDuplicateKeyUpdateConfig, ): SingleStoreInsertWithout { const setSql = this.dialect.buildUpdateSet(this.config.table, mapUpdateSet(this.config.table, config.set)); this.config.onConflict = sql`update ${setSql}`; return this as any; } ``` Sources: [drizzle-orm/src/singlestore-core/query-builders/insert.ts:246-253](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/query-builders/insert.ts#L246-L253) --- ## SQLite Query Builders SQLite query compilation (`SQLiteDialect`) manages parameter formatting (`?`), string escaping (`escapeString`), and identifier quoting (`escapeName`). Sources: [drizzle-orm/src/sqlite-core/dialect.ts:57-67](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/dialect.ts#L57-L67) ```typescript escapeName(name: string): string { return `"${name.replace(/"/g, '""')}"`; } escapeParam(_num: number): string { return '?'; } escapeString(str: string): string { return `'${str.replace(/'/g, "''")}'`; } ``` Sources: [drizzle-orm/src/sqlite-core/dialect.ts:57-67](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/dialect.ts#L57-L67) The `SQLiteInsertBase` builder handles table insertion records, falling back to column defaults or `null` values when parameters are omitted, and supports `.returning()` and `.onConflictDoNothing()` / `.onConflictDoUpdate()` clauses. Sources: [drizzle-orm/src/sqlite-core/query-builders/insert.ts:306-317](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/insert.ts#L306-L317) ```typescript onConflictDoNothing(config: { target?: IndexColumn | IndexColumn[]; where?: SQL } = {}): this { if (!this.config.onConflict) this.config.onConflict = []; if (config.target === undefined) { this.config.onConflict.push(sql` on conflict do nothing`); } else { const targetSql = Array.isArray(config.target) ? sql`${config.target}` : sql`${[config.target]}`; const whereSql = config.where ? sql` where ${config.where}` : sql``; this.config.onConflict.push(sql` on conflict ${targetSql} do nothing${whereSql}`); } return this; } ``` Sources: [drizzle-orm/src/sqlite-core/query-builders/insert.ts:306-317](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/query-builders/insert.ts#L306-L317) ## Related - [Dialects And Schema Schema Definition](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/dialects-and-schema/dialects-and-schema-schema-definition) - [Drivers And Runtimes](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/drivers-and-runtimes/drivers-and-runtimes) --- ## Technical docs: Drivers And Runtimes URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/drivers-and-runtimes/drivers-and-runtimes
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-orm/src/netlify-db/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/session.ts) - [drizzle-orm/src/neon-http/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-http/session.ts) - [drizzle-orm/src/xata-http/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/xata-http/session.ts) - [drizzle-orm/src/neon-serverless/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-serverless/session.ts) - [drizzle-kit/src/cli/connections.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/connections.ts) - [drizzle-orm/src/tidb-serverless/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/tidb-serverless/session.ts) - [drizzle-orm/src/neon-http/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-http/driver.ts) - [drizzle-orm/src/vercel-postgres/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/vercel-postgres/session.ts) - [drizzle-orm/src/xata-http/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/xata-http/driver.ts) - [drizzle-orm/src/singlestore/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore/session.ts) - [drizzle-orm/src/pg-proxy/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-proxy/session.ts) - [drizzle-orm/src/planetscale-serverless/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/planetscale-serverless/session.ts) - [drizzle-orm/src/aws-data-api/pg/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/aws-data-api/pg/session.ts) - [drizzle-orm/src/netlify-db/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/driver.ts) - [drizzle-orm/src/node-postgres/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/node-postgres/session.ts) - [drizzle-orm/src/postgres-js/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/postgres-js/session.ts) - [drizzle-orm/src/neon-serverless/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-serverless/driver.ts) - [drizzle-orm/src/sqlite-proxy/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-proxy/session.ts) - [drizzle-orm/src/pglite/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pglite/session.ts) - [drizzle-orm/src/singlestore-proxy/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-proxy/session.ts) - [drizzle-orm/src/aws-data-api/pg/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/aws-data-api/pg/driver.ts) - [drizzle-orm/src/libsql/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/session.ts) - [drizzle-orm/src/pg-core/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-core/session.ts) - [drizzle-orm/src/durable-sqlite/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/durable-sqlite/session.ts) - [drizzle-orm/src/neon-serverless/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-serverless/index.ts) - [drizzle-orm/src/planetscale-serverless/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/planetscale-serverless/index.ts) - [drizzle-orm/src/neon-http/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-http/index.ts) - [drizzle-orm/src/aws-data-api/pg/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/aws-data-api/pg/index.ts) - [drizzle-orm/src/xata-http/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/xata-http/index.ts) - [drizzle-orm/src/tidb-serverless/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/tidb-serverless/index.ts)
## Overview The Drizzle ORM driver and runtime subsystem abstracts database communication across diverse connection models, ranging from traditional persistent TCP socket pools in Node.js to connectionless HTTP request-response APIs, WebSocket tunnels, cloud-managed SDK endpoints, and edge-native embedded runtimes. Drivers bridge database-specific client libraries with Drizzle's dialect query builders and session mechanics. Each driver exposes specialized initialization routines (`drizzle()`), session implementations (`PgSession`, `MySqlSession`, `SQLiteSession`), and prepared query objects that normalize parameter binding, row mapping, and caching strategies. Different execution environments impose strict architectural constraints. Serverless functions and edge workers cannot maintain long-lived TCP connections without exhausting connection limits or failing due to idle timeouts. To accommodate this, Drizzle integrates with stateless HTTP drivers such as Neon HTTP, Xata HTTP, and AWS Data API, which submit individual queries over HTTP POST requests. Conversely, environments requiring transactional semantics or stateful protocols rely on WebSocket-tunneled pool clients (like Neon Serverless and Netlify DB) or native driver pools (`node-postgres`, `postgres-js`, `mysql2`). By decoupling query generation from driver execution through abstract session classes, Drizzle provides a unified API surface regardless of whether queries execute against local embedded files, remote serverless REST endpoints, or proxied worker channels. Sources: [drizzle-orm/src/neon-http/session.ts:1-14](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-http/session.ts#L1-L14), [drizzle-orm/src/postgres-js/session.ts:1-15](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/postgres-js/session.ts#L1-L15), [drizzle-orm/src/aws-data-api/pg/driver.ts:1-20](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/aws-data-api/pg/driver.ts#L1-L20) ## Custom Proxy Drivers Custom proxy drivers route database execution through user-supplied callback functions rather than managing direct network sockets. This architecture is heavily utilized in edge environments, testing frameworks, and migration tools where query execution must be intercepted, logged, or forwarded to a remote worker bridge. The proxy subsystem implements separate adapters for PostgreSQL (`PgRemoteSession`), MySQL/SingleStore (`SingleStoreRemoteSession`), and SQLite (`SQLiteRemoteSession`), translating Drizzle's prepared query executions into generic callback invocations. Sources: [drizzle-orm/src/pg-proxy/session.ts:16-41](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-proxy/session.ts#L16-L41) When a query executes under a proxy session, the framework bypasses native database drivers and invokes a remote callback function with the compiled SQL string, parameter values, execution method, and optional type hints. For instance, the PostgreSQL proxy prepared query evaluates placeholder values via `fillPlaceholders()`, logs the statement, and invokes the client callback with `'execute'` or `'all'` modes. Sources: [drizzle-orm/src/pg-proxy/session.ts:91-129](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-proxy/session.ts#L91-L129) ```typescript // Example usage of a PostgreSQL proxy driver initialization import { drizzle } from 'drizzle-orm/pg-proxy'; const db = drizzle(async (sql, params, method, typings) => { const res = await fetch('https://api.database.proxy/query', { method: 'POST', body: JSON.stringify({ sql, params, method, typings }), }); return { rows: await res.json() }; }); ``` Sources: [drizzle-orm/src/pg-proxy/session.ts:95-154](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-proxy/session.ts#L95-L154) Because stateless proxies do not maintain persistent socket state, multi-statement transactions are fundamentally unsupported. Attempting to initiate a transaction on a proxy session immediately throws an explicit error indicating that transactions are unavailable for the proxy driver. Sources: [drizzle-orm/src/pg-proxy/session.ts:70-76](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-proxy/session.ts#L70-L76), [drizzle-orm/src/singlestore-proxy/session.ts:72-78](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-proxy/session.ts#L72-L78) ## MySQL and Serverless Drivers MySQL and serverless MySQL runtimes are powered by drivers such as PlanetScale Serverless and TiDB Cloud Serverless. These drivers operate over HTTP or fetch-based APIs, delivering connectionless execution ideal for serverless and edge environments. The session implementations (`PlanetscaleSession` and `TiDBServerlessSession`) extend `MySqlSession` and coordinate query preparation via `PlanetScalePreparedQuery` and `TiDBServerlessPreparedQuery`. Sources: [drizzle-orm/src/planetscale-serverless/session.ts:22-48](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/planetscale-serverless/session.ts#L22-L48), [drizzle-orm/src/tidb-serverless/session.ts:26-48](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/tidb-serverless/session.ts#L26-L48) Unlike traditional MySQL drivers that rely on persistent TCP connections, serverless MySQL clients accept an HTTP client or connection handle and execute queries via stateless request methods. For instance, `PlanetScalePreparedQuery` utilizes an execution configuration object (`{ as: 'object' }` or `{ as: 'array' }`) to dictate row formatting. When executing write queries without custom result mappers, the driver calculates affected rows and insert IDs, handling synthetic returning clauses for auto-incrementing primary keys or generated identifiers. Sources: [drizzle-orm/src/planetscale-serverless/session.ts:49-96](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/planetscale-serverless/session.ts#L49-L96), [drizzle-orm/src/tidb-serverless/session.ts:50-86](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/tidb-serverless/session.ts#L50-L86) ```mermaid flowchart TD A["Query Builder"] --> B["PlanetScalePreparedQuery.execute()"] B --> C{"Fields or Custom Mapper?"} C -- "No" --> D["client.execute(sql, params, { as: 'object' })"] C -- "Yes" --> E["client.execute(sql, params, { as: 'array' })"] E --> F["mapResultRow()"] ``` Sources: [drizzle-orm/src/planetscale-serverless/session.ts:49-106](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/planetscale-serverless/session.ts#L49-L106) > [!NOTE] > Streaming and database-level iterators are explicitly disabled in serverless MySQL drivers. Calling `.iterator()` on a `PlanetScalePreparedQuery` or `TiDBServerlessPreparedQuery` throws an error because HTTP request-response cycles cannot maintain open streams. Sources: [drizzle-orm/src/planetscale-serverless/session.ts:108-111](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/planetscale-serverless/session.ts#L108-L111), [drizzle-orm/src/tidb-serverless/session.ts:99-102](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/tidb-serverless/session.ts#L99-L102) ## Node.js PostgreSQL Drivers Node.js PostgreSQL runtimes rely on persistent TCP socket drivers, specifically `node-postgres` (`pg`) and `postgres-js` (`postgres`). These drivers manage connection pools (`Pool`), individual client connections (`Client`), and transaction blocks. Drizzle implements `NodePgSession` and `PostgresJsSession` to bridge these native clients with PostgreSQL query generation. Sources: [drizzle-orm/src/node-postgres/session.ts:19-43](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/node-postgres/session.ts#L19-L43), [drizzle-orm/src/postgres-js/session.ts:17-36](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/postgres-js/session.ts#L17-L36) Both sessions configure custom type parsers during initialization to prevent automatic transformation of date, timestamp, timestamptz, interval, and array types into JavaScript `Date` objects unless desired. This preserves raw string representations for high-precision decimal and timestamp handling. Transaction management in `PostgresJsSession` leverages the native `.begin()` callback wrapper provided by `postgres-js`, automatically provisioning a transaction-scoped client instance and applying transaction configuration parameters via `.setTransaction(config)`. Sources: [drizzle-orm/src/node-postgres/session.ts:44-131](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/node-postgres/session.ts#L44-L131), [drizzle-orm/src/postgres-js/session.ts:167-184](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/postgres-js/session.ts#L167-L184) ```typescript // Initializing Drizzle with postgres-js in Node.js import { drizzle } from 'drizzle-orm/postgres-js'; import postgres from 'postgres'; const queryClient = postgres('postgres://user:pass@localhost:5432/db'); const db = drizzle(queryClient); ``` Sources: [drizzle-kit/src/cli/connections.ts:274-297](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/connections.ts#L274-L297) Tracing is deeply integrated into Node.js PostgreSQL sessions via OpenTelemetry spans (`tracer.startActiveSpan`). Query execution is wrapped in nested spans (`drizzle.execute`, `drizzle.driver.execute`, and `drizzle.mapResponse`), capturing query text, parameters, and execution duration as span attributes. Sources: [drizzle-orm/src/node-postgres/session.ts:133-171](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/node-postgres/session.ts#L133-L171), [drizzle-orm/src/postgres-js/session.ts:38-74](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/postgres-js/session.ts#L38-L74) ## Serverless PostgreSQL Drivers Serverless PostgreSQL drivers provide connectionless execution models tailored for edge runtimes, serverless functions, and managed cloud platforms. This group includes Neon HTTP (`NeonHttpSession`), Xata HTTP (`XataHttpSession`), AWS Data API (`AwsDataApiSession`), Neon Serverless (`NeonSession`), Vercel Postgres (`VercelPgSession`), and Netlify DB (`NetlifyDbSession`). Sources: [drizzle-orm/src/neon-http/session.ts:149-173](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-http/session.ts#L149-L173), [drizzle-orm/src/xata-http/session.ts:98-120](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/xata-http/session.ts#L98-L120), [drizzle-orm/src/aws-data-api/pg/session.ts:165-191](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/aws-data-api/pg/session.ts#L165-L191) HTTP-based drivers (Neon HTTP, Xata HTTP) submit queries as REST payloads over HTTP POST requests rather than maintaining persistent socket connections. For instance, `XataHttpSession` delegates execution to the Xata client plugin (`client.sql`), specifying response types (`array` or `json`) to govern whether rows return as tuples or objects. Neon HTTP utilizes a fetch-based query function and supports batch execution via its transaction endpoint (`client.transaction(builtQueries, queryConfig)`), enabling multiple independent queries to execute in a single round trip. Sources: [drizzle-orm/src/neon-http/session.ts:199-220](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-http/session.ts#L199-L220), [drizzle-orm/src/xata-http/session.ts:47-91](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/xata-http/session.ts#L47-L91) ```mermaid sequenceDiagram participant App as Drizzle ORM participant Session as NeonHttpSession participant Client as Neon HTTP Client participant DB as Neon Cloud API App->>Session: execute() / batch() Session->>Client: clientQuery(sql, params, opts) Client->>DB: HTTP POST /v2/query DB-->>Client: FullQueryResults Client-->>Session: Result rows Session-->>App: Mapped result entities ``` Sources: [drizzle-orm/src/neon-http/session.ts:221-235](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-http/session.ts#L221-L235), [drizzle-orm/src/netlify-db/session.ts:130-142](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/session.ts#L130-L142) AWS Data API (`AwsDataApiSession`) interacts with Amazon RDS databases through the AWS SDK (`RDSDataClient`). It translates Drizzle parameter bindings into named parameters (`:1`, `:2`) via `AwsPgDialect.escapeParam()` and converts column metadata into structured row objects when result headers are present. Sources: [drizzle-orm/src/aws-data-api/pg/driver.ts:50-56](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/aws-data-api/pg/driver.ts#L50-L56), [drizzle-orm/src/aws-data-api/pg/session.ts:30-65](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/aws-data-api/pg/session.ts#L30-L65) > [!WARNING] > HTTP-based drivers such as Neon HTTP and Xata HTTP do not support traditional SQL transactions (`BEGIN`/`COMMIT`/`ROLLBACK`) across separate HTTP requests. Calling `.transaction()` on these sessions throws an explicit error, except where WebSocket fallback connections are explicitly provisioned (such as Netlify DB's hybrid pool). Sources: [drizzle-orm/src/neon-http/session.ts:248-255](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-http/session.ts#L248-L255), [drizzle-orm/src/xata-http/session.ts:167-174](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/xata-http/session.ts#L167-L174), [drizzle-orm/src/netlify-db/session.ts:151-179](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/session.ts#L151-L179) ## SingleStore and Gel Drivers SingleStore and Gel drivers manage relational connectivity for high-performance distributed analytics and advanced graph-relational runtimes. SingleStore driver sessions (`SingleStoreDriverSession`) integrate with the `mysql2` promise client, managing connection pools and standalone connections. Sources: [drizzle-orm/src/singlestore/session.ts:202-220](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore/session.ts#L202-L220) During query execution, `SingleStoreDriverSession` overrides the default `query()` method to configure custom type casting, ensuring `TIMESTAMP`, `DATETIME`, and `DATE` fields return as raw strings: Sources: [drizzle-orm/src/singlestore/session.ts:251-270](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore/session.ts#L251-L270) ```typescript const result = await this.client.query({ sql: query, values: params, rowsAsArray: true, typeCast: function(field: any, next: any) { if (field.type === 'TIMESTAMP' || field.type === 'DATETIME' || field.type === 'DATE') { return field.string(); } return next(); }, }); ``` Sources: [drizzle-orm/src/singlestore/session.ts:255-269](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore/session.ts#L255-L269) Transactions in SingleStore check whether the underlying client is a connection pool (`isPool()`). If so, a dedicated `PoolConnection` is acquired via `client.getConnection()`, configured with isolation levels or start transaction statements, and released in a `finally` block once execution completes or rolls back. Nested transactions utilize SQL savepoints (`savepoint sp1`, `rollback to savepoint sp1`). Sources: [drizzle-orm/src/singlestore/session.ts:277-350](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore/session.ts#L277-L350), [drizzle-kit/src/cli/connections.ts:536-545](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/connections.ts#L536-L545) ## SQLite File and LibSQL Drivers SQLite file and edge runtimes are handled by specialized drivers including LibSQL (`libsql`), Cloudflare Durable Objects (`durable-sqlite`), and PGlite. These drivers support embedded storage engines, local WebAssembly runtimes, and distributed SQLite services like Turso. `SQLiteDOSession` integrates with Cloudflare Durable Object storage (`DurableObjectStorage`), executing synchronous SQLite queries against `storage.sql`. Because Durable Object storage operates synchronously within isolate execution, queries are executed via `.exec()` and results are converted using `.toArray()` or iterator advancement (`.next().value`). Similarly, LibSQL sessions (`LibSQLSession`) manage asynchronous remote and embedded connections using `@libsql/client`, normalizing row data structures and handling `ArrayBuffer`-to-`Buffer` or `TextDecoder` conversions for binary blob fields. Sources: [drizzle-orm/src/durable-sqlite/session.ts:23-72](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/durable-sqlite/session.ts#L23-L72), [drizzle-orm/src/libsql/session.ts:145-201](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/session.ts#L145-L201), [drizzle-orm/src/pglite/session.ts:123-195](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pglite/session.ts#L123-L195) ## Related - [Dialects And Schema Query Builders](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/dialects-and-schema/dialects-and-schema-query-builders) - [Edge and Mobile SQLite](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/drivers-and-runtimes/edge-and-mobile-sqlite) - [Sessions and Transactions](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/sessions-and-transactions) --- ## Technical docs: Edge and Mobile SQLite URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/drivers-and-runtimes/edge-and-mobile-sqlite
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-orm/src/durable-sqlite/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/durable-sqlite/driver.ts) - [drizzle-orm/src/durable-sqlite/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/durable-sqlite/index.ts) - [drizzle-orm/src/d1/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/d1/driver.ts) - [drizzle-orm/src/sql-js/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql-js/driver.ts) - [drizzle-orm/src/expo-sqlite/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/expo-sqlite/driver.ts) - [drizzle-orm/src/libsql/wasm/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/wasm/index.ts) - [drizzle-orm/src/prisma/sqlite/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/sqlite/driver.ts) - [drizzle-orm/src/sqlite-proxy/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-proxy/driver.ts) - [drizzle-orm/src/libsql/sqlite3/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/sqlite3/index.ts) - [drizzle-orm/src/op-sqlite/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/op-sqlite/driver.ts) - [drizzle-orm/src/pglite/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pglite/driver.ts) - [drizzle-kit/src/cli/connections.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/connections.ts) - [drizzle-orm/src/libsql/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/driver.ts) - [drizzle-orm/src/libsql/node/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/node/index.ts) - [drizzle-orm/src/bun-sqlite/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/bun-sqlite/driver.ts) - [drizzle-orm/src/libsql/ws/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/ws/index.ts) - [drizzle-orm/src/d1/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/d1/session.ts) - [drizzle-orm/src/durable-sqlite/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/durable-sqlite/session.ts) - [drizzle-orm/src/neon-serverless/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-serverless/driver.ts) - [drizzle-orm/src/vercel-postgres/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/vercel-postgres/driver.ts) - [drizzle-orm/src/sql-js/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql-js/session.ts) - [drizzle-orm/src/libsql/web/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/web/index.ts) - [drizzle-orm/src/prisma/sqlite/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/sqlite/index.ts) - [drizzle-orm/src/libsql/http/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/http/index.ts) - [drizzle-orm/src/planetscale-serverless/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/planetscale-serverless/driver.ts) - [drizzle-orm/type-tests/sqlite/db.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/sqlite/db.ts) - [drizzle-orm/src/expo-sqlite/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/expo-sqlite/index.ts) - [drizzle-orm/src/better-sqlite3/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/better-sqlite3/driver.ts) - [drizzle-orm/src/singlestore/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore/driver.ts) - [drizzle-orm/src/sqlite-core/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/session.ts)
## Overview Drizzle ORM provides dedicated driver integrations and session handlers for running SQLite databases across edge runtimes, serverless workers, WebAssembly environments, and native mobile applications. These drivers bridge Drizzle's synchronous and asynchronous query dialects with target environments such as Cloudflare D1, Cloudflare Durable Objects storage, Expo SQLite for React Native, OP-SQLite bindings, `sql.js` WebAssembly instances, and remote RPC sqlite-proxy endpoints. Each driver configures customized statement preparation, batch execution, and transaction lifecycle management tailored to the constraints and performance characteristics of its underlying runtime. Sources: [drizzle-orm/src/durable-sqlite/driver.ts:1-60](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/durable-sqlite/driver.ts#L1-L60), [drizzle-orm/src/d1/driver.ts:1-78](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/d1/driver.ts#L1-L78), [drizzle-orm/src/sql-js/driver.ts:1-45](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql-js/driver.ts#L1-L45), [drizzle-orm/src/expo-sqlite/driver.ts:1-53](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/expo-sqlite/driver.ts#L1-L53), [drizzle-orm/src/sqlite-proxy/driver.ts:1-100](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-proxy/driver.ts#L1-L100), [drizzle-orm/src/op-sqlite/driver.ts:1-57](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/op-sqlite/driver.ts#L1-L57), [drizzle-orm/src/d1/session.ts:30-126](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/d1/session.ts#L30-L126), [drizzle-orm/src/durable-sqlite/session.ts:23-72](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/durable-sqlite/session.ts#L23-L72), [drizzle-orm/src/sql-js/session.ts:24-66](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql-js/session.ts#L24-L66) ## Cloudflare D1 Driver Architecture ### Driver Initialization and Client Configuration The Cloudflare D1 integration initializes through the `drizzle()` entrypoint function which accepts a D1 database client (`AnyD1Database`, supporting both official `@cloudflare/workers-types` and Miniflare D1 bindings) and an optional `DrizzleConfig` parameter. It configures an asynchronous SQLite dialect (`SQLiteAsyncDialect`) utilizing the specified casing configuration, instantiates a logger (defaulting to `DefaultLogger` when `config.logger` is `true`), and extracts relational schema configurations if provided via `config.schema`. ```typescript export function drizzle< TSchema extends Record = Record, TClient extends AnyD1Database = AnyD1Database, >( client: TClient, config: DrizzleConfig = {}, ): DrizzleD1Database & { $client: TClient; } { const dialect = new SQLiteAsyncDialect({ casing: config.casing }); let logger; if (config.logger === true) { logger = new DefaultLogger(); } else if (config.logger !== false) { logger = config.logger; } let schema: RelationalSchemaConfig | undefined; if (config.schema) { const tablesConfig = extractTablesRelationalConfig( config.schema, createTableRelationsHelpers, ); schema = { fullSchema: config.schema, schema: tablesConfig.tables, tableNamesMap: tablesConfig.tableNamesMap, }; } const session = new SQLiteD1Session(client as D1Database, dialect, schema, { logger, cache: config.cache }); const db = new DrizzleD1Database('async', dialect, session, schema) as DrizzleD1Database; ( db).$client = client; ( db).$cache = config.cache; if (( db).$cache) { ( db).$cache['invalidate'] = config.cache?.onMutate; } return db as any; } ``` Sources: [drizzle-orm/src/d1/driver.ts:39-78](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/d1/driver.ts#L39-L78) The initialization function wires up `SQLiteD1Session` with the client, dialect, schema, and operational options including caching. It then constructs a `DrizzleD1Database` instance, attaches the raw client as `$client`, and exposes cache invalidation handlers on `$cache` when present. ```typescript const session = new SQLiteD1Session(client as D1Database, dialect, schema, { logger, cache: config.cache }); const db = new DrizzleD1Database('async', dialect, session, schema) as DrizzleD1Database; ( db).$client = client; ( db).$cache = config.cache; if (( db).$cache) { ( db).$cache['invalidate'] = config.cache?.onMutate; } ``` Sources: [drizzle-orm/src/d1/driver.ts:69-76](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/d1/driver.ts#L69-L76) ### Async Dialect Integration and Session Management `SQLiteD1Session` extends `SQLiteSession` with an `'async'` execution mode and handles query preparation by invoking `client.prepare(query.sql)` on the underlying D1 database handle. Prepared statements are wrapped in `D1PreparedQuery` instances that manage parameter binding, query logging, caching execution, and result mapping. ```typescript prepareQuery( query: Query, fields: SelectedFieldsOrdered | undefined, executeMethod: SQLiteExecuteMethod, isResponseInArrayMode: boolean, customResultMapper?: (rows: unknown[][]) => unknown, queryMetadata?: { type: 'select' | 'update' | 'delete' | 'insert'; tables: string[]; }, cacheConfig?: WithCacheConfig, ): D1PreparedQuery { const stmt = this.client.prepare(query.sql); return new D1PreparedQuery( stmt, query, this.logger, this.cache, queryMetadata, cacheConfig, fields, executeMethod, isResponseInArrayMode, customResultMapper, ); } ``` Sources: [drizzle-orm/src/d1/session.ts:50-75](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/d1/session.ts#L50-L75) Batch operations executed through `session.batch()` iterate over batch items, extract underlying prepared queries, bind parameters when present, or prepare fresh SQL statements if parameters are absent, before dispatching them concurrently via `client.batch()`. ```typescript async batch[] | readonly BatchItem<'sqlite'>[]>(queries: T) { const preparedQueries: PreparedQuery[] = []; const builtQueries: D1PreparedStatement[] = []; for (const query of queries) { const preparedQuery = query._prepare(); const builtQuery = preparedQuery.getQuery(); preparedQueries.push(preparedQuery); if (builtQuery.params.length > 0) { builtQueries.push((preparedQuery as D1PreparedQuery).stmt.bind(...builtQuery.params)); } else { const builtQuery = preparedQuery.getQuery(); builtQueries.push( this.client.prepare(builtQuery.sql).bind(...builtQuery.params), ); } } const batchResults = await this.client.batch(builtQueries); return batchResults.map((result, i) => preparedQueries[i]!.mapResult(result, true)); } ``` Sources: [drizzle-orm/src/d1/session.ts:77-97](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/d1/session.ts#L77-L97) ### Transaction Lifecycle and Statement Execution Transactions are managed explicitly via SQL commands issued against the session. The `transaction()` method initiates a block by executing `begin` with optional behavior configuration, runs the transaction callback with a `D1Transaction` instance, commits on success, or rolls back upon catching any error. ```typescript override async transaction( transaction: (tx: D1Transaction) => T | Promise, config?: SQLiteTransactionConfig, ): Promise { const tx = new D1Transaction('async', this.dialect, this, this.schema); await this.run(sql.raw(`begin${config?.behavior ? ' ' + config.behavior : ''}`)); try { const result = await transaction(tx); await this.run(sql`commit`); return result; } catch (err) { await this.run(sql`rollback`); throw err; } } ``` Sources: [drizzle-orm/src/d1/session.ts:111-125](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/d1/session.ts#L111-L125) Nested transactions within `D1Transaction` rely on SQLite savepoints. Each nested level generates a unique savepoint name using its `nestedIndex`, executing `savepoint spN`, releasing it upon completion, or rolling back to the savepoint on failure. ```typescript override async transaction(transaction: (tx: D1Transaction) => Promise): Promise { const savepointName = `sp${this.nestedIndex}`; const tx = new D1Transaction('async', this.dialect, this.session, this.schema, this.nestedIndex + 1); await this.session.run(sql.raw(`savepoint ${savepointName}`)); try { const result = await transaction(tx); await this.session.run(sql.raw(`release savepoint ${savepointName}`)); return result; } catch (err) { await this.session.run(sql.raw(`rollback to savepoint ${savepointName}`)); throw err; } } ``` Sources: [drizzle-orm/src/d1/session.ts:134-146](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/d1/session.ts#L134-L146) > [!NOTE] > `D1PreparedQuery` methods (`run`, `all`, `get`, `values`) substitute query placeholders using `fillPlaceholders()`, log parameters through the configured logger, and optionally wrap execution in `queryWithCache()` before delegating directly to D1's `.run()`, `.all()`, or `.raw()` statement bindings. Sources: [drizzle-orm/src/d1/session.ts:199-283](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/d1/session.ts#L199-L283) ## Cloudflare Durable Objects Storage Driver ### Driver Initialization and Synchronous Dialect Setup The Cloudflare Durable Objects storage driver initializes through the `drizzle()` entrypoint function which accepts a `DurableObjectStorage` client and an optional `DrizzleConfig` parameter. It instantiates a synchronous SQLite dialect (`SQLiteSyncDialect`) using the specified casing configuration, configures logging through `DefaultLogger` or custom loggers, and extracts relational schema configurations when supplied. ```typescript export function drizzle< TSchema extends Record = Record, TClient extends DurableObjectStorage = DurableObjectStorage, >( client: TClient, config: DrizzleConfig = {}, ): DrizzleSqliteDODatabase & { $client: TClient; } { const dialect = new SQLiteSyncDialect({ casing: config.casing }); let logger; if (config.logger === true) { logger = new DefaultLogger(); } else if (config.logger !== false) { logger = config.logger; } let schema: RelationalSchemaConfig | undefined; if (config.schema) { const tablesConfig = extractTablesRelationalConfig( config.schema, createTableRelationsHelpers, ); schema = { fullSchema: config.schema, schema: tablesConfig.tables, tableNamesMap: tablesConfig.tableNamesMap, }; } ``` Sources: [drizzle-orm/src/durable-sqlite/driver.ts:25-53](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/durable-sqlite/driver.ts#L25-L53) The initialization function wires up `SQLiteDOSession` with the storage client, dialect, schema, and operational options. It constructs a `DrizzleSqliteDODatabase` instance operating in `'sync'` mode, assigns the raw client to `$client`, and returns the database handle. ```typescript const session = new SQLiteDOSession(client as DurableObjectStorage, dialect, schema, { logger }); const db = new DrizzleSqliteDODatabase('sync', dialect, session, schema) as DrizzleSqliteDODatabase; ( db).$client = client; return db as any; } ``` Sources: [drizzle-orm/src/durable-sqlite/driver.ts:55-60](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/durable-sqlite/driver.ts#L55-L60) ### Session Management and Synchronous Prepared Queries `SQLiteDOSession` extends `SQLiteSession` with a `'sync'` execution mode and maps queries to `SQLiteDOPreparedQuery` instances via `prepareQuery()`. Transactions within the session invoke `client.transactionSync()` directly on the underlying storage client to wrap operations in synchronous transaction blocks. ```typescript export class SQLiteDOSession, TSchema extends TablesRelationalConfig> extends SQLiteSession< 'sync', SqlStorageCursor>, TFullSchema, TSchema > { static override readonly [entityKind]: string = 'SQLiteDOSession'; private logger: Logger; constructor( private client: DurableObjectStorage, dialect: SQLiteSyncDialect, private schema: RelationalSchemaConfig | undefined, options: SQLiteDOSessionOptions = {}, ) { super(dialect); this.logger = options.logger ?? new NoopLogger(); } prepareQuery>( query: Query, fields: SelectedFieldsOrdered | undefined, executeMethod: SQLiteExecuteMethod, isResponseInArrayMode: boolean, customResultMapper?: (rows: unknown[][]) => unknown, ): SQLiteDOPreparedQuery { return new SQLiteDOPreparedQuery( this.client, query, this.logger, fields, executeMethod, isResponseInArrayMode, customResultMapper, ); } override transaction( transaction: ( tx: SQLiteTransaction<'sync', SqlStorageCursor>, TFullSchema, TSchema>, ) => T, _config?: SQLiteTransactionConfig, ): T { const tx = new SQLiteDOTransaction('sync', this.dialect, this, this.schema); return this.client.transactionSync(() => transaction(tx)); } } ``` Sources: [drizzle-orm/src/durable-sqlite/session.ts:23-72](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/durable-sqlite/session.ts#L23-L72) `SQLiteDOPreparedQuery` executes statements synchronously against `client.sql.exec()`. Depending on the requested method, it processes results across several execution paths: | Method | Return Type | Execution Behavior | | :--- | :--- | :--- | | `run()` | `void` | Executes `client.sql.exec()` with parameters when present, returning no result. | | `all()` | `T['all']` | Returns an array of rows by calling `.toArray()` on the execution result, mapping fields if configured. | | `get()` | `T['get']` | Returns the first row value by invoking `.next().value` or mapping the first row of result arrays. | | `values()` | `T['values']` | Returns raw array-of-arrays representation using `.raw().toArray()`. | ```typescript export class SQLiteDOPreparedQuery extends PreparedQueryBase<{ type: 'sync'; run: void; all: T['all']; get: T['get']; values: T['values']; execute: T['execute']; }> { static override readonly [entityKind]: string = 'SQLiteDOPreparedQuery'; constructor( private client: DurableObjectStorage, query: Query, private logger: Logger, private fields: SelectedFieldsOrdered | undefined, executeMethod: SQLiteExecuteMethod, private _isResponseInArrayMode: boolean, private customResultMapper?: (rows: unknown[][]) => unknown, ) { // 3-6 params are for cache. As long as we don't support sync cache - it will be skipped here super('sync', executeMethod, query, undefined, undefined, undefined); } run(placeholderValues?: Record): void { const params = fillPlaceholders(this.query.params, placeholderValues ?? {}); this.logger.logQuery(this.query.sql, params); params.length > 0 ? this.client.sql.exec(this.query.sql, ...params) : this.client.sql.exec(this.query.sql); } all(placeholderValues?: Record): T['all'] { const { fields, joinsNotNullableMap, query, logger, client, customResultMapper } = this; if (!fields && !customResultMapper) { const params = fillPlaceholders(query.params, placeholderValues ?? {}); logger.logQuery(query.sql, params); return params.length > 0 ? client.sql.exec(query.sql, ...params).toArray() : client.sql.exec(query.sql).toArray(); } const rows = this.values(placeholderValues) as unknown[][]; if (customResultMapper) { return customResultMapper(rows) as T['all']; } return rows.map((row) => mapResultRow(fields!, row, joinsNotNullableMap)); } get(placeholderValues?: Record): T['get'] { const params = fillPlaceholders(this.query.params, placeholderValues ?? {}); this.logger.logQuery(this.query.sql, params); const { fields, client, joinsNotNullableMap, customResultMapper, query } = this; if (!fields && !customResultMapper) { return (params.length > 0 ? client.sql.exec(query.sql, ...params) : client.sql.exec(query.sql)).next().value; } const rows = this.values(placeholderValues) as unknown[][]; const row = rows[0]; if (!row) { return undefined; } if (customResultMapper) { return customResultMapper(rows) as T['get']; } return mapResultRow(fields!, row, joinsNotNullableMap); } values(placeholderValues?: Record): T['values'] { const params = fillPlaceholders(this.query.params, placeholderValues ?? {}); this.logger.logQuery(this.query.sql, params); const res = params.length > 0 ? this.client.sql.exec(this.query.sql, ...params) : this.client.sql.exec(this.query.sql); // @ts-ignore .raw().toArray() exists return res.raw().toArray(); } } ``` Sources: [drizzle-orm/src/durable-sqlite/session.ts:90-177](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/durable-sqlite/session.ts#L90-L177) > [!NOTE] > `SQLiteDOTransaction` extends `SQLiteTransaction` to support nested transaction nesting indices, spawning new `SQLiteDOTransaction` instances and delegating back to `this.session.transaction()` to maintain synchronous execution safety across storage boundaries. Sources: [drizzle-orm/src/durable-sqlite/session.ts:74-88](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/durable-sqlite/session.ts#L74-L88) ## Expo SQLite Driver Implementation ### Driver Initialization and Synchronous Dialect Setup The Expo SQLite driver initializes through the `drizzle()` export function, accepting an `expo-sqlite` database client (`SQLiteDatabase`) and an optional `DrizzleConfig` object. It instantiates a `SQLiteSyncDialect` instance configured with any provided column casing rules. When schema definitions are present, it invokes `extractTablesRelationalConfig()` along with table relation helpers to build a relational schema structure containing full schemas, table maps, and name mappings. ```typescript export function drizzle = Record>( client: SQLiteDatabase, config: DrizzleConfig = {}, ): ExpoSQLiteDatabase & { $client: SQLiteDatabase; } { const dialect = new SQLiteSyncDialect({ casing: config.casing }); let logger; if (config.logger === true) { logger = new DefaultLogger(); } else if (config.logger !== false) { logger = config.logger; } let schema: RelationalSchemaConfig | undefined; if (config.schema) { const tablesConfig = extractTablesRelationalConfig( config.schema, createTableRelationsHelpers, ); schema = { fullSchema: config.schema, schema: tablesConfig.tables, tableNamesMap: tablesConfig.tableNamesMap, }; } ``` Sources: [drizzle-orm/src/expo-sqlite/driver.ts:21-46](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/expo-sqlite/driver.ts#L21-L46) The `drizzle()` function constructs an `ExpoSQLiteSession` passing the client, dialect, schema, and logger options. It then instantiates an `ExpoSQLiteDatabase` instance operating in `'sync'` mode, assigns the raw client handle to the `$client` property, and returns the database handle typed against the provided schema. ```typescript const session = new ExpoSQLiteSession(client, dialect, schema, { logger }); const db = new ExpoSQLiteDatabase('sync', dialect, session, schema) as ExpoSQLiteDatabase; ( db).$client = client; return db as any; } ``` Sources: [drizzle-orm/src/expo-sqlite/driver.ts:48-53](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/expo-sqlite/driver.ts#L48-L53) > [!NOTE] > `ExpoSQLiteDatabase` extends `BaseSQLiteDatabase` with a fixed `'sync'` execution mode type parameter and an entity kind of `'ExpoSQLiteDatabase'`. Sources: [drizzle-orm/src/expo-sqlite/driver.ts:15-19](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/expo-sqlite/driver.ts#L15-L19) ## OP-SQLite React Native Driver ### Driver Initialization and Async Dialect Setup The OP-SQLite driver provides native SQLite integration for React Native environments via `@op-engineering/op-sqlite`. The `drizzle()` initialization function accepts an `OPSQLiteConnection` client and an optional `DrizzleConfig` record, returning an `OPSQLiteDatabase` instance configured for asynchronous execution mode. ```typescript export function drizzle = Record>( client: OPSQLiteConnection, config: DrizzleConfig = {}, ): OPSQLiteDatabase & { $client: OPSQLiteConnection; } { const dialect = new SQLiteAsyncDialect({ casing: config.casing }); ``` Sources: [drizzle-orm/src/op-sqlite/driver.ts:21-27](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/op-sqlite/driver.ts#L21-L27) The function configures logging based on the boolean or custom logger provided in `config.logger`, and maps relational table configurations when `config.schema` is defined. ```typescript let logger; if (config.logger === true) { logger = new DefaultLogger(); } else if (config.logger !== false) { logger = config.logger; } let schema: RelationalSchemaConfig | undefined; if (config.schema) { const tablesConfig = extractTablesRelationalConfig( config.schema, createTableRelationsHelpers, ); schema = { fullSchema: config.schema, schema: tablesConfig.tables, tableNamesMap: tablesConfig.tableNamesMap, }; } ``` Sources: [drizzle-orm/src/op-sqlite/driver.ts:28-46](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/op-sqlite/driver.ts#L28-L46) ### Session Orchestration and Client Properties An `OPSQLiteSession` is instantiated with the connection client, asynchronous dialect, schema configuration, logger, and cache options. The returned database object exposes both the underlying client handle via `$client` and cache mutation handlers when cache options are active. ```typescript const session = new OPSQLiteSession(client, dialect, schema, { logger, cache: config.cache }); const db = new OPSQLiteDatabase('async', dialect, session, schema) as OPSQLiteDatabase; ( db).$client = client; ( db).$cache = config.cache; if (( db).$cache) { ( db).$cache['invalidate'] = config.cache?.onMutate; } return db as any; ``` Sources: [drizzle-orm/src/op-sqlite/driver.ts:48-56](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/op-sqlite/driver.ts#L48-L56) > [!NOTE] > `OPSQLiteDatabase` extends `BaseSQLiteDatabase` with an `'async'` execution mode and a `QueryResult` return type, establishing entity identity via its static entity kind property. Sources: [drizzle-orm/src/op-sqlite/driver.ts:15-19](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/op-sqlite/driver.ts#L15-L19) ## SQL.js In-Memory WebAssembly Sessions ### Driver Initialization and Synchronous Dialect Setup The sql.js driver executes SQLite queries inside browser and sandbox environments using WebAssembly memory instances. The entry point `drizzle()` accepts an `sql.js` `Database` client instance alongside an optional `DrizzleConfig` record, returning an `SQLJsDatabase` instance configured for synchronous execution (`'sync'`). ```typescript export function drizzle = Record>( client: Database, config: DrizzleConfig = {}, ): SQLJsDatabase { ``` Sources: [drizzle-orm/src/sql-js/driver.ts:18-21](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql-js/driver.ts#L18-L21) During initialization, it creates a `SQLiteSyncDialect` instance utilizing any casing rules specified in configuration options. It inspects `config.logger` to instantiate either a `DefaultLogger` when set to `true` or a custom logger object when provided. If `config.schema` is defined, `extractTablesRelationalConfig()` processes table relations helpers to construct relational configuration maps. ```typescript const dialect = new SQLiteSyncDialect({ casing: config.casing }); let logger; if (config.logger === true) { logger = new DefaultLogger(); } else if (config.logger !== false) { logger = config.logger; } let schema: RelationalSchemaConfig | undefined; if (config.schema) { const tablesConfig = extractTablesRelationalConfig( config.schema, createTableRelationsHelpers, ); schema = { fullSchema: config.schema, schema: tablesConfig.tables, tableNamesMap: tablesConfig.tableNamesMap, }; } ``` Sources: [drizzle-orm/src/sql-js/driver.ts:22-41](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql-js/driver.ts#L22-L41) An `SQLJsSession` is then instantiated with the database client, dialect, schema configuration, and logger options, which wraps a `BaseSQLiteDatabase` instance operating in synchronous mode. ```typescript const session = new SQLJsSession(client, dialect, schema, { logger }); return new BaseSQLiteDatabase('sync', dialect, session, schema) as SQLJsDatabase; ``` Sources: [drizzle-orm/src/sql-js/driver.ts:43-44](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql-js/driver.ts#L43-L44) > [!NOTE] > `SQLJsDatabase` is type-defined as a `BaseSQLiteDatabase<'sync', void, TSchema>` alias, enforcing synchronous execution across all query builders and operations. Sources: [drizzle-orm/src/sql-js/driver.ts:14-16](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql-js/driver.ts#L14-L16) ### Session Management, Transactions, and Field Normalization The `SQLJsSession` manages synchronous query preparation and transaction lifecycles over the WebAssembly `Database` client. Transactions execute raw SQL statements for `begin`, `commit`, and `rollback`, whereas `SQLJsTransaction` implements nested savepoints using `savepoint spN`, `release savepoint spN`, and `rollback to savepoint spN`. ```typescript override transaction( transaction: (tx: SQLJsTransaction) => T, config: SQLiteTransactionConfig = {}, ): T { const tx = new SQLJsTransaction('sync', this.dialect, this, this.schema); this.run(sql.raw(`begin${config.behavior ? ` ${config.behavior}` : ''}`)); try { const result = transaction(tx); this.run(sql`commit`); return result; } catch (err) { this.run(sql`rollback`); throw err; } } } export class SQLJsTransaction< TFullSchema extends Record, TSchema extends TablesRelationalConfig, > extends SQLiteTransaction<'sync', void, TFullSchema, TSchema> { static override readonly [entityKind]: string = 'SQLJsTransaction'; override transaction(transaction: (tx: SQLJsTransaction) => T): T { const savepointName = `sp${this.nestedIndex + 1}`; const tx = new SQLJsTransaction('sync', this.dialect, this.session, this.schema, this.nestedIndex + 1); tx.run(sql.raw(`savepoint ${savepointName}`)); try { const result = transaction(tx); tx.run(sql.raw(`release savepoint ${savepointName}`)); return result; } catch (err) { tx.run(sql.raw(`rollback to savepoint ${savepointName}`)); throw err; } } ``` Sources: [drizzle-orm/src/sql-js/session.ts:51-86](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql-js/session.ts#L51-L86) The `PreparedQuery` class handles execution methods `run`, `all`, `get`, and `values` by preparing statements via `this.client.prepare()`, binding placeholders with `fillPlaceholders()`, logging queries, and freeing statement handles after execution completes. ```typescript run(placeholderValues?: Record): void { const stmt = this.client.prepare(this.query.sql); const params = fillPlaceholders(this.query.params, placeholderValues ?? {}); this.logger.logQuery(this.query.sql, params); const result = stmt.run(params as BindParams); stmt.free(); return result; } all(placeholderValues?: Record): T['all'] { const stmt = this.client.prepare(this.query.sql); const { fields, joinsNotNullableMap, logger, query, customResultMapper } = this; if (!fields && !customResultMapper) { const params = fillPlaceholders(query.params, placeholderValues ?? {}); logger.logQuery(query.sql, params); stmt.bind(params as BindParams); const rows: unknown[] = []; while (stmt.step()) { rows.push(stmt.getAsObject()); } stmt.free(); return rows; } const rows = this.values(placeholderValues) as unknown[][]; if (customResultMapper) { return customResultMapper(rows, normalizeFieldValue) as T['all']; } return rows.map((row) => mapResultRow(fields!, row.map((v) => normalizeFieldValue(v)), joinsNotNullableMap)); } get(placeholderValues?: Record): T['get'] { const stmt = this.client.prepare(this.query.sql); const params = fillPlaceholders(this.query.params, placeholderValues ?? {}); this.logger.logQuery(this.query.sql, params); const { fields, joinsNotNullableMap, customResultMapper } = this; if (!fields && !customResultMapper) { const result = stmt.getAsObject(params as BindParams); stmt.free(); return result; } const row = stmt.get(params as BindParams); stmt.free(); if (!row || (row.length === 0 && fields!.length > 0)) { return undefined; } if (customResultMapper) { return customResultMapper([row], normalizeFieldValue) as T['get']; } return mapResultRow(fields!, row.map((v) => normalizeFieldValue(v)), joinsNotNullableMap); } values(placeholderValues?: Record): T['values'] { const stmt = this.client.prepare(this.query.sql); const params = fillPlaceholders(this.query.params, placeholderValues ?? {}); this.logger.logQuery(this.query.sql, params); stmt.bind(params as BindParams); const rows: unknown[] = []; while (stmt.step()) { rows.push(stmt.get()); } stmt.free(); return rows; } ``` Sources: [drizzle-orm/src/sql-js/session.ts:106-189](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql-js/session.ts#L106-L189) | Helper Function | Input Type | Output Type | Behavior | | :--- | :--- | :--- | :--- | | `normalizeFieldValue` | `unknown` | `unknown` | Inspects `Uint8Array` instances, converting them via `Buffer.from()` if `Buffer` exists, or via `TextDecoder().decode()` if available. | | `fillPlaceholders` | `unknown[]`, `Record` | `unknown[]` | Maps query parameter placeholders to runtime values supplied in execution parameters. | ```typescript function normalizeFieldValue(value: unknown) { if (value instanceof Uint8Array) { // eslint-disable-line no-instanceof/no-instanceof if (typeof Buffer !== 'undefined') { if (!(value instanceof Buffer)) { // eslint-disable-line no-instanceof/no-instanceof return Buffer.from(value); } return value; } if (typeof TextDecoder !== 'undefined') { return new TextDecoder().decode(value); } throw new Error('TextDecoder is not available. Please provide either Buffer or TextDecoder polyfill.'); } return value; } ``` Sources: [drizzle-orm/src/sql-js/session.ts:197-210](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql-js/session.ts#L197-L210) > [!WARNING] > `normalizeFieldValue` throws an explicit runtime error when encountering a `Uint8Array` binary result row if neither `Buffer` nor `TextDecoder` environment globals are defined. Sources: [drizzle-orm/src/sql-js/session.ts:197-209](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sql-js/session.ts#L197-L209) ## Generic SQLite Proxy Driver Protocol ### Remote Callback Types and Database Initialization The remote SQLite proxy driver delegates execution via asynchronous callback functions rather than tying directly to a local database library. The entry point `drizzle()` accepts an `AsyncRemoteCallback`, an optional `AsyncBatchRemoteCallback`, and a `DrizzleConfig` record to construct a `SqliteRemoteDatabase` instance operating in asynchronous mode (`'async'`). ```typescript export type AsyncRemoteCallback = ( sql: string, params: any[], method: 'run' | 'all' | 'values' | 'get', ) => Promise<{ rows: any[] }>; export type AsyncBatchRemoteCallback = (batch: { sql: string; params: any[]; method: 'run' | 'all' | 'values' | 'get'; }[]) => Promise<{ rows: any[] }[]>; export type RemoteCallback = AsyncRemoteCallback; export function drizzle = Record>( callback: RemoteCallback, config?: DrizzleConfig, ): SqliteRemoteDatabase; export function drizzle = Record>( callback: RemoteCallback, batchCallback?: AsyncBatchRemoteCallback, config?: DrizzleConfig, ): SqliteRemoteDatabase; export function drizzle = Record>( callback: RemoteCallback, batchCallback?: AsyncBatchRemoteCallback | DrizzleConfig, config?: DrizzleConfig, ): SqliteRemoteDatabase { ``` Sources: [drizzle-orm/src/sqlite-proxy/driver.ts:30-57](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-proxy/driver.ts#L30-L57) During construction, `drizzle()` initializes a `SQLiteAsyncDialect` using casing configurations, sets up logging via `DefaultLogger` when `config.logger` is enabled, and extracts relational table structures if `config.schema` is specified. ```typescript const dialect = new SQLiteAsyncDialect({ casing: config?.casing }); let logger; let cache; let _batchCallback: AsyncBatchRemoteCallback | undefined; let _config: DrizzleConfig = {}; if (batchCallback) { if (typeof batchCallback === 'function') { _batchCallback = batchCallback as AsyncBatchRemoteCallback; _config = config ?? {}; } else { _batchCallback = undefined; _config = batchCallback as DrizzleConfig; } if (_config.logger === true) { logger = new DefaultLogger(); } else if (_config.logger !== false) { logger = _config.logger; cache = _config.cache; } } let schema: RelationalSchemaConfig | undefined; if (_config.schema) { const tablesConfig = extractTablesRelationalConfig( _config.schema, createTableRelationsHelpers, ); schema = { fullSchema: _config.schema, schema: tablesConfig.tables, tableNamesMap: tablesConfig.tableNamesMap, }; } ``` Sources: [drizzle-orm/src/sqlite-proxy/driver.ts:58-92](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-proxy/driver.ts#L58-L92) The resulting `SqliteRemoteDatabase` binds a `SQLiteRemoteSession` containing the remote callbacks, dialect, schema definitions, and cache handlers, and configures cache invalidation hooks on `$cache` when provided. ```typescript const session = new SQLiteRemoteSession(callback, dialect, schema, _batchCallback, { logger, cache }); const db = new SqliteRemoteDatabase('async', dialect, session, schema) as SqliteRemoteDatabase; ( db).$cache = cache; if (( db).$cache) { ( db).$cache['invalidate'] = cache?.onMutate; } return db; ``` Sources: [drizzle-orm/src/sqlite-proxy/driver.ts:93-100](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-proxy/driver.ts#L93-L100) > [!NOTE] > `SqliteRemoteDatabase` overrides the `batch()` method to forward batch query arrays directly to the underlying session's batch handler. Sources: [drizzle-orm/src/sqlite-proxy/driver.ts:23-28](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-proxy/driver.ts#L23-L28) ### Remote Callback Signatures and Packaging | Callback Type | Parameter Signature | Return Type | Purpose | | :--- | :--- | :--- | :--- | | `AsyncRemoteCallback` | `sql: string, params: any[], method: 'run' \| 'all' \| 'values' \| 'get'` | `Promise<{ rows: any[] }>` | Executes a single SQL statement remotely with parameters and execution method. | | `AsyncBatchRemoteCallback` | `batch: { sql: string, params: any[], method: 'run' \| 'all' \| 'values' \| 'get' }[]` | `Promise<{ rows: any[] }[]>` | Packages multiple statements into a single batch payload for remote RPC transmission. | ```typescript export type AsyncRemoteCallback = ( sql: string, params: any[], method: 'run' | 'all' | 'values' | 'get', ) => Promise<{ rows: any[] }>; export type AsyncBatchRemoteCallback = (batch: { sql: string; params: any[]; method: 'run' | 'all' | 'values' | 'get'; }[]) => Promise<{ rows: any[] }[]>; ``` Sources: [drizzle-orm/src/sqlite-proxy/driver.ts:30-40](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-proxy/driver.ts#L30-L40) ## Related - [Drivers And Runtimes](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/drivers-and-runtimes/drivers-and-runtimes) - [Dialects And Schema Query Builders](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/dialects-and-schema/dialects-and-schema-query-builders) --- ## Technical docs: Knex Kysely and Prisma Interop URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/drivers-and-runtimes/knex-kysely-and-prisma-interop
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-orm/src/neon-serverless/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-serverless/session.ts) - [drizzle-orm/src/neon-serverless/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-serverless/driver.ts) - [drizzle-orm/src/prisma/sqlite/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/sqlite/driver.ts) - [drizzle-kit/src/api.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/api.ts) - [drizzle-orm/src/prisma/pg/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/pg/session.ts) - [drizzle-orm/src/prisma/mysql/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/mysql/driver.ts) - [drizzle-orm/src/prisma/mysql/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/mysql/session.ts) - [drizzle-orm/src/netlify-db/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/session.ts) - [drizzle-orm/src/singlestore/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore/session.ts) - [drizzle-orm/src/prisma/pg/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/pg/driver.ts) - [drizzle-orm/src/netlify-db/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/driver.ts) - [drizzle-orm/src/prisma/sqlite/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/sqlite/session.ts) - [drizzle-orm/src/gel/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel/session.ts) - [drizzle-kit/src/cli/connections.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/connections.ts) - [drizzle-orm/src/gel/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel/driver.ts) - [drizzle-orm/src/planetscale-serverless/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/planetscale-serverless/session.ts) - [drizzle-orm/src/mysql2/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql2/session.ts) - [drizzle-orm/src/node-postgres/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/node-postgres/driver.ts) - [drizzle-orm/src/postgres-js/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/postgres-js/session.ts) - [drizzle-orm/src/singlestore/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore/driver.ts) - [drizzle-orm/src/mysql2/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql2/driver.ts) - [drizzle-orm/src/durable-sqlite/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/durable-sqlite/driver.ts) - [drizzle-orm/src/vercel-postgres/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/vercel-postgres/driver.ts) - [drizzle-orm/src/vercel-postgres/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/vercel-postgres/session.ts) - [drizzle-orm/src/planetscale-serverless/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/planetscale-serverless/driver.ts) - [drizzle-orm/src/aws-data-api/pg/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/aws-data-api/pg/session.ts) - [drizzle-orm/src/postgres-js/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/postgres-js/driver.ts) - [drizzle-orm/src/pglite/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pglite/driver.ts) - [drizzle-orm/src/aws-data-api/pg/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/aws-data-api/pg/driver.ts) - [drizzle-orm/src/neon-http/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-http/driver.ts)
## Overview The Prisma interop layer bridges Drizzle's query builder and schema definitions with Prisma Client across PostgreSQL, MySQL, and SQLite dialects. By defining Prisma extensions with `$drizzle`, Drizzle maps SQL operations to Prisma's underlying raw execution methods such as `$queryRawUnsafe`. Sources: [drizzle-orm/src/prisma/sqlite/driver.ts:1-32](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/sqlite/driver.ts#L1-L32), [drizzle-orm/src/prisma/pg/session.ts:16-40](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/pg/session.ts#L16-L40), [drizzle-orm/src/prisma/mysql/driver.ts:1-42](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/mysql/driver.ts#L1-L42) ## Prisma PostgreSQL Driver and Session Integration ### Driver Initialization and Prisma Extension Setup The PostgreSQL interop layer is initialized through the `drizzle()` function, which consumes a `PrismaPgConfig` configuration object excluding the schema definition. If `config.logger` is set to `true`, a `DefaultLogger` is instantiated; otherwise, custom logger instances or `false` are assigned. The function returns a Prisma extension defined via `Prisma.defineExtension`, attaching a `PrismaPgDatabase` instance to the client under the `$drizzle` property. ```typescript export type PrismaPgConfig = Omit; export function drizzle(config: PrismaPgConfig = {}) { let logger: Logger | undefined; if (config.logger === true) { logger = new DefaultLogger(); } else if (config.logger !== false) { logger = config.logger; } return Prisma.defineExtension((client) => { return client.$extends({ name: 'drizzle', client: { $drizzle: new PrismaPgDatabase(client, logger), }, }); }); } ``` Sources: [drizzle-orm/src/prisma/pg/driver.ts:22-40](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/pg/driver.ts#L22-L40) `PrismaPgDatabase` extends `PgDatabase` with `PrismaPgQueryResultHKT` and an empty record type, constructing a `PgDialect` and a `PrismaPgSession` initialized with the Prisma client and session options containing the logger. ```typescript export class PrismaPgDatabase extends PgDatabase> { static override readonly [entityKind]: string = 'PrismaPgDatabase'; constructor(client: PrismaClient, logger: Logger | undefined) { const dialect = new PgDialect(); super(dialect, new PrismaPgSession(dialect, client, { logger }), undefined); } } ``` Sources: [drizzle-orm/src/prisma/pg/driver.ts:13-20](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/pg/driver.ts#L13-L20) ### Session Management and Prepared Query Execution `PrismaPgSession` extends `PgSession`, configuring its logger to either the provided session option or a `NoopLogger` fallback. Executing a raw SQL query delegates to `prepareQuery` using `this.dialect.sqlToQuery(query)`, subsequently calling `.execute()`. ```typescript export class PrismaPgSession extends PgSession { static override readonly [entityKind]: string = 'PrismaPgSession'; private readonly logger: Logger; constructor( dialect: PgDialect, private readonly prisma: PrismaClient, private readonly options: PrismaPgSessionOptions, ) { super(dialect); this.logger = options.logger ?? new NoopLogger(); } override execute(query: SQL): Promise { return this.prepareQuery(this.dialect.sqlToQuery(query)).execute(); } override prepareQuery(query: Query): PgPreparedQuery { return new PrismaPgPreparedQuery(this.prisma, query, this.logger); } ``` Sources: [drizzle-orm/src/prisma/pg/session.ts:46-66](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/pg/session.ts#L46-L66) > [!WARNING] > Both `PrismaPgSession.transaction` and `PrismaPgPreparedQuery.all` throw explicit `Method not implemented.` errors when invoked, meaning transactions and array-mode responses are unsupported under the Prisma PostgreSQL interop session. ```typescript override all(): Promise { throw new Error('Method not implemented.'); } ``` Sources: [drizzle-orm/src/prisma/pg/session.ts:33-35](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/pg/session.ts#L33-L35), [drizzle-orm/src/prisma/pg/session.ts:68-73](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/pg/session.ts#L68-L73) `PrismaPgPreparedQuery` extends `PgPreparedQuery` to execute statements against the underlying `PrismaClient`. When `execute()` is called, placeholders are filled via `fillPlaceholders()`, the query and parameters are logged, and execution proceeds through `prisma.$queryRawUnsafe()`. ```typescript export class PrismaPgPreparedQuery extends PgPreparedQuery { static override readonly [entityKind]: string = 'PrismaPgPreparedQuery'; constructor( private readonly prisma: PrismaClient, query: Query, private readonly logger: Logger, ) { super(query, undefined, undefined, undefined); } override execute(placeholderValues?: Record): Promise { const params = fillPlaceholders(this.query.params, placeholderValues ?? {}); this.logger.logQuery(this.query.sql, params); return this.prisma.$queryRawUnsafe(this.query.sql, ...params); } ``` Sources: [drizzle-orm/src/prisma/pg/session.ts:16-31](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/pg/session.ts#L16-L31) ## Prisma MySQL Session and Query Handling ### Driver Initialization and Prisma Extension Setup The MySQL interop module exposes `PrismaMySqlDatabase`, which extends `MySqlDatabase` with `PrismaMySqlQueryResultHKT`, `PrismaMySqlPreparedQueryHKT`, and an empty record type. Its constructor instantiates a `MySqlDialect` and a `PrismaMySqlSession` equipped with the provided `PrismaClient` and logger options. ```typescript export class PrismaMySqlDatabase extends MySqlDatabase> { static override readonly [entityKind]: string = 'PrismaMySqlDatabase'; constructor(client: PrismaClient, logger: Logger | undefined) { const dialect = new MySqlDialect(); super(dialect, new PrismaMySqlSession(dialect, client, { logger }), undefined, 'default'); } } ``` Sources: [drizzle-orm/src/prisma/mysql/driver.ts:13-22](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/mysql/driver.ts#L13-L22) The `drizzle()` entry point accepts a `PrismaMySqlConfig` type, omitting the `schema` property from `DrizzleConfig`. If `config.logger` is set to `true`, a `DefaultLogger` is created; otherwise, custom loggers or `false` are preserved. The function returns a Prisma extension via `Prisma.defineExtension`, appending the `$drizzle` database client instance to the extended Prisma client. ```typescript export type PrismaMySqlConfig = Omit; export function drizzle(config: PrismaMySqlConfig = {}) { let logger: Logger | undefined; if (config.logger === true) { logger = new DefaultLogger(); } else if (config.logger !== false) { logger = config.logger; } return Prisma.defineExtension((client) => { return client.$extends({ name: 'drizzle', client: { $drizzle: new PrismaMySqlDatabase(client, logger), }, }); }); } ``` Sources: [drizzle-orm/src/prisma/mysql/driver.ts:24-42](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/mysql/driver.ts#L24-L42) ### Session Management and Prepared Query Execution `PrismaMySqlSession` extends `MySqlSession`, resolving its logger option to either the supplied logger or a `NoopLogger` fallback. The session implements raw execution by converting `SQL` objects via `this.dialect.sqlToQuery(query)` and delegating to `prepareQuery().execute()`. ```typescript export class PrismaMySqlSession extends MySqlSession { static override readonly [entityKind]: string = 'PrismaMySqlSession'; private readonly logger: Logger; constructor( dialect: MySqlDialect, private readonly prisma: PrismaClient, private readonly options: PrismaMySqlSessionOptions, ) { super(dialect); this.logger = options.logger ?? new NoopLogger(); } override execute(query: SQL): Promise { return this.prepareQuery(this.dialect.sqlToQuery(query)).execute(); } ``` Sources: [drizzle-orm/src/prisma/mysql/session.ts:43-60](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/mysql/session.ts#L43-L60) ```typescript override prepareQuery( query: Query, ): MySqlPreparedQuery { return new PrismaMySqlPreparedQuery(this.prisma, query, this.logger); } ``` Sources: [drizzle-orm/src/prisma/mysql/session.ts:65-69](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/mysql/session.ts#L65-L69) > [!WARNING] > `PrismaMySqlSession` does not implement `all`, `transaction`, or `PrismaMySqlPreparedQuery.iterator`. Invoking any of these methods throws an explicit `Method not implemented.` error at runtime. ```typescript override iterator(_placeholderValues?: Record | undefined): AsyncGenerator { throw new Error('Method not implemented.'); } ``` Sources: [drizzle-orm/src/prisma/mysql/session.ts:19-21](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/mysql/session.ts#L19-L21), [drizzle-orm/src/prisma/mysql/session.ts:61-63](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/mysql/session.ts#L61-L63), [drizzle-orm/src/prisma/mysql/session.ts:71-84](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/mysql/session.ts#L71-L84) `PrismaMySqlPreparedQuery` extends `MySqlPreparedQuery` to bind queries against `PrismaClient`. When `execute()` is called, parameter placeholders are populated using `fillPlaceholders()`, the query is logged, and the statement executes through `prisma.$queryRawUnsafe()`. ```typescript export class PrismaMySqlPreparedQuery extends MySqlPreparedQuery { override iterator(_placeholderValues?: Record | undefined): AsyncGenerator { throw new Error('Method not implemented.'); } static override readonly [entityKind]: string = 'PrismaMySqlPreparedQuery'; constructor( private readonly prisma: PrismaClient, private readonly query: Query, private readonly logger: Logger, ) { super(undefined, undefined, undefined); } override execute(placeholderValues?: Record): Promise { const params = fillPlaceholders(this.query.params, placeholderValues ?? {}); this.logger.logQuery(this.query.sql, params); return this.prisma.$queryRawUnsafe(this.query.sql, ...params); } } ``` Sources: [drizzle-orm/src/prisma/mysql/session.ts:18-37](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/mysql/session.ts#L18-L37) ## Prisma SQLite Async Driver Architecture ### Driver Initialization and Prisma Extension Setup The SQLite interop module provides a `drizzle()` function that accepts a `PrismaSQLiteConfig` type, omitting the `schema` property from `DrizzleConfig`. It instantiates a `SQLiteAsyncDialect` and resolves the logger configuration: setting up a `DefaultLogger` when `config.logger` is `true`, preserving custom loggers, or omitting it otherwise. ```typescript export type PrismaSQLiteConfig = Omit; export function drizzle(config: PrismaSQLiteConfig = {}) { const dialect = new SQLiteAsyncDialect(); let logger: Logger | undefined; if (config.logger === true) { logger = new DefaultLogger(); } else if (config.logger !== false) { logger = config.logger; } ``` Sources: [drizzle-orm/src/prisma/sqlite/driver.ts:11-20](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/sqlite/driver.ts#L11-L20) The function returns a Prisma extension via `Prisma.defineExtension()`, instantiating a `PrismaSQLiteSession` with the underlying client, dialect, and logger. It then injects the `$drizzle` database client initialized as a `BaseSQLiteDatabase` with an `'async'` mode into the extended client. ```typescript return Prisma.defineExtension((client) => { const session = new PrismaSQLiteSession(client, dialect, { logger }); return client.$extends({ name: 'drizzle', client: { $drizzle: new BaseSQLiteDatabase('async', dialect, session, undefined) as PrismaSQLiteDatabase, }, }); }); ``` Sources: [drizzle-orm/src/prisma/sqlite/driver.ts:22-31](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/sqlite/driver.ts#L22-L31) ### Session Management and Prepared Query Execution `PrismaSQLiteSession` extends `SQLiteSession` with `'async'` execution mode, configuring its logger to either the provided options logger or a `NoopLogger` fallback. The session implements `prepareQuery()` to construct `PrismaSQLitePreparedQuery` instances and overrides `transaction()` to throw an unimplemented error. ```typescript export class PrismaSQLiteSession extends SQLiteSession<'async', unknown, Record, Record> { static override readonly [entityKind]: string = 'PrismaSQLiteSession'; private readonly logger: Logger; constructor( private readonly prisma: PrismaClient, dialect: SQLiteAsyncDialect, options: PrismaSQLiteSessionOptions, ) { super(dialect); this.logger = options.logger ?? new NoopLogger(); } override prepareQuery>( query: Query, fields: SelectedFieldsOrdered | undefined, executeMethod: SQLiteExecuteMethod, ): PrismaSQLitePreparedQuery { return new PrismaSQLitePreparedQuery(this.prisma, query, this.logger, executeMethod); } override transaction( _transaction: (tx: SQLiteTransaction<'async', unknown, Record, Record>) => Promise, _config?: SQLiteTransactionConfig, ): Promise { throw new Error('Method not implemented.'); } } ``` Sources: [drizzle-orm/src/prisma/sqlite/session.ts:62-90](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/sqlite/session.ts#L62-L90) > [!WARNING] > `PrismaSQLiteSession.transaction()` and `PrismaSQLitePreparedQuery.values()` are not implemented. Invoking either method throws a `Method not implemented.` error at runtime. ```typescript override values(_placeholderValues?: Record | undefined): Promise { throw new Error('Method not implemented.'); } ``` Sources: [drizzle-orm/src/prisma/sqlite/session.ts:49-51](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/sqlite/session.ts#L49-L51), [drizzle-orm/src/prisma/sqlite/session.ts:84-89](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/sqlite/session.ts#L84-L89) `PrismaSQLitePreparedQuery` extends `SQLitePreparedQuery` to execute statements against `PrismaClient`. The `all()` method populates statement parameters via `fillPlaceholders()`, logs the query, and delegates to `prisma.$queryRawUnsafe()`. ```typescript export class PrismaSQLitePreparedQuery extends SQLitePreparedQuery< { type: 'async'; run: []; all: T['all']; get: T['get']; values: never; execute: T['execute'] } > { static override readonly [entityKind]: string = 'PrismaSQLitePreparedQuery'; constructor( private readonly prisma: PrismaClient, query: Query, private readonly logger: Logger, executeMethod: SQLiteExecuteMethod, ) { super('async', executeMethod, query); } override all(placeholderValues?: Record): Promise { const params = fillPlaceholders(this.query.params, placeholderValues ?? {}); this.logger.logQuery(this.query.sql, params); return this.prisma.$queryRawUnsafe(this.query.sql, ...params); } ``` Sources: [drizzle-orm/src/prisma/sqlite/session.ts:19-37](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/sqlite/session.ts#L19-L37) The prepared query handles additional execution modalities by building upon `all()`. Specifically, `run()` executes the query and returns an empty array, `get()` retrieves the first row from the result set, and `isResponseInArrayMode()` explicitly returns `false`. ```typescript override async run(placeholderValues?: Record | undefined): Promise<[]> { await this.all(placeholderValues); return []; } override async get(placeholderValues?: Record | undefined): Promise { const all = await this.all(placeholderValues) as unknown[]; return all[0]; } override values(_placeholderValues?: Record | undefined): Promise { throw new Error('Method not implemented.'); } override isResponseInArrayMode(): boolean { return false; } } ``` Sources: [drizzle-orm/src/prisma/sqlite/session.ts:39-56](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/prisma/sqlite/session.ts#L39-L56) ## Serverless and Managed Adapter Interoperability ### Neon and Netlify DB Driver Initialization The serverless architecture adapts HTTP and WebSocket-based PostgreSQL clients for connectionless or pooled execution runtimes. The Neon serverless driver exports the `NeonDriver` and `NeonDatabase` classes, supporting initialization via connection strings, pool configurations, or pre-constructed client instances through `drizzle()`. ```typescript export function drizzle< TSchema extends Record = Record, TClient extends NeonClient = Pool, >( ...params: [ TClient | string, ] | [ TClient | string, DrizzleConfig, ] | [ ( & DrizzleConfig & ({ connection: string | PoolConfig; } | { client: TClient; }) & { ws?: any; } ), ] ): NeonDatabase & { $client: NeonClient extends TClient ? Pool : TClient; } { ``` Sources: [drizzle-orm/src/neon-serverless/driver.ts:91-115](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-serverless/driver.ts#L115-L147) Similarly, the Netlify DB driver establishes type parsers during driver construction for temporal and array data types using `types.setTypeParser()`. ```typescript export class NetlifyDbDriver { static readonly [entityKind]: string = 'NetlifyDbDriver'; constructor( private httpClient: NeonHttpClient, private pool: Pool, private dialect: PgDialect, private options: NetlifyDbDriverOptions = {}, ) { this.initMappers(); } createSession( schema: V1.RelationalSchemaConfig | undefined, ): NetlifyDbSession, V1.TablesRelationalConfig> { return new NetlifyDbSession(this.httpClient, this.pool, this.dialect, schema, { logger: this.options.logger, cache: this.options.cache, }); } initMappers() { types.setTypeParser(types.builtins.TIMESTAMPTZ, (val: any) => val); types.setTypeParser(types.builtins.TIMESTAMP, (val: any) => val); types.setTypeParser(types.builtins.DATE, (val: any) => val); types.setTypeParser(types.builtins.INTERVAL, (val: any) => val); types.setTypeParser(1231, (val: any) => val); types.setTypeParser(1115, (val: any) => val); types.setTypeParser(1185, (val: any) => val); types.setTypeParser(1187, (val: any) => val); types.setTypeParser(1182, (val: any) => val); } } ``` Sources: [drizzle-orm/src/netlify-db/driver.ts:37-69](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/driver.ts#L37-L69) Type parsers registered during Netlify DB driver initialization map specific PostgreSQL built-in type OIDs directly to raw values without altering formats. | OID Constant / Built-in | Parser Target | Sources | | :--- | :--- | :--- | | `types.builtins.TIMESTAMPTZ` | Returns raw value | [drizzle-orm/src/netlify-db/driver.ts:59](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/driver.ts#L59) | | `types.builtins.TIMESTAMP` | Returns raw value | [drizzle-orm/src/netlify-db/driver.ts:60](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/driver.ts#L60) | | `types.builtins.DATE` | Returns raw value | [drizzle-orm/src/netlify-db/driver.ts:61](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/driver.ts#L61) | | `types.builtins.INTERVAL` | Returns raw value | [drizzle-orm/src/netlify-db/driver.ts:62](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/driver.ts#L62) | | `1231` | Returns raw value | [drizzle-orm/src/netlify-db/driver.ts:63](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/driver.ts#L63) | | `1115` | Returns raw value | [drizzle-orm/src/netlify-db/driver.ts:64](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/driver.ts#L64) | | `1185` | Returns raw value | [drizzle-orm/src/netlify-db/driver.ts:65](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/driver.ts#L65) | | `1187` | Returns raw value | [drizzle-orm/src/netlify-db/driver.ts:66](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/driver.ts#L66) | | `1182` | Returns raw value | [drizzle-orm/src/netlify-db/driver.ts:67](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/driver.ts#L67) | Sources: [drizzle-orm/src/netlify-db/driver.ts:59-67](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/driver.ts#L59-L67) ### Session Execution and Transaction Semantics `NeonSession` manages query preparation, logging, caching, and statement execution. When handling transactions, it inspects whether the underlying client is a `Pool` instance; if so, it acquires a dedicated client connection for the duration of the transaction block and releases it afterward in a `finally` block. ```typescript override async transaction( transaction: (tx: NeonTransaction) => Promise, config: PgTransactionConfig = {}, ): Promise { const session = this.client instanceof Pool // eslint-disable-line no-instanceof/no-instanceof ? new NeonSession(await this.client.connect(), this.dialect, this.schema, this.options) : this; const tx = new NeonTransaction(this.dialect, session, this.schema); await tx.execute(sql`begin ${tx.getTransactionConfigSQL(config)}`); try { const result = await transaction(tx); await tx.execute(sql`commit`); return result; } catch (error) { await tx.execute(sql`rollback`); throw error; } finally { if (this.client instanceof Pool) { // eslint-disable-line no-instanceof/no-instanceof (session.client as PoolClient).release(); } } } ``` Sources: [drizzle-orm/src/neon-serverless/session.ts:260-281](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-serverless/session.ts#L260-L281) > [!WARNING] > `NeonSession.transaction()` checks `this.client instanceof Pool` to branch between acquiring a pooled client connection or reusing the existing session client. Failing to release pool clients in custom implementations leaks connections. ```typescript const session = this.client instanceof Pool // eslint-disable-line no-instanceof/no-instanceof ? new NeonSession(await this.client.connect(), this.dialect, this.schema, this.options) : this; ``` Sources: [drizzle-orm/src/neon-serverless/session.ts:264-266](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-serverless/session.ts#L264-L266), [drizzle-orm/src/neon-serverless/session.ts:277-279](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-serverless/session.ts#L277-L279) Nested transactions in both `NeonTransaction` and `NetlifyDbTransaction` utilize PostgreSQL savepoints with automatically incremented identifiers. Each nested transaction level generates a savepoint named via `sp${this.nestedIndex + 1}`, releasing or rolling back to that savepoint depending on execution success. ```typescript override async transaction(transaction: (tx: NeonTransaction) => Promise): Promise { const savepointName = `sp${this.nestedIndex + 1}`; const tx = new NeonTransaction(this.dialect, this.session, this.schema, this.nestedIndex + 1); await tx.execute(sql.raw(`savepoint ${savepointName}`)); try { const result = await transaction(tx); await tx.execute(sql.raw(`release savepoint ${savepointName}`)); return result; } catch (e) { await tx.execute(sql.raw(`rollback to savepoint ${savepointName}`)); throw e; } } ``` Sources: [drizzle-orm/src/neon-serverless/session.ts:290-302](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/neon-serverless/session.ts#L290-L302), [drizzle-orm/src/netlify-db/session.ts:273-292](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/netlify-db/session.ts#L273-L292) ## Cloud Runtime Driver Interop Patterns ### Gel Driver and Client Initialization The Gel driver interface supports initialization via connection strings, existing `Client` instances, or configuration objects containing connection options. The `drizzle()` factory function inspects its parameters to construct a `GelDriver` instance paired with a `GelDialect`. | Parameter Variant | Handling Behavior | Sources | | :--- | :--- | :--- | | `string` (DSN) | Creates a client via `createClient({ dsn })` | [drizzle-orm/src/gel/driver.ts:109-113](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel/driver.ts#L109-L113) | | `Object` (Config with `client`) | Uses the provided client instance directly | [drizzle-orm/src/gel/driver.ts:115-121](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel/driver.ts#L115-L121) | | `Object` (Config with `connection`) | Instantiates a client with `connection` options | [drizzle-orm/src/gel/driver.ts:115-126](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel/driver.ts#L115-L126) | | Direct `Client` | Constructs database instance using the client | [drizzle-orm/src/gel/driver.ts:128](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel/driver.ts#L128) | | `drizzle.mock()` | Initializes a mock client object | [drizzle-orm/src/gel/driver.ts:131-138](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel/driver.ts#L131-L138) | Sources: [drizzle-orm/src/gel/driver.ts:109-138](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel/driver.ts#L109-L138) ```typescript export function drizzle< TSchema extends Record = Record, TClient extends GelClient = Client, >( ...params: | [TClient | string] | [TClient | string, DrizzleConfig] | [ & DrizzleConfig & ( | { connection: string | ConnectOptions; } | { client: TClient; } ), ] ``` Sources: [drizzle-orm/src/gel/driver.ts:88-105](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel/driver.ts#L88-L105) ### AWS Data API Parameter Customization The AWS Data API PostgreSQL driver specializes query execution through `AwsPgDialect`, which overrides parameter escaping and array handling. Positional parameters are formatted as `:${num + 1}`, and array columns in insert and update operations are explicitly cast to their SQL type definitions. ```typescript export class AwsPgDialect extends PgDialect { static override readonly [entityKind]: string = 'AwsPgDialect'; override escapeParam(num: number): string { return `:${num + 1}`; } ``` Sources: [drizzle-orm/src/aws-data-api/pg/driver.ts:50-56](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/aws-data-api/pg/driver.ts#L50-L56), [drizzle-orm/src/aws-data-api/pg/driver.ts:67-72](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/aws-data-api/pg/driver.ts#L67-L72) > [!NOTE] > `AwsPgDialect` intercepts insert and update building to locate encoder instances matching `PgArray`. When array values are present, it wraps them in an explicit `cast(... as ...)` expression to satisfy strict AWS RDS Data API typing requirements. ```typescript const colValue = value[fieldName]; if ( is(colValue, Param) && colValue.value !== undefined && is(colValue.encoder, PgArray) && Array.isArray(colValue.value) ) { value[fieldName] = sql`cast(${colValue} as ${sql.raw(colValue.encoder.getSQLType())})`; } } ``` Sources: [drizzle-orm/src/aws-data-api/pg/driver.ts:65-72](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/aws-data-api/pg/driver.ts#L65-L72), [drizzle-orm/src/aws-data-api/pg/driver.ts:83-90](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/aws-data-api/pg/driver.ts#L83-L90) ## Related - [Sessions and Transactions](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/sessions-and-transactions) --- ## Technical docs: CLI Command Architecture URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/cli-command-architecture
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-kit/src/cli/commands/migrate.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/migrate.ts) - [drizzle-kit/src/cli/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/index.ts) - [drizzle-kit/src/cli/schema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/schema.ts) - [drizzle-kit/src/cli/views.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/views.ts) - [drizzle-kit/src/api.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/api.ts) - [drizzle-kit/src/cli/commands/utils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/utils.ts) - [drizzle-kit/src/snapshotsDiffer.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/snapshotsDiffer.ts) - [drizzle-kit/src/cli/commands/introspect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/introspect.ts) - [drizzle-kit/src/cli/commands/push.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/push.ts) - [drizzle-kit/src/cli/connections.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/connections.ts) - [drizzle-kit/src/cli/commands/check.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/check.ts) - [drizzle-kit/src/cli/validations/outputs.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/outputs.ts) - [drizzle-kit/src/cli/commands/singlestorePushUtils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/singlestorePushUtils.ts) - [drizzle-kit/src/utils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/utils.ts) - [drizzle-kit/src/cli/commands/pgPushUtils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/pgPushUtils.ts) - [drizzle-kit/src/cli/validations/common.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/common.ts) - [drizzle-kit/src/cli/utils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/utils.ts) - [drizzle-kit/src/cli/validations/sqlite.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/sqlite.ts) - [drizzle-kit/src/cli/validations/cli.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/cli.ts) - [drizzle-kit/src/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/index.ts) - [drizzle-kit/src/cli/commands/singlestoreUp.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/singlestoreUp.ts) - [drizzle-kit/src/cli/commands/drop.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/drop.ts) - [drizzle-kit/src/cli/selector-ui.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/selector-ui.ts)
## Overview The CLI command architecture of `drizzle-kit` orchestrates schema migrations, [database introspection](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/database-introspection), direct synchronization, and local environment execution by wiring command definitions, argument parsing, runtime compilation, and interactive terminal interfaces together. Powered by Brocli entrypoints and Hanji terminal renderers, the command layer handles user execution flows across PostgreSQL, MySQL, SQLite, Turso, SingleStore, and Gel dialects. It bridges configuration validation utilities with migration generators and snapshot diffing tools, ensuring schema integrity and managing the complete lifecycle of database development workflows. Sources: [drizzle-kit/src/cli/commands/migrate.ts:1-57](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/migrate.ts#L1-L57), [drizzle-kit/src/cli/index.ts:1-48](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/index.ts#L1-L48), [drizzle-kit/src/cli/schema.ts:1-113](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/schema.ts#L1-L113), [drizzle-kit/src/cli/views.ts:1-16](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/views.ts#L1-L16), [drizzle-kit/src/cli/commands/utils.ts:33-102](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/utils.ts#L33-L102) ## Command Registration and Brocli Entrypoints ### Brocli Command Execution and Entrypoint The CLI entrypoint of `drizzle-kit` initializes command parsing and dispatching via the `@drizzle-team/brocli` package. The root execution runner `run` accepts an array of active schema commands along with legacy command aliases, passing configuration options such as the CLI name `drizzle-kit` and the version handler function. ```typescript run([generate, migrate, pull, push, studio, up, check, drop, exportRaw, ...legacy], { name: 'drizzle-kit', version: version, }); ``` Sources: [drizzle-kit/src/cli/index.ts:45-48](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/index.ts#L45-L48) The version check asynchronous function queries `ormCoreVersions` to inspect underlying package metadata, formatting both the `drizzle-kit` version string (from `process.env.DRIZZLE_KIT_VERSION` or defaulting to `--`) and the `drizzle-orm` npm version before printing the result via `chalk.gray`. ```typescript const version = async () => { const { npmVersion } = await ormCoreVersions(); const ormVersion = npmVersion ? `drizzle-orm: v${npmVersion}` : ''; const envVersion = process.env.DRIZZLE_KIT_VERSION; const kitVersion = envVersion ? `v${envVersion}` : '--'; const versions = `drizzle-kit: ${kitVersion}\n${ormVersion}`; console.log(chalk.gray(versions), '\n'); }; ``` Sources: [drizzle-kit/src/cli/index.ts:6-13](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/index.ts#L6-L13) ### Command Definitions and Legacy Aliases Active schema operations are declared using Brocli's `command` function in `schema.ts`, establishing command names, option filters, argument transformations, and asynchronous handlers. To maintain backward compatibility during major upgrades, the CLI registers hidden legacy commands that intercept obsolete dialect-specific commands and output migration instructions pointing to upgrade documentation. | Legacy Command Name | Target Replacement | Hidden Status | | :--- | :--- | :--- | | `generate:pg`, `generate:mysql`, `generate:sqlite` | `generate` | `true` | | `push:pg`, `push:mysql`, `push:sqlite` | `push` | `true` | | `introspect:pg`, `introspect:mysql`, `introspect:sqlite` | `introspect` | `true` | | `up:pg`, `up:mysql`, `up:sqlite` | `up` | `true` | | `check:pg`, `check:mysql`, `check:sqlite` | `check` | `true` | ```typescript const legacyCommand = (name: string, newName: string) => { return command({ name, hidden: true, handler: () => { console.log( `This command is deprecated, please use updated '${newName}' command (see https://orm.drizzle.team/kit-docs/upgrade-21#how-to-migrate-to-0210)`, ); }, }); }; const legacy = [ legacyCommand('generate:pg', 'generate'), legacyCommand('generate:mysql', 'generate'), legacyCommand('generate:sqlite', 'generate'), legacyCommand('push:pg', 'push'), legacyCommand('push:mysql', 'push'), legacyCommand('push:sqlite', 'push'), legacyCommand('introspect:pg', 'introspect'), legacyCommand('introspect:mysql', 'introspect'), legacyCommand('introspect:sqlite', 'introspect'), legacyCommand('up:pg', 'up'), legacyCommand('up:mysql', 'up'), legacyCommand('up:sqlite', 'up'), legacyCommand('check:pg', 'check'), legacyCommand('check:mysql', 'check'), legacyCommand('check:sqlite', 'check'), ]; ``` Sources: [drizzle-kit/src/cli/index.ts:15-43](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/index.ts#L15-L43) > [!WARNING] > Legacy commands are explicitly marked with `hidden: true` and execute a handler that prints a deprecation warning rather than performing database operations, requiring users to upgrade to the unified dialect-agnostic command syntax. ### Version Assertions and Environment Validation Before executing command handlers, `drizzle-kit` performs rigorous core version and dependency assertions to guarantee compatibility between the CLI toolkit and the installed ORM runtime. The `assertOrmCoreVersion` utility queries `drizzle-orm/version` for its `compatibilityVersion` and verifies that it matches the required API version constant `10`. ```typescript const requiredApiVersion = 10; export const assertOrmCoreVersion = async () => { try { const { compatibilityVersion } = await import('drizzle-orm/version'); await import('drizzle-orm/relations'); if (compatibilityVersion && compatibilityVersion === requiredApiVersion) { return; } if (!compatibilityVersion || compatibilityVersion < requiredApiVersion) { console.log( 'This version of drizzle-kit requires newer version of drizzle-orm\nPlease update drizzle-orm package to the latest version 👍', ); } else { console.log( 'This version of drizzle-kit is outdated\nPlease update drizzle-kit package to the latest version 👍', ); } } catch (e) { console.log('Please install latest version of drizzle-orm'); } process.exit(1); }; ``` Sources: [drizzle-kit/src/cli/utils.ts:77-101](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/utils.ts#L77-L101) > [!IMPORTANT] > If `compatibilityVersion` is missing or less than `10`, the process logs an update prompt and exits with code `1` to prevent schema corruption caused by mismatched serializer protocols. Additional helper assertions validate environment preconditions, such as checking that Node.js version 18 or above is active when running Drizzle Studio via `assertStudioNodeVersion`, and verifying required peer packages with `assertPackages` or `assertEitherPackage`. ```typescript export const assertStudioNodeVersion = () => { if (semver.gte(process.version, '18.0.0')) return; err('Drizzle Studio requires NodeJS v18 or above'); process.exit(1); }; ``` Sources: [drizzle-kit/src/cli/utils.ts:16-21](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/utils.ts#L16-L21) ## Config Loading and Runtime Preparation ### TSX Runtime Registration and ES5 Assertions To support TypeScript configuration files and schema definitions without prior manual compilation, `drizzle-kit` initializes runtime TypeScript execution via `tsx`. The `ensureTsxRegistered` function checks whether Bun or Deno is the active global runtime environment; if neither is detected, it requires and registers `tsx/cjs/api`. ```typescript let tsxRegistered = false; const ensureTsxRegistered = () => { if (tsxRegistered) return; const isBun = typeof (globalThis as any).Bun !== 'undefined'; const isDeno = typeof (globalThis as any).Deno !== 'undefined'; if (isBun || isDeno) { tsxRegistered = true; return; } const tsx = require('tsx/cjs/api'); tsx.register(); tsxRegistered = true; }; ``` Sources: [drizzle-kit/src/cli/commands/utils.ts:79-93](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/utils.ts#L79-L93) Concurrency across asynchronous configuration loading is managed by an `InMemoryMutex` implementation (`registerMutex`), which serializes execution locks through `safeRegister`. ```typescript export class InMemoryMutex { private lockPromise: Promise | null = null; async withLock(fn: () => Promise): Promise { // Wait for any existing lock while (this.lockPromise) { await this.lockPromise; } let resolveLock: (() => void) | undefined; this.lockPromise = new Promise((resolve) => { resolveLock = resolve; }); try { return await fn(); } finally { this.lockPromise = null; resolveLock!(); // non-null assertion: TS now knows it's definitely assigned } } } ``` Sources: [drizzle-kit/src/cli/commands/utils.ts:54-75](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/utils.ts#L54-L75) Before evaluating configuration files, the runtime runs `assertES5` to inspect compiler target options. If an unsupported target such as `es5` is encountered via configuration errors, the process logs a corrective instruction and exits. ```typescript const assertES5 = async () => { try { await import('./_es5'); } catch (e: any) { if ('errors' in e && Array.isArray(e.errors) && e.errors.length > 0) { const es5Error = (e.errors as any[]).filter((it) => it.text?.includes(`("es5") is not supported yet`)).length > 0; if (es5Error) { console.log( error( `Please change compilerOptions.target from 'es5' to 'es6' or above in your tsconfig.json`, ), ); process.exit(1); } } console.error(e); process.exit(1); } }; ``` Sources: [drizzle-kit/src/cli/commands/utils.ts:34-52](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/utils.ts#L34-L52) > [!CAUTION] > Next.js default target configurations set to `es5` cannot be consumed by `esbuild-register`; `drizzle-kit` explicitly intercepts this error and terminates execution if `compilerOptions.target` is not elevated to `es6` or above. ### Parameter Transformation and Validation Bridges Command options parsed from the CLI or configuration files are normalized through dedicated parameter preparation helpers in `utils.ts` and validated via schema bridges. For instance, `prepareCheckParams` inspects whether parameters originate from the CLI or an external configuration file, validating that `out` and `dialect` properties are present. ```typescript export const prepareCheckParams = async ( options: { config?: string; dialect?: Dialect; out?: string; }, from: 'cli' | 'config', ): Promise<{ out: string; dialect: Dialect }> => { const config = from === 'config' ? await drizzleConfigFromFile(options.config as string | undefined) : options; if (!config.out || !config.dialect) { let text = `Please provide required params for AWS Data API driver:\n`; console.log(error(text)); console.log(wrapParam('database', config.out)); console.log(wrapParam('secretArn', config.dialect)); process.exit(1); } return { out: config.out, dialect: config.dialect }; }; ``` Sources: [drizzle-kit/src/cli/commands/utils.ts:103-123](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/utils.ts#L103-L123) Similarly, `prepareDropParams` evaluates drop targets, explicitly rejecting the `gel` dialect by terminating the process with an error message. ```typescript export const prepareDropParams = async ( options: { config?: string; out?: string; driver?: Driver; dialect?: Dialect; }, from: 'cli' | 'config', ): Promise<{ out: string; bundle: boolean }> => { const config = from === 'config' ? await drizzleConfigFromFile(options.config as string | undefined) : options; if (config.dialect === 'gel') { console.log( error( `You can't use 'drop' command with Gel dialect`, ), ); process.exit(1); } return { out: config.out || 'drizzle', bundle: config.driver === 'expo' }; }; ``` Sources: [drizzle-kit/src/cli/commands/utils.ts:125-148](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/utils.ts#L125-L148) The table below outlines core configuration validation outputs and error messages defined for connection requirements and parameter constraints across database dialects. | Context | Error Condition | Validation Message | | :--- | :--- | :--- | | `common` | Ambiguous parameters | `You can't use both --config and other cli options for {command} command` | | `postgres` | Missing connection parameters | `Either "url" or "host", "database" are required for database connection` | | `mysql` / `singlestore` | Invalid driver option | `Only "mysql2" is available options for "--driver"` | | `sqlite` | Missing driver parameter | `Either 'better-sqlite3', 'libsql', 'turso', 'expo', 'durable-sqlite' are available options for 'driver' param` | | `studio` | Unspecified dialect | `Please specify 'dialect' param in config, either of 'postgresql', 'mysql', 'sqlite', turso or singlestore` | ```typescript ambiguousParams: (command: string) => withStyle.error( `You can't use both --config and other cli options for ${command} command`, ), schema: (command: string) => withStyle.error(`"--schema" is a required field for ${command} command`), }, postgres: { connection: { required: () => withStyle.error( `Either "url" or "host", "database" are required for database connection`, ), awsDataApi: () => withStyle.error( "You need to provide 'database', 'secretArn' and 'resourceArn' for Drizzle Kit to connect to AWS Data API", ), }, }, mysql: { connection: { driver: () => withStyle.error(`Only "mysql2" is available options for "--driver"`), required: () => withStyle.error( `Either "url" or "host", "database" are required for database connection`, ), }, }, sqlite: { connection: { driver: () => { const listOfDrivers = sqliteDriversLiterals .map((it) => `'${it.value}'`) .join(', '); return withStyle.error( `Either ${listOfDrivers} are available options for 'driver' param`, ); }, url: (driver: string) => withStyle.error( `"url" is a required option for driver "${driver}". You can read more about drizzle.config: https://orm.drizzle.team/kit-docs/config-reference`, ), authToken: (driver: string) => withStyle.error( `"authToken" is a required option for driver "${driver}". You can read more about drizzle.config: https://orm.drizzle.team/kit-docs/config-reference`, ), }, introspect: {}, push: {}, }, singlestore: { connection: { driver: () => withStyle.error(`Only "mysql2" is available options for "--driver"`), required: () => withStyle.error( `Either "url" or "host", "database" are required for database connection`, ), }, ``` Sources: [drizzle-kit/src/cli/validations/outputs.ts:33-89](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/outputs.ts#L33-L89) ## Migration Generation and Interactive Disambiguation ### Migration Preparation and Snapshot Diffing When executing migration generation via `[[Migration Toolkit Schema]]`, `drizzle-kit` initializes dialect-specific migration preparation and snapshot diffing routines. The migration workflow validates output directories using `assertV1OutFolder` and prepares migration folders via `prepareMigrationFolder` to ensure journals and snapshots conform to active specifications [Migration Toolkit Schema](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/migration-toolkit-schema). Schema changes are calculated by comparing current schema definitions against previous serialized snapshots using dedicated differ applications such as `applyPgSnapshotsDiff`, `applyMysqlSnapshotsDiff`, `applySqliteSnapshotsDiff`, `applyLibSQLSnapshotsDiff`, and `applySingleStoreSnapshotsDiff`. ```typescript applyLibSQLSnapshotsDiff, applyMysqlSnapshotsDiff, applyPgSnapshotsDiff, applySingleStoreSnapshotsDiff, applySqliteSnapshotsDiff, ``` Sources: [drizzle-kit/src/cli/commands/migrate.ts:23-27](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/migrate.ts#L23-L27) > [!WARNING] > Attempting to run migration generation or schema pushes with outdated V1 migration folders containing 14-digit numeric directory formats will cause `assertV1OutFolder` to immediately terminate the process with an error instructing the user to run `drizzle-kit up` [Migration Toolkit Schema](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/migration-toolkit-schema). ### Interactive Conflict Disambiguation When schema structural modifications introduce ambiguity—such as determining whether an object was renamed, moved between schemas, created, or deleted—resolver hooks prompt users interactively. The migration command module defines resolvers for schemas, tables, views, sequences, roles, policies, enums, and columns. For instance, `schemasResolver` invokes `promptSchemasConflict`, while `tablesResolver`, `viewsResolver`, and `enumsResolver` delegate to `promptNamedWithSchemasConflict`. ```typescript export const schemasResolver = async ( input: ResolverInput
, ): Promise> => { try { const { created, deleted, renamed } = await promptSchemasConflict( input.created, input.deleted, ); return { created: created, deleted: deleted, renamed: renamed }; } catch (e) { console.error(e); throw e; } }; export const tablesResolver = async ( input: ResolverInput
, ): Promise> => { try { const { created, deleted, moved, renamed } = await promptNamedWithSchemasConflict( input.created, input.deleted, 'table', ); return { created: created, deleted: deleted, moved: moved, renamed: renamed, }; } catch (e) { console.error(e); throw e; } }; export const viewsResolver = async ( input: ResolverInput, ): Promise> => { try { const { created, deleted, moved, renamed } = await promptNamedWithSchemasConflict( input.created, input.deleted, 'view', ); ``` Sources: [drizzle-kit/src/cli/commands/migrate.ts:68-115](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/migrate.ts#L68-L115) The table below lists the conflict resolver functions, their expected input types, and their corresponding output resolution signatures in the migration command architecture. | Resolver Function | Input Type | Output Type | Conflict Prompt Routine | | :--- | :--- | :--- | :--- | | `schemasResolver` | `ResolverInput
` | `ResolverOutput
` | `promptSchemasConflict` | | `tablesResolver` | `ResolverInput
` | `ResolverOutputWithMoved
` | `promptNamedWithSchemasConflict` | | `viewsResolver` | `ResolverInput` | `ResolverOutputWithMoved` | `promptNamedWithSchemasConflict` | | `sequencesResolver` | `ResolverInput` | `ResolverOutputWithMoved` | `promptNamedWithSchemasConflict` | | `roleResolver` | `RolesResolverInput` | `RolesResolverOutput` | `promptNamedConflict` | | `policyResolver` | `TablePolicyResolverInput` | `TablePolicyResolverOutput` | `promptColumnsConflicts` | | `enumsResolver` | `ResolverInput` | `ResolverOutputWithMoved` | `promptNamedWithSchemasConflict` | | `columnsResolver` | `ColumnsResolverInput` | `ColumnsResolverOutput` | `promptColumnsConflicts` | ```typescript export const schemasResolver = async ( input: ResolverInput
, ): Promise> => { try { const { created, deleted, renamed } = await promptSchemasConflict( input.created, input.deleted, ); return { created: created, deleted: deleted, renamed: renamed }; } catch (e) { console.error(e); throw e; } }; export const tablesResolver = async ( input: ResolverInput
, ): Promise> => { try { const { created, deleted, moved, renamed } = await promptNamedWithSchemasConflict( input.created, input.deleted, 'table', ); return { created: created, deleted: deleted, moved: moved, renamed: renamed, }; } catch (e) { console.error(e); throw e; } }; export const viewsResolver = async ( input: ResolverInput, ): Promise> => { try { const { created, deleted, moved, renamed } = await promptNamedWithSchemasConflict( input.created, input.deleted, 'view', ); return { created: created, deleted: deleted, moved: moved, renamed: renamed, }; } catch (e) { console.error(e); throw e; } }; export const mySqlViewsResolver = async ( input: ResolverInput, ): Promise> => { try { const { created, deleted, moved, renamed } = await promptNamedWithSchemasConflict( input.created, input.deleted, 'view', ); return { created: created, deleted: deleted, moved: moved, renamed: renamed, }; } catch (e) { console.error(e); throw e; } ``` Sources: [drizzle-kit/src/cli/commands/migrate.ts:68-300](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/migrate.ts#L68-L300) ## Schema Integrity Verification Workflow ### Folder Preparation and Snapshot Validation The `check` command handler verifies the structural integrity of migration snapshots stored in the output directory. It initiates folder inspection through `prepareOutFolder`, which ensures the `meta` subdirectory and `_journal.json` file exist, initializes a dry journal via `dryJournal` if missing, and collects all active snapshot file paths [Migration Toolkit Schema](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/migration-toolkit-schema). ```typescript export const checkHandler = (out: string, dialect: Dialect) => { const { snapshots } = prepareOutFolder(out, dialect); const report = validateWithReport(snapshots, dialect); ``` Sources: [drizzle-kit/src/cli/commands/check.ts:4-6](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/check.ts#L6-L6), [drizzle-kit/src/utils.ts:75-113](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/utils.ts#L75-L113) Snapshot validation is performed by `validateWithReport`, which maps over each snapshot file and evaluates it against dialect-specific validation schemas provided by `validatorForDialect`. | Dialect | Validator Schema | Target Version | | :--- | :--- | :--- | | `postgresql` | `backwardCompatiblePgSchema` | 7 | | `sqlite` | `backwardCompatibleSqliteSchema` | 6 | | `turso` | `backwardCompatibleSqliteSchema` | 6 | | `mysql` | `backwardCompatibleMysqlSchema` | 5 | | `singlestore` | `backwardCompatibleSingleStoreSchema` | 1 | | `gel` | `backwardCompatibleGelSchema` | 1 | ```typescript const validatorForDialect = (dialect: Dialect) => { switch (dialect) { case 'postgresql': return { validator: backwardCompatiblePgSchema, version: 7 }; case 'sqlite': return { validator: backwardCompatibleSqliteSchema, version: 6 }; case 'turso': return { validator: backwardCompatibleSqliteSchema, version: 6 }; case 'mysql': return { validator: backwardCompatibleMysqlSchema, version: 5 }; case 'singlestore': return { validator: backwardCompatibleSingleStoreSchema, version: 1 }; case 'gel': return { validator: backwardCompatibleGelSchema, version: 1 }; } }; ``` Sources: [drizzle-kit/src/utils.ts:115-130](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/utils.ts#L115-L130) > [!CAUTION] > If a snapshot file contains a version number exceeding the validator's maximum supported version, `validateWithReport` immediately logs an unsupported version message and terminates execution via `process.exit(0)`. ### Validation Reporting and Collision Detection The `checkHandler` function processes the report returned by `validateWithReport` to detect outdated files, malformed JSON data, and branching snapshot collisions. It evaluates three primary conditions before determining whether to abort execution: 1. **Non-latest snapshots:** If `report.nonLatest` contains entries, it logs that each snapshot is outdated and instructs users to execute `drizzle-kit up`, exiting with code `1`. 2. **Malformed data:** If `report.malformed` contains entries, it logs malformed warnings for each failing file. 3. **Snapshot collisions:** It inspects `report.idsMap` to locate parent IDs referenced by multiple child snapshots (`it[1].snapshots.length > 1`), reporting any branching lineage collisions. ```typescript if (report.nonLatest.length > 0) { console.log( report.nonLatest .map((it) => { return `${it} is not of the latest version, please run "drizzle-kit up"`; }) .join('\n'), ); process.exit(1); } if (report.malformed.length) { const message = report.malformed .map((it) => { return `${it} data is malformed`; }) .join('\n'); console.log(message); } const collisionEntries = Object.entries(report.idsMap).filter( (it) => it[1].snapshots.length > 1, ); const message = collisionEntries .map((it) => { const data = it[1]; return `[${ data.snapshots.join( ', ', ) }] are pointing to a parent snapshot: ${data.parent}/snapshot.json which is a collision.`; }) .join('\n'); if (message) { console.log(message); } const abort = report.malformed.length!! || collisionEntries.length > 0; if (abort) { process.exit(1); } ``` Sources: [drizzle-kit/src/cli/commands/check.ts:8-51](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/check.ts#L8-L51) > [!NOTE] > The abort condition checks both malformed snapshot presence and collision entries using `report.malformed.length!! || collisionEntries.length > 0`, terminating the process with exit code `1` if integrity errors are found. ```typescript const abort = report.malformed.length!! || collisionEntries.length > 0; if (abort) { process.exit(1); } ``` Sources: [drizzle-kit/src/cli/commands/check.ts:47-51](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/check.ts#L47-L51) ## Migration Lifecycle Pruning and Upgrades ### Migration Pruning via Drop The `dropMigration` function manages the interactive removal of generated migration entries, cleaning up corresponding SQL files, meta snapshots, and journal records. It reads the migration journal from `meta/_journal.json` within the designated output folder and verifies that entries exist before proceeding [Migration Toolkit Schema](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/migration-toolkit-schema). ```typescript const metaFilePath = join(out, 'meta', '_journal.json'); const journal = JSON.parse(readFileSync(metaFilePath, 'utf-8')) as Journal; if (journal.entries.length === 0) { console.log( `[${chalk.blue('i')}] no migration entries found in ${metaFilePath}`, ); return; } ``` Sources: [drizzle-kit/src/cli/commands/drop.ts:17-25](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/drop.ts#L25-L25) If entries are found, `dropMigration` renders an interactive selection view using `DropMigrationView` to let users pick which migration entry to remove. If the selection is aborted, the function returns immediately without modifying the file system. ```typescript const result = await render(new DropMigrationView(journal.entries)); if (result.status === 'aborted') return; ``` Sources: [drizzle-kit/src/cli/commands/drop.ts:27-28](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/drop.ts#L27-L28) Once a migration is selected, its entry is filtered out of the journal, and the associated `.sql` migration file and `_snapshot.json` file are permanently deleted from disk. If the `bundle` flag is enabled, an updated embedded migrations bundle is written via `embeddedMigrations`. | File / Path Target | Action | Source Reference | | :--- | :--- | :--- | | `meta/_journal.json` | Read and updated to remove the selected entry | [drizzle-kit/src/cli/commands/drop.ts:17-18](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/drop.ts#L17-L18), [drizzle-kit/src/cli/commands/drop.ts:32-35](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/drop.ts#L32-L35) | | `.sql` | Unlinked via `rmSync` | [drizzle-kit/src/cli/commands/drop.ts:36](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/drop.ts#L36-L36), [drizzle-kit/src/cli/commands/drop.ts:42](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/drop.ts#L42-L42) | | `meta/_snapshot.json` | Unlinked via `rmSync` | [drizzle-kit/src/cli/commands/drop.ts:37-41](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/drop.ts#L37-L41), [drizzle-kit/src/cli/commands/drop.ts:43](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/drop.ts#L43-L43) | | `migrations.js` | Rewritten if `bundle` is true | [drizzle-kit/src/cli/commands/drop.ts:46-50](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/drop.ts#L46-L50) | Sources: [drizzle-kit/src/cli/commands/drop.ts:17-50](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/drop.ts#L17-L50) > [!CAUTION] > The `dropMigration` function uses `rmSync` directly on the resolved `.sql` and snapshot file paths without checking file existence first, meaning unhandled file descriptor exceptions will occur if target files are missing or out of sync with the journal. ### Dialect-Specific Up Handlers Dialect upgrade commands update legacy or non-latest migration snapshot formats to match current serializer specifications [Migration Toolkit Schema](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/migration-toolkit-schema). The CLI routes upgrade execution through dedicated dialect handlers depending on the active configuration. ```typescript export const upSinglestoreHandler = (out: string) => {}; ``` Sources: [drizzle-kit/src/cli/commands/singlestoreUp.ts:1](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/singlestoreUp.ts#L1-L1) > [!NOTE] > The SingleStore up command handler `upSinglestoreHandler` accepts an output directory path string but currently executes as a no-op stub awaiting full upgrade sequence implementation. Sources: [drizzle-kit/src/cli/commands/singlestoreUp.ts:1](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/singlestoreUp.ts#L1-L1) ## Terminal Rendering and Interactive Components ### CLI Views and Formatting Helpers The CLI uses `chalk` and the `hanji` library to output formatted messages, warnings, errors, and schema summaries to the terminal. Message formatting functions wrap strings with specific color codes and styles depending on message severity. ```typescript export const warning = (msg: string) => { render(`[${chalk.yellow('Warning')}] ${msg}`); }; export const err = (msg: string) => { render(`${chalk.bold.red('Error')} ${msg}`); }; export const info = (msg: string, greyMsg: string = ''): string => { return `${chalk.blue.bold('Info:')} ${msg} ${greyMsg ? chalk.grey(greyMsg) : ''}`.trim(); }; ``` Sources: [drizzle-kit/src/cli/views.ts:7-16](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/views.ts#L7-L16) The `schema` view function formats a `CommonSchema` structure into a readable block displaying table counts, column counts, index counts, foreign keys, and enum definitions. For SingleStore schemas, foreign key counts are omitted since SingleStore lacks foreign key support in this context. ```typescript export const schema = (schema: CommonSchema): string => { type TableEntry = (typeof schema)['tables'][keyof (typeof schema)['tables']]; const tables = Object.values(schema.tables) as unknown as TableEntry[]; let msg = chalk.bold(`${tables.length} tables\n`); msg += tables .map((t) => { const columnsCount = Object.values(t.columns).length; const indexesCount = Object.values(t.indexes).length; let foreignKeys: number = 0; // Singlestore doesn't have foreign keys if (schema.dialect !== 'singlestore') { // @ts-expect-error foreignKeys = Object.values(t.foreignKeys).length; } return `${chalk.bold.blue(t.name)} ${ chalk.gray( `${columnsCount} columns ${indexesCount} indexes ${foreignKeys} fks`, ) }`; }) .join('\n'); ``` Sources: [drizzle-kit/src/cli/views.ts:25-49](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/views.ts#L25-L49) | Function Name | Parameters | Return Type | Purpose | Source Reference | | :--- | :--- | :--- | :--- | :--- | | `warning` | `msg: string` | `void` | Renders a yellow `[Warning]` tag and message via `hanji` | [drizzle-kit/src/cli/views.ts:7-9](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/views.ts#L7-L9) | | `err` | `msg: string` | `void` | Renders a bold red `Error` tag and message via `render` | [drizzle-kit/src/cli/views.ts:10-12](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/views.ts#L10-L12) | | `info` | `msg: string, greyMsg?: string` | `string` | Returns a bold blue `Info:` label followed by message and grey text | [drizzle-kit/src/cli/views.ts:14-16](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/views.ts#L14-L16) | | `grey` | `msg: string` | `string` | Returns the input string styled in grey | [drizzle-kit/src/cli/views.ts:17-19](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/views.ts#L17-L19) | | `error` | `error: string, greyMsg?: string` | `string` | Returns a red background white text ` Error ` badge with message | [drizzle-kit/src/cli/views.ts:21-23](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/views.ts#L21-L23) | | `schema` | `schema: CommonSchema` | `string` | Serializes table and enum summary counts with styled names | [drizzle-kit/src/cli/views.ts:25-76](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/views.ts#L25-L76) | | `tableKey` | `it: NamedWithSchema` | `string` | Formats a table key using schema prefix if schema is present and not public | [drizzle-kit/src/cli/views.ts:161-165](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/views.ts#L161-L165) | Sources: [drizzle-kit/src/cli/views.ts:7-76](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/views.ts#L7-L76), [drizzle-kit/src/cli/views.ts:161-165](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/views.ts#L161-L165) ### Interactive Prompts and Selectors Interactive selection components extend `Prompt` from `hanji` and bind to `SelectState` instances to handle user input and keyboard navigation. ```typescript export class Select extends Prompt<{ index: number; value: string }> { private readonly data: SelectState<{ label: string; value: string }>; constructor(items: string[]) { super(); this.on('attach', (terminal) => terminal.toggleCursor('hide')); this.on('detach', (terminal) => terminal.toggleCursor('show')); this.data = new SelectState( items.map((it) => ({ label: it, value: `${it}-value` })), ); this.data.bind(this); } ``` Sources: [drizzle-kit/src/cli/selector-ui.ts:4-16](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/selector-ui.ts#L4-L16) The `Select` class maps an array of string items into label-value objects, hiding the terminal cursor upon attachment and restoring it upon detachment. When rendered, it highlights the currently selected item with a green `❯` prefix and returns the selected index and value via `result()`. ```typescript render(status: 'idle' | 'submitted' | 'aborted'): string { if (status === 'submitted' || status === 'aborted') return ''; let text = ``; this.data.items.forEach((it, idx) => { text += idx === this.data.selectedIdx ? `${chalk.green('❯ ' + it.label)}` : ` ${it.label}`; text += idx != this.data.items.length - 1 ? '\n' : ''; }); return text; } result() { return { index: this.data.selectedIdx, value: this.data.items[this.data.selectedIdx]!.value!, }; } ``` Sources: [drizzle-kit/src/cli/selector-ui.ts:18-37](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/selector-ui.ts#L18-L37) For column and entity renaming disambiguation during migrations, `ResolveColumnSelect`, `ResolveSelectNamed`, and `ResolveSelect` prompts distinguish between column creation (`+`) and column renaming (`~`) actions. ```typescript export class ResolveColumnSelect extends Prompt< RenamePropmtItem | T > { private readonly data: SelectState | T>; constructor( private readonly tableName: string, private readonly base: Named, data: (RenamePropmtItem | T)[], ) { super(); this.on('attach', (terminal) => terminal.toggleCursor('hide')); this.data = new SelectState(data); this.data.bind(this); } ``` Sources: [drizzle-kit/src/cli/views.ts:89-103](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/views.ts#L89-L103) > [!NOTE] > The `isRenamePromptItem` type guard checks whether an item contains both `from` and `to` properties to identify whether a schema element has been renamed rather than newly created. Sources: [drizzle-kit/src/cli/views.ts:83-87](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/views.ts#L83-L87) ### Progress Spinners Task execution progress is rendered through specialized view classes extending `TaskView` that animate spinner characters across terminal updates. ```typescript export class MigrateProgress extends TaskView { private readonly spinner: Spinner = new Spinner('⣷⣯⣟⡿⢿⣻⣽⣾'.split('')); ``` Sources: [drizzle-kit/src/cli/views.ts:528-529](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/views.ts#L528-L529) The `MigrateProgress` task view initializes a `Spinner` instance with a unicode frame sequence (`⣷⣯⣟⡿⢿⣻⣽⣾`) to render real-time progress indicators during migration operations. Sources: [drizzle-kit/src/cli/views.ts:528-529](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/views.ts#L528-L529) ## Related - [Migration Toolkit Schema](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/migration-toolkit-schema) --- ## Technical docs: Migration Toolkit Schema URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/migration-toolkit-schema
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-kit/src/serializer/gelSchema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/gelSchema.ts) - [drizzle-kit/src/snapshotsDiffer.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/snapshotsDiffer.ts) - [drizzle-kit/src/jsonStatements.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/jsonStatements.ts) - [drizzle-kit/src/introspect-pg.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-pg.ts) - [drizzle-kit/src/introspect-singlestore.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-singlestore.ts) - [drizzle-kit/src/introspect-gel.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-gel.ts) - [drizzle-kit/src/api.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/api.ts) - [drizzle-kit/src/serializer/pgSchema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/pgSchema.ts) - [drizzle-kit/src/introspect-mysql.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-mysql.ts) - [drizzle-kit/src/serializer/sqliteSchema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/sqliteSchema.ts) - [drizzle-kit/src/serializer/gelSerializer.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/gelSerializer.ts) - [drizzle-kit/src/serializer/singlestoreSchema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/singlestoreSchema.ts) - [drizzle-kit/src/serializer/mysqlSchema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/mysqlSchema.ts) - [drizzle-typebox/src/column.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts) - [drizzle-arktype/src/column.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/column.ts) - [integration-tests/drizzle2/mysql/meta/_journal.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/drizzle2/mysql/meta/_journal.json) - [integration-tests/drizzle2/singlestore/meta/0000_snapshot.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/drizzle2/singlestore/meta/0000_snapshot.json) - [integration-tests/drizzle2/pg/meta/_journal.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/drizzle2/pg/meta/_journal.json) - [drizzle-seed/src/types/drizzleStudio.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/types/drizzleStudio.ts) - [integration-tests/drizzle2/mysql-proxy/first/meta/0000_snapshot.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/drizzle2/mysql-proxy/first/meta/0000_snapshot.json) - [integration-tests/drizzle2/mysql-proxy/second/meta/0000_snapshot.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/drizzle2/mysql-proxy/second/meta/0000_snapshot.json) - [drizzle-kit/src/cli/commands/libSqlPushUtils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/libSqlPushUtils.ts) - [drizzle-kit/src/cli/commands/mysqlPushUtils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/mysqlPushUtils.ts) - [drizzle-kit/src/cli/commands/pgPushUtils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/pgPushUtils.ts) - [drizzle-kit/src/cli/commands/push.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/push.ts) - [drizzle-kit/src/cli/commands/singlestorePushUtils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/singlestorePushUtils.ts) - [drizzle-kit/src/cli/commands/sqlitePushUtils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/sqlitePushUtils.ts) - [drizzle-kit/src/migrationPreparator.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/migrationPreparator.ts) - [drizzle-kit/src/serializer/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/index.ts)
## Overview The Migration Toolkit Schema subsystem forms the structural bridge between user-defined TypeScript database layouts in Drizzle ORM and physical database state. It operates across multiple target dialects—PostgreSQL, MySQL, SQLite (including LibSQL/Turso), SingleStore, and Gel—by translating code definitions and live database introspections into versioned, normalized JSON snapshots and migration journals. Sources: [drizzle-kit/src/api.ts:64-92](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/api.ts#L64-L92) At its core, this architecture decouples schema representation from specific database drivers. By validating schema objects against Zod structural specifications, `drizzle-kit` can diff successive snapshots, compute granular change sets (`jsonStatements`), filter out non-breaking or pseudo-changes (such as automatic type promotions), and safely apply structural mutations or generate migration files. Sources: [drizzle-kit/src/serializer/index.ts:12-56](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/index.ts#L12-L56) ```mermaid graph TD A["TypeScript Schema Definition"] --> B["Serialization Modules
(serializePg, serializeMySql, etc.)"] C["Live Database Catalog"] --> D["Database Introspection
(pgPushIntrospect, mysqlPushIntrospect, etc.)"] B --> E["Normalized JSON Snapshot
(pgSchema, mysqlSchema, sqliteSchema)"] D --> E E --> F["Snapshots Differ Engine
(applyPgSnapshotsDiff, etc.)"] F --> G["Intermediate JSON Statements
(JsonStatement[])"] G --> H["SQL Generator & Push Engine
(fromJson, pushSchema, pushMySQLSchema)"] ``` Sources: [drizzle-kit/src/snapshotsDiffer.ts:1-16](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/snapshotsDiffer.ts#L1-L16) --- ## Schema Diffing and SQL Generation The schema diffing subsystem compares a previous schema snapshot (`json1`) against a current schema snapshot (`json2`) to produce an intermediate array of semantic JSON statement descriptors. These descriptors are subsequently lowered into concrete SQL queries by the SQL generator or filtered and executed by the push utilities. Sources: [drizzle-kit/src/snapshotsDiffer.ts:98-123](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/snapshotsDiffer.ts#L98-L123) When generating migrations or pushing schema updates, `applyPgSnapshotsDiff`, `applyMysqlSnapshotsDiff`, and related diffing functions inspect tables, columns, constraints, foreign keys, and indexes. For dialects like SQLite and LibSQL where table alterations are restricted, the differ identifies situations requiring table recreation (`recreate_table`) via temporary tables and data copying (`_moveDataStatements`). Sources: [drizzle-kit/src/api.ts:159-186](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/api.ts#L159-L186) ```mermaid sequenceDiagram participant CLI as Push / Migrate CLI participant Diff as snapshotsDiffer participant Gen as jsonStatements / sqlgenerator participant DB as Target Database CLI->>Diff: applyPgSnapshotsDiff(squashedPrev, squashedCur, ...) Diff-->>CLI: { statements, _meta } CLI->>Gen: fromJson(statements, dialect, mode, json2) Gen-->>CLI: SQL string array (statementsToExecute) CLI->>DB: Execute queries (with safety checks) DB-->>CLI: Acknowledge completion ``` Sources: [drizzle-kit/src/cli/commands/libSqlPushUtils.ts:28-111](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/libSqlPushUtils.ts#L28-L111) The table below outlines common statement types generated during the diffing process and their structural targets across dialects: | Statement Type | Description | Target Dialects | | :--- | :--- | :--- | | `create_table` | Provisions a new database table with columns and constraints | PostgreSQL, MySQL, SingleStore, SQLite | | `drop_table` | Removes a table and verifies dependent row counts | All Dialects | | `alter_table_add_column` | Appends a column definition to an existing table | All Dialects | | `alter_table_drop_column` | Drops a column after checking for item counts | All Dialects | | `recreate_table` | Rebuilds SQLite/LibSQL tables via temporary `__new_` tables | SQLite, LibSQL | | `create_type_enum` | Creates native enumeration types | PostgreSQL | Sources: [drizzle-kit/src/jsonStatements.ts:45-111](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/jsonStatements.ts#L45-L111), [drizzle-kit/src/cli/commands/libSqlPushUtils.ts:32-64](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/libSqlPushUtils.ts#L32-L64) --- ## Schema Push Mechanics Schema push operations (`pushSchema`, `mysqlPush`, `pgPush`, `sqlitePush`, `libSQLPush`) synchronize a live database instance with the TypeScript schema without generating explicit migration files. They achieve this by introspecting the live database catalog into a normalized schema structure, serializing the target TypeScript schema, running the snapshot differ, filtering pseudo-changes, and prompting users when destructive operations are detected. Sources: [drizzle-kit/src/api.ts:125-188](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/api.ts#L125-L188) Filtering mechanisms prevent redundant updates, such as boolean default variations or automatic promotions between `bigint unsigned` and `serial` column types in MySQL and SingleStore. Furthermore, safety validation layers inspect live row counts before executing destructive statements such as dropping tables or columns, adding non-null columns without defaults, or modifying primary keys. Sources: [drizzle-kit/src/cli/commands/mysqlPushUtils.ts:10-105](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/mysqlPushUtils.ts#L10-L105) > [!WARNING] > When pushing changes to SQLite or LibSQL databases, adding a `NOT NULL` column without a default value to a populated table triggers an automatic table truncation or forces deletion of rows to prevent constraint violations. Sources: [drizzle-kit/src/cli/commands/libSqlPushUtils.ts:173-196](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/libSqlPushUtils.ts#L173-L196) The following example demonstrates how programmatic schema pushing is invoked using `pushSchema` for PostgreSQL: ```typescript import { pushSchema } from 'drizzle-kit/api'; import { drizzle } from 'drizzle-orm/node-postgres'; import * as schema from './schema'; const dbInstance = drizzle(process.env.DATABASE_URL!); async function syncSchema() { const result = await pushSchema(schema, dbInstance, ['public'], ['__drizzle_migrations']); if (result.hasDataLoss) { console.warn('Warnings:', result.warnings); } await result.apply(); console.log('Schema pushed successfully.'); } ``` Sources: [drizzle-kit/src/api.ts:125-188](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/api.ts#L125-L188) --- ## Schema Snapshot Serializer The snapshot serializer transforms AST exports and database reflection results into versioned, structured Zod-validated JSON documents. Each dialect maintains strict validation schemas (e.g., `pgSchemaInternal`, `schemaInternal` for SQLite and SingleStore, `gelSchemaExternal`) capturing tables, columns, indexes, foreign keys, composite primary keys, check constraints, unique constraints, and policies. Sources: [drizzle-kit/src/serializer/pgSchema.ts:365-438](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/pgSchema.ts#L365-L438) Versioning ensures backward compatibility across migration toolkit upgrades. For example, PostgreSQL snapshots have evolved through versions `3` through `7`, introducing proper schema namespace support (`schema.table` notation), sequence metadata tracking, and internal kit state tracking (`kitInternals`). Sources: [drizzle-kit/src/serializer/sqliteSchema.ts:82-132](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/sqliteSchema.ts#L82-L132), [drizzle-kit/src/serializer/singlestoreSchema.ts:89-102](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/singlestoreSchema.ts#L89-L102), [drizzle-kit/src/serializer/gelSchema.ts:216-222](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/gelSchema.ts#L216-L222) ## Related - [CLI Command Architecture](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/cli-command-architecture) - [Database Introspection](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/database-introspection) --- ## Technical docs: Database Introspection URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/database-introspection
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-kit/src/introspect-singlestore.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-singlestore.ts) - [drizzle-kit/src/introspect-mysql.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-mysql.ts) - [drizzle-kit/src/cli/commands/introspect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/introspect.ts) - [drizzle-kit/src/api.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/api.ts) - [drizzle-kit/src/cli/schema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/schema.ts) - [drizzle-kit/src/serializer/singlestoreSerializer.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/singlestoreSerializer.ts) - [drizzle-kit/src/serializer/gelSerializer.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/gelSerializer.ts) - [drizzle-kit/src/serializer/studio.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/studio.ts) - [drizzle-kit/src/introspect-pg.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-pg.ts) - [drizzle-kit/src/cli/commands/sqliteIntrospect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/sqliteIntrospect.ts) - [drizzle-kit/src/introspect-gel.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-gel.ts) - [drizzle-kit/src/serializer/mysqlSerializer.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/mysqlSerializer.ts) - [drizzle-kit/src/introspect-sqlite.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-sqlite.ts) - [drizzle-kit/src/serializer/pgSerializer.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/pgSerializer.ts) - [drizzle-kit/src/cli/commands/mysqlIntrospect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/mysqlIntrospect.ts) - [drizzle-kit/src/sqlgenerator.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/sqlgenerator.ts) - [drizzle-kit/src/cli/commands/singlestoreIntrospect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/singlestoreIntrospect.ts) - [drizzle-kit/src/serializer/sqliteSerializer.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/sqliteSerializer.ts) - [drizzle-kit/src/serializer/mysqlSchema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/mysqlSchema.ts) - [integration-tests/drizzle2/planetscale/meta/0000_snapshot.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/drizzle2/planetscale/meta/0000_snapshot.json) - [integration-tests/drizzle2/mysql/meta/0000_snapshot.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/drizzle2/mysql/meta/0000_snapshot.json) - [integration-tests/drizzle2/singlestore/meta/0000_snapshot.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/drizzle2/singlestore/meta/0000_snapshot.json) - [drizzle-kit/src/cli/commands/pgIntrospect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/pgIntrospect.ts) - [integration-tests/drizzle2/pg/meta/0000_snapshot.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/drizzle2/pg/meta/0000_snapshot.json) - [integration-tests/drizzle2/mysql-proxy/first/meta/0000_snapshot.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/drizzle2/mysql-proxy/first/meta/0000_snapshot.json)
## Overview Database introspection in Drizzle Kit recovers relational database schemas from live database instances across multiple supported dialects, normalizing catalog metadata into structured JSON migration snapshots and translating them into idiomatic Drizzle TypeScript schema definitions. Sources: [drizzle-kit/src/cli/schema.ts:538-623](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/schema.ts#L538-L623), [drizzle-kit/src/serializer/singlestoreSerializer.ts:400-411](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/singlestoreSerializer.ts#L400-L411), and [drizzle-kit/src/serializer/mysqlSerializer.ts:564-573](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/mysqlSerializer.ts#L564-L573) ## CLI Introspection Orchestration ### Dialect Dispatch and Driver Checks The CLI command handler for introspection ensures output directories are created recursively via `mkdirSync(out, { recursive: true })` and evaluates dialect branches to dynamically import and invoke dialect-specific introspection routines. For PostgreSQL credentials carrying a specific driver option, version compatibility checks against `drizzle-orm` are enforced before proceeding. | Dialect | Credential Type | Introspection Function | Target Module File | | :--- | :--- | :--- | :--- | | `postgresql` | `PostgresCredentials` | `introspectPostgres` | `drizzle-kit/src/cli/commands/introspect.ts` | | `mysql` | `MysqlCredentials` | `introspectMysql` | `drizzle-kit/src/cli/commands/introspect.ts` | | `sqlite` | `SqliteCredentials` | `introspectSqlite` | `drizzle-kit/src/cli/commands/introspect.ts` | | `turso` | `LibSQLCredentials` | `introspectLibSQL` | `drizzle-kit/src/cli/commands/introspect.ts` | | `singlestore` | `SingleStoreCredentials` | `introspectSingleStore` | `drizzle-kit/src/cli/commands/introspect.ts` | | `gel` | `GelCredentials` | `introspectGel` | `drizzle-kit/src/cli/commands/introspect.ts` | > [!WARNING] > When executing PostgreSQL introspection with the `aws-data-api` driver, `drizzle-orm` version `0.30.10` or higher is strictly required; using `pglite` requires version `0.30.6` or higher. Failing this check terminates the process with exit code `1`. Sources: [drizzle-kit/src/cli/schema.ts:524-625](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/schema.ts#L524-L625) ### Filtering and Progress Reporting Table filtering is implemented across database dialects by mapping each provided table filter string into a `Minimatch` instance. The filter function evaluates table names against all matchers, taking negation patterns into account and enforcing that all match criteria pass via `flags.every(Boolean)`. ```typescript const matchers = tablesFilter.map((it) => { return new Minimatch(it); }); const filter = (tableName: string) => { if (matchers.length === 0) return true; let flags: boolean[] = []; for (let matcher of matchers) { if (matcher.negate) { if (!matcher.match(tableName)) { flags.push(false); } } if (matcher.match(tableName)) { flags.push(true); } } if (flags.length > 0) { return flags.every(Boolean); } return false; }; ``` Progress reporting runs concurrently with database extraction by instantiating an `IntrospectProgress` reporter and wrapping the database fetch task with `renderWithTask`, where status updates propagate stage, count, and status arguments down to `progress.update(stage, count, status)`. Sources: [drizzle-kit/src/cli/commands/introspect.ts:184-234](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/introspect.ts#L184-L234), [drizzle-kit/src/cli/commands/introspect.ts:318-351](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/introspect.ts#L318-L351) ### Snapshot Diffing and Output Generation Once schema objects are retrieved from the database and converted into TypeScript files (`schema.ts` and `relations.ts`), migration folders are inspected via `prepareOutFolder(out, dialect)`. If no existing snapshots are detected (`snapshots.length === 0`), dialect-specific snapshot diff functions compute SQL migration statements and metadata. ```typescript const { snapshots, journal } = prepareOutFolder(out, 'mysql'); if (snapshots.length === 0) { const { sqlStatements, _meta } = await applyMysqlSnapshotsDiff( squashMysqlScheme(dryMySql), squashMysqlScheme(schema), tablesResolver, columnsResolver, mySqlViewsResolver, dryMySql, schema, ); writeResult({ cur: schema, sqlStatements, journal, _meta, outFolder: out, breakpoints, type: 'introspect', prefixMode: prefix, }); } else { render( `[${ chalk.blue( 'i', ) }] No SQL generated, you already have migrations in project`, ); } ``` > [!NOTE] > If snapshot files already exist inside the project output folder, introspection skips generating new migration SQL and outputs an informational message indicating that migrations are already present. Sources: [drizzle-kit/src/cli/commands/introspect.ts:364-395](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/introspect.ts#L364-L395) ## PostgreSQL Catalog Inspection ### PostgreSQL Introspection and Push Execution PostgreSQL schema introspection is driven through `pgPushIntrospect`, which processes user-supplied table filter strings into `Minimatch` instances to evaluate and filter table names against positive and negative match criteria. ```typescript const matchers = filters.map((it) => { return new Minimatch(it); }); const filter = (tableName: string) => { if (matchers.length === 0) return true; let flags: boolean[] = []; for (let matcher of matchers) { if (matcher.negate) { if (!matcher.match(tableName)) { flags.push(false); } } if (matcher.match(tableName)) { flags.push(true); } } if (flags.length > 0) { return flags.every(Boolean); } return false; }; ``` Sources: [drizzle-kit/src/cli/commands/pgIntrospect.ts:17-42](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/pgIntrospect.ts#L17-L42) The introspection execution wraps schema pulling within a terminal progress view using `renderWithTask` before appending internal identifiers to construct the final serialized `PgSchema` payload. ```typescript const progress = new ProgressView( 'Pulling schema from database...', 'Pulling schema from database...', ); const res = await renderWithTask( progress, fromDatabase(db, filter, schemaFilters, entities, undefined, tsSchema), ); const schema = { id: originUUID, prevId: '', ...res } as PgSchema; const { internal, ...schemaWithoutInternals } = schema; return { schema: schemaWithoutInternals }; ``` Sources: [drizzle-kit/src/cli/commands/pgIntrospect.ts:43-54](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/pgIntrospect.ts#L43-L54) ### Catalog Transformation and TypeScript Generation Catalog reconstruction inspects database entities, mapping identities, sequences, columns, roles, and schema definitions into corresponding TypeScript constructs. When reconstructing column identities, parameters such as `maxValue`, `cache`, and `cycle` are serialized into `.generatedAlwaysAsIdentity()` or `.generatedByDefaultAsIdentity()` calls. ```typescript if (identity?.maxValue) { paramsObj += `, maxValue: ${identity.maxValue}`; } if (identity?.cache) { paramsObj += `, cache: ${identity.cache}`; } if (identity?.cycle) { paramsObj += `, cycle: true`; } paramsObj += ' }'; if (identity?.type === 'always') { return `.generatedAlwaysAsIdentity(${paramsObj})`; } return `.generatedByDefaultAsIdentity(${paramsObj})`; ``` Sources: [drizzle-kit/src/introspect-pg.ts:289-302](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-pg.ts#L289-L302) > [!NOTE] > Parameter name generation uses `paramNameFor`, appending a capitalised schema suffix when a non-public schema is present to avoid name collisions across distinct PostgreSQL schemas. Sources: [drizzle-kit/src/introspect-pg.ts:304-307](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-pg.ts#L304-L307) ## MySQL and SingleStore Schema Recovery ### Introspection Commands and Table Filtering MySQL and SingleStore schema introspection processes database metadata by executing database pulls through `mysqlPushIntrospect` and `singlestorePushIntrospect`. Both routines accept database connection handles, target database names, and filter arrays to construct `Minimatch` instances that selectively include or exclude tables based on pattern matching rules and negated match flags. ```typescript const matchers = filters.map((it) => { return new Minimatch(it); }); const filter = (tableName: string) => { if (matchers.length === 0) return true; let flags: boolean[] = []; for (let matcher of matchers) { if (matcher.negate) { if (!matcher.match(tableName)) { flags.push(false); } } if (matcher.match(tableName)) { flags.push(true); } } if (flags.length > 0) { return flags.every(Boolean); } return false; }; ``` Sources: [drizzle-kit/src/cli/commands/mysqlIntrospect.ts:14-39](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/mysqlIntrospect.ts#L14-L39), [drizzle-kit/src/cli/commands/singlestoreIntrospect.ts:14-39](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/singlestoreIntrospect.ts#L14-L39) > [!NOTE] > During push introspection, the `ProgressView` utility renders a terminal task indicator labeled `'Pulling schema from database...'` while `fromDatabase` queries catalog tables. Sources: [drizzle-kit/src/cli/commands/mysqlIntrospect.ts:41-48](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/mysqlIntrospect.ts#L41-L48), [drizzle-kit/src/cli/commands/singlestoreIntrospect.ts:41-48](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/singlestoreIntrospect.ts#L41-L48) ### Casing Transformation and Schema Squashing Field names and identifiers undergo casing transformation determined by the active casing configuration. The `prepareCasing` helper checks whether casing is set to `'preserve'` or `'camel'`, routing column keys through `escapeColumnKey` or string transformation methods. ```typescript const escapeColumnKey = (value: string) => { if (/^(?![a-zA-Z_$][a-zA-Z0-9_$]*$).+$/.test(value)) { return `"${value}"`; } return value; }; const prepareCasing = (casing?: Casing) => (value: string) => { if (casing === 'preserve') { return escapeColumnKey(value); } if (casing === 'camel') { return escapeColumnKey(value.camelCase()); } assertUnreachable(casing); }; ``` Sources: [drizzle-kit/src/introspect-mysql.ts:104-120](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-mysql.ts#L104-L120), [drizzle-kit/src/introspect-singlestore.ts:110-126](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-singlestore.ts#L110-L126) Catalog serialization and migration diffing rely on squasher functions defined in `mysqlSchema.ts`. The squasher flattens indices, foreign keys, primary keys, unique constraints, check constraints, and views into delimited string representations for snapshot comparison. | Squasher Method | Serialized Components | Source Reference | | :--- | :--- | :--- | | `squashIdx` | `name`, `columns`, `isUnique`, `using`, `algorithm`, `lock` | [drizzle-kit/src/serializer/mysqlSchema.ts:223-228](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/mysqlSchema.ts#L223-L228) | | `squashPK` | `name`, `columns` | [drizzle-kit/src/serializer/mysqlSchema.ts:241-243](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/mysqlSchema.ts#L241-L243) | | `squashUnique` | `name`, `columns` | [drizzle-kit/src/serializer/mysqlSchema.ts:248-250](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/mysqlSchema.ts#L248-L250) | | `squashFK` | `name`, `tableFrom`, `columnsFrom`, `tableTo`, `columnsTo`, `onUpdate`, `onDelete` | [drizzle-kit/src/serializer/mysqlSchema.ts:255-259](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/mysqlSchema.ts#L255-L259) | | `squashCheck` | `name`, `value` | [drizzle-kit/src/serializer/mysqlSchema.ts:282-284](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/mysqlSchema.ts#L282-L284) | | `squashView` | `algorithm`, `sqlSecurity`, `withCheckOption` | [drizzle-kit/src/serializer/mysqlSchema.ts:290-292](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/mysqlSchema.ts#L290-L292) | Sources: [drizzle-kit/src/serializer/mysqlSchema.ts:223-292](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/mysqlSchema.ts#L223-L292) > [!WARNING] > In MySQL schemas, text and tinytext columns cannot have default values assigned; introspection guards against unsupported defaults when mapping column properties. Sources: [drizzle-kit/src/introspect-mysql.ts:602-609](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-mysql.ts#L602-L609) ## SQLite Catalog Recovery ### Table Filtering and Introspection Execution The SQLite introspection pipeline connects to live SQLite and LibSQL databases using configured credentials, applying glob table filters via `Minimatch` before delegating schema serialization to `fromDatabase`. The `sqliteIntrospect` and `sqlitePushIntrospect` functions process filter matchers supporting negation rules, evaluating table names through an array accumulator and returning boolean conditions. ```typescript export const sqliteIntrospect = async ( credentials: SqliteCredentials, filters: string[], casing: Casing, ) => { const { connectToSQLite } = await import('../connections'); const db = await connectToSQLite(credentials); const matchers = filters.map((it) => { return new Minimatch(it); }); const filter = (tableName: string) => { if (matchers.length === 0) return true; let flags: boolean[] = []; for (let matcher of matchers) { if (matcher.negate) { if (!matcher.match(tableName)) { flags.push(false); } } if (matcher.match(tableName)) { flags.push(true); } } if (flags.length > 0) { return flags.every(Boolean); } return false; }; const progress = new IntrospectProgress(); const res = await renderWithTask( progress, fromDatabase(db, filter, (stage, count, status) => { progress.update(stage, count, status); }), ); const schema = { id: originUUID, prevId: '', ...res } as SQLiteSchema; const ts = schemaToTypeScript(schema, casing); return { schema, ts }; }; ``` Sources: [drizzle-kit/src/cli/commands/sqliteIntrospect.ts:12-58](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/sqliteIntrospect.ts#L12-L58) > [!NOTE] > When executing `sqlitePushIntrospect`, the CLI renders a `ProgressView` terminal task instead of interactive progress bars while querying catalog tables from the target database instance. Sources: [drizzle-kit/src/cli/commands/sqliteIntrospect.ts:88-92](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/sqliteIntrospect.ts#L88-L92) ### Column Mapping and Default Value Parsing Recovered SQLite column types map database definitions to TypeScript declarations while processing default values, column flags, and self-referential or cyclic foreign key constraints. The `mapColumnDefault` utility handles SQL expressions enclosed in parentheses, stringified `NULL` constants, and quoted string defaults by unescaping interior quotes. ```typescript const mapColumnDefault = (defaultValue: any) => { if ( typeof defaultValue === 'string' && defaultValue.startsWith('(') && defaultValue.endsWith(')') ) { return `sql\`${defaultValue}\``; } if (defaultValue === 'NULL') { return `sql\`NULL\``; } if ( typeof defaultValue === 'string' ) { return defaultValue.substring(1, defaultValue.length - 1).replaceAll('"', '\\"').replaceAll("''", "'"); } return defaultValue; }; ``` Sources: [drizzle-kit/src/introspect-sqlite.ts:258-278](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-sqlite.ts#L258-L278) > [!WARNING] > SQLite stores literal null values as the string `'NULL'` or wrapped representations in system catalogs; introspection catches these specifically to emit explicit `sql\`NULL\`` expressions. Sources: [drizzle-kit/src/introspect-sqlite.ts:266-269](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-sqlite.ts#L266-L269) Foreign key relationships are analyzed for self-referential structures and cyclic dependencies by checking key pairs against registered relation sets. | Relation Helper | Condition Evaluated | Source Reference | | :--- | :--- | :--- | | `isCyclic` | Checks whether both `tableFrom-tableTo` and reverse `tableTo-tableFrom` exist in relations | [drizzle-kit/src/introspect-sqlite.ts:248-252](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-sqlite.ts#L248-L252) | | `isSelf` | Verifies if `tableFrom` matches `tableTo` on the foreign key definition | [drizzle-kit/src/introspect-sqlite.ts:254-256](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-sqlite.ts#L254-L256) | Sources: [drizzle-kit/src/introspect-sqlite.ts:248-256](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-sqlite.ts#L248-L256) ## Gel Schema Extraction ### Default Value Mapping Rules Gel introspection maps database types, array flags, and default expression constraints into structured TypeScript declarations [Migration Toolkit Schema](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/migration-toolkit-schema). The `mapDefault` function inspects column metadata, handling type-specific formatting for integers, floating-point numbers, UUIDs, dates, durations, JSON, and byte arrays. ```typescript const isCyclic = (fk: ForeignKey) => { const key = `${fk.tableFrom}-${fk.tableTo}`; const reverse = `${fk.tableTo}-${fk.tableFrom}`; return relations.has(key) && relations.has(reverse); }; const isSelf = (fk: ForeignKey) => { return fk.tableFrom === fk.tableTo; }; ``` Sources: [drizzle-kit/src/introspect-gel.ts:522-530](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-gel.ts#L522-L530) Array defaults undergo sanitization through `buildArrayDefault`, checking whether the default value string begins with `ARRAY[` or `_nullif_array_nulls(ARRAY[` before wrapping expressions in SQL template literals. ```typescript const buildArrayDefault = (defaultValue: string, typeName: string): string => { if ( typeof defaultValue === 'string' && !(defaultValue.startsWith('_nullif_array_nulls(ARRAY[') || defaultValue.startsWith('ARRAY[')) ) { return `sql\`${defaultValue}\``; } const regex = /ARRAY\[(.*)\]/; const match = defaultValue.match(regex); if (!match) { return `sql\`${defaultValue}\``; } defaultValue = match[1]; return `sql\`[${defaultValue}]\``; }; ``` Sources: [drizzle-kit/src/introspect-gel.ts:532-549](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-gel.ts#L532-L549) > [!NOTE] > Gel column mapping distinguishes between standard SQL types and prefixed extension types such as `edgedbt.bigint_t`, `edgedbt.date_duration_t`, `edgedbt.timestamptz_t`, `edgedbt.duration_t`, `edgedbt.date_t`, and `edgedbt.relative_duration_t`. Sources: [drizzle-kit/src/introspect-gel.ts:596-673](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-gel.ts#L596-L673) | Data Type Prefix / Condition | Default Evaluation Behavior | Source Reference | | :--- | :--- | :--- | | `name === 'id'` | Returns `.default(sql\`uuid_generate_v4()\`)` | [drizzle-kit/src/introspect-gel.ts:564-566](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-gel.ts#L564-L566) | | `isArray` | Delegates to `buildArrayDefault` when `defaultValue` is defined | [drizzle-kit/src/introspect-gel.ts:568-570](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-gel.ts#L568-L570) | | `edgedbt.bigint_t` | Wraps parsed column default inside `BigInt(...)` | [drizzle-kit/src/introspect-gel.ts:596-600](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-gel.ts#L596-L600) | | `uuid` (`gen_random_uuid()`) | Emits `.defaultRandom()` | [drizzle-kit/src/introspect-gel.ts:618-620](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-gel.ts#L618-L620) | | `edgedbt.timestamptz_t` (`now()`) | Emits `.defaultNow()` | [drizzle-kit/src/introspect-gel.ts:637-639](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-gel.ts#L637-L639) | | `edgedbt.date_t` (`now()`) | Emits `.defaultNow()` | [drizzle-kit/src/introspect-gel.ts:661-663](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-gel.ts#L661-L663) | Sources: [drizzle-kit/src/introspect-gel.ts:564-663](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-gel.ts#L564-L663) > [!WARNING] > Integer, smallint, and bigint default values strip enclosing parentheses via `.replaceAll('(', '').replaceAll(')', '')` before being passed to `mapColumnDefault`. Sources: [drizzle-kit/src/introspect-gel.ts:578-594](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-gel.ts#L578-L594) ## TypeScript Declaration Code Generation ### Schema to TypeScript Mapping and Imports The code generation phase inspects recovered schema structures and aggregates column types, constraints, and relational entities to emit standard Drizzle ORM TypeScript declarations. Across PostgreSQL, MySQL, SingleStore, SQLite, and Gel introspectors, builders verify dependency names and compile distinct import lists. For instance, SingleStore and MySQL generation evaluate table column types, composite primary keys, unique constraints, and indexes to construct the required core imports[Migration Toolkit Schema](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/migration-toolkit-schema). Casing configurations (`preserve` or `camel`) determine whether identifiers undergo key escaping via `prepareCasing` and `escapeColumnKey`. ```typescript const singlestoreImportsList = new Set([ 'singlestoreTable', 'singlestoreEnum', 'bigint', 'binary', 'boolean', 'char', 'date', 'datetime', 'decimal', 'double', 'float', 'int', 'json', // TODO: add new type BSON // TODO: add new type Blob // TODO: add new type UUID // TODO: add new type GUID // TODO: add new type Vector // TODO: add new type GeoPoint 'mediumint', 'real', 'serial', 'smallint', 'text', 'tinytext', 'mediumtext', 'longtext', 'time', 'timestamp', 'tinyint', 'varbinary', 'varchar', 'vector', 'year', 'enum', ]); ``` Sources: [drizzle-kit/src/introspect-singlestore.ts:19-55](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-singlestore.ts#L19-L55) > [!NOTE] > When table names or column identifiers collide with reserved import tokens or require safe property syntax, `escapeColumnKey` wraps them in double quotes if they fail valid identifier regex checks. Sources: [drizzle-kit/src/introspect-singlestore.ts:110-115](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-singlestore.ts#L110-L115), [drizzle-kit/src/introspect-mysql.ts:104-109](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-mysql.ts#L104-L109) ### Column Mapping and Default Value Formatting Column generators translate raw data types and constraint flags into chainable Drizzle builder methods. Unsigned integer modifiers, auto-increment configurations, and default expressions are formatted through dialect-specific helper functions such as `mapColumnDefault`, `mapColumnDefaultForJson`, and `binaryConfig`. ```typescript const mapColumnDefault = (defaultValue: any, isExpression?: boolean) => { if (isExpression) { return `sql\`${defaultValue}\``; } return defaultValue; }; const mapColumnDefaultForJson = (defaultValue: any) => { if ( typeof defaultValue === 'string' && defaultValue.startsWith("('") && defaultValue.endsWith("')") ) { return defaultValue.substring(2, defaultValue.length - 2); } return defaultValue; }; ``` Sources: [drizzle-kit/src/introspect-singlestore.ts:341-359](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-singlestore.ts#L341-L359) | Column Type / Dialect Helper | Behavior and Transformation | Source Reference | | :--- | :--- | :--- | | `serial` | Emits `serial(...)` without explicit type parameters | [drizzle-kit/src/introspect-singlestore.ts:376-378](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-singlestore.ts#L376-L378) | | `int` (Unsigned) | Appends `{ unsigned: true }` configuration object if lowered type includes `unsigned` | [drizzle-kit/src/introspect-singlestore.ts:380-388](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-singlestore.ts#L380-L388) | | Expression Defaults | Wraps expressions inside `sql\`...\`` via `mapColumnDefault` | [drizzle-kit/src/introspect-singlestore.ts:341-347](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-singlestore.ts#L341-L347) | | JSON Defaults | Strips wrapping parentheses and quotes from JSON default strings via `mapColumnDefaultForJson` | [drizzle-kit/src/introspect-singlestore.ts:349-359](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-singlestore.ts#L349-L359) | Sources: [drizzle-kit/src/introspect-singlestore.ts:341-388](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-singlestore.ts#L341-L388) > [!WARNING] > Cyclic foreign key relationships between tables trigger the inclusion of utility type imports like `AnyPgColumn` or specialized constraint checks to prevent circular type inference failures in generated schemas. Sources: [drizzle-kit/src/introspect-pg.ts:333-335](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-pg.ts#L333-L335), [drizzle-kit/src/introspect-mysql.ts:156-160](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-mysql.ts#L156-L160) ## Related - [Migration Toolkit Schema](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/migration-toolkit-schema) - [CLI Command Architecture](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/cli-command-architecture) --- ## Technical docs: Studio Server Bridge URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/studio-server-bridge
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-kit/src/serializer/studio.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/studio.ts) - [drizzle-kit/src/api.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/api.ts) - [drizzle-kit/src/utils/certs.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/utils/certs.ts) - [drizzle-kit/src/cli/schema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/schema.ts) - [drizzle-kit/src/cli/connections.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/connections.ts) - [drizzle-kit/src/cli/commands/introspect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/introspect.ts) - [drizzle-kit/src/cli/commands/sqliteIntrospect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/sqliteIntrospect.ts) - [drizzle-orm/src/singlestore-proxy/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-proxy/driver.ts) - [drizzle-orm/src/mysql-proxy/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-proxy/driver.ts) - [drizzle-orm/src/pg-proxy/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-proxy/driver.ts) - [drizzle-kit/src/cli/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/index.ts) - [drizzle-kit/src/cli/validations/studio.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/studio.ts) - [drizzle-kit/src/introspect-sqlite.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-sqlite.ts) - [drizzle-kit/src/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/index.ts) - [drizzle-orm/src/libsql/http/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/libsql/http/index.ts) - [drizzle-kit/src/utils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/utils.ts) - [drizzle-kit/src/cli/commands/singlestoreUp.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/singlestoreUp.ts) - [drizzle-kit/src/cli/commands/singlestoreIntrospect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/singlestoreIntrospect.ts) - [drizzle-kit/src/cli/validations/sqlite.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/sqlite.ts) - [integration-tests/drizzle2/pg-proxy/first/meta/_journal.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/drizzle2/pg-proxy/first/meta/_journal.json) - [drizzle-kit/package.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/package.json) - [drizzle-orm/src/singlestore-proxy/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-proxy/index.ts) - [drizzle-kit/src/serializer/mysqlImports.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/mysqlImports.ts) - [drizzle-kit/src/serializer/pgImports.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/pgImports.ts) - [drizzle-kit/src/serializer/singlestoreImports.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/singlestoreImports.ts)
## Overview Drizzle Studio provides an interactive web-based interface for exploring and modifying database contents via the `drizzle-kit studio` command. The [CLI Command Architecture](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/cli-command-architecture) parses parameters and validates options from configuration files before initializing the server entrypoint. The [Configuration and Validations](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/configuration-and-validations) subsystem is responsible for resolving dialect choices, database credentials, and path globs from `drizzle.config.ts`. Sources: [drizzle-kit/src/cli/schema.ts:652-675](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/schema.ts#L652-L675) Automated self-signed TLS certificates are generated and cached in environment-specific paths using tools such as `mkcert` to secure HTTPS connections. If `mkcert` is missing or fails, the server falls back to plain HTTP. Sources: [drizzle-kit/src/utils/certs.ts:15-44](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/utils/certs.ts#L15-L44) Local HTTP and HTTPS servers are initialized to orchestrate session startup, while dialect-specific database connections leverage proxy drivers to bridge remote query execution. The proxy architecture provides a standardized callback interface documented in [Drivers And Runtimes](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/drivers-and-runtimes/drivers-and-runtimes) for executing raw queries across remote and serverless execution environments. Sources: [drizzle-kit/src/serializer/studio.ts:832-847](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/studio.ts#L832-L847), [drizzle-orm/src/pg-proxy/driver.ts:27-61](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pg-proxy/driver.ts#L27-L61) Schema metadata serialization and relation extraction inspect exported TypeScript definitions to build normalized migration snapshots and relation graphs. For live databases, [Database Introspection](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/database-introspection) is used to inspect existing schemas and reverse-engineer structural snapshots before computing schema diffs. Sources: [drizzle-kit/src/serializer/studio.ts:515-584](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/studio.ts#L515-L584) ## CLI Command Wiring and Configuration Validation ### Studio CLI Parameters and Schema Validation The `studio` command defined in `drizzle-kit` uses Zod schemas to validate CLI options and configuration inputs. The command accepts custom options for network binding and configuration paths via `studioCliParams`, while `studioConfig` validates the database dialect, schema file paths or arrays, and casing options. ```typescript export const studioCliParams = object({ port: coerce.number().optional().default(4983), host: string().optional().default('127.0.0.1'), config: string().optional(), }); export const studioConfig = object({ dialect, schema: union([string(), string().array()]).optional(), casing: casingType.optional(), }); ``` Sources: [drizzle-kit/src/cli/validations/studio.ts:16-26](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/studio.ts#L16-L26) ### Command Handler Execution Flow When a user executes `drizzle-kit studio`, the handler checks core ORM versions, validates installed packages, and checks the Node.js runtime version. It then prepares the configuration, evaluates database credentials based on the selected dialect, and sets up dialect-specific database adapters. ```mermaid flowchart TD A["studio handler"] --> B["assertOrmCoreVersion()"] B --> C["assertPackages('drizzle-orm')"] C --> D["assertStudioNodeVersion()"] D --> E["prepareStudioConfig(opts)"] E --> F{"Dialect check"} F -->|postgresql| G["preparePgSchema & drizzleForPostgres"] F -->|mysql| H["prepareMySqlSchema & drizzleForMySQL"] F -->|sqlite| I["prepareSQLiteSchema & drizzleForSQLite"] F -->|turso| J["prepareSQLiteSchema & drizzleForLibSQL"] F -->|singlestore| K["prepareSingleStoreSchema & drizzleForSingleStore"] F -->|gel| L["Exit: Studio not supported"] G --> M["prepareServer(setup)"] H --> M I --> M J --> M K --> M M --> N["server.start(...)"] ``` Sources: [drizzle-kit/src/cli/schema.ts:662-756](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/schema.ts#L662-L756) ### Supported CLI Options and Drivers The Studio CLI command exposes specific parameters and driver version constraints that are validated at runtime before server startup. | Option | Type | Default | Purpose | | :--- | :--- | :--- | :--- | | `port` | number | `4983` | Custom port for Drizzle Studio | | `host` | string | `0.0.0.0` (CLI) / `127.0.0.1` (Validation) | Custom host for Drizzle Studio | | `verbose` | boolean | `false` | Print all statements executed by Studio | | `config` | string | `undefined` | Path to the configuration file | Sources: [drizzle-kit/src/cli/schema.ts:654-661](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/schema.ts#L654-L661), [drizzle-kit/src/cli/validations/studio.ts:16-20](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/studio.ts#L16-L20) > [!CAUTION] > Attempting to run the `studio` command with the `gel` dialect triggers an explicit termination via `process.exit(1)`, as Studio does not support Gel. > > Sources: [drizzle-kit/src/cli/schema.ts:743-749](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/schema.ts#L743-L749) > [!WARNING] > Specific PostgreSQL drivers impose strict version checks on `drizzle-orm`. Using `aws-data-api` requires `drizzle-orm` version greater than `0.30.10`, and `pglite` requires version greater than `0.30.6`, otherwise the process exits with an error. > > Sources: [drizzle-kit/src/cli/schema.ts:694-708](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/schema.ts#L694-L708) ## TLS Certificate Generation and Lifecycle ### Certificate Discovery and Storage Path Drizzle-kit automates the provisioning of local self-signed TLS certificates for secure HTTPS Studio connections by leveraging `mkcert` and `env-paths`. When starting the server, `certs()` first inspects whether `mkcert` is installed by running `mkcert --help`. Sources: [drizzle-kit/src/utils/certs.ts:15-18](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/utils/certs.ts#L15-L18) If the command succeeds with an exit code of `0`, it resolves the platform-specific data directory using `env-paths` with the application name `drizzle-studio` and an empty suffix, ensuring the directory exists recursively. Sources: [drizzle-kit/src/utils/certs.ts:19-25](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/utils/certs.ts#L19-L25) ### Caching and Generation Flow Within the resolved data path, `drizzle-kit` looks for cached PEM files named `localhost-key.pem` and `localhost.pem`. It tests accessibility via `fs/promises` `access`, generating fresh credentials via `mkcert localhost` if missing. Sources: [drizzle-kit/src/utils/certs.ts:26-36](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/utils/certs.ts#L26-L36) Finally, it reads both files using UTF-8 encoding and returns them as a `{ key, cert }` object, falling back to `null` if `mkcert` is unavailable or if certificate generation fails. Sources: [drizzle-kit/src/utils/certs.ts:37-44](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/utils/certs.ts#L37-L44) > [!NOTE] > If `mkcert` is not installed on the host machine, `certs()` returns `null`, causing the Studio server to fall back to plain HTTP connections instead of HTTPS. > > Sources: [drizzle-kit/src/utils/certs.ts:15-43](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/utils/certs.ts#L15-L43), [drizzle-kit/src/api.ts:654](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/api.ts#L654) ## Local HTTP Server Initialization ### Server Setup and Listener Configuration The initialization of the local Studio listener is orchestrated through `startServerFromSetup` in `api.ts` and `prepareServer` in `studio.ts`. Once the database setup and schema introspection wrappers are resolved, `startServerFromSetup` invokes `prepareServer(setup)` to construct the core request handler and server control handles. It defaults the binding host to `127.0.0.1` and the port to `4983` if explicit options are omitted, retrieves active TLS certificates via `certs()`, and invokes `server.start()` to spin up the underlying listener. ```typescript const startServerFromSetup = async (setup: Setup, options?: { host?: string; port?: number; }) => { const { prepareServer } = await import('./serializer/studio'); const server = await prepareServer(setup); const host = options?.host || '127.0.0.1'; const port = options?.port || 4983; const { key, cert } = (await certs()) || {}; server.start({ host, port, key, cert, cb: (err) => { if (err) { console.error(err); } else { console.log(`Studio is running at ${key ? 'https' : 'http'}://${host}:${port}`); } }, }); }; ``` Sources: [drizzle-kit/src/api.ts:634-658](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/api.ts#L634-L658) ### Listener Options and Execution Parameters The `server.start()` method accepts a parameter object containing network binding properties and optional SSL credentials. When a TLS key is present, it explicitly configures Node's native `createServer` factory function alongside the provided private key and certificate paths. | Parameter | Type | Default | Purpose | | :--- | :--- | :--- | :--- | | `host` | string | `127.0.0.1` (API) / `0.0.0.0` (CLI) | Hostname or IP address for the HTTP listener | | `port` | number | `4983` | TCP port for the Studio server | | `key` | string \| undefined | `undefined` | PEM-encoded private TLS key for HTTPS | | `cert` | string \| undefined | `undefined` | PEM-encoded TLS certificate for HTTPS | | `cb` | function | `(err) => void` | Callback executed after listener startup | Sources: [drizzle-kit/src/serializer/studio.ts:831-847](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/studio.ts#L831-L847), [drizzle-kit/src/api.ts:642-657](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/api.ts#L642-L657) ```typescript return { start: (params: Parameters[0]) => { serve( { fetch: app!.fetch, createServer: params.key ? createServer : undefined, hostname: params.host, port: params.port, serverOptions: { key: params.key, cert: params.cert, }, }, () => params.cb(null, `${params.host}:${params.port}`), ); }, }; ``` Sources: [drizzle-kit/src/serializer/studio.ts:831-847](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/studio.ts#L831-L847) > [!NOTE] > The `serve` wrapper selectively binds `createServer` only when `params.key` is defined, enabling switching between secure HTTPS listeners and standard unencrypted HTTP streams depending on `mkcert` availability. > > Sources: [drizzle-kit/src/serializer/studio.ts:833-843](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/studio.ts#L833-L843) ## Dialect Adapters and Remote Query Proxying ### Remote Database Sessions and Callbacks The remote query proxy architecture bridges database interactions by instantiating dialect-specific remote sessions that delegate statement execution over asynchronous callback channels. In MySQL and SingleStore driver implementations, the `drizzle` factory function accepts a `RemoteCallback` alongside optional configuration properties like casing and loggers. This callback receives raw SQL strings, parameter bindings, and execution methods, returning a standardized result structure containing rows, insert identifiers, and affected row counts. ```typescript export type RemoteCallback = ( sql: string, params: any[], method: 'all' | 'execute', ) => Promise<{ rows: any[]; insertId?: number; affectedRows?: number }>; export function drizzle = Record>( callback: RemoteCallback, config: DrizzleConfig = {}, ): MySqlRemoteDatabase { ``` Sources: [drizzle-orm/src/mysql-proxy/driver.ts:20-29](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-proxy/driver.ts#L20-L29) ```typescript export type RemoteCallback = ( sql: string, params: any[], method: 'all' | 'execute', ) => Promise<{ rows: any[]; insertId?: number; affectedRows?: number }>; ``` Sources: [drizzle-orm/src/singlestore-proxy/driver.ts:24-28](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-proxy/driver.ts#L24-L28) ### Driver Session Classes and Dialect Binding Both MySQL and SingleStore remote entrypoints instantiate specialized database and session classes to process query generation through their respective core dialects. The `MySqlRemoteDatabase` extends `MySqlDatabase` utilizing `MySqlRemoteQueryResultHKT`, `MySqlRemotePreparedQueryHKT`, and `MySqlRemoteSession`. Similarly, `SingleStoreRemoteDatabase` extends `SingleStoreDatabase` utilizing `SingleStoreRemoteQueryResultHKT`, `SingleStoreRemotePreparedQueryHKT`, and `SingleStoreRemoteSession`. | Database Class | Dialect Class | Session Class | Query HKT Types | | :--- | :--- | :--- | :--- | | `MySqlRemoteDatabase` | `MySqlDialect` | `MySqlRemoteSession` | `MySqlRemoteQueryResultHKT`, `MySqlRemotePreparedQueryHKT` | | `SingleStoreRemoteDatabase` | `SingleStoreDialect` | `SingleStoreRemoteSession` | `SingleStoreRemoteQueryResultHKT`, `SingleStoreRemotePreparedQueryHKT` | Sources: [drizzle-orm/src/mysql-proxy/driver.ts:14-18](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-proxy/driver.ts#L14-L18), [drizzle-orm/src/mysql-proxy/driver.ts:30-55](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-proxy/driver.ts#L30-L55), [drizzle-orm/src/singlestore-proxy/driver.ts:18-22](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-proxy/driver.ts#L18-L22), [drizzle-orm/src/singlestore-proxy/driver.ts:34-55](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-proxy/driver.ts#L34-L55) > [!NOTE] > Schema tables passed into remote driver configurations are extracted via `extractTablesRelationalConfig` combined with `createTableRelationsHelpers`, binding table structures and map mappings directly to the database session instance. > > Sources: [drizzle-orm/src/mysql-proxy/driver.ts:40-51](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-proxy/driver.ts#L40-L51), [drizzle-orm/src/singlestore-proxy/driver.ts:44-53](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-proxy/driver.ts#L44-L53) ## Schema Serialization and Call-Chain Walkthrough ### Call-Chain Execution Walkthrough: PushSingleStoreSchema -> PrepareFromExports The execution flow for `PushSingleStoreSchema -> PrepareFromExports` is traced through the following call order: `pushSingleStoreSchema` → `generateSingleStoreDrizzleJson` → `prepareFromExports`. 1. **Step 1 (`pushSingleStoreSchema`):** The operation begins in `drizzle-kit/src/api.ts` where `pushSingleStoreSchema` receives schema exports, a `SingleStoreDriverDatabase` instance, and a database name. It prepares the database query callback interface and invokes `generateSingleStoreDrizzleJson(imports)` to produce the target snapshot. Sources: [drizzle-kit/src/api.ts:545-565](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/api.ts#L545-L565) 2. **Step 2 (`generateSingleStoreDrizzleJson`):** In `drizzle-kit/src/api.ts`, `generateSingleStoreDrizzleJson` dynamically imports `prepareFromExports` from `./serializer/singlestoreImports` and calls `prepareFromExports(imports)` to isolate valid table exports. It generates a new random snapshot ID via `randomUUID()` and falls back to `originUUID` for `prevId` before invoking `generateSingleStoreSnapshot`. Sources: [drizzle-kit/src/api.ts:499-517](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/api.ts#L499-L517) 3. **Step 3 (`prepareFromExports`):** In `drizzle-kit/src/serializer/singlestoreImports.ts`, `prepareFromExports` iterates through `Object.values(exports)` and checks each export using `if (is(t, SingleStoreTable))` to filter and return `{ tables }`. Sources: [drizzle-kit/src/serializer/singlestoreImports.ts:6-22](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/singlestoreImports.ts#L6-L22) ```mermaid sequenceDiagram participant api as drizzle-kit/src/api.ts participant singlestoreImports as drizzle-kit/src/serializer/singlestoreImports.ts participant singlestoreSerializer as drizzle-kit/src/serializer/singlestoreSerializer.ts api->>api: pushSingleStoreSchema(imports, drizzleInstance, databaseName) api->>api: generateSingleStoreDrizzleJson(imports) api->>singlestoreImports: prepareFromExports(imports) singlestoreImports-->>api: return { tables } api->>singlestoreSerializer: generateSingleStoreSnapshot(prepared.tables, casing) singlestoreSerializer-->>api: return snapshot api-->>api: return SingleStoreSchemaKit ``` Sources: [drizzle-kit/src/api.ts:499-565](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/api.ts#L499-L565), [drizzle-kit/src/serializer/singlestoreImports.ts:6-22](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/singlestoreImports.ts#L6-L22) ### Relational Schema Configuration and Relation Extraction Studio requires a complete model of relations across tables. The `extractRelations` function processes relational table definitions extracted by Drizzle ORM, resolving foreign keys, casing adjustments, and referenced schemas across dialects: ```typescript export const extractRelations = ( tablesConfig: { tables: TablesRelationalConfig; tableNamesMap: Record; }, casing?: CasingType, ): Relation[] => { const relations = Object.values(tablesConfig.tables) .map((it) => Object.entries(it.relations).map(([name, relation]) => { try { const normalized = normalizeRelation( tablesConfig.tables, tablesConfig.tableNamesMap, relation, ); const rel = relation; const refTableName = rel.referencedTableName; const refTable = rel.referencedTable; const fields = normalized.fields .map((it) => getColumnCasing(it, casing)) .flat(); const refColumns = normalized.references .map((it) => getColumnCasing(it, casing)) .flat(); let refSchema: string | undefined; if (is(refTable, PgTable)) { refSchema = pgTableConfig(refTable).schema; } else if (is(refTable, MySqlTable)) { refSchema = mysqlTableConfig(refTable).schema; } else if (is(refTable, SQLiteTable)) { refSchema = undefined; } else if (is(refTable, SingleStoreTable)) { refSchema = singlestoreTableConfig(refTable).schema; } else { throw new Error('unsupported dialect'); } let type: 'one' | 'many'; if (is(rel, One)) { type = 'one'; } else if (is(rel, Many)) { type = 'many'; } else { throw new Error('unsupported relation type'); } return { name, type, table: it.dbName, schema: it.schema || 'public', columns: fields, refTable: refTableName, refSchema: refSchema || 'public', refColumns: refColumns, }; } catch { throw new Error( `Invalid relation "${relation.fieldName}" for table "${ it.schema ? `${it.schema}.${it.dbName}` : it.dbName }"`, ); } }) ) .flat(); return relations; }; ``` Sources: [drizzle-kit/src/serializer/studio.ts:515-584](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/studio.ts#L515-L584) > [!WARNING] > Relation extraction will catch errors and issue console warnings if table relations are ambiguous or misconfigured, guiding developers to verify schema definitions against disambiguation documentation. > > Sources: [drizzle-kit/src/serializer/studio.ts:758-771](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/studio.ts#L758-L771) ## Serialization Details and Design Trade-offs ### Serialization Transformers and Data Formatting When Studio requests initialization metadata or executes proxy queries, responses undergo specific transformations in `jsonStringify` before being serialized. This custom serializer addresses JavaScript data types that do not natively map to standard JSON primitives: | Data Type | Detection Condition | Serialized Representation | Rationale | | :--- | :--- | :--- | :--- | | `Error` | `value instanceof Error` | `{ error: value.message }` | Prevents empty object serialization of error instances | | `bigint` | `typeof value === 'bigint'` | `value.toString()` | Avoids `TypeError: Do not know how to serialize a BigInt` | | `Buffer` | `value instanceof Buffer` \|\| `value.type === 'Buffer'` | Base64 string via `Buffer.from(value).toString('base64')` | Ensures binary database blobs transmit over HTTP JSON APIs safely | | `ArrayBuffer` | `value instanceof ArrayBuffer` | Base64 string via `Buffer.from(value).toString('base64')` | Allows browser/typed array binary buffers to serialize | Sources: [drizzle-kit/src/serializer/studio.ts:645-670](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/studio.ts#L645-L670) ### Design Trade-offs The architectural design of the Studio Server Bridge balances local developer experience with lightweight server execution: | Design Choice | Benefit | Cost | | :--- | :--- | :--- | | CLI-driven child process execution (`mkcert`) | Avoids native OpenSSL dependencies and manages local CA trusts automatically | Requires external `mkcert` binary on the host machine path or falls back to HTTP [drizzle-kit/src/utils/certs.ts:16-43](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/utils/certs.ts#L16-L43) | | In-memory proxy callback dispatching | Reuses dialect-specific ORM drivers without maintaining permanent database pools | Lacks persistent cross-query transaction handles for certain serverless drivers [drizzle-kit/src/cli/connections.ts:112-114](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/connections.ts#L112-L114) | | Base64 binary serialization in JSON replacer | Transmits binary data and byte buffers without special transport layers | Increases payload transfer size for large binary columns [drizzle-kit/src/serializer/studio.ts:669](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/studio.ts#L669) | | Dynamic runtime imports of dialects and drivers | Reduces CLI startup time by deferring heavy database drivers | Introduces async require/import latency on first command dispatch [drizzle-kit/src/cli/schema.ts:677-688](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/schema.ts#L677-L688) | Sources: [drizzle-kit/src/utils/certs.ts:16-43](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/utils/certs.ts#L16-L43), [drizzle-kit/src/cli/connections.ts:112-114](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/connections.ts#L112-L114), [drizzle-kit/src/serializer/studio.ts:669](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/studio.ts#L669), [drizzle-kit/src/cli/schema.ts:677-688](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/schema.ts#L677-L688) ### Runnable API Usage Example The Studio server can also be launched programmatically via the `startStudioPostgresServer` or `startStudioMySQLServer` APIs exposed in `drizzle-kit/api`: ```typescript import { startStudioPostgresServer } from 'drizzle-kit/api'; import { pgTable, serial, text } from 'drizzle-orm/pg-core'; const users = pgTable('users', { id: serial('id').primaryKey(), name: text('name').notNull(), }); await startStudioPostgresServer( { users }, { host: '127.0.0.1', port: 5432, user: 'postgres', password: 'password', database: 'app_db', }, { host: '127.0.0.1', port: 4983, }, ); ``` Sources: [drizzle-kit/src/api.ts:205-221](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/api.ts#L205-L221), [drizzle-kit/src/api.ts:634-658](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/api.ts#L634-L658) ## Related - [CLI Command Architecture](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/cli-command-architecture) - [Migration Toolkit Schema](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/migration-toolkit-schema) --- ## Technical docs: Configuration and Validations URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/configuration-and-validations
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-kit/src/cli/commands/utils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/utils.ts) - [drizzle-kit/src/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/index.ts) - [drizzle-kit/src/snapshotsDiffer.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/snapshotsDiffer.ts) - [drizzle-kit/src/api.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/api.ts) - [drizzle-kit/src/serializer/studio.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/studio.ts) - [drizzle-kit/src/cli/connections.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/connections.ts) - [drizzle-orm/src/utils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/utils.ts) - [drizzle-orm/src/gel-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/dialect.ts) - [drizzle-kit/src/cli/validations/common.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/common.ts) - [drizzle-kit/src/cli/validations/sqlite.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/sqlite.ts) - [drizzle-kit/src/cli/validations/studio.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/studio.ts) - [drizzle-kit/src/cli/validations/gel.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/gel.ts) - [drizzle-kit/src/cli/validations/postgres.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/postgres.ts) - [drizzle-kit/src/serializer/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/index.ts) - [drizzle-kit/src/utils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/utils.ts) - [drizzle-kit/src/serializer/pgImports.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/pgImports.ts) - [drizzle-orm/src/mysql2/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql2/driver.ts) - [drizzle-kit/src/cli/validations/cli.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/cli.ts) - [drizzle-kit/src/cli/validations/libsql.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/libsql.ts) - [drizzle-kit/src/schemaValidator.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/schemaValidator.ts) - [drizzle-kit/src/cli/validations/mysql.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/mysql.ts) - [drizzle-orm/src/better-sqlite3/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/better-sqlite3/driver.ts) - [drizzle-kit/src/cli/validations/singlestore.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/singlestore.ts) - [drizzle-orm/src/relations.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/relations.ts) - [eslint-plugin-drizzle/src/configs/all.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/configs/all.ts) - [eslint-plugin-drizzle/src/utils/options.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/utils/options.ts) - [drizzle-kit/src/cli/validations/outputs.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/outputs.ts) - [drizzle-seed/tsconfig.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/tsconfig.json) - [drizzle-valibot/tsconfig.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/tsconfig.json) - [drizzle-orm/tsup.config.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/tsup.config.ts)
## Overview Configuration and Validations provides the schema definitions, parsing routines, and validation rules that govern `drizzle.config.ts` loading and command-line options across supported database engines. It leverages Zod schemas to validate configuration properties such as dialects, schema paths, migration output directories, and database credentials for PostgreSQL, MySQL, SQLite, LibSQL, SingleStore, and Gel. By validating user inputs early, the subsystem detects missing or ambiguous parameters, resolves file globs, and reports diagnostic issues via chalk-styled terminal outputs. Sources: [drizzle-kit/src/cli/commands/utils.ts:310-326](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/utils.ts#L310-L326), [drizzle-kit/src/index.ts:23-349](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/index.ts#L23-L349), [drizzle-kit/src/cli/validations/common.ts:30-116](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/common.ts#L30-L116), [drizzle-kit/src/cli/validations/outputs.ts:4-91](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/outputs.ts#L4-L91) ## Configuration File Discovery and Resolution ### Config Loading and CLI Override Flag Integration Configuration preparation routines retrieve settings either directly from command-line arguments or by loading configuration files based on the specified source origin. When `from` is set to `'config'`, the system invokes `drizzleConfigFromFile` with an optional configuration path string to load file-based settings, then passes the result through `flattenDatabaseCredentials` to merge nested `dbCredentials` properties directly into the root configuration object. CLI-provided flags take precedence or supplement configuration file properties during execution setup. For example, `preparePushConfig` explicitly evaluates options by setting `raw.verbose ||= options.verbose` if provided via the CLI for debugging, and `raw.strict ||= options.strict` exclusively from command-line flags. ```typescript const raw = flattenDatabaseCredentials( from === 'config' ? await drizzleConfigFromFile(options.config as string | undefined) : options, ); raw.verbose ||= options.verbose; // if provided in cli to debug raw.strict ||= options.strict; // if provided in cli only ``` Sources: [drizzle-kit/src/cli/commands/utils.ts:310-318](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/utils.ts#L310-L318) > [!NOTE] > Database credentials inside configuration files are defined under the `dbCredentials` property, which `flattenDatabaseCredentials` flattens alongside the rest of the configuration object to align with validation schemas. Sources: [drizzle-kit/src/cli/commands/utils.ts:251-260](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/utils.ts#L251-L260) ### Credential Flattening and Pull Config Transformation The utility module provides specific transformation helpers to normalize configuration shapes depending on whether an inspection pull or schema push is requested. The `flattenPull` helper extracts `dbCredentials` and `introspect` properties from the config object, merging connection properties into the root and extracting `casing: introspect?.casing` for schema generation. ```typescript const flattenPull = (config: any) => { if ('dbCredentials' in config) { const { dbCredentials, introspect, ...rest } = config; return { ...rest, ...dbCredentials, casing: introspect?.casing, }; } return config; }; ``` Sources: [drizzle-kit/src/cli/commands/utils.ts:262-272](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/utils.ts#L262-L272) ## Dialect Schema Validation with Zod ### Public Configuration Types and Top-Level Dialect Schemas The configuration subsystem relies on Zod definitions to establish strict TypeScript types and runtime validation rules for public settings. The central dialect enum schema defines all supported database engines, compiling them into a union type utilized across CLI and file-based configurations. ```typescript export const dialects = ['postgresql', 'mysql', 'sqlite', 'turso', 'singlestore', 'gel'] as const; export const dialect = enumType(dialects); export type Dialect = (typeof dialects)[number]; const _: Dialect = '' as TypeOf; ``` Sources: [drizzle-kit/src/schemaValidator.ts:7-11](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/schemaValidator.ts#L7-L11) The supported dialects and core driver options are formally structured via validation literals and enums across the validation modules. | Constant / Property | Type / Literals | Meaning / Purpose | | :--- | :--- | :--- | | `dialects` | `['postgresql', 'mysql', 'sqlite', 'turso', 'singlestore', 'gel']` | Supported database engines across Drizzle Kit commands. | | `sqliteDriversLiterals` | `['d1-http', 'expo', 'durable-sqlite']` | Specific client drivers available for SQLite configurations. | | `postgresqlDriversLiterals` | `['aws-data-api', 'pglite']` | Specific client drivers available for PostgreSQL configurations. | | `prefixes` | `['index', 'timestamp', 'supabase', 'unix', 'none']` | Migration naming prefix formats. | | `casingTypes` | `['snake_case', 'camelCase']` | Identifier casing strategies. | Sources: [drizzle-kit/src/cli/validations/common.ts:64-91](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/common.ts#L64-L91), [drizzle-kit/src/schemaValidator.ts:7-8](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/schemaValidator.ts#L7-L8) > [!NOTE] > The `defineConfig` helper function acts as a typed identity wrapper for `Config` definitions in configuration files, ensuring users get proper IDE autocompletion without runtime transformation overhead. Sources: [drizzle-kit/src/index.ts:347-349](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/index.ts#L347-L349) ### Core Zod Validation Structures Common validation schemas establish baseline expectations for common properties such as migration settings, output directories, breakpoints, and table filters. The `configCommonSchema` validates general options using `.passthrough()` to allow engine-specific connection properties within `dbCredentials` or root structures. ```typescript export const configCommonSchema = object({ dialect: dialect, schema: union([string(), string().array()]).optional(), out: string().optional(), breakpoints: boolean().optional().default(true), verbose: boolean().optional().default(false), driver: driver.optional(), tablesFilter: union([string(), string().array()]).optional(), schemaFilter: union([string(), string().array()]).default(['public']), migrations: configMigrations, dbCredentials: any().optional(), casing: casingType.optional(), sql: boolean().default(true), }).passthrough(); ``` Sources: [drizzle-kit/src/cli/validations/common.ts:103-116](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/common.ts#L103-L116) Specialized parameter schemas handle specific commands like introspection, generation, and schema pushing. For example, `pushParams` and `pullParams` require a `dialect`, accept table and schema filters with a default `public` schema array, and support extended entities such as roles configuration. ```typescript export const pushParams = object({ dialect: dialect, casing: casingType.optional(), schema: union([string(), string().array()]), tablesFilter: union([string(), string().array()]).optional(), schemaFilter: union([string(), string().array()]) .optional() .default(['public']), extensionsFilters: literal('postgis').array().optional(), verbose: boolean().optional(), strict: boolean().optional(), entities: object({ roles: boolean().or(object({ provider: string().optional(), include: string().array().optional(), exclude: string().array().optional(), })).optional().default(false), }).optional(), }).passthrough(); ``` Sources: [drizzle-kit/src/cli/validations/cli.ts:18-36](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/cli.ts#L18-L36) > [!WARNING] > The `schemaFilter` property defaults to `['public']` across common and push validation schemas; omitting it explicitly scopes introspection and schema push targets to the PostgreSQL public schema. Sources: [drizzle-kit/src/cli/validations/common.ts:111-111](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/common.ts#L111-L111), [drizzle-kit/src/cli/validations/cli.ts:23-25](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/cli.ts#L23-L25) ## Relational Engine Connection Specifications ### PostgreSQL, MySQL, and SingleStore Connection Rules Connection specifications for PostgreSQL, MySQL, and SingleStore rely on Zod union schemas that validate discrete parameter combinations. PostgreSQL credentials support standard host-port tuples, connection strings via `url`, AWS Data API configurations utilizing `driver: 'aws-data-api'` alongside `database`, `secretArn`, and `resourceArn`, and PGLite instances using `driver: 'pglite'` with a `url`. | Credential Variant | Required Parameters | Optional Parameters | Driver Literal / Notes | | :--- | :--- | :--- | :--- | | PostgreSQL Host-Port | `host`, `database` | `port`, `user`, `password`, `ssl` | Standard TCP connection | | PostgreSQL URL | `url` | None | Connection URI string | | PostgreSQL AWS Data API | `database`, `secretArn`, `resourceArn` | None | `driver: 'aws-data-api'` | | PostgreSQL PGLite | `url` | None | `driver: 'pglite'` | | MySQL / SingleStore Host-Port | `host`, `database` | `port`, `user`, `password`, `ssl` | TCP socket or pool connection | | MySQL / SingleStore URL | `url` | None | Connection URI string | Sources: [drizzle-kit/src/cli/validations/postgres.ts:5-42](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/postgres.ts#L5-L42), [drizzle-kit/src/cli/validations/mysql.ts:6-30](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/mysql.ts#L6-L30), [drizzle-kit/src/cli/validations/singlestore.ts:6-30](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/singlestore.ts#L6-L30) > [!WARNING] > When configuring MySQL or SingleStore with explicit host parameters, the `database` property is mandatory alongside `host`, whereas URL-based connections require only the `url` string. Sources: [drizzle-kit/src/cli/validations/mysql.ts:6-30](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/mysql.ts#L6-L30), [drizzle-kit/src/cli/validations/singlestore.ts:6-30](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/singlestore.ts#L6-L30) ### SSL and TLS Parameter Structures Both MySQL and SingleStore share identical validation schemas for SSL configurations, accepting either a connection string or a detailed object containing certificate files and verification controls. PostgreSQL permits boolean values, specific string literals, or passthrough configuration objects for its `ssl` property. ```typescript ssl: union([ string(), object({ pfx: string().optional(), key: string().optional(), passphrase: string().optional(), cert: string().optional(), ca: union([string(), string().array()]).optional(), crl: union([string(), string().array()]).optional(), ciphers: string().optional(), rejectUnauthorized: boolean().optional(), }), ]).optional(), ``` Sources: [drizzle-kit/src/cli/validations/mysql.ts:13-25](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/mysql.ts#L13-L25) The MySQL and SingleStore SSL option object supports specific cryptographic properties for secure socket establishment: | SSL Property | Expected Type | Description | | :--- | :--- | :--- | | `pfx` | `string` (optional) | Private key, certificate, and CA certificates in PFX or PKCS12 format. | | `key` | `string` (optional) | Private key for the connection in PEM format. | | `passphrase` | `string` (optional) | Shared passphrase for private key or pfx. | | `cert` | `string` (optional) | Cert chain to use in PEM format. | | `ca` | `string \| string[]` (optional) | Trusted certificate authorities. | | `crl` | `string \| string[]` (optional) | Certificate revocation lists. | | `ciphers` | `string` (optional) | Cipher suites to use or exclude. | | `rejectUnauthorized` | `boolean` (optional) | Controls server certificate verification against list of supplied CAs. | Sources: [drizzle-kit/src/cli/validations/mysql.ts:15-24](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/mysql.ts#L15-L24), [drizzle-kit/src/cli/validations/singlestore.ts:15-24](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/singlestore.ts#L15-L24) > [!NOTE] > PostgreSQL SSL validation accepts literal string values including `'require'`, `'allow'`, `'prefer'`, and `'verify-full'`, alongside standard booleans and passthrough objects. Sources: [drizzle-kit/src/cli/validations/postgres.ts:13-20](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/postgres.ts#L13-L20) ## Embedded SQLite and LibSQL Validation ### SQLite Schema Variants and Connection Credentials The SQLite validation module evaluates credentials across multiple driver variants using Zod union schemas. The supported configurations include Turso connections requiring a URL and optional auth token, Cloudflare D1 HTTP instances requiring an account ID, database ID, and token, and standard local SQLite database files where the driver is undefined and a file path `url` is specified. | SQLite Credential Variant | Required Parameters | Optional Parameters | Driver Literal / Notes | | :--- | :--- | :--- | :--- | | Turso Cloud | `url` | `authToken` | `driver: 'turso'` | | Cloudflare D1 HTTP | `accountId`, `databaseId`, `token` | None | `driver: 'd1-http'` | | Local File SQLite | `url` | None | `driver: undefined` | Sources: [drizzle-kit/src/cli/validations/sqlite.ts:6-25](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/sqlite.ts#L6-L25) LibSQL credentials share a dedicated validation object requiring a `url` string with an optional `authToken` string. ```typescript export const libSQLCredentials = object({ url: string().min(1), authToken: string().min(1).optional(), }); ``` Sources: [drizzle-kit/src/cli/validations/libsql.ts:6-9](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/libsql.ts#L6-L9) > [!WARNING] > When defining local SQLite paths via the undefined driver variant, Zod transforms the object by explicitly deleting the `driver` property before passing the parsed configuration through. Sources: [drizzle-kit/src/cli/validations/sqlite.ts:18-24](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/sqlite.ts#L18-L24) ### Better-SQLite3 Client Construction and Configuration The Better-SQLite3 driver initializes synchronization sessions by accepting database instances, file path strings, or comprehensive configuration options through its `drizzle` entry point. The configuration accepts client objects or connection configuration blocks containing source definitions and native Better-SQLite3 options. | Parameter Type | Accepted Values | Behavior | | :--- | :--- | :--- | | `client` | `Database` instance | Directly uses the provided Better-SQLite3 database instance. | | `connection` | `string`, `Buffer`, or object with `source` and options | Instantiates a new `Client` with the given file source and options. | | `undefined` / string | `undefined` or file path string | Creates a new in-memory or file-backed `Client` instance. | Sources: [drizzle-orm/src/better-sqlite3/driver.ts:15-22](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/better-sqlite3/driver.ts#L15-L22), [drizzle-orm/src/better-sqlite3/driver.ts:68-123](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/better-sqlite3/driver.ts#L68-L123) > [!NOTE] > The `drizzle.mock()` method constructs a synchronous Better-SQLite3 database instance using an empty dummy client where `$client` is explicitly marked as unavailable. Sources: [drizzle-orm/src/better-sqlite3/driver.ts:125-133](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/better-sqlite3/driver.ts#L125-L133) ## Schema Globs and Filter Normalization ### Resolving Schema Globs and File Preparation During configuration preparation via `preparePushConfig`, the configuration object is parsed using `pushParams.safeParse(raw)`, retrieving raw schema definitions that may be specified as a single string path or an array of path globs. These schema glob patterns are passed directly to `prepareFilenames` to locate matching typescript or javascript files across the file system. If no schema files are found matching the pattern, an informational message is rendered to the terminal using `render` with a blue info icon, and execution terminates cleanly without performing database changes. Sources: [drizzle-kit/src/cli/commands/utils.ts:330-334](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/utils.ts#L330-L334) > [!CAUTION] Grep-like pattern matching or glob expansion via `prepareFilenames` must locate at least one file; an empty file array causes the process to exit immediately with status code `0`, preventing subsequent database synchronization steps from executing. Sources: [drizzle-kit/src/cli/commands/utils.ts:331-334](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/utils.ts#L331-L334) ### Table and Schema Filter Normalization Configured table filters and database schema filters undergo type normalization before being applied to introspection or push operations. The configuration values retrieved from `config.tablesFilter` and `config.schemaFilter` can be provided either as a single string or as an array of strings. Normalization handles these input types uniformly by wrapping scalar strings in an array or defaulting to an empty array when undefined. | Configuration Key | Normalization Logic | Default Value | Target Array Result | | :--- | :--- | :--- | :--- | | `tablesFilter` | `typeof tablesFilterConfig === 'string' ? [tablesFilterConfig] : tablesFilterConfig` | `[]` | `string[]` | | `schemaFilter` | `typeof schemasFilterConfig === 'string' ? [schemasFilterConfig] : schemasFilterConfig` | `[]` | `string[]` | Sources: [drizzle-kit/src/cli/commands/utils.ts:336-349](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/utils.ts#L336-L349) > [!NOTE] Additional table filters derived from registered dialect extensions are dynamically appended to the normalized `tablesFilter` array using `tablesFilter.push(...getTablesFilterByExtensions(config))`. Sources: [drizzle-kit/src/cli/commands/utils.ts:351-351](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/utils.ts#L351-L351) ### PostgreSQL Import Processing and Entity Categorization When handling PostgreSQL schema imports, `prepareFromPgImports` iterates over resolved import paths inside a safe module registration context, requiring each file and categorizing its exported Drizzle entities. The `prepareFromExports` function inspects the exported dictionary values using typeguards to separate tables, enums, schemas, sequences, views, materialized views, roles, policies, and relations into distinct typed arrays. | Entity Category | Detection Guard / Type Identifier | Result Array Type | | :--- | :--- | :--- | | Tables | `is(t, PgTable)` | `AnyPgTable[]` | | Enums | `isPgEnum(t)` | `PgEnum[]` | | Schemas | `is(t, PgSchema)` | `PgSchema[]` | | Sequences | `isPgSequence(t)` | `PgSequence[]` | | Views | `isPgView(t)` | `PgView[]` | | Materialized Views | `isPgMaterializedView(t)` | `PgMaterializedView[]` | | Roles | `is(t, PgRole)` | `PgRole[]` | | Policies | `is(t, PgPolicy)` | `PgPolicy[]` | | Relations | `is(t, Relations)` | `Relations[]` | Sources: [drizzle-kit/src/serializer/pgImports.ts:16-67](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/pgImports.ts#L16-L67), [drizzle-kit/src/serializer/pgImports.ts:70-109](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/pgImports.ts#L70-L109) ## Validation Diagnostics and Terminal Reporting ### Terminal Output Styling and Error Formatting Drizzle Kit uses `chalk` combined with custom style helpers (`withStyle`) to render validation diagnostics, warnings, and error messages to the terminal. The `withStyle` utility provides standardized visual badges such as inverted background tags for invalid inputs, warnings, and suggestions. Parameter formatting uses `wrapParam` to display configuration checkmarks or crosses alongside masked secrets and sanitized database connection URLs. | Style Function | Visual Output Format | Purpose | | :--- | :--- | :--- | | `withStyle.error` | `Invalid input` (white text on red background) + error message | Formatting critical configuration validation failures | | `withStyle.warning` | `Warning` (white text on gray background) + warning text | Displaying non-fatal configuration warnings | | `withStyle.errorWarning` | `Warning` (white text on red background) + warning text | Highlighting severe warnings | | `withStyle.fullWarning` | `Warning` (black text on yellow bold background) + message | Highlighting prominent warnings | | `withStyle.suggestion` | `Suggestion` (white text on gray background) + advice | Providing actionable recommendations | | `withStyle.info` | Grey text | Rendering informational diagnostics | Sources: [drizzle-kit/src/cli/validations/outputs.ts:4-11](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/outputs.ts#L4-L11) > [!NOTE] The `wrapParam` utility automatically detects string parameters, masking password components in database connection URLs using a regex replacement (`param.replace(/(?<=:\/\/[^:\n]*:)([^@]*)/, '****')`) while displaying `'*****'` for explicit secrets and green checkmarks or red crosses based on presence. Sources: [drizzle-kit/src/cli/validations/common.ts:170-188](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/common.ts#L170-L188) ### Output Definitions and Dialect Diagnostics The `outputs` dictionary catalogs all structured error messages for Drizzle Studio, general CLI commands, and database dialects including PostgreSQL, MySQL, SQLite, and SingleStore. When required configuration parameters or connection credentials are omitted, these functions generate descriptive messages referencing documentation URLs. ```typescript export const outputs = { studio: { drivers: (param: string) => withStyle.error( `"${param}" is not a valid driver. Available drivers: "pg", "mysql2", "better-sqlite", "libsql", "turso". You can read more about drizzle.config: https://orm.drizzle.team/kit-docs/config-reference`, ), noCredentials: () => withStyle.error( `Please specify a 'dbCredentials' param in config. It will help drizzle to know how to query you database. You can read more about drizzle.config: https://orm.drizzle.team/kit-docs/config-reference`, ), noDriver: () => withStyle.error( `Please specify a 'driver' param in config. It will help drizzle to know how to query you database. You can read more about drizzle.config: https://orm.drizzle.team/kit-docs/config-reference`, ), noDialect: () => withStyle.error( `Please specify 'dialect' param in config, either of 'postgresql', 'mysql', 'sqlite', turso or singlestore`, ), }, ``` Sources: [drizzle-kit/src/cli/validations/outputs.ts:13-31](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/outputs.ts#L13-L31) > [!WARNING] Using ambiguous parameters—such as supplying both `--config` and explicit conflicting CLI options for commands like `generate`, `introspect`, or `push`—triggers `outputs.common.ambiguousParams(command)` and terminates execution with `process.exit(1)`. Sources: [drizzle-kit/src/cli/validations/common.ts:30-62](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/common.ts#L30-L62), [drizzle-kit/src/cli/validations/outputs.ts:32-38](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/validations/outputs.ts#L32-L38) ## Related - [CLI Command Architecture](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/cli-command-architecture) --- ## Technical docs: Drizzle Zod Integration URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/ecosystem-packages/drizzle-zod-integration
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-zod/src/schema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.ts) - [drizzle-orm/type-tests/mysql/tables.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/tables.ts) - [drizzle-orm/type-tests/pg/tables.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/tables.ts) - [drizzle-valibot/src/schema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/schema.ts) - [drizzle-kit/src/snapshotsDiffer.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/snapshotsDiffer.ts) - [drizzle-kit/src/serializer/pgSchema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/pgSchema.ts) - [drizzle-arktype/src/schema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.ts) - [drizzle-typebox/src/schema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts) - [drizzle-kit/src/serializer/gelSchema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/gelSchema.ts) - [drizzle-zod/src/schema.types.internal.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.types.internal.ts) - [drizzle-kit/src/introspect-pg.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-pg.ts) - [drizzle-kit/src/introspect-gel.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-gel.ts) - [drizzle-valibot/src/column.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/column.ts) - [drizzle-kit/src/introspect-mysql.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-mysql.ts) - [drizzle-zod/src/column.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/column.ts) - [drizzle-zod/src/column.types.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/column.types.ts) - [drizzle-typebox/src/schema.types.internal.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.types.internal.ts) - [drizzle-kit/src/introspect-singlestore.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-singlestore.ts) - [drizzle-kit/src/serializer/sqliteSchema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/sqliteSchema.ts) - [drizzle-valibot/src/schema.types.internal.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/schema.types.internal.ts) - [drizzle-valibot/src/column.types.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/column.types.ts) - [drizzle-kit/src/serializer/mysqlSchema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/mysqlSchema.ts) - [drizzle-arktype/src/schema.types.internal.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.types.internal.ts) - [drizzle-typebox/src/column.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts) - [drizzle-zod/src/schema.types.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.types.ts) - [drizzle-kit/src/serializer/studio.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/studio.ts) - [drizzle-valibot/src/schema.types.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/schema.types.ts) - [drizzle-typebox/src/column.types.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.types.ts) - [drizzle-typebox/src/schema.types.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.types.ts) - [drizzle-arktype/src/schema.types.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.types.ts)
## Overview Drizzle Zod Integration automatically generates modular Zod validation schemas directly from Drizzle ORM table and view definitions, bridging database schema declarations with runtime input validation. By analyzing column types, nullability constraints, default values, and generated identities, the integration produces precise Zod objects tailored for select, insert, and update operations. Custom schema factories allow developers to configure type coercion rules and custom Zod instances across operations. Sources: [drizzle-zod/src/schema.ts:15-123](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.ts#L15-L123), [drizzle-zod/src/schema.types.ts:6-60](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.types.ts#L6-L60) ## Schema Generation Architecture ### Operation Condition Matrix Public generator functions `createSelectSchema`, `createInsertSchema`, and `createUpdateSchema` analyze Drizzle ORM tables, views, and PostgreSQL enums to dynamically construct corresponding Zod validation schemas. The architecture relies on internal condition sets (`selectConditions`, `insertConditions`, and `updateConditions`) that dictate whether individual columns are omitted (`never`), marked optional (`optional`), or flagged as nullable (`nullable`) depending on the database operation. Sources: [drizzle-zod/src/schema.ts:76-120](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.types.ts#L76-L120) | Operation Rule Set | Omitted Columns (`never`) | Optional Columns (`optional`) | Nullable Columns (`nullable`) | | :--- | :--- | :--- | :--- | | `selectConditions` | `() => false` | `() => false` | `!column.notNull` | | `insertConditions` | `generated.type === 'always' \|\| generatedIdentity.type === 'always'` | `!column.notNull \|\| (column.notNull && column.hasDefault)` | `!column.notNull` | | `updateConditions` | `generated.type === 'always' \|\| generatedIdentity.type === 'always'` | `() => true` | `!column.notNull` | Sources: [drizzle-zod/src/schema.ts:76-92](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.ts#L76-L92) ### Column and Entity Processing The core schema builder resolves table and view columns via `getColumns`, which delegates to `getTableColumns` for table definitions and `getViewSelectedFields` for database views. Recursive execution handles nested relation structures and custom field groups. ```typescript function getColumns(tableLike: Table | View) { return isTable(tableLike) ? getTableColumns(tableLike) : getViewSelectedFields(tableLike); } function handleColumns( columns: Record, refinements: Record, conditions: Conditions, factory?: CreateSchemaFactoryOptions< Partial> | true | undefined >, ): z.ZodType { const columnSchemas: Record = {}; for (const [key, selected] of Object.entries(columns)) { if (!is(selected, Column) && !is(selected, SQL) && !is(selected, SQL.Aliased) && typeof selected === 'object') { const columns = isTable(selected) || isView(selected) ? getColumns(selected) : selected; columnSchemas[key] = handleColumns(columns, refinements[key] ?? {}, conditions, factory); continue; } ``` Sources: [drizzle-zod/src/schema.ts:15-34](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.ts#L15-L34) > [!NOTE] > When processing PostgreSQL enums via `createSelectSchema`, the generator bypasses column inspection entirely, resolving directly to `zod.enum(enum_.enumValues)` or using a custom `zodInstance` supplied through `createSchemaFactory`. > Sources: [drizzle-zod/src/schema.ts:66-74](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.ts#L66-L74), [drizzle-zod/src/schema.ts:98-100](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.ts#L98-L100) ### Schema Factory Configuration The `createSchemaFactory` function accepts options containing a custom `zodInstance` or global `coerce` rules, returning scoped instances of `createSelectSchema`, `createInsertSchema`, and `createUpdateSchema` bound to those configurations. ```typescript export function createSchemaFactory< TCoerce extends Partial> | true | undefined, >(options?: CreateSchemaFactoryOptions) { const createSelectSchema: CreateSelectSchema = ( entity: Table | View | PgEnum<[string, ...string[]]>, refine?: Record, ) => { if (isPgEnum(entity)) { return handleEnum(entity, options); } const columns = getColumns(entity); return handleColumns(columns, refine ?? {}, selectConditions, options) as any; }; const createInsertSchema: CreateInsertSchema = ( entity: Table, refine?: Record, ) => { const columns = getColumns(entity); return handleColumns(columns, refine ?? {}, insertConditions, options) as any; }; const createUpdateSchema: CreateUpdateSchema = ( entity: Table, refine?: Record, ) => { const columns = getColumns(entity); return handleColumns(columns, refine ?? {}, updateConditions, options) as any; }; return { createSelectSchema, createInsertSchema, createUpdateSchema }; } ``` Sources: [drizzle-zod/src/schema.ts:121-152](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.ts#L121-L152) > [!WARNING] > Columns defined with `generatedalways` or `generatedIdentity` set to `'always'` evaluate to true under `conditions.never` for both insert and update operations, causing them to be entirely stripped from the resulting Zod object schemas. > Sources: [drizzle-zod/src/schema.ts:83-83](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.ts#L83-L83), [drizzle-zod/src/schema.ts:89-89](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.ts#L89-L89) ## Column Conversion and Dialect Mapping ### Low-Level Column Mapping The `columnToSchema` function inspects individual Drizzle column definitions to produce corresponding Zod type instances. For columns with defined enumerations, it constructs an enum schema using `z.enum(column.enumValues)`, falling back to a standard string schema if the list of values is empty. ```typescript export function columnToSchema( column: Column, factory: | CreateSchemaFactoryOptions< Partial> | true | undefined > | undefined, ): zod.ZodType { const z: typeof zod = factory?.zodInstance ?? zod; const coerce = factory?.coerce ?? {}; let schema!: zod.ZodType; if (isWithEnum(column)) { schema = column.enumValues.length ? z.enum(column.enumValues) : z.string(); } ``` Sources: [drizzle-zod/src/column.ts:70-85](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/column.ts#L70-L85) PostgreSQL geometric, vector, and line types receive specialized structural mapping. Tuple-based representations map to fixed-length Zod tuples, whereas object-based representations map to explicit Zod records with named coordinate keys. ```typescript if (!schema) { // Handle specific types if (isColumnType | PgPointTuple>(column, ['PgGeometry', 'PgPointTuple'])) { schema = z.tuple([z.number(), z.number()]); } else if ( isColumnType | PgGeometryObject>(column, ['PgGeometryObject', 'PgPointObject']) ) { schema = z.object({ x: z.number(), y: z.number() }); } else if (isColumnType | PgVector>(column, ['PgHalfVector', 'PgVector'])) { schema = z.array(z.number()); schema = column.dimensions ? (schema as zod.ZodArray).length(column.dimensions) : schema; } else if (isColumnType>(column, ['PgLine'])) { schema = z.tuple([z.number(), z.number(), z.number()]); } else if (isColumnType>(column, ['PgLineABC'])) { schema = z.object({ a: z.number(), b: z.number(), c: z.number(), }); } // Handle other types ``` Sources: [drizzle-zod/src/column.ts:86-105](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/column.ts#L86-L105) > [!NOTE] > Vector and array columns inspect `column.dimensions` or `column.size` properties to apply exact length validation constraints via Zod array length modifiers. > Sources: [drizzle-zod/src/column.ts:94-96](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/column.ts#L94-L96), [drizzle-zod/src/column.ts:106-108](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/column.ts#L106-L108) ### DataType and Coercion Handling For standard data types, column mapping resolves primitive categories (`number`, `bigint`, `boolean`, `date`, `string`, `json`, `custom`, and `buffer`) and applies optional coercion settings defined via `createSchemaFactory`. ```typescript } else if (column.dataType === 'array') { schema = z.array(z.any()); } else if (column.dataType === 'number') { schema = numberColumnToSchema(column, z, coerce); } else if (column.dataType === 'bigint') { schema = bigintColumnToSchema(column, z, coerce); } else if (column.dataType === 'boolean') { schema = coerce === true || coerce.boolean ? z.coerce.boolean() : z.boolean(); } else if (column.dataType === 'date') { schema = coerce === true || coerce.date ? z.coerce.date() : z.date(); } else if (column.dataType === 'string') { schema = stringColumnToSchema(column, z, coerce); } else if (column.dataType === 'json') { schema = jsonSchema; } else if (column.dataType === 'custom') { schema = z.any(); } else if (column.dataType === 'buffer') { schema = bufferSchema; } } ``` Sources: [drizzle-zod/src/column.ts:109-128](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/column.ts#L109-L128) | Column DataType | Default Zod Mapping | Coercion Rule (`coerce.*` or `true`) | | :--- | :--- | :--- | | `number` | `numberColumnToSchema` | Handled internally by numeric range/integer logic | | `bigint` | `bigintColumnToSchema` | Handled internally by bigint parsing rules | | `boolean` | `z.boolean()` | `z.coerce.boolean()` | | `date` | `z.date()` | `z.coerce.date()` | | `string` | `stringColumnToSchema` | Handled internally by string configuration | | `json` | `jsonSchema` | Unaffected by scalar coercion | | `custom` | `z.any()` | Unaffected by scalar coercion | | `buffer` | `bufferSchema` | Unaffected by scalar coercion | Sources: [drizzle-zod/src/column.ts:111-127](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/column.ts#L111-L127) > [!WARNING] > If a column datatype matches none of the recognized branches and has no associated enum structure, `columnToSchema` defaults the resulting validation target to `z.any()`. > Sources: [drizzle-zod/src/column.ts:130-132](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/column.ts#L130-L132) ### Enum Normalization and SQL Translation PostgreSQL enums processed outside table definitions via `handleEnum` extract enum values directly from `enum_.enumValues` using the active Zod instance. ```typescript function handleEnum( enum_: PgEnum, factory?: CreateSchemaFactoryOptions< Partial> | true | undefined >, ) { const zod: typeof z = factory?.zodInstance ?? z; return zod.enum(enum_.enumValues); } ``` Sources: [drizzle-zod/src/schema.ts:66-74](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.ts#L66-L74) Numeric columns inspect their SQL type definitions through `column.getSQLType()` to detect unsigned flags, establishing strict min and max boundaries corresponding to database integer widths. ```typescript function numberColumnToSchema( column: Column, z: typeof zod, coerce: CreateSchemaFactoryOptions< Partial> | true | undefined >['coerce'], ): zod.ZodType { let unsigned = column.getSQLType().includes('unsigned'); let min!: number; let max!: number; let integer = false; if (isColumnType | SingleStoreTinyInt>(column, ['MySqlTinyInt', 'SingleStoreTinyInt'])) { min = unsigned ? 0 : CONSTANTS.INT8_MIN; max = unsigned ? CONSTANTS.INT8_UNSIGNED_MAX : CONSTANTS.INT8_MAX; integer = true; ``` Sources: [drizzle-zod/src/column.ts:137-152](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/column.ts#L137-L152) ## Type Inference and Internal Constraints ### Compile-Time Schema Types and Utility Helpers The compilation phase orchestrates how database tables, columns, and relations are mapped into strongly-typed Zod object schemas via recursive helper types. The core builder utility `BuildSchema` accepts an operation mode (`'select' | 'insert' | 'update'`), a record of columns, refinement configurations, and coercion rules. It iterates through table keys, applying generated-column filters where generated-always-as columns are restricted to select schemas while remaining present or omitted across other operation types. ```typescript export type BuildSchema< TType extends 'select' | 'insert' | 'update', TColumns extends Record, TRefinements extends Record | undefined, TCoerce extends Partial> | true | undefined, > = z.ZodObject< Simplify< { [ K in keyof TColumns as ColumnIsGeneratedAlwaysAs extends true ? TType extends 'select' ? K : never : K ]: TColumns[K] extends infer TColumn extends Column ? IsRefinementDefined extends true ? Assume, z.ZodType> : HandleColumn : TColumns[K] extends infer TObject extends SelectedFieldsFlat | Table | View ? BuildSchema< TType, GetSelection, TRefinements extends object ? TRefinements[K & keyof TRefinements] : undefined, TCoerce > : z.ZodAny; } >, { out: {}; in: {} } >; ``` Sources: [drizzle-zod/src/schema.types.internal.ts:40-66](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.types.internal.ts#L40-L66) The framework evaluates column nullability and default states through conditional wrapper types like `HandleSelectColumn`, `HandleInsertColumn`, and `HandleUpdateColumn`. Required select fields retain their underlying Zod schema types, whereas nullable columns wrap them in `z.ZodNullable`. Insert and update helpers inject `z.ZodOptional` based on whether columns possess default values or allow null assignment. ```typescript type HandleSelectColumn< TSchema extends z.ZodType, TColumn extends Column, > = TColumn['_']['notNull'] extends true ? TSchema : z.ZodNullable; type HandleInsertColumn< TSchema extends z.ZodType, TColumn extends Column, > = TColumn['_']['notNull'] extends true ? TColumn['_']['hasDefault'] extends true ? z.ZodOptional : TSchema : z.ZodOptional>; type HandleUpdateColumn< TSchema extends z.ZodType, TColumn extends Column, > = TColumn['_']['notNull'] extends true ? z.ZodOptional : z.ZodOptional>; ``` Sources: [drizzle-zod/src/column.types.ts:76-94](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/column.ts#L76-L94) | Operation Mode | Nullable & No Default | Not-Null & Has Default | Not-Null & No Default | | :--- | :--- | :--- | :--- | | `select` | `z.ZodNullable` | `TSchema` | `TSchema` | | `insert` | `z.ZodOptional>` | `z.ZodOptional` | `TSchema` | | `update` | `z.ZodOptional>` | `z.ZodOptional` | `z.ZodOptional` | Sources: [drizzle-zod/src/column.types.ts:76-94](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/column.types.ts#L76-L94) > [!NOTE] > Selection fields supporting nested relations or embedded objects recursively invoke `BuildSchema` against sub-selections derived from `GetSelection`. > Sources: [drizzle-zod/src/schema.types.internal.ts:56-61](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.types.internal.ts#L56-L61) ### Guardrails and DrizzleTypeError Protection To prevent invalid schema configurations at compile time, internal type assertions use `DrizzleTypeError` guardrails. When schema refinements introduce keys that do not exist on the target comparison type, `NoUnknownKeys` intercepts the invalid property and triggers a descriptive compile-time failure. ```typescript export type NoUnknownKeys< TRefinement extends Record, TCompare extends Record, > = { [K in keyof TRefinement]: K extends keyof TCompare ? TRefinement[K] extends Record ? NoUnknownKeys : TRefinement[K] : DrizzleTypeError<`Found unknown key in refinement: "${K & string}"`>; }; ``` Sources: [drizzle-zod/src/schema.types.internal.ts:68-76](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.types.internal.ts#L68-L76) Type coercion validation relies on the `CanCoerce` helper, which checks whether global coercion is enabled (`true`) or if specific primitive flags within the partial coercion record are marked as true for types like `bigint`, `boolean`, `date`, `number`, or `string`. ```typescript type CanCoerce< TCoerce extends Partial> | true | undefined, TTo extends 'bigint' | 'boolean' | 'date' | 'number' | 'string', > = TCoerce extends true ? true : TCoerce extends Record ? TCoerce[TTo] extends true ? true : false : false; ``` Sources: [drizzle-zod/src/column.types.ts:36-42](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/column.ts#L36-L42) > [!WARNING] > Passing unregistered keys inside refinement objects causes `NoUnknownKeys` to evaluate the property against `DrizzleTypeError`, halting compilation with an explicit error message naming the offending key. > Sources: [drizzle-zod/src/schema.types.internal.ts:68-76](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.types.internal.ts#L68-L76) ## Custom Overrides and Refinement Pipelines ### Column Refinements and Direct Replacements The schema generation pipeline accepts an optional refinement record as its second parameter, allowing developers to customize individual column validation rules or completely replace generated Zod types. During schema building in `handleColumns`, the generator checks whether a refinement is defined for a given column key. If the refinement value is provided and is not a function, it directly overrides the column schema. If the refinement is defined as a function, it is invoked with the automatically generated column schema as its argument, enabling chaining or custom validation transformations. ```typescript function handleColumns( columns: Record, refinements: Record, conditions: Conditions, factory?: CreateSchemaFactoryOptions< Partial> | true | undefined >, ): z.ZodType { const columnSchemas: Record = {}; for (const [key, selected] of Object.entries(columns)) { if (!is(selected, Column) && !is(selected, SQL) && !is(selected, SQL.Aliased) && typeof selected === 'object') { const columns = isTable(selected) || isView(selected) ? getColumns(selected) : selected; columnSchemas[key] = handleColumns(columns, refinements[key] ?? {}, conditions, factory); continue; } const refinement = refinements[key]; if (refinement !== undefined && typeof refinement !== 'function') { columnSchemas[key] = refinement; continue; } const column = is(selected, Column) ? selected : undefined; const schema = column ? columnToSchema(column, factory) : z.any(); const refined = typeof refinement === 'function' ? refinement(schema) : schema; ``` Sources: [drizzle-zod/src/schema.ts:19-45](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.ts#L19-L45) ```typescript const userInsertSchema = createInsertSchema(users, { email: (schema) => schema.email(), age: z.number().min(18), }); ``` Sources: [drizzle-zod/src/schema.ts:105-111](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.ts#L105-L111) > [!NOTE] > Refinement functions receive the exact base schema generated by `columnToSchema`, preserving nullability and optional wrapping unless explicitly overridden inside the transform callback. > Sources: [drizzle-zod/src/schema.ts:42-45](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.ts#L42-L45) ### Nested Structures and View Field Selections When processing tables, views, or relational selections, `handleColumns` inspects entry values recursively. If an entry key represents a nested object or view rather than a primitive column or SQL expression, the generator retrieves the underlying column map via `getColumns`—which evaluates `getTableColumns` for tables and `getViewSelectedFields` for database views—and processes the nested record recursively using the matching refinement subsection. ```typescript function getColumns(tableLike: Table | View) { return isTable(tableLike) ? getTableColumns(tableLike) : getViewSelectedFields(tableLike); } function handleColumns( columns: Record, refinements: Record, conditions: Conditions, factory?: CreateSchemaFactoryOptions< Partial> | true | undefined >, ): z.ZodType { const columnSchemas: Record = {}; for (const [key, selected] of Object.entries(columns)) { if (!is(selected, Column) && !is(selected, SQL) && !is(selected, SQL.Aliased) && typeof selected === 'object') { const columns = isTable(selected) || isView(selected) ? getColumns(selected) : selected; columnSchemas[key] = handleColumns(columns, refinements[key] ?? {}, conditions, factory); continue; } ``` Sources: [drizzle-zod/src/schema.ts:15-34](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.ts#L15-L34) Type checking for these nested refinement structures is enforced at compile time through recursive conditional typing. The `BuildRefine` type utility maps over columns and nested relations, validating that any provided refinement matches either a valid Zod type or a transformation function accepting the corresponding column type schema. ```typescript export type BuildRefine< TColumns extends Record, TCoerce extends Partial> | true | undefined, > = { [K in keyof TColumns as TColumns[K] extends Column | SelectedFieldsFlat | Table | View ? K : never]?: TColumns[K] extends Column ? BuildRefineField> : BuildRefine, TCoerce>; }; ``` Sources: [drizzle-zod/src/schema.types.internal.ts:14-21](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.types.internal.ts#L14-L21) > [!WARNING] > Supplying an unknown key inside a nested refinement tree trips the `NoUnknownKeys` helper, halting type compilation with a `DrizzleTypeError` indicating the illegal property name. > Sources: [drizzle-zod/src/schema.types.internal.ts:68-76](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.types.internal.ts#L68-L76) ## Form Handling and Runtime Validation ### Input Mutation Parsing and Mutation Validation Generated Zod schemas integrate into application form handling and API request validation pipelines by defining runtime parsers for database mutations. Using `createInsertSchema` and `createUpdateSchema`, applications validate incoming payloads before executing database operations. The condition rules built into `insertConditions` and `updateConditions` automatically omit database-generated columns—such as columns configured with `always` generation or identity defaults—while enforcing required fields, nullability, and optional defaults for client-supplied payloads. ```typescript const insertConditions: Conditions = { never: (column) => column?.generated?.type === 'always' || column?.generatedIdentity?.type === 'always', optional: (column) => !column.notNull || (column.notNull && column.hasDefault), nullable: (column) => !column.notNull, }; const updateConditions: Conditions = { never: (column) => column?.generated?.type === 'always' || column?.generatedIdentity?.type === 'always', optional: () => true, nullable: (column) => !column.notNull, }; ``` Sources: [drizzle-zod/src/schema.ts:82-93](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.ts#L82-L93) ```typescript const insertUserSchema = createInsertSchema(users); const validatedData = insertUserSchema.parse(requestBody); ``` Sources: [drizzle-zod/src/schema.ts:105-111](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.ts#L105-L111) > [!CAUTION] > Columns defined with `generatedAlwaysAs` or `always` identity are completely excluded from insert and update schemas via `conditions.never`, causing Zod to strip these fields if submitted in client mutation payloads. > Sources: [drizzle-zod/src/schema.ts:83-89](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.ts#L83-L89) ### Query Result and View Validation For read operations and user interface rendering, `createSelectSchema` generates runtime validation contracts that reflect exact table structures and database views. Unlike insertion handlers, select schemas evaluate columns against `selectConditions`, preserving all table fields while mapping nullable database columns to Zod nullable wrappers without marking them optional. This ensures API responses and UI form initializers match the exact shape queried from the database. ```typescript const selectConditions: Conditions = { never: () => false, optional: () => false, nullable: (column) => !column.notNull, }; ``` Sources: [drizzle-zod/src/schema.ts:76-80](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.ts#L76-L80) ```typescript const selectUserSchema = createSelectSchema(users); const userProfile = selectUserSchema.parse(dbRecord); ``` Sources: [drizzle-zod/src/schema.ts:94-103](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.ts#L94-L103) > [!NOTE] > When passed a database view or an enumerated type directly, `createSelectSchema` resolves view selected fields via `getViewSelectedFields` or builds a Zod enum parser from `enumValues`. > Sources: [drizzle-zod/src/schema.ts:15-17](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.ts#L15-L17), [drizzle-zod/src/schema.ts:98-100](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.ts#L98-L100) ## Related - [Table and Column Models](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/table-and-column-models) - [Drizzle TypeBox Integration](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/ecosystem-packages/drizzle-typebox-integration) - [Drizzle Valibot Integration](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/ecosystem-packages/drizzle-valibot-integration) --- ## Technical docs: Drizzle TypeBox Integration URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/ecosystem-packages/drizzle-typebox-integration
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-typebox/src/column.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts) - [drizzle-orm/type-tests/mysql/tables.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/tables.ts) - [drizzle-valibot/src/column.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/column.ts) - [drizzle-arktype/src/column.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/column.ts) - [drizzle-kit/src/introspect-pg.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-pg.ts) - [drizzle-valibot/src/column.types.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/column.types.ts) - [drizzle-orm/type-tests/singlestore/tables.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/tables.ts) - [drizzle-kit/src/introspect-mysql.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-mysql.ts) - [drizzle-kit/src/introspect-singlestore.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-singlestore.ts) - [drizzle-zod/src/column.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/column.ts) - [drizzle-kit/src/serializer/gelSchema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/gelSchema.ts) - [drizzle-typebox/src/column.types.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.types.ts) - [drizzle-typebox/src/schema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts) - [drizzle-valibot/src/schema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/schema.ts) - [drizzle-typebox/src/utils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/utils.ts) - [drizzle-zod/src/column.types.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/column.types.ts) - [drizzle-kit/src/serializer/pgSchema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/pgSchema.ts) - [drizzle-typebox/src/schema.types.internal.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.types.internal.ts) - [drizzle-kit/src/serializer/mysqlSchema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/mysqlSchema.ts) - [drizzle-orm/src/singlestore-core/columns/text.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/columns/text.ts) - [drizzle-valibot/src/utils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/utils.ts) - [drizzle-orm/src/sqlite-core/columns/text.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/sqlite-core/columns/text.ts) - [drizzle-zod/src/utils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/utils.ts) - [drizzle-valibot/src/schema.types.internal.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/schema.types.internal.ts) - [drizzle-arktype/src/schema.types.internal.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.types.internal.ts) - [drizzle-zod/src/schema.types.internal.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.types.internal.ts) - [drizzle-arktype/src/column.types.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/column.types.ts) - [drizzle-typebox/src/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/index.ts)
## Overview Drizzle TypeBox Integration automates the creation of runtime validation schemas directly from Drizzle ORM table and view definitions using the TypeBox library. By translating database columns, nullability constraints, defaults, and relational structures into TypeBox schemas, it eliminates boilerplate schema duplication and maintains synchronization between database models and application validation. The package provides generators such as `createSelectSchema`, `createInsertSchema`, and `createUpdateSchema`, along with customizable schema factories that handle operation-specific column optionality and database-specific types [drizzle-typebox/src/schema.ts:88-143](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts#L88-L143). Static type inference resolves TypeScript types from the generated TypeBox schemas, supporting advanced column types, enums, and custom refinements [drizzle-typebox/src/column.types.ts:12-58](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.types.ts#L12-L58), [drizzle-typebox/src/schema.types.internal.ts:39-60](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.types.internal.ts#L39-L60). ## Public Package API Surface ### Top-Level Exports and Generators The `drizzle-typebox` package exposes its primary functionality through modular entry points and re-exports from core source files [drizzle-typebox/src/index.ts:1-6](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/index.ts#L1-L6). Top-level schema generators include `createSelectSchema`, `createInsertSchema`, and `createUpdateSchema`, which construct TypeBox validation schemas from database entities such as tables, views, and PostgreSQL enums [drizzle-typebox/src/schema.ts:88-113](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts#L88-L113). Additionally, the factory helper `createSchemaFactory` allows developers to supply custom TypeBox instances for schema generation [drizzle-typebox/src/schema.ts:115-143](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts#L115-L143). ```typescript export function createSchemaFactory(options?: CreateSchemaFactoryOptions) { const createSelectSchema: CreateSelectSchema = ( entity: Table | View | PgEnum<[string, ...string[]]>, refine?: Record, ) => { if (isPgEnum(entity)) { return handleEnum(entity, options); } const columns = getColumns(entity); return handleColumns(columns, refine ?? {}, selectConditions, options) as any; }; const createInsertSchema: CreateInsertSchema = ( entity: Table, refine?: Record, ) => { const columns = getColumns(entity); return handleColumns(columns, refine ?? {}, insertConditions, options) as any; }; const createUpdateSchema: CreateUpdateSchema = ( entity: Table, refine?: Record, ) => { const columns = getColumns(entity); return handleColumns(columns, refine ?? {}, updateConditions, options) as any; }; return { createSelectSchema, createInsertSchema, createUpdateSchema }; ``` Sources: [drizzle-typebox/src/schema.ts:115-143](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts#L115-L143) ### Custom TypeBox Types and Helpers The package defines specialized custom schemas and utility helpers to handle non-standard database types that do not map directly to standard TypeBox primitives [drizzle-typebox/src/column.ts:62-65](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L62-L65). This includes `literalSchema`, `jsonSchema`, `bufferSchema`, and enum mapping functions [drizzle-typebox/src/column.ts:62-69](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L62-L69). A custom type registry entry for `'Buffer'` validates binary instances at runtime [drizzle-typebox/src/column.ts:64-65](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L64-L65). | Export Name | Origin File | Description | | :--- | :--- | :--- | | `createSelectSchema` | `drizzle-typebox/src/schema.ts` | Generates a select validation schema for tables, views, or enums [drizzle-typebox/src/schema.ts:88-97](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts#L88-L97). | | `createInsertSchema` | `drizzle-typebox/src/schema.ts` | Generates an insert validation schema handling defaults and generated columns [drizzle-typebox/src/schema.ts:99-105](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts#L99-L105). | | `createUpdateSchema` | `drizzle-typebox/src/schema.ts` | Generates an update validation schema making fields optional [drizzle-typebox/src/schema.ts:107-113](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts#L107-L113). | | `createSchemaFactory` | `drizzle-typebox/src/schema.ts` | Factory function accepting custom TypeBox instance options [drizzle-typebox/src/schema.ts:115-143](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts#L115-L143). | | `literalSchema` | `drizzle-typebox/src/column.ts` | Union schema matching string, number, boolean, or null values [drizzle-typebox/src/column.ts:62](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L62). | | `jsonSchema` | `drizzle-typebox/src/column.ts` | Union schema covering literals, arrays, and string-keyed records [drizzle-typebox/src/column.ts:63](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L63). | | `bufferSchema` | `drizzle-typebox/src/column.ts` | Custom TypeBox schema definition configured via `TypeRegistry` for `Buffer` [drizzle-typebox/src/column.ts:64-65](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L64-L65). | | `mapEnumValues` | `drizzle-typebox/src/column.ts` | Transforms an array of string values into an object record mapping keys to values [drizzle-typebox/src/column.ts:67-69](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L67-L69). | Sources: [drizzle-typebox/src/column.ts:62-69](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L62-L69), [drizzle-typebox/src/schema.ts:88-143](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts#L88-L143) > [!NOTE] > The `bufferSchema` registers a custom `Buffer` check against `TypeRegistry` at module initialization time, requiring consumers to import `drizzle-typebox` so that TypeBox evaluates binary buffer instances correctly during validation [drizzle-typebox/src/column.ts:64-65](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L64-L65). Sources: [drizzle-typebox/src/column.ts:64-65](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L64-L65) ## Column Type Translation to TypeBox ### Core Translation Logic The translation process inspects individual database columns and maps them to appropriate TypeBox validation schemas using `columnToSchema` [drizzle-typebox/src/column.ts:71-141](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L71-L141). Columns containing predefined enums are processed first, generating a TypeBox enum schema via `mapEnumValues` if enum values exist, or falling back to a standard string schema [drizzle-typebox/src/column.ts:74-76](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L74-L76). ```typescript export function columnToSchema(column: Column, t: typeof typebox): TSchema { let schema!: TSchema; if (isWithEnum(column)) { schema = column.enumValues.length ? t.Enum(mapEnumValues(column.enumValues)) : t.String(); } ``` Sources: [drizzle-typebox/src/column.ts:71-77](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L71-L77) If the column is not an enum, the translation checks specific column types and general data types. Specialized geometric and vector types from PostgreSQL are mapped directly to tuples, objects, or arrays with dimension constraints [drizzle-typebox/src/column.ts:80-103](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L80-L103). For instance, `PgGeometry` and `PgPointTuple` columns translate to a two-element number tuple, while `PgHalfVector` and `PgVector` translate to number arrays constrained by column dimensions [drizzle-typebox/src/column.ts:80-95](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L80-L95). ```typescript if (isColumnType | PgPointTuple>(column, ['PgGeometry', 'PgPointTuple'])) { schema = t.Tuple([t.Number(), t.Number()]); } else if ( isColumnType | PgGeometryObject>(column, ['PgGeometryObject', 'PgPointObject']) ) { schema = t.Object({ x: t.Number(), y: t.Number() }); } else if (isColumnType | PgVector>(column, ['PgHalfVector', 'PgVector'])) { schema = t.Array( t.Number(), column.dimensions ? { minItems: column.dimensions, maxItems: column.dimensions, } : undefined, ); ``` Sources: [drizzle-typebox/src/column.ts:80-95](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L80-L95) ### Primitive and General Data Types When a column does not match specialized geometry or vector types, translation falls back to general `column.dataType` properties or specific numeric boundaries [drizzle-typebox/src/column.ts:115-133](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L115-L133). PostgreSQL array columns preserve base column definitions and size constraints recursively, whereas generic array types default to an array of any values [drizzle-typebox/src/column.ts:105-116](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L105-L116). | Data Type | Target TypeBox Schema | Source Reference | | :--- | :--- | :--- | | `array` (PgArray) | `t.Array(columnToSchema(baseColumn), { minItems, maxItems })` | [drizzle-typebox/src/column.ts:105-114](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L105-L114) | | `array` (Generic) | `t.Array(t.Any())` | [drizzle-typebox/src/column.ts:115-116](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L115-L116) | | `number` | `numberColumnToSchema(column, t)` | [drizzle-typebox/src/column.ts:117-118](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L117-L118) | | `bigint` | `bigintColumnToSchema(column, t)` | [drizzle-typebox/src/column.ts:119-120](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L119-L120) | | `boolean` | `t.Boolean()` | [drizzle-typebox/src/column.ts:121-122](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L121-L122) | | `date` | `t.Date()` | [drizzle-typebox/src/column.ts:123-124](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L123-L124) | | `string` | `stringColumnToSchema(column, t)` | [drizzle-typebox/src/column.ts:125-126](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L125-L126) | | `json` | `jsonSchema` | [drizzle-typebox/src/column.ts:127-128](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L127-L128) | | `custom` | `t.Any()` | [drizzle-typebox/src/column.ts:129-130](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L129-L130) | | `buffer` | `bufferSchema` | [drizzle-typebox/src/column.ts:131-132](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L131-L132) | Sources: [drizzle-typebox/src/column.ts:105-133](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L105-L133) > [!WARNING] > Unrecognized column types that fail to match any explicit conditional branch default to `t.Any()` as a final fallback, bypassing strict runtime property validation for those specific fields [drizzle-typebox/src/column.ts:136-138](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L136-L138). Sources: [drizzle-typebox/src/column.ts:136-138](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L136-L138) ## Table and View Schema Generation ### Extracting and Handling Fields Schema generation begins by evaluating whether the input entity is a Drizzle table or view. The `getColumns` helper function inspects the entity, calling `getTableColumns` if it is a table or `getViewSelectedFields` if it is a view [drizzle-typebox/src/schema.ts:16-18](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts#L16-L18). ```typescript export function getColumns(tableLike: Table | View) { return isTable(tableLike) ? getTableColumns(tableLike) : getViewSelectedFields(tableLike); } ``` Sources: [drizzle-typebox/src/schema.ts:16-18](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts#L16-L18) Once individual field definitions are acquired, `handleColumns` iterates over the record entries, recursively processing nested relations or resolving columns against active factory conditions [drizzle-typebox/src/schema.ts:28-60](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts#L28-L60). If a selected entry is an object rather than a column or SQL expression, it retrieves child columns and recursively invokes `handleColumns` [drizzle-typebox/src/schema.ts:29-33](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts#L29-L33). ```typescript for (const [key, selected] of Object.entries(columns)) { if (!is(selected, Column) && !is(selected, SQL) && !is(selected, SQL.Aliased) && typeof selected === 'object') { const columns = isTable(selected) || isView(selected) ? getColumns(selected) : selected; columnSchemas[key] = handleColumns(columns, refinements[key] ?? {}, conditions, factory); continue; } ``` Sources: [drizzle-typebox/src/schema.ts:28-33](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts#L28-L33) ### Schema Conditions and Operations Different database operations impose distinct requirements on whether fields must be optional, nullable, or omitted entirely. These rules are governed by three internal condition sets: `selectConditions`, `insertConditions`, and `updateConditions` [drizzle-typebox/src/schema.ts:70-86](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts#L70-L86). | Condition Set | Never Omit Rule (`never`) | Optional Rule (`optional`) | Nullable Rule (`nullable`) | Source Reference | | :--- | :--- | :--- | :--- | :--- | | `selectConditions` | `() => false` | `() => false` | `(column) => !column.notNull` | [drizzle-typebox/src/schema.ts:70-74](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts#L70-L74) | | `insertConditions` | Generated always columns (`always`) | Not null or has default | `(column) => !column.notNull` | [drizzle-typebox/src/schema.ts:76-80](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts#L76-L80) | | `updateConditions` | Generated always columns (`always`) | `() => true` | `(column) => !column.notNull` | [drizzle-typebox/src/schema.ts:82-86](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts#L82-L86) | Sources: [drizzle-typebox/src/schema.ts:70-86](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts#L70-L86) > [!NOTE] > Columns defined with `generated always as` or `generatedIdentity` of type `'always'` are strictly filtered out during insert and update schema generation via the `never` condition check [drizzle-typebox/src/schema.ts:77-83](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts#L77-L83). Sources: [drizzle-typebox/src/schema.ts:77-83](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts#L77-L83) ### Factory Functions and Enums The public generators `createSelectSchema`, `createInsertSchema`, and `createUpdateSchema` orchestrate these condition sets against database tables, views, or PostgreSQL enums [drizzle-typebox/src/schema.ts:88-113](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts#L88-L113). When evaluating a PostgreSQL enum via `createSelectSchema`, the utility delegates directly to `handleEnum`, mapping enum values using the provided or default TypeBox instance [drizzle-typebox/src/schema.ts:65-68](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts#L65-L68), [drizzle-typebox/src/schema.ts:92-94](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts#L92-L94). Custom TypeBox instances and shared options can also be bundled by invoking `createSchemaFactory`, which returns bound generator functions sharing the same configuration context [drizzle-typebox/src/schema.ts:115-144](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts#L115-L144). ```typescript export function createSchemaFactory(options?: CreateSchemaFactoryOptions) { const createSelectSchema: CreateSelectSchema = ( entity: Table | View | PgEnum<[string, ...string[]]>, refine?: Record, ) => { if (isPgEnum(entity)) { return handleEnum(entity, options); } const columns = getColumns(entity); return handleColumns(columns, refine ?? {}, selectConditions, options) as any; }; ``` Sources: [drizzle-typebox/src/schema.ts:115-125](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts#L115-L125) ## Static Type Inference Mechanics ### Schema Construction and Operations Type-level transformations handle the translation of Drizzle table definitions and column properties into valid TypeBox object schemas using `BuildSchema` [drizzle-typebox/src/schema.types.internal.ts:39-59](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.types.internal.ts#L39-L59). This utility iterates over record entries, filtering out columns where `ColumnIsGeneratedAlwaysAs` evaluates to true [drizzle-typebox/src/schema.types.internal.ts:46](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.types.internal.ts#L46). Depending on the operation mode (`select`, `insert`, or `update`), columns are wrapped or modified using helper handlers [drizzle-typebox/src/column.types.ts:85-91](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.types.ts#L85-L91). | Operation Type | Nullability Handling (`notNull`) | Default Value Handling (`hasDefault`) | Optionality Rule | Source Reference | | :--- | :--- | :--- | :--- | :--- | | `select` | `!notNull` adds `t.TNull` union | None | Never optional | [drizzle-typebox/src/column.types.ts:66-70](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.types.ts#L66-L70) | | `insert` | `!notNull` adds `t.TNull` union | `hasDefault` wraps in `t.TOptional` | Optional if nullable or has default | [drizzle-typebox/src/column.types.ts:72-77](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.types.ts#L72-L77) | | `update` | `!notNull` adds `t.TNull` union | Always wraps in `t.TOptional` | Always optional | [drizzle-typebox/src/column.types.ts:79-83](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.types.ts#L79-L83) | Sources: [drizzle-typebox/src/column.types.ts:66-83](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.types.ts#L66-L83) > [!NOTE] > During insert operations, columns marked as `notNull` without a default value remain required, whereas nullable columns and columns with defaults are wrapped in `t.TOptional` [drizzle-typebox/src/column.types.ts:72-77](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.types.ts#L72-L77). Sources: [drizzle-typebox/src/column.types.ts:72-77](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.types.ts#L72-L77) ### Refinements and Key Validation Refinements allow overriding or transforming generated column schemas [drizzle-typebox/src/schema.types.internal.ts:14-20](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.types.internal.ts#L14-L20). The `HandleRefinement` type checks whether a refinement function is provided, applies it to the underlying column schema, appends nullability if the column is nullable, and wraps the result in an optional modifier when processing update schemas [drizzle-typebox/src/schema.types.internal.ts:22-30](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.types.internal.ts#L22-L30). Sources: [drizzle-typebox/src/schema.types.internal.ts:22-30](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.types.internal.ts#L22-L30) To maintain type safety when refining schemas, `NoUnknownKeys` inspects refinement keys against comparison schemas [drizzle-typebox/src/schema.types.internal.ts:61-69](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.types.internal.ts#L61-L69). If an unknown key is detected in the refinement object, it returns a `DrizzleTypeError` [drizzle-typebox/src/schema.types.internal.ts:68](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.types.internal.ts#L68). Sources: [drizzle-typebox/src/schema.types.internal.ts:61-69](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.types.internal.ts#L61-L69) > [!WARNING] > Supplying an unrecognized column name inside a refinement object triggers a static `DrizzleTypeError` via `NoUnknownKeys`, halting compilation before invalid schemas can be constructed [drizzle-typebox/src/schema.types.internal.ts:61-69](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.types.internal.ts#L61-L69). Sources: [drizzle-typebox/src/schema.types.internal.ts:61-69](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.types.internal.ts#L61-L69) ## Custom Type Extensions and Overrides Generated schemas can be tailored using specialized helper structures and built-in type bindings designed for binary and structured data. For complex objects, JSON helper schemas unite literal values, arrays, and record structures into a single validating union [drizzle-typebox/src/column.ts:62-63](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L62-L63). ```typescript export const literalSchema = t.Union([t.String(), t.Number(), t.Boolean(), t.Null()]); export const jsonSchema: JsonSchema = t.Union([literalSchema, t.Array(t.Any()), t.Record(t.String(), t.Any())]) as any; ``` Sources: [drizzle-typebox/src/column.ts:62-63](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L62-L63) Binary buffer handling relies on custom registry registration using TypeBox's extension API. The runtime type registry evaluates buffer columns by verifying runtime `Buffer` instances [drizzle-typebox/src/column.ts:64-65](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L64-L65). ```typescript TypeRegistry.Set('Buffer', (_, value) => value instanceof Buffer); // eslint-disable-line no-instanceof/no-instanceof export const bufferSchema: BufferSchema = { [Kind]: 'Buffer', type: 'buffer' } as any; ``` Sources: [drizzle-typebox/src/column.ts:64-65](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L64-L65) > [!TIP] > Custom buffer column translation depends on registering the custom keyword `'Buffer'` with `TypeRegistry.Set`, ensuring TypeBox can correctly serialize and validate Node.js Buffer instances [drizzle-typebox/src/column.ts:64-65](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L64-L65). Sources: [drizzle-typebox/src/column.ts:64-65](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts#L64-L65) ## Related - [Drizzle Zod Integration](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/ecosystem-packages/drizzle-zod-integration) - [Table and Column Models](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/table-and-column-models) --- ## Technical docs: Drizzle Valibot Integration URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/ecosystem-packages/drizzle-valibot-integration
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-valibot/src/column.types.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/column.types.ts) - [drizzle-orm/type-tests/mysql/tables.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/tables.ts) - [drizzle-valibot/src/column.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/column.ts) - [drizzle-orm/type-tests/singlestore/tables.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/tables.ts) - [drizzle-kit/src/snapshotsDiffer.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/snapshotsDiffer.ts) - [drizzle-valibot/src/schema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/schema.ts) - [drizzle-kit/src/serializer/gelSchema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/gelSchema.ts) - [drizzle-kit/src/serializer/pgSchema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/pgSchema.ts) - [drizzle-kit/src/introspect-pg.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-pg.ts) - [drizzle-orm/type-tests/mysql/1000columns.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/1000columns.ts) - [drizzle-kit/src/introspect-mysql.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-mysql.ts) - [drizzle-kit/src/introspect-gel.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-gel.ts) - [drizzle-typebox/src/schema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.ts) - [drizzle-valibot/src/schema.types.internal.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/schema.types.internal.ts) - [drizzle-kit/src/serializer/mysqlSchema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/mysqlSchema.ts) - [drizzle-kit/src/introspect-singlestore.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-singlestore.ts) - [drizzle-zod/src/schema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/src/schema.ts) - [drizzle-valibot/src/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/index.ts) - [drizzle-typebox/src/column.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts) - [drizzle-seed/src/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts) - [drizzle-kit/src/serializer/studio.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/studio.ts) - [drizzle-kit/src/serializer/sqliteSchema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/sqliteSchema.ts) - [drizzle-valibot/package.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/package.json) - [drizzle-kit/src/serializer/singlestoreSchema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/singlestoreSchema.ts) - [drizzle-valibot/src/utils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/utils.ts) - [drizzle-kit/src/serializer/singlestoreSerializer.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/singlestoreSerializer.ts) - [drizzle-kit/src/schemaValidator.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/schemaValidator.ts) - [drizzle-typebox/src/schema.types.internal.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.types.internal.ts)
## Overview Drizzle Valibot Integration translates Drizzle ORM table definitions, database views, and column specifications into corresponding Valibot runtime validation schemas. It provides factory functions such as `createSelectSchema`, `createInsertSchema`, and `createUpdateSchema` that inspect column nullability, default values, and generation rules to build precise object schemas for querying, inserting, and updating data. Sources: [drizzle-valibot/src/schema.ts:58-94](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/schema.ts#L58-L94) The integration handles column mapping across various SQL dialects, converting primitive types, arrays, JSON objects, enums, and custom types into their Valibot validator equivalents with proper type safety and constraints. Sources: [drizzle-valibot/src/column.ts:73-126](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/column.ts#L73-L126), [drizzle-valibot/src/column.types.ts:42-88](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/column.types.ts#L42-L88) Developers can also supply custom refinements to override or extend individual field validators while maintaining compile-time type inference across operations. Sources: [drizzle-valibot/src/schema.ts:28-36](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/schema.ts#L28-L36), [drizzle-valibot/src/schema.types.internal.ts:14-29](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/schema.types.internal.ts#L14-L29) ## Public API surface ### Entry-Point Exports and Module Structure The `drizzle-valibot` package exposes its public API through a main entry point defined in `drizzle-valibot/src/index.ts`. The primary exports include explicit column utility schemas (`bufferSchema`, `jsonSchema`, `literalSchema`) alongside star exports for column types, schema factories, internal schema types, and general utility functions. ```typescript export { bufferSchema, jsonSchema, literalSchema } from './column.ts'; export * from './column.types.ts'; export * from './schema.ts'; export * from './schema.types.internal.ts'; export * from './schema.types.ts'; export * from './utils.ts'; ``` Sources: [drizzle-valibot/src/index.ts:1-6](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/index.ts#L1-L6) > [!NOTE] > The entry-point exports are bundled to support both ESM and CommonJS module resolution paths via conditional exports in package configuration. ### Package Configuration and Exports Map The module distribution is governed by `drizzle-valibot/package.json`, which specifies dual CJS and ESM output paths, type definitions, peer dependencies on `drizzle-orm` (`>=0.36.0`) and `valibot` (`>=1.0.0-beta.7`), and provenance publishing configuration. | Field | Target / Value | Purpose | | :--- | :--- | :--- | | `main` | `./index.cjs` | CommonJS entry point | | `module` | `./index.mjs` | ECMAScript module entry point | | `types` | `./index.d.ts` | TypeScript type definitions | | `peerDependencies` | `drizzle-orm`, `valibot` | Required host library versions | | `publishConfig` | `provenance: true` | Cryptographic provenance for npm publishing | Sources: [drizzle-valibot/package.json:14-33](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/package.json#L14-L33) ## Schema generation architecture ### Entity Dispatch and Column Resolution The runtime schema generation process begins by resolving the input entity—whether a table, view, or PostgreSQL enum—into its constituent column definitions or selected fields. The helper function `getColumns` inspects the entity using `isTable`, returning columns via `getTableColumns` if it represents a table or `getViewSelectedFields` if it represents a view. For PostgreSQL enums identified via `isPgEnum`, `createSelectSchema` bypasses column iteration entirely, mapping the enum's string values directly to a Valibot enum validator using `mapEnumValues`. ```typescript function getColumns(tableLike: Table | View) { return isTable(tableLike) ? getTableColumns(tableLike) : getViewSelectedFields(tableLike); } ``` Sources: [drizzle-valibot/src/schema.ts:10-12](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/schema.ts#L10-L12) ```typescript export const createSelectSchema: CreateSelectSchema = ( entity: Table | View | PgEnum<[string, ...string[]]>, refine?: Record, ) => { if (isPgEnum(entity)) { return v.enum(mapEnumValues(entity.enumValues)); } const columns = getColumns(entity); return handleColumns(columns, refine ?? {}, { never: () => false, optional: () => false, nullable: (column) => !column.notNull, }) as any; }; ``` Sources: [drizzle-valibot/src/schema.ts:58-71](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/schema.ts#L58-L71) ### Operation-Specific Condition Strategies The core schema builder function `handleColumns` iterates over column records while accepting a `Conditions` interface that dictates how individual column properties translate into Valibot wrappers for select, insert, and update operations. Each factory injects a specific condition strategy: | Factory Function | `never` Condition | `optional` Condition | `nullable` Condition | | :--- | :--- | :--- | :--- | | `createSelectSchema` | `() => false` | `() => false` | `(column) => !column.notNull` | | `createInsertSchema` | `(column) => column?.generated?.type === 'always' || column?.generatedIdentity?.type === 'always'` | `(column) => !column.notNull || (column.notNull && column.hasDefault)` | `(column) => !column.notNull` | | `createUpdateSchema` | `(column) => column?.generated?.type === 'always' || column?.generatedIdentity?.type === 'always'` | `() => true` | `(column) => !column.notNull` | Sources: [drizzle-valibot/src/schema.ts:66-70](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/schema.ts#L66-L70), [drizzle-valibot/src/schema.ts:78-82](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/schema.ts#L78-L82), [drizzle-valibot/src/schema.ts:90-94](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/schema.ts#L90-L94) > [!NOTE] > Columns with database-generated values (`generated?.type === 'always'` or `generatedIdentity?.type === 'always'`) return true for the `never` condition during insert and update operations, causing them to be entirely omitted from the resulting Valibot object schema. ```typescript export const createInsertSchema: CreateInsertSchema = ( entity: Table, refine?: Record, ) => { const columns = getColumns(entity); return handleColumns(columns, refine ?? {}, { never: (column) => column?.generated?.type === 'always' || column?.generatedIdentity?.type === 'always', optional: (column) => !column.notNull || (column.notNull && column.hasDefault), nullable: (column) => !column.notNull, }) as any; }; ``` Sources: [drizzle-valibot/src/schema.ts:73-83](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/schema.ts#L73-L83) ```typescript export const createUpdateSchema: CreateUpdateSchema = ( entity: Table, refine?: Record, ) => { const columns = getColumns(entity); return handleColumns(columns, refine ?? {}, { never: (column) => column?.generated?.type === 'always' || column?.generatedIdentity?.type === 'always', optional: () => true, nullable: (column) => !column.notNull, }) as any; }; ``` Sources: [drizzle-valibot/src/schema.ts:85-95](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/schema.ts#L85-L95) ### Recursive Handling of Nested Relations and Refinements When `handleColumns` encounters nested object properties, aliased SQL expressions, or relational selections rather than raw column instances, it recursively evaluates sub-schemas. If a static refinement value is provided for a key, it bypasses column conversion and assigns the replacement schema directly. Otherwise, it generates the base schema via `columnToSchema`, applies any functional refinement, evaluates exclusion via `conditions.never`, and wraps the resulting validator with `v.nullable` or `v.optional` based on the active condition strategy. ```typescript function handleColumns( columns: Record, refinements: Record, conditions: Conditions, ): v.GenericSchema { const columnSchemas: Record = {}; for (const [key, selected] of Object.entries(columns)) { if (!is(selected, Column) && !is(selected, SQL) && !is(selected, SQL.Aliased) && typeof selected === 'object') { const columns = isTable(selected) || isView(selected) ? getColumns(selected) : selected; columnSchemas[key] = handleColumns(columns, refinements[key] ?? {}, conditions); continue; } const refinement = refinements[key]; if (refinement !== undefined && typeof refinement !== 'function') { columnSchemas[key] = refinement; continue; } const column = is(selected, Column) ? selected : undefined; const schema = column ? columnToSchema(column) : v.any(); const refined = typeof refinement === 'function' ? refinement(schema) : schema; if (conditions.never(column)) { continue; } else { columnSchemas[key] = refined; } if (column) { if (conditions.nullable(column)) { columnSchemas[key] = v.nullable(columnSchemas[key]!); } if (conditions.optional(column)) { columnSchemas[key] = v.optional(columnSchemas[key]!); } } } return v.object(columnSchemas) as any; } ``` Sources: [drizzle-valibot/src/schema.ts:14-56](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/schema.ts#L14-L56) ## Column mapping engine ### Enum and Geometric Type Dispatch The column mapping engine translates individual Drizzle column definitions into Valibot primitive and structured validators by examining column properties and type metadata. The primary entry point function `columnToSchema` first checks whether a column possesses an enumeration configuration via `isWithEnum`. If enumeration values are present, it transforms them using `mapEnumValues` into a Valibot enum validator, falling back to a standard string validator if the enumeration is empty. ```typescript export function columnToSchema(column: Column): v.GenericSchema { let schema!: v.GenericSchema; if (isWithEnum(column)) { schema = column.enumValues.length ? v.enum(mapEnumValues(column.enumValues)) : v.string(); } ``` Sources: [drizzle-valibot/src/column.ts:73-78](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/column.ts#L73-L78) For columns lacking enums, `columnToSchema` dispatches specialized PostgreSQL geometric and vector types by matching their internal column type identifiers through `isColumnType`. Geometric pairs like point tuples and geometries are mapped to a two-element number tuple, while point and geometry objects map to an `x` and `y` coordinate object. Vector types map to a number array, adding a Valibot length pipe validator if explicit dimensions are defined. | Column Type Matcher | Identifiers Checked | Generated Valibot Schema Structure | | :--- | :--- | :--- | | `PgGeometry` / `PgPointTuple` | `['PgGeometry', 'PgPointTuple']` | `v.tuple([v.number(), v.number()])` | | `PgGeometryObject` / `PgPointObject` | `['PgGeometryObject', 'PgPointObject']` | `v.object({ x: v.number(), y: v.number() })` | | `PgHalfVector` / `PgVector` | `['PgHalfVector', 'PgVector']` | `v.array(v.number())` (with optional length pipe) | | `PgLine` (Tuple) | `['PgLine']` | `v.tuple([v.number(), v.number(), v.number()])` | | `PgLineABC` (Object) | `['PgLineABC']` | `v.object({ a: v.number(), b: v.number(), c: v.number() })` | Sources: [drizzle-valibot/src/column.ts:82-95](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/column.ts#L82-L95) > [!NOTE] > Vector and array column generators inspect `column.dimensions` or `column.size` properties respectively, attaching a Valibot length validation constraint dynamically if a fixed size constraint is set on the Drizzle column builder. ```typescript } else if (isColumnType | PgVector>(column, ['PgHalfVector', 'PgVector'])) { schema = v.array(v.number()); schema = column.dimensions ? v.pipe(schema as v.ArraySchema, v.length(column.dimensions)) : schema; ``` Sources: [drizzle-valibot/src/column.ts:88-90](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/column.ts#L88-L90) ### Scalar and Composite Data Type Mapping When handling standard data categories, the mapping engine inspects `column.dataType` to route execution to appropriate helper functions or primitive constructors. Array columns recursively map their base column definition or fall back to an unconstrained `v.any()` array if untyped. Numerical, bigint, and string columns delegate to dedicated conversion functions that parse SQL type options, while boolean, date, json, custom, and buffer types map directly to their Valibot equivalents using shared constants like `jsonSchema` and `bufferSchema`. ```typescript else if (isColumnType>(column, ['PgArray'])) { schema = v.array(columnToSchema(column.baseColumn)); schema = column.size ? v.pipe(schema as v.ArraySchema, v.length(column.size)) : schema; } else if (column.dataType === 'array') { schema = v.array(v.any()); } else if (column.dataType === 'number') { schema = numberColumnToSchema(column); } else if (column.dataType === 'bigint') { schema = bigintColumnToSchema(column); } else if (column.dataType === 'boolean') { schema = v.boolean(); } else if (column.dataType === 'date') { schema = v.date(); } else if (column.dataType === 'string') { schema = stringColumnToSchema(column); } else if (column.dataType === 'json') { schema = jsonSchema; } else if (column.dataType === 'custom') { schema = v.any(); } else if (column.dataType === 'buffer') { schema = bufferSchema; } ``` Sources: [drizzle-valibot/src/column.ts:97-118](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/column.ts#L97-L118) ```typescript export const literalSchema = v.union([v.string(), v.number(), v.boolean(), v.null()]); export const jsonSchema: v.GenericSchema = v.union([ literalSchema, v.array(v.any()), v.record(v.string(), v.any()), ]); export const bufferSchema: v.GenericSchema = v.custom((v) => v instanceof Buffer); // eslint-disable-line no-instanceof/no-instanceof ``` Sources: [drizzle-valibot/src/column.ts:61-67](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/column.ts#L61-L67) If a column matches none of the recognized database types or data categories, `columnToSchema` defaults the schema to `v.any()` as a safe fallback. ```typescript if (!schema) { schema = v.any(); } return schema; ``` Sources: [drizzle-valibot/src/column.ts:121-125](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/column.ts#L121-L125) ## Static type inference ### Schema Inference and Property Extraction Static type inference in `drizzle-valibot` maps Drizzle column configurations and table shapes directly to Valibot schema type arguments at compile time. The conditional type `ExtractAdditionalProperties` inspects a column's internal type definition (`columnType`) to extract maximum lengths, dimensions, or array sizes. For example, character and text columns from PostgreSQL, MySQL, SQLite, and SingleStore resolve to their respective length bounds, while vector columns extract their dimension counts. ```typescript export type ExtractAdditionalProperties = { max: TColumn['_']['columnType'] extends 'PgVarchar' | 'SQLiteText' | 'PgChar' | 'MySqlChar' | 'SingleStoreChar' ? Assume['length'] : TColumn['_']['columnType'] extends 'MySqlText' | 'MySqlVarChar' | 'SingleStoreText' | 'SingleStoreVarChar' ? number : TColumn['_']['columnType'] extends 'PgBinaryVector' | 'PgHalfVector' | 'PgVector' ? Assume['dimensions'] : TColumn['_']['columnType'] extends 'PgArray' ? Assume['size'] : undefined; fixedLength: TColumn['_']['columnType'] extends 'PgChar' | 'PgHalfVector' | 'PgVector' | 'PgArray' | 'MySqlChar' | 'SingleStoreChar' ? true : false; }; ``` Sources: [drizzle-valibot/src/column.types.ts:12-24](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/column.types.ts#L12-L24) | Column Type Group | Checked Column Types | Extracted Property Type | | :--- | :--- | :--- | | Character Limits | `PgVarchar`, `SQLiteText`, `PgChar`, `MySqlChar`, `SingleStoreChar` | `length` (number \| undefined) | | Text / VarChar Sizes | `MySqlText`, `MySqlVarChar`, `SingleStoreText`, `SingleStoreVarChar` | `number` | | Vector Dimensions | `PgBinaryVector`, `PgHalfVector`, `PgVector` | `dimensions` (number) | | Array Sizes | `PgArray` | `size` (number \| undefined) | Sources: [drizzle-valibot/src/column.types.ts:13-20](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/column.types.ts#L13-L20) > [!NOTE] > The helper `HasBaseColumn` evaluates whether a column possesses a defined base column reference, enabling nested array type resolution for multi-dimensional array structures. ```typescript export type HasBaseColumn = TColumn extends { _: { baseColumn: Column | undefined } } ? IsNever extends false ? true : false : false; ``` Sources: [drizzle-valibot/src/column.types.ts:5-8](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/column.types.ts#L5-L8) ### Type Mapping and Nullability Handlers The central type-level mapping function `GetValibotType` processes the extracted data types, column types, enum definitions, and base columns to yield the exact Valibot schema shape. Depending on whether a column enforces a default value or allows nulls, secondary wrapper utilities adjust the final inferred type. Specifically, `HandleSelectColumn`, `HandleInsertColumn`, and `HandleUpdateColumn` wrap underlying Valibot schemas with `v.NullableSchema` or `v.OptionalSchema` conditional containers. ```typescript type HandleSelectColumn< TSchema extends v.GenericSchema, TColumn extends Column, > = TColumn['_']['notNull'] extends true ? TSchema : v.NullableSchema; type HandleInsertColumn< TSchema extends v.GenericSchema, TColumn extends Column, > = TColumn['_']['notNull'] extends true ? TColumn['_']['hasDefault'] extends true ? v.OptionalSchema : TSchema : v.OptionalSchema, undefined>; type HandleUpdateColumn< TSchema extends v.GenericSchema, TColumn extends Column, > = TColumn['_']['notNull'] extends true ? v.OptionalSchema : v.OptionalSchema, undefined>; ``` Sources: [drizzle-valibot/src/column.types.ts:133-152](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/column.types.ts#L133-L152) > [!WARNING] > `HandleInsertColumn` and `HandleUpdateColumn` mark columns with defaults or nullable constraints as optional, which changes how partial payloads validate during insert and update operations. ```typescript type HandleInsertColumn< TSchema extends v.GenericSchema, TColumn extends Column, > = TColumn['_']['notNull'] extends true ? TColumn['_']['hasDefault'] extends true ? v.OptionalSchema : TSchema : v.OptionalSchema, undefined>; type HandleUpdateColumn< TSchema extends v.GenericSchema, TColumn extends Column, > = TColumn['_']['notNull'] extends true ? v.OptionalSchema : v.OptionalSchema, undefined>; ``` Sources: [drizzle-valibot/src/column.types.ts:139-152](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/column.types.ts#L139-L152) Furthermore, `BuildSchema` iterates over table columns while automatically omitting columns designated with `ColumnIsGeneratedAlwaysAs`. It resolves custom user-provided refinements through `IsRefinementDefined` and `HandleRefinement`, guaranteeing that overridden fields preserve correct nullability and optionality modifiers in the final compiled object schema. ```typescript export type BuildSchema< TType extends 'select' | 'insert' | 'update', TColumns extends Record, TRefinements extends Record | undefined, > = v.ObjectSchema< Simplify< { readonly [K in keyof TColumns as ColumnIsGeneratedAlwaysAs extends true ? never : K]: TColumns[K] extends infer TColumn extends Column ? IsRefinementDefined> extends true ? Assume, v.GenericSchema> : HandleColumn : TColumns[K] extends infer TObject extends SelectedFieldsFlat | Table | View ? BuildSchema< TType, GetSelection, TRefinements extends object ? TRefinements[K & keyof TRefinements] : undefined > : v.AnySchema; } >, undefined >; ``` Sources: [drizzle-valibot/src/schema.types.internal.ts:50-71](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/schema.types.internal.ts#L50-L71) ## Custom schema overrides ### Refinement Dispatch and Execution Schema generation functions (`createSelectSchema`, `createInsertSchema`, and `createUpdateSchema`) accept an optional second argument `refine`, represented as a record of column keys mapped to either direct Valibot validator schemas or transformer functions. During schema compilation, `handleColumns` iterates over table columns and inspects any corresponding entry in the `refinements` dictionary. If a refinement value is provided and is not a function, it directly replaces the generated column schema. If the refinement is instead a function, it receives the automatically generated Valibot schema as its argument, allowing developers to wrap, constrain, or transform the base validator. ```typescript const refinement = refinements[key]; if (refinement !== undefined && typeof refinement !== 'function') { columnSchemas[key] = refinement; continue; } const column = is(selected, Column) ? selected : undefined; const schema = column ? columnToSchema(column) : v.any(); const refined = typeof refinement === 'function' ? refinement(schema) : schema; ``` Sources: [drizzle-valibot/src/schema.ts:28-36](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/schema.ts#L28-L36) > [!NOTE] > When nesting occurs across relations, views, or embedded object structures, `handleColumns` recursively processes child objects and passes down corresponding nested refinement dictionaries via `refinements[key] ?? {}`. ```typescript if (!is(selected, Column) && !is(selected, SQL) && !is(selected, SQL.Aliased) && typeof selected === 'object') { const columns = isTable(selected) || isView(selected) ? getColumns(selected) : selected; columnSchemas[key] = handleColumns(columns, refinements[key] ?? {}, conditions); continue; } ``` Sources: [drizzle-valibot/src/schema.ts:22-26](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/schema.ts#L22-L26) ### Handling Nullability and Optionality in Refinements After applying a custom refinement function or static schema replacement, `handleColumns` evaluates table-level and column-level conditions to enforce database constraints. Even when a column schema is overridden, subsequent checks verify whether the underlying column is nullable or optional. If the column allows nulls according to the active condition set, the refined schema is automatically wrapped using `v.nullable()`. Similarly, if conditions specify optionality for inserts or updates, an optional wrapper is applied. ```typescript if (column) { if (conditions.nullable(column)) { columnSchemas[key] = v.nullable(columnSchemas[key]!); } if (conditions.optional(column)) { columnSchemas[key] = v.optional(columnSchemas[key]!); } } ``` Sources: [drizzle-valibot/src/schema.ts:44-52](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/schema.ts#L44-L52) > [!WARNING] > Generated columns whose generation type is set to `'always'` or identity columns configured as `'always'` trigger the `conditions.never` check, causing the column to be omitted entirely from the generated object schema regardless of any supplied refinement. ```typescript if (conditions.never(column)) { continue; } else { columnSchemas[key] = refined; } ``` Sources: [drizzle-valibot/src/schema.ts:38-42](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/schema.ts#L38-L42) ## Related - [Drizzle Zod Integration](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/ecosystem-packages/drizzle-zod-integration) - [Table and Column Models](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/table-and-column-models) --- ## Technical docs: Drizzle ArkType Integration URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/ecosystem-packages/drizzle-arktype-integration
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-arktype/src/column.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/column.ts) - [drizzle-orm/type-tests/mysql/tables.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/tables.ts) - [drizzle-arktype/src/schema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.ts) - [drizzle-orm/type-tests/singlestore/tables.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/tables.ts) - [drizzle-kit/src/serializer/gelSchema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/gelSchema.ts) - [drizzle-kit/src/introspect-mysql.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-mysql.ts) - [drizzle-arktype/src/schema.types.internal.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.types.internal.ts) - [drizzle-kit/src/introspect-pg.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-pg.ts) - [drizzle-kit/src/serializer/pgSchema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/pgSchema.ts) - [drizzle-arktype/src/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/index.ts) - [drizzle-kit/src/introspect-singlestore.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-singlestore.ts) - [drizzle-kit/src/introspect-gel.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-gel.ts) - [drizzle-arktype/src/column.types.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/column.types.ts) - [drizzle-kit/src/serializer/mysqlSchema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/mysqlSchema.ts) - [drizzle-valibot/src/column.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/column.ts) - [drizzle-kit/src/serializer/pgSerializer.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/pgSerializer.ts) - [drizzle-arktype/src/utils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/utils.ts) - [drizzle-valibot/src/column.types.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/column.types.ts) - [drizzle-valibot/src/schema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/src/schema.ts) - [drizzle-typebox/src/column.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/column.ts) - [drizzle-kit/src/schemaValidator.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/schemaValidator.ts) - [drizzle-kit/src/serializer/sqliteSchema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/sqliteSchema.ts) - [drizzle-arktype/src/schema.types.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.types.ts) - [drizzle-seed/src/types/drizzleStudio.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/types/drizzleStudio.ts) - [drizzle-kit/src/serializer/studio.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/studio.ts) - [integration-tests/drizzle2/pg/meta/0000_snapshot.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/drizzle2/pg/meta/0000_snapshot.json) - [drizzle-kit/src/serializer/singlestoreSchema.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/singlestoreSchema.ts) - [drizzle-seed/src/types/tables.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/types/tables.ts) - [drizzle-typebox/src/schema.types.internal.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/src/schema.types.internal.ts)
## Overview Drizzle ArkType Integration bridges Drizzle ORM definitions with the ArkType validation library by automatically generating runtime type validators and static TypeScript types from database schemas. Operating across tables, views, and enums, it translates column primitives, constraints, and relational selections into validated ArkType structures, powering type-safe data validation and insertions. Sources: [drizzle-arktype/src/column.ts:66-126](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/column.ts#L66-L126), [drizzle-arktype/src/schema.ts:61-98](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.ts#L61-L98), [drizzle-arktype/src/schema.types.ts:6-48](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.types.ts#L6-L48) ## Public Schema Generation API ### Schema Factory Functions The public API provides three main factory functions — `createSelectSchema`, `createInsertSchema`, and `createUpdateSchema` — to generate ArkType validation schemas from Drizzle table, view, and enum definitions. Each factory inspects the entity columns or fields, applies custom field refinements, and enforces nullability and optionality rules according to the operation type. ```typescript export const createSelectSchema = (( entity: Table | View | PgEnum<[string, ...string[]]>, refine?: Record, ) => { if (isPgEnum(entity)) { return type.enumerated(...entity.enumValues); } const columns = getColumns(entity); return handleColumns(columns, refine ?? {}, { never: () => false, optional: () => false, nullable: (column) => !column.notNull, }) as any; }) as CreateSelectSchema; export const createInsertSchema = (( entity: Table, refine?: Record, ) => { const columns = getColumns(entity); return handleColumns(columns, refine ?? {}, { never: (column) => column?.generated?.type === 'always' || column?.generatedIdentity?.type === 'always', optional: (column) => !column.notNull || (column.notNull && column.hasDefault), nullable: (column) => !column.notNull, }) as any; }) as CreateInsertSchema; export const createUpdateSchema = (( entity: Table, refine?: Record, ) => { const columns = getColumns(entity); return handleColumns(columns, refine ?? {}, { never: (column) => column?.generated?.type === 'always' || column?.generatedIdentity?.type === 'always', optional: () => true, nullable: (column) => !column.notNull, }) as any; }) as CreateUpdateSchema; ``` Sources: [drizzle-arktype/src/schema.ts:61-98](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.ts#L61-L98) The behavior of each factory function depends on specific condition evaluators configured during column iteration: | Function | Target Entity | `never` Condition | `optional` Condition | `nullable` Condition | | :--- | :--- | :--- | :--- | :--- | | `createSelectSchema` | Table, View, PgEnum | Always `false` | Always `false` | `!column.notNull` | | `createInsertSchema` | Table | `generated === 'always'` or `generatedIdentity === 'always'` | `!column.notNull || (column.notNull && column.hasDefault)` | `!column.notNull` | | `createUpdateSchema` | Table | `generated === 'always'` or `generatedIdentity === 'always'` | Always `true` | `!column.notNull` | ```typescript export const createSelectSchema = (( entity: Table | View | PgEnum<[string, ...string[]]>, refine?: Record, ) => { if (isPgEnum(entity)) { return type.enumerated(...entity.enumValues); } const columns = getColumns(entity); return handleColumns(columns, refine ?? {}, { never: () => false, optional: () => false, nullable: (column) => !column.notNull, }) as any; }) as CreateSelectSchema; export const createInsertSchema = (( entity: Table, refine?: Record, ) => { const columns = getColumns(entity); return handleColumns(columns, refine ?? {}, { never: (column) => column?.generated?.type === 'always' || column?.generatedIdentity?.type === 'always', optional: (column) => !column.notNull || (column.notNull && column.hasDefault), nullable: (column) => !column.notNull, }) as any; }) as CreateInsertSchema; export const createUpdateSchema = (( entity: Table, refine?: Record, ) => { const columns = getColumns(entity); return handleColumns(columns, refine ?? {}, { never: (column) => column?.generated?.type === 'always' || column?.generatedIdentity?.type === 'always', optional: () => true, nullable: (column) => !column.notNull, }) as any; }) as CreateUpdateSchema; ``` Sources: [drizzle-arktype/src/schema.ts:61-98](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.ts#L61-L98) > [!NOTE] > When `createSelectSchema` receives a `PgEnum`, it bypasses column iteration entirely and immediately constructs an ArkType enumerated validator using the enum's `enumValues`. Sources: [drizzle-arktype/src/schema.ts:65-67](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.ts#L65-L67) ### Overloads and Refinement Signatures The TypeScript interfaces for `createSelectSchema`, `createInsertSchema`, and `createUpdateSchema` support overloaded signatures for tables and views, as well as optional refinement objects to customize field validators. ```typescript export interface CreateSelectSchema { (table: TTable): BuildSchema<'select', TTable['_']['columns'], undefined>; < TTable extends Table, TRefine extends BuildRefine, >( table: TTable, refine?: NoUnknownKeys, ): BuildSchema<'select', TTable['_']['columns'], TRefine>; (view: TView): BuildSchema<'select', TView['_']['selectedFields'], undefined>; < TView extends View, TRefine extends BuildRefine, >( view: TView, refine: NoUnknownKeys, ): BuildSchema<'select', TView['_']['selectedFields'], TRefine>; >(enum_: TEnum): Type; } export interface CreateInsertSchema { (table: TTable): BuildSchema<'insert', TTable['_']['columns'], undefined>; < TTable extends Table, TRefine extends BuildRefine>, >( table: TTable, refine?: NoUnknownKeys, ): BuildSchema<'insert', TTable['_']['columns'], TRefine>; } export interface CreateUpdateSchema { (table: TTable): BuildSchema<'update', TTable['_']['columns'], undefined>; < TTable extends Table, TRefine extends BuildRefine>, >( table: TTable, refine?: TRefine, ): BuildSchema<'update', TTable['_']['columns'], TRefine>; } ``` Sources: [drizzle-arktype/src/schema.types.ts:6-48](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.types.ts#L6-L48) > [!IMPORTANT] > For insert and update schemas, refinement typings are constrained via `NoUnknownKeys` to keys present in `$inferInsert`, preventing developers from specifying refinements for uninsertable or generated columns. Sources: [drizzle-arktype/src/schema.types.ts:28-48](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.types.ts#L28-L48) ## Column to ArkType Conversion Pipeline ### Column Data Type Routing The `columnToSchema` function inspects incoming Drizzle column definitions and routes them to specific ArkType validators. If a column has associated enumeration values, it generates an enumerated validator using `column.enumValues`, or falls back to `type.string` if the enumeration is empty. ```typescript export function columnToSchema(column: Column): Type { let schema!: Type; if (isWithEnum(column)) { schema = column.enumValues.length ? type.enumerated(...column.enumValues) : type.string; } ``` Sources: [drizzle-arktype/src/column.ts:66-72](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/column.ts#L66-L72) For specialized geometric, vector, and line types, columns map directly to fixed-tuple structures or object shapes with coordinate properties. Array columns recursively resolve their base column schema via `columnToSchema` and enforce exact element dimensions when a column size or dimension is specified. | Column Type Matcher | Column Subtypes Checked | Generated ArkType Structure | | :--- | :--- | :--- | | Tuple Geometry / Point | `PgGeometry`, `PgPointTuple` | `type([type.number, type.number])` | | Object Geometry / Point | `PgGeometryObject`, `PgPointObject` | `type({ x: type.number, y: type.number })` | | Vector | `PgHalfVector`, `PgVector` | `type.number.array()` (with optional `.exactlyLength(column.dimensions)`) | | Line Tuple | `PgLine` | `type([type.number, type.number, type.number])` | | Line ABC Object | `PgLineABC` | `type({ a: type.number, b: type.number, c: type.number })` | | Array | `PgArray` | `columnToSchema(column.baseColumn).array()` (with optional `.exactlyLength(column.size)`) | ```typescript // Handle specific types if (isColumnType | PgPointTuple>(column, ['PgGeometry', 'PgPointTuple'])) { schema = type([type.number, type.number]); } else if ( isColumnType | PgGeometryObject>(column, ['PgGeometryObject', 'PgPointObject']) ) { schema = type({ x: type.number, y: type.number, }); } else if (isColumnType | PgVector>(column, ['PgHalfVector', 'PgVector'])) { schema = column.dimensions ? type.number.array().exactlyLength(column.dimensions) : type.number.array(); } else if (isColumnType>(column, ['PgLine'])) { schema = type([type.number, type.number, type.number]); } else if (isColumnType>(column, ['PgLineABC'])) { schema = type({ a: type.number, b: type.number, c: type.number, }); } // Handle other types else if (isColumnType>(column, ['PgArray'])) { const arraySchema = columnToSchema(column.baseColumn).array(); schema = column.size ? arraySchema.exactlyLength(column.size) : arraySchema; } else if (column.dataType === 'array') { schema = type.unknown.array(); ``` Sources: [drizzle-arktype/src/column.ts:74-101](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/column.ts#L74-L101) ### Primitive and Complex Type Mappings Standard data types are resolved by checking `column.dataType`. Numeric and bigint columns delegate to dedicated boundary-resolution functions, while booleans map to `type.boolean`, dates map to `type.Date`, JSON columns map to `jsonSchema`, buffers map to `bufferSchema`, and custom types fall back to `type.unknown`. ```typescript } else if (column.dataType === 'number') { schema = numberColumnToSchema(column); } else if (column.dataType === 'bigint') { schema = bigintColumnToSchema(column); } else if (column.dataType === 'boolean') { schema = type.boolean; } else if (column.dataType === 'date') { schema = type.Date; } else if (column.dataType === 'string') { schema = stringColumnToSchema(column); } else if (column.dataType === 'json') { schema = jsonSchema; } else if (column.dataType === 'custom') { schema = type.unknown; } else if (column.dataType === 'buffer') { schema = bufferSchema; } ``` Sources: [drizzle-arktype/src/column.ts:102-118](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/column.ts#L102-L118) > [!NOTE] > If a column matches none of the recognized database types or enumerations, `columnToSchema` defaults to `type.unknown` as a safe fallback validator. Sources: [drizzle-arktype/src/column.ts:121-125](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/column.ts#L121-L125) ### Column Nullability and Operational Handling The `HandleColumn` type utility determines whether a generated schema requires nullability or optionality wrappers based on whether an operation targets select, insert, or update statements. Nullable columns wrap their underlying schemas with `ArktypeNullable`, allowing `null` values, whereas defaultable insert columns and all update columns incorporate `ArktypeOptional`. ```typescript export type HandleColumn< TType extends 'select' | 'insert' | 'update', TColumn extends Column, > = TType extends 'select' ? HandleSelectColumn, TColumn> : TType extends 'insert' ? HandleInsertColumn, TColumn> : TType extends 'update' ? HandleUpdateColumn, TColumn> : GetArktypeType; ``` Sources: [drizzle-arktype/src/column.types.ts:35-41](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/column.types.ts#L35-L41) > [!IMPORTANT] > JSON columns use specialized type extraction via `GetArktypeType`, which resolves unconstrained JSON data columns to the `Json` union type rather than standard `unknown` descriptors. Sources: [drizzle-arktype/src/column.types.ts:9-14](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/column.types.ts#L9-L14) ## Table and View Column Resolution ### Column Extraction and Recursive Traversal The `getColumns` helper inspects whether an incoming entity is a table or view, invoking `getTableColumns` or `getViewSelectedFields` respectively to extract its base field mappings. ```typescript function getColumns(tableLike: Table | View) { return isTable(tableLike) ? getTableColumns(tableLike) : getViewSelectedFields(tableLike); } ``` Sources: [drizzle-arktype/src/schema.ts:10-12](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.ts#L10-L12) The `handleColumns` engine iterates over column records and recursively processes nested object relations or inline selections whenever an entry is an object and not an instance of `Column`, `SQL`, or `SQL.Aliased`. ```typescript function handleColumns( columns: Record, refinements: Record, conditions: Conditions, ): Type { const columnSchemas: Record = {}; for (const [key, selected] of Object.entries(columns)) { if (!is(selected, Column) && !is(selected, SQL) && !is(selected, SQL.Aliased) && typeof selected === 'object') { const columns = isTable(selected) || isView(selected) ? getColumns(selected) : selected; columnSchemas[key] = handleColumns(columns, refinements[key] ?? {}, conditions); continue; } ``` Sources: [drizzle-arktype/src/schema.ts:14-26](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.ts#L14-L26) ### Conditional Constraints and Refinement Processing During column iteration, `handleColumns` applies operational conditions and field-level user refinements to build the final composite `Type` schema object. ```typescript const refinement = refinements[key]; if ( refinement !== undefined && (typeof refinement !== 'function' || (typeof refinement === 'function' && refinement.expression !== undefined)) ) { columnSchemas[key] = refinement; continue; } const column = is(selected, Column) ? selected : undefined; const schema = column ? columnToSchema(column) : type.unknown; const refined = typeof refinement === 'function' ? refinement(schema) : schema; if (conditions.never(column)) { continue; } else { columnSchemas[key] = refined; } if (column) { if (conditions.nullable(column)) { columnSchemas[key] = columnSchemas[key]!.or(type.null); } if (conditions.optional(column)) { columnSchemas[key] = columnSchemas[key]!.optional() as any; } } } return type(columnSchemas); } ``` Sources: [drizzle-arktype/src/schema.ts:27-59](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.ts#L27-L59) > [!NOTE] > When `conditions.never(column)` evaluates to true—such as for database-generated columns in insert or update schemas—the property is omitted from the resulting ArkType definition entirely. Sources: [drizzle-arktype/src/schema.ts:41-45](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.ts#L41-L45) > [!IMPORTANT] > The `createSelectSchema`, `createInsertSchema`, and `createUpdateSchema` factories supply distinct condition rulesets governing nullability (`!column.notNull`), optionality (`!column.notNull || (column.notNull && column.hasDefault)` for inserts, always true for updates), and exclusion (`generated.type === 'always'`). Sources: [drizzle-arktype/src/schema.ts:61-98](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.ts#L61-L98) ## Static Type Inference and Refinements ### Compile-Time Schema Inference and Utilities Internal type utilities orchestrate compile-time schema composition, parameter validation, and refinement mapping across select, insert, and update operations. The `BuildSchema` type maps table columns or view fields into an instantiated ArkType object schema, omitting any columns marked as generated always via `ColumnIsGeneratedAlwaysAs`. ```typescript export type BuildSchema< TType extends 'select' | 'insert' | 'update', TColumns extends Record, TRefinements extends Record | undefined, > = type.instantiate< Simplify< { readonly [K in keyof TColumns as ColumnIsGeneratedAlwaysAs extends true ? never : K]: TColumns[K] extends infer TColumn extends Column ? IsRefinementDefined extends true ? HandleRefinement : HandleColumn : TColumns[K] extends infer TNested extends SelectedFieldsFlat | Table | View ? BuildSchema< TType, GetSelection, TRefinements extends object ? TRefinements[K & keyof TRefinements] : undefined > : any; } > >; ``` Sources: [drizzle-arktype/src/schema.types.internal.ts:43-63](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.types.internal.ts#L43-L63) The `Conditions` interface specifies functional predicates that determine whether columns are excluded, optional, or nullable during schema generation. ```typescript export interface Conditions { never: (column?: Column) => boolean; optional: (column: Column) => boolean; nullable: (column: Column) => boolean; } ``` Sources: [drizzle-arktype/src/schema.types.internal.ts:6-10](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.types.internal.ts#L6-L10) | Condition Utility | Parameter Type | Return Type | Purpose | | :--- | :--- | :--- | :--- | | `never` | `column?: Column` | `boolean` | Determines if a column should be omitted entirely from the generated schema | | `optional` | `column: Column` | `boolean` | Evaluates whether a column accepts optional input values | | `nullable` | `column: Column` | `boolean` | Evaluates whether a column permits null values | Sources: [drizzle-arktype/src/schema.types.internal.ts:6-10](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.types.internal.ts#L6-L10) ### Field Refinement and Validation Typings User-supplied field refinements are typed and validated through dedicated utility types that ensure type safety and prevent unknown keys. `BuildRefine` constructs a mapped type over table columns, accepting either a generic ArkType schema, a refinement function returning a generic schema, or nested selections. ```typescript export type BuildRefine< TColumns extends Record, > = { [K in keyof TColumns as TColumns[K] extends Column | SelectedFieldsFlat | Table | View ? K : never]?: TColumns[K] extends Column ? BuildRefineField> : BuildRefine>; }; ``` Sources: [drizzle-arktype/src/schema.types.internal.ts:16-22](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.types.internal.ts#L16-L22) The `NoUnknownKeys` utility validates refinement keys against comparison schemas, returning a `DrizzleTypeError` when an unrecognized key is encountered. ```typescript export type NoUnknownKeys< TRefinement extends Record, TCompare extends Record, > = { [K in keyof TRefinement]: K extends keyof TCompare ? TRefinement[K] extends Record ? NoUnknownKeys : TRefinement[K] : DrizzleTypeError<`Found unknown key in refinement: "${K & string}"`>; }; ``` Sources: [drizzle-arktype/src/schema.types.internal.ts:65-73](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.types.internal.ts#L65-L73) > [!CAUTION] > Supplying an unrecognized key within a refinement object triggers `NoUnknownKeys` to evaluate a `DrizzleTypeError` string literal type, failing compilation. Sources: [drizzle-arktype/src/schema.types.internal.ts:65-73](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.types.internal.ts#L65-L73) ### Refinement Resolution and Operation Handling The `HandleRefinement` type processes user-defined refinement functions or static schemas based on the operation context (`select`, `insert`, or `update`). If a refinement is defined as a function, `HandleRefinement` checks column nullability and applies `ArktypeNullable` when not strictly not-null, and wraps the resulting schema in `ArktypeOptional` for update operations. ```typescript type HandleRefinement< TType extends 'select' | 'insert' | 'update', TRefinement, TColumn extends Column, > = TRefinement extends (schema: any) => GenericSchema ? ( TColumn['_']['notNull'] extends true ? ReturnType : ArktypeNullable> ) extends infer TSchema ? TType extends 'update' ? ArktypeOptional : TSchema : Type : TRefinement; ``` Sources: [drizzle-arktype/src/schema.types.internal.ts:24-34](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.types.internal.ts#L24-L34) The presence of a refinement for any given key is verified by `IsRefinementDefined`, which inspects whether the refinement property extends `GenericSchema` or a valid refinement builder function. ```typescript type IsRefinementDefined< TRefinements extends Record | undefined, TKey extends string | symbol | number, > = TRefinements extends object ? TRefinements[TKey] extends GenericSchema | ((schema: any) => any) ? true : false : false; ``` Sources: [drizzle-arktype/src/schema.types.internal.ts:36-41](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.types.internal.ts#L36-L41) > [!NOTE] > During schema building, `IsRefinementDefined` acts as a conditional gate: when it evaluates to true, `HandleRefinement` processes the custom rule; otherwise, standard column rules via `HandleColumn` take effect. Sources: [drizzle-arktype/src/schema.types.internal.ts:51-54](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/schema.types.internal.ts#L51-L54) ## Specialized Column Schemas and Helpers ### Standalone Column Builders and Primitives The library exports standalone schema definitions and helper utilities designed for validating specific runtime structures, primitive types, and buffer values without requiring a full table configuration. The `literalSchema` accepts strings, numbers, booleans, and null values, serving as the foundation for broader structural definitions. ```typescript export const literalSchema = type.string.or(type.number).or(type.boolean).or(type.null); export const jsonSchema = literalSchema.or(type.unknown.as().array()).or(type.object.as>()); export const bufferSchema = type.unknown.narrow((value) => value instanceof Buffer).as().describe( // eslint-disable-line no-instanceof/no-instanceof 'a Buffer instance', ); ``` Sources: [drizzle-arktype/src/column.ts:60-64](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/column.ts#L60-L64) The `jsonSchema` composes `literalSchema` with unknown arrays and arbitrary object records to validate nested JSON payloads. Meanwhile, `bufferSchema` uses a narrowing check to enforce runtime validation for `Buffer` instances with a descriptive error string. ```typescript export const jsonSchema = literalSchema.or(type.unknown.as().array()).or(type.object.as>()); export const bufferSchema = type.unknown.narrow((value) => value instanceof Buffer).as().describe( // eslint-disable-line no-instanceof/no-instanceof 'a Buffer instance', ); ``` Sources: [drizzle-arktype/src/column.ts:61-64](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/column.ts#L61-L64) | Helper Schema | Underlying Definition | Target Runtime Structure | | :--- | :--- | :--- | | `literalSchema` | `type.string.or(type.number).or(type.boolean).or(type.null)` | Primitive scalars and null values | | `jsonSchema` | `literalSchema.or(type.unknown.array()).or(type.object)` | Nested JSON-compatible data structures | | `bufferSchema` | `type.unknown.narrow((value) => value instanceof Buffer)` | Node.js `Buffer` byte arrays | Sources: [drizzle-arktype/src/column.ts:60-64](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/column.ts#L60-L64) ### Enum Constraint Checking and Resolution Column definitions containing restricted sets of allowed values are processed using `isWithEnum` to determine whether an explicit enumeration constraint exists. When enum values are present and non-empty, `columnToSchema` constructs an ArkType enumerated type using `type.enumerated(...column.enumValues)`. If the column lacks explicit values or the array is empty, it falls back to a standard string type. ```typescript if (isWithEnum(column)) { schema = column.enumValues.length ? type.enumerated(...column.enumValues) : type.string; } ``` Sources: [drizzle-arktype/src/column.ts:69-71](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/column.ts#L69-L71) The utility function `isWithEnum` verifies column configurations by checking whether the `enumValues` property exists on the column object, is an array, and contains a positive length. The related `isPgEnum` helper casts this check to validate PostgreSQL-specific enum entities. ```typescript export function isWithEnum(column: Column): column is typeof column & { enumValues: [string, ...string[]] } { return 'enumValues' in column && Array.isArray(column.enumValues) && column.enumValues.length > 0; } export const isPgEnum: (entity: any) => entity is PgEnum<[string, ...string[]]> = isWithEnum as any; ``` Sources: [drizzle-arktype/src/utils.ts:10-14](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/utils.ts#L10-L14) > [!CAUTION] > Passing a column object with an empty `enumValues` array will bypass the enumerated schema builder and default to an unrestricted string validator. Sources: [drizzle-arktype/src/column.ts:69-71](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/src/column.ts#L69-L71) ## Related - [Drizzle Zod Integration](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/ecosystem-packages/drizzle-zod-integration) - [Table and Column Models](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/table-and-column-models) --- ## Technical docs: Seed Service Engine URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/ecosystem-packages/seed-service-engine
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-seed/src/services/SeedService.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts) - [drizzle-seed/src/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts) - [drizzle-kit/src/api.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/api.ts) - [drizzle-seed/src/services/Generators.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/Generators.ts) - [drizzle-kit/src/introspect-mysql.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-mysql.ts) - [drizzle-kit/src/serializer/gelSerializer.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/gelSerializer.ts) - [drizzle-kit/src/serializer/studio.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/studio.ts) - [drizzle-kit/src/introspect-singlestore.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-singlestore.ts) - [drizzle-seed/src/types/seedService.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/types/seedService.ts) - [drizzle-seed/type-tests/mysql.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/type-tests/mysql.ts) - [drizzle-seed/type-tests/sqlite.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/type-tests/sqlite.ts) - [drizzle-kit/src/sqlgenerator.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/sqlgenerator.ts) - [drizzle-seed/type-tests/pg.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/type-tests/pg.ts) - [drizzle-seed/src/types/drizzleStudio.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/types/drizzleStudio.ts) - [drizzle-seed/src/services/apiVersion.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/apiVersion.ts) - [drizzle-seed/src/services/utils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/utils.ts)
## Overview The seed service engine is a deterministic test data generation framework built into Drizzle ORM that populates database tables with realistic mock data, handles schema introspection, and executes database mutations [[drizzle-seed/src/index.ts:301-364](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L301-L364), [Seed Data Generators](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/ecosystem-packages/seed-data-generators)]. It provides the core engine behind the Seed Client Interface, bridging TypeScript table definitions and relation metadata with robust random value generators while supporting versioned generator configurations and user-defined refinements [drizzle-seed/src/index.ts:196-205](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L196-L205), [drizzle-seed/src/index.ts:301-364](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L301-L364), [drizzle-seed/src/services/SeedService.ts:305-337](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L305-L337). The engine addresses complex database population challenges such as foreign key dependencies, cyclic table relations, and type-safe generator mapping across multiple SQL dialects [[drizzle-seed/src/services/SeedService.ts:339-483](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L339-L483), [drizzle-seed/src/services/SeedService.ts:503-991](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L503-L991), [Database Introspection](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/database-introspection), [Migration Toolkit Schema](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/migration-toolkit-schema)]. By employing topological sorting for insertion ordering and deferred updates for cyclic references, the engine enables reliable batch seeding and resetting for PostgreSQL, MySQL, and SQLite databases [[drizzle-seed/src/services/SeedService.ts:375-422](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L375-L422), [drizzle-seed/src/services/SeedService.ts:911-961](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L911-L961), [Studio Server Bridge](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/studio-server-bridge)]. Sources: [drizzle-seed/src/index.ts:196-205](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L196-L205), [drizzle-seed/src/index.ts:301-364](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L301-L364), [drizzle-seed/src/services/SeedService.ts:305-337](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L305-L337), [drizzle-seed/src/services/SeedService.ts:339-483](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L339-L483), [drizzle-seed/src/services/SeedService.ts:503-991](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L503-L991) ## Seed Client Interface The public client interface for the seed service engine centers around the top-level `seed()` and `reset()` entrypoint functions, which accept a database connection, a schema definition object, and an optional configuration object [drizzle-seed/src/index.ts:346-364](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L346-L364), [drizzle-seed/type-tests/mysql.ts:4](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/type-tests/mysql.ts#L4). The `seed()` function returns a `SeedPromise` instance, enabling promise chaining and invocation of the `.refine()` method [drizzle-seed/src/index.ts:310-363](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L310-L363). The `.refine()` method accepts a callback function providing versioned generator functions (`funcs`), allowing users to customize column-level mock data generation and table row counts [drizzle-seed/src/index.ts:196-205](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L196-L205), [drizzle-seed/src/index.ts:324-342](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L324-L342). ```typescript export function seed< DB extends | PgDatabase | MySqlDatabase | BaseSQLiteDatabase, SCHEMA extends { [key: string]: | PgTable | PgSchema | MySqlTable | MySqlSchema | SQLiteTable | Relations | any; }, VERSION extends '2' | '1' | undefined, >(db: DB, schema: SCHEMA, options?: { count?: number; seed?: number; version?: VERSION }) { return new SeedPromise(db, schema, options); } ``` Sources: [drizzle-seed/src/index.ts:346-364](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L346-L364) The options object supports a global `count` parameter specifying the default number of rows to generate per table, a deterministic `seed` number to control the pseudo-random number generator state, and a `version` string (`'1'` or `'2'`) selecting between generator function API versions [drizzle-seed/src/index.ts:196-210](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L196-L210), [drizzle-seed/src/index.ts:304-309](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L304-L309), [drizzle-seed/src/index.ts:362](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L362). When `options.version` is undefined or set to `'2'`, the engine resolves generator functions from `generatorsFuncsV2`; otherwise, it uses legacy `generatorsFuncs` [drizzle-seed/src/index.ts:200-202](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L200-L202), [drizzle-seed/src/index.ts:208-210](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L208-L210). > [!NOTE] > Passing an explicit `seed` number guarantees deterministic data generation: running the seeding script multiple times with the same seed value yields identical database content, provided the schema and refinement definitions remain unchanged [drizzle-seed/src/index.ts:308](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L308). Sources: [drizzle-seed/src/index.ts:308](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L308) | Option Key | Type | Default | Description | | :--- | :--- | :--- | :--- | | `count` | `number` | `undefined` | Number of rows to generate per table globally. | | `seed` | `number` | `undefined` | Seed value controlling the pseudo-random generator state. | | `version` | `'1' \| '2'` | `undefined` | Version specifier (`'2'` maps to `generatorsFuncsV2`, `'1'` maps to `generatorsFuncs`). | Sources: [drizzle-seed/src/index.ts:196-210](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L196-L210), [drizzle-seed/src/index.ts:304-309](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L304-L309), [drizzle-seed/src/index.ts:362](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L362) ```mermaid sequenceDiagram participant User participant seed as seed() participant SeedPromise participant seedFunc User->>seed: seed(db, schema, options) seed->>SeedPromise: new SeedPromise(db, schema, options) User->>SeedPromise: .refine(callback) SeedPromise->>seedFunc: seedFunc(db, schema, options, refinements) seedFunc-->>User: Promise ``` Sources: [drizzle-seed/src/index.ts:196-205](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L196-L205), [drizzle-seed/src/index.ts:346-364](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L346-L364) ## Dialect Schema Inspection The dialect schema inspection phase processes database schemas and metadata representations from Drizzle Studio or active database connections, transforming raw table definitions into standardized internal models [drizzle-seed/src/index.ts:216-260](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L216-L260), [drizzle-seed/src/index.ts:366-380](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L366-L380). When seeding via Drizzle Studio objects, the engine iterates over schemas, tables, and columns, extracting properties such as column names, data types, nullability, defaults, uniqueness constraints, and primary keys [drizzle-seed/src/index.ts:238-260](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L238-L260). Composite primary keys and column-level primary flags populate the table's primary key list [drizzle-seed/src/index.ts:258](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L258). ```typescript export type DbPrimaryKey = { name: string; columns: string[]; }; export type DbForeignKey = { name: string; tableFrom: string; columnsFrom: string[]; schemaFrom: string; schemaTo: string; tableTo: string; columnsTo: string[]; onUpdate?: string; onDelete?: string; }; ``` Sources: [drizzle-seed/src/types/drizzleStudio.ts:1-16](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/types/drizzleStudio.ts#L1-L16) For relational wiring, `seedForDrizzleStudio` extracts and filters Drizzle Studio relations where the relation type is `'one'` and matches the target schema boundaries [drizzle-seed/src/index.ts:237](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L237), [drizzle-seed/src/index.ts:263](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L263). It evaluates reciprocal relation pairs to detect cyclic dependencies, tagging each relation with an `isCyclic` boolean flag before generating possible column generators [drizzle-seed/src/index.ts:264-285](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L264-L285). MySQL table filtering filters schema entries to isolate `MySqlTable` and `Relations` instances, mapping database table names back to their TypeScript counterparts via `getTableName` [drizzle-seed/src/index.ts:886-928](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L886-L928), [drizzle-seed/src/index.ts:963-973](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L963-L973). | Property | Type | Description | | :--- | :--- | :--- | | `name` | `string` | Constraint identifier name. | | `columnsFrom` / `columnsTo` | `string[]` | Source and target columns involved in the foreign key relationship. | | `schemaFrom` / `schemaTo` | `string` | Source and target database schema names. | | `tableFrom` / `tableTo` | `string` | Source and target table names. | | `onUpdate` / `onDelete` | `string` (optional) | Referential action rules for updates and deletes. | Sources: [drizzle-seed/src/types/drizzleStudio.ts:6-16](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/types/drizzleStudio.ts#L6-L16) > [!NOTE] > Relations are filtered specifically for `'one'` types during Drizzle Studio seeding initialization to correctly build structural parent-child table trees before generating row data [drizzle-seed/src/index.ts:237](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L237). Sources: [drizzle-seed/src/index.ts:237](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L237) ## Dependency Graph Ordering The engine determines insertion sequence by inspecting table relationships and analyzing inbound and outbound dependency edges [drizzle-seed/src/services/SeedService.ts:424-483](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L424-L483). The method `getInfoFromRelations` aggregates relation arrays into a lookup map containing inbound and outbound counts, self-reference flags, and sets of required or dependent table names [drizzle-seed/src/services/SeedService.ts:424-480](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L424-L480). Leaf tables—defined as those with zero outbound relations or where all outbound edges are self-references—seed the initial queue for topological sorting [drizzle-seed/src/services/SeedService.ts:378-385](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L378-L385). ```typescript getOrderedTablesList = ( tablesInOutRelations: ReturnType['tablesInOutRelations'], ): string[] => { const leafTablesNames = Object.entries(tablesInOutRelations) .filter( (tableRel) => tableRel[1].out === 0 || (tableRel[1].out !== 0 && tableRel[1].selfRelCount === tableRel[1].out), ) .map((tableRel) => tableRel[0]); const orderedTablesNames: string[] = []; let parent: string, children: string[]; for (let i = 0; leafTablesNames.length !== 0; i++) { parent = leafTablesNames.shift() as string; if (orderedTablesNames.includes(parent)) { continue; } if (tablesInOutRelations[parent] === undefined) { orderedTablesNames.push(parent); continue; } for (const orderedTableName of orderedTablesNames) { tablesInOutRelations[parent]!.requiredTableNames.delete(orderedTableName); } if ( tablesInOutRelations[parent]!.requiredTableNames.size === 0 || equalSets( tablesInOutRelations[parent]!.requiredTableNames, tablesInOutRelations[parent]!.dependantTableNames, ) ) { orderedTablesNames.push(parent); } else { leafTablesNames.push(...tablesInOutRelations[parent]!.requiredTableNames, parent); continue; } children = [...tablesInOutRelations[parent]!.dependantTableNames]; leafTablesNames.push(...children); } return orderedTablesNames; }; ``` Sources: [drizzle-seed/src/services/SeedService.ts:375-422](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L375-L422) Cyclic relations are evaluated via depth-first search in `isRelationCyclic` to identify back-edges, and `cyclicTablesCompare` resolves ordering priority between tables involved in circular dependencies [drizzle-seed/src/services/SeedService.ts:339-373](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L339-L373), [drizzle-seed/src/services/SeedService.ts:832-864](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L832-L864). If both tables in a cyclic pair contain `notNull` foreign key columns, the engine rejects the schema configuration, as circular non-null constraints prevent sequential insertion [drizzle-seed/src/services/SeedService.ts:355-360](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L355-L360). | Relation Property | Type | Description | | :--- | :--- | :--- | | `out` | `number` | Count of outbound foreign key references originating from the table. | | `in` | `number` | Count of inbound foreign key references pointing to the table. | | `selfRelation` | `boolean` | Indicates whether the relation references the table itself. | | `selfRelCount` | `number` | Number of columns involved in a self-reference. | | `requiredTableNames` | `Set` | Set of prerequisite tables that must be seeded first. | | `dependantTableNames` | `Set` | Set of dependent tables requiring this table's primary keys. | Sources: [drizzle-seed/src/services/SeedService.ts:425-433](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L425-L433) > [!CAUTION] > Attempting to seed cyclic tables where both tables contain `notNull` foreign key columns triggers an immediate error, because neither table can be populated first without violating constraints [drizzle-seed/src/services/SeedService.ts:355-360](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L355-L360). Sources: [drizzle-seed/src/services/SeedService.ts:355-360](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L355-L360) ## Column Generator Selection ### Version Selection and Generator Mapping The seed engine maps column data types, base types, and uniqueness constraints to concrete generator instances by invoking dialect-specific pickers like `selectGeneratorForSqlite` and `selectGeneratorForPostgresColumn`. Once an initial generator is instantiated, `replaceIfUnique` handles columns with uniqueness constraints by substituting specialized unique variant generators [drizzle-seed/src/services/SeedService.ts:283-286](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L283-L286). The resulting generator instance is then passed to `selectVersionOfGenerator`, which inspects the entity kind and resolves constructors defined in `generatorsMap` according to the active API version [drizzle-seed/src/services/SeedService.ts:289](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L289), [drizzle-seed/src/services/SeedService.ts:305-316](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L305-L316). ```typescript selectVersionOfGenerator = (generator: AbstractGenerator) => { const entityKind = generator.getEntityKind(); if (entityKind === 'GenerateArray') { const oldBaseColumnGen = (generator as GenerateArray).params.baseColumnGen; const newBaseColumnGen = this.selectVersionOfGenerator(oldBaseColumnGen); // newGenerator.baseColumnDataType = oldGenerator.baseColumnDataType; (generator as GenerateArray).params.baseColumnGen = newBaseColumnGen; } const possibleGeneratorConstructors = generatorsMap[entityKind as keyof typeof generatorsMap]; const possibleGeneratorConstructorsFiltered = possibleGeneratorConstructors?.filter((possGenCon) => possGenCon.version <= this.version! // sorting in ascending order by version ).sort((a, b) => a.version - b.version); const generatorConstructor = possibleGeneratorConstructorsFiltered?.at(-1) as | (new(params: any) => AbstractGenerator) | undefined; if (generatorConstructor === undefined) { throw new Error(`Can't select ${entityKind} generator for ${this.version} version.`); } const newGenerator = new generatorConstructor(generator.params); newGenerator.baseColumnDataType = generator.baseColumnDataType; newGenerator.isUnique = generator.isUnique; // TODO: for now only GenerateValuesFromArray support notNull property newGenerator.notNull = generator.notNull; newGenerator.dataType = generator.dataType; newGenerator.stringLength = generator.stringLength; return newGenerator; }; ``` Sources: [drizzle-seed/src/services/SeedService.ts:305-337](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L305-L337) The latest supported engine version is tracked as a constant, and filtering logic sorts available generator constructors in ascending order by version, selecting the highest version that does not exceed `this.version` [drizzle-seed/src/services/SeedService.ts:316-321](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L316-L321), [drizzle-seed/src/services/apiVersion.ts:1-1](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/apiVersion.ts#L1-L1). For nested structures such as `GenerateArray`, the version selection procedure recursively traverses and resolves base column generators before instantiating the wrapper [drizzle-seed/src/services/SeedService.ts:307-314](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L307-L314). | Property / Field | Type | Description | | :--- | :--- | :--- | | `columnName` | `string` | Target column name in the database schema. | | `generator` | `AbstractGenerator \| undefined` | Active mock data generator assigned to the column. | | `isUnique` | `boolean` | Flag indicating whether uniqueness constraints apply. | | `notNull` | `boolean` | Flag indicating whether null values are forbidden. | | `primary` | `boolean` | Flag indicating whether the column forms part of the primary key. | | `generatedIdentityType` | `'always' \| 'byDefault' \| undefined` | Identity generation strategy for auto-incrementing columns. | | `wasRefined` | `boolean` | Indicates if the generator was modified by user refinements. | | `wasDefinedBefore` | `boolean` | Tracking flag for prior definition state. | | `isCyclic` | `boolean` | Indicates involvement in a cyclic table relationship. | Sources: [drizzle-seed/src/types/seedService.ts:14-24](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/types/seedService.ts#L14-L24) > [!NOTE] > When selecting generator versions, if `possibleGeneratorConstructorsFiltered` finds no matching constructor for the requested version, an explicit error is thrown indicating that the generator cannot be selected [drizzle-seed/src/services/SeedService.ts:324-326](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L324-L326). Sources: [drizzle-seed/src/services/SeedService.ts:324-326](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L324-L326) ### SQLite Column Type Selection Rules For SQLite schemas, `selectGeneratorForSqlite` inspects primary keys, column types, and data types to assign the appropriate generator instance [drizzle-seed/src/services/SeedService.ts:993-997](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L993-L997). Integer primary keys map directly to `GenerateIntPrimaryKey`, whereas boolean flags and timestamps map to `GenerateBoolean` and `GenerateTimestamp` respectively [drizzle-seed/src/services/SeedService.ts:999-1015](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L999-L1015). Numeric columns with precision and scale parameters calculate a `maxAbsoluteValue` to bound `GenerateNumber` parameters [drizzle-seed/src/services/SeedService.ts:1026-1038](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L1026-L1038). ```typescript selectGeneratorForSqlite = ( table: Table, col: Column, ) => { const pickGenerator = (table: Table, col: Column) => { // int section --------------------------------------------------------------------------------------- if ( (col.columnType === 'integer' || col.columnType === 'numeric') && table.primaryKeys.includes(col.name) ) { const generator = new generatorsMap.GenerateIntPrimaryKey[0](); return generator; } if (col.columnType === 'integer' && col.dataType === 'boolean') { const generator = new generatorsMap.GenerateBoolean[0](); return generator; } if ((col.columnType === 'integer' && col.dataType === 'date')) { const generator = new generatorsMap.GenerateTimestamp[0](); return generator; } if ( col.columnType === 'integer' || (col.dataType === 'bigint' && col.columnType === 'blob') ) { const generator = new generatorsMap.GenerateInt[0](); return generator; } // number section ------------------------------------------------------------------------------------ if (col.columnType.startsWith('real') || col.columnType.startsWith('numeric')) { if (col.typeParams.precision !== undefined) { const precision = col.typeParams.precision; const scale = col.typeParams.scale === undefined ? 0 : col.typeParams.scale; const maxAbsoluteValue = Math.pow(10, precision - scale) - Math.pow(10, -scale); const generator = new generatorsMap.GenerateNumber[0]({ minValue: -maxAbsoluteValue, maxValue: maxAbsoluteValue, precision: Math.pow(10, scale), }); return generator; } const generator = new generatorsMap.GenerateNumber[0](); return generator; } ``` Sources: [drizzle-seed/src/services/SeedService.ts:993-1043](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L993-L1043) Text, numeric, and blob columns undergo pattern matching against column names to assign domain-specific generators such as `GenerateFirstName` and `GenerateEmail`, falling back to `GenerateString` or `GenerateUniqueString` depending on primary key status [drizzle-seed/src/services/SeedService.ts:1045-1083](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L1045-L1083). | Column Condition | Column Type / Metadata | Assigned Generator | | :--- | :--- | :--- | | Primary Key Integer | `integer` / `numeric` + primary key | `GenerateIntPrimaryKey` | | Boolean Flag | `integer` + `dataType: 'boolean'` | `GenerateBoolean` | | Timestamp | `integer` + `dataType: 'date'` | `GenerateTimestamp` | | Standard Integer | `integer` / `blob` (`bigint`) | `GenerateInt` | | Bounded Number | `real` / `numeric` + precision params | `GenerateNumber` (with custom bounds) | | Unique Text | `text` / `numeric` / `blob` + primary key | `GenerateUniqueString` | | Name Field | `text` / `numeric` / `blob` + name includes `'name'` | `GenerateFirstName` | | Email Field | `text` / `numeric` / `blob` + name includes `'email'` | `GenerateEmail` | Sources: [drizzle-seed/src/services/SeedService.ts:999-1073](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L999-L1073) > [!WARNING] > Property propagation during version selection currently copies `notNull`, `dataType`, and `stringLength` properties, but the engine notes that only `GenerateValuesFromArray` fully supports runtime enforcement of the `notNull` property [drizzle-seed/src/services/SeedService.ts:291-293](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L291-L293), [drizzle-seed/src/services/SeedService.ts:331-333](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L331-L333). Sources: [drizzle-seed/src/services/SeedService.ts:291-293](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L291-L293), [drizzle-seed/src/services/SeedService.ts:331-333](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L331-L333) ## Database Mutation Execution ### Cyclic Table Validation and Ordering Before executing record generation and database insertion, `seedMySql` inspects schema relationships to identify cyclic dependencies [drizzle-seed/src/index.ts:926-928](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L926-L928). When tables participate in cyclic relationships, `preserveCyclicTablesData` is enabled to manage foreign key constraints across interdependent entities [drizzle-seed/src/index.ts:939-946](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L939-L946). > [!CAUTION] > `cyclicTablesCompare` explicitly throws an error if two cyclic tables both contain `notNull` foreign key columns, as the engine cannot seed cyclic relationships with mandatory foreign keys [drizzle-seed/src/services/SeedService.ts:355-359](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L355-L359). Sources: [drizzle-seed/src/services/SeedService.ts:355-359](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L355-L359) ```typescript cyclicTablesCompare = ( table1: Table, table2: Table, relation: Relation & { isCyclic: boolean }, reverseRelation: Relation & { isCyclic: boolean } | undefined, ) => { // TODO: revise const hasTable1NotNullColumns = relation.columns.some((colIName) => table1.columns.find((colJ) => colJ.name === colIName)?.notNull === true ); if (reverseRelation !== undefined) { const hasTable2NotNullColumns = reverseRelation.columns.some((colIName) => table2.columns.find((colJ) => colJ.name === colIName)?.notNull === true ); if (hasTable1NotNullColumns && hasTable2NotNullColumns) { throw new Error( `The '${table1.name}' and '${table2.name}' tables have not null foreign keys. You can't seed cyclic tables with not null foreign key columns.`, ); } if (hasTable1NotNullColumns) return 1; else if (hasTable2NotNullColumns) return -1; return 0; } ``` Sources: [drizzle-seed/src/services/SeedService.ts:339-364](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L339-L364) ### Table Value Generation and Insertion Pipeline `SeedService` drives the generation of record values across ordered topological tables and handles subsequent filtering of cyclic relations to perform secondary updates [drizzle-seed/src/index.ts:941-960](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L941-L960). For MySQL environments, `resetMySql` temporarily disables foreign key checks by executing `SET FOREIGN_KEY_CHECKS = 0;`, truncates each target table using raw SQL statements, and restores foreign key checks with `SET FOREIGN_KEY_CHECKS = 1;` before inserting generated batches [drizzle-seed/src/index.ts:867-884](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L867-L884). | Step | Action | Execution Details | | :--- | :--- | :--- | | 1 | Table Filtering & Info Extraction | Filters schema definitions into valid MySQL tables and relations via `filterMysqlTables` and `getMySqlInfo` [drizzle-seed/src/index.ts:926-927](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L926-L927). | | 2 | Initial Value Generation | Generates initial table values via `generateTablesValues` with cyclic preservation enabled [drizzle-seed/src/index.ts:941-947](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L941-L947). | | 3 | Cyclic Filtering | Filters cyclic table generators using `filterCyclicTables` to isolate unique non-null columns needing deferred updates [drizzle-seed/src/index.ts:949-952](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L949-L952). | | 4 | Secondary Database Update | Executes subsequent row updates in the database when filtered generators are present [drizzle-seed/src/index.ts:954-960](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L954-L960). | Sources: [drizzle-seed/src/index.ts:926-960](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L926-L960) ## Related - [Seed Data Generators](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/ecosystem-packages/seed-data-generators) - [Table and Column Models](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/table-and-column-models) --- ## Technical docs: Seed Data Generators URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/ecosystem-packages/seed-data-generators
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-seed/src/services/Generators.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/Generators.ts) - [drizzle-seed/src/services/SeedService.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts) - [drizzle-seed/src/services/GeneratorFuncs.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/GeneratorFuncs.ts) - [drizzle-kit/src/introspect-pg.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-pg.ts) - [drizzle-seed/src/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts) - [drizzle-seed/src/services/versioning/v2.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/versioning/v2.ts) - [drizzle-seed/src/types/seedService.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/types/seedService.ts) - [drizzle-seed/type-tests/pg.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/type-tests/pg.ts) - [drizzle-seed/type-tests/sqlite.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/type-tests/sqlite.ts) - [drizzle-seed/src/datasets/countries.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/datasets/countries.ts) - [drizzle-seed/src/datasets/emailDomains.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/datasets/emailDomains.ts) - [drizzle-seed/src/datasets/jobsTitles.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/datasets/jobsTitles.ts)
## Overview Seed data generators power the [Seed Service Engine](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/ecosystem-packages/seed-service-engine) by programmatically constructing typed mock values for database columns across PostgreSQL, MySQL, and SQLite. Built upon a unified class architecture with deterministic pseudo-random number generation, these generators map database types and column constraints to realistic synthetic datasets, unique identifiers, and weighted distributions. Sources: [drizzle-seed/src/services/Generators.ts:17-67](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/Generators.ts#L17-L67), [drizzle-seed/src/services/SeedService.ts:503-795](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L503-L795) ## Abstract Generator Base Architecture ### Class Lifecycle and Properties The foundational abstract class `AbstractGenerator` establishes the common contract, static metadata, and runtime properties shared by all mock data generators in `drizzle-seed`. Every concrete generator inherits static properties such as `entityKind` (defaulting to `'AbstractGenerator'`) and `version` (defaulting to `1`), alongside instance flags including `isUnique`, `notNull`, `dataType`, `timeSpent`, `arraySize`, `baseColumnDataType`, and `stringLength`. ```typescript export abstract class AbstractGenerator { static readonly entityKind: string = 'AbstractGenerator'; static readonly version: number = 1; public isUnique = false; public notNull = false; // param for generators which have a unique version of themselves public uniqueVersionOfGen?: new(params: T) => AbstractGenerator; public dataType?: string; public timeSpent?: number; // public arraySize?: number; public baseColumnDataType?: string; // param for text-like generators public stringLength?: number; // params for GenerateValuesFromArray public weightedCountSeed?: number | undefined; public maxRepeatedValuesCount?: number | { weight: number; count: number | number[] }[] | undefined; public params: T; constructor(params?: T) { this.params = params === undefined ? {} as T : params as T; } ``` Sources: [drizzle-seed/src/services/Generators.ts:17-45](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/Generators.ts#L17-L45) The lifecycle of a generator proceeds from instantiation through parameter initialization and value generation. When instantiated without parameters, it assigns an empty object. Subclasses implement the abstract `generate({ i }: { i: number })` method to emit typed values for individual row iterations. ```typescript init(params: { count: number | { weight: number; count: number | number[] }[]; seed: number }): void; init() { this.updateParams(); } updateParams() { if ((this.params as any).arraySize !== undefined) { this.arraySize = (this.params as any).arraySize; } if ((this.params as any).isUnique !== undefined) { if ((this.params as any).isUnique === false && this.isUnique === true) { throw new Error('specifying non unique generator to unique column.'); } this.isUnique = (this.params as any).isUnique; } } abstract generate(params: { i: number }): number | string | boolean | unknown | undefined | void; ``` Sources: [drizzle-seed/src/services/Generators.ts:47-67](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/Generators.ts#L47-L67) ### Parameter Synchronization Protocol The `updateParams()` method normalizes configuration state by synchronizing runtime options from the parameter object onto instance properties. Specifically, it maps `arraySize` and enforces constraints on `isUnique`. If parameters specify `isUnique: false` on an instance where `isUnique` is already `true`, it throws a fatal error preventing non-unique generators from binding to unique database columns. ```typescript updateParams() { if ((this.params as any).arraySize !== undefined) { this.arraySize = (this.params as any).arraySize; } if ((this.params as any).isUnique !== undefined) { if ((this.params as any).isUnique === false && this.isUnique === true) { throw new Error('specifying non unique generator to unique column.'); } this.isUnique = (this.params as any).isUnique; } } ``` Sources: [drizzle-seed/src/services/Generators.ts:52-64](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/Generators.ts#L52-L64) > [!CAUTION] > Attempting to pass `isUnique: false` to a generator configured for a unique column triggers an immediate `Error('specifying non unique generator to unique column.')`. Always verify column constraints before modifying generator uniqueness parameters. In addition to parameter synchronization, `AbstractGenerator` provides structural replacement handlers for unique constraint escalation and array column wrapping. The `replaceIfUnique()` method checks for a registered `uniqueVersionOfGen` constructor and `isUnique` flag, instantiating the specialized unique variant while preserving data types and parameters. Similarly, `replaceIfArray()` detects non-array generators flagged with an `arraySize`, wrapping the base or unique generator inside a `GenerateArray` container instance. ```typescript replaceIfUnique() { this.updateParams(); if ( this.uniqueVersionOfGen !== undefined && this.isUnique === true ) { const uniqueGen = new this.uniqueVersionOfGen({ ...this.params, }); uniqueGen.isUnique = this.isUnique; uniqueGen.dataType = this.dataType; return uniqueGen; } return; } replaceIfArray() { this.updateParams(); if (!(this.getEntityKind() === 'GenerateArray') && this.arraySize !== undefined) { const uniqueGen = this.replaceIfUnique(); const baseColumnGen = uniqueGen === undefined ? this : uniqueGen; baseColumnGen.dataType = this.baseColumnDataType; const arrayGen = new GenerateArray( { baseColumnGen, size: this.arraySize, }, ); return arrayGen; } return; } ``` Sources: [drizzle-seed/src/services/Generators.ts:73-108](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/Generators.ts#L73-L108) ### Pseudo-Random Number Generation with Pure-Rand Generators requiring random distributions initialize stateful pseudo-random number generators (PRNGs) via the `pure-rand` library. For instance, `GenerateWeightedCount` seeds a `prand.xoroshiro128plus` instance alongside precalculated weighted index arrays, sampling uniform integer distributions across configured frequency weights during generation cycles. ```typescript override init({ seed, count }: { count: { weight: number; count: number | number[] }[]; seed: number }) { const rng = prand.xoroshiro128plus(seed); const weightedIndices = getWeightedIndices(count.map((val) => val.weight)); this.state = { rng, weightedIndices, weightedCount: count }; } generate() { if (this.state === undefined) { throw new Error('state is not defined.'); } // logic for this generator let idx: number; const weightedCount = this.state.weightedCount; [idx, this.state.rng] = prand.uniformIntDistribution(0, this.state.weightedIndices.length - 1, this.state.rng); const objIdx = this.state.weightedIndices[idx] as number; if (typeof weightedCount[objIdx]!.count === 'number') { return weightedCount[objIdx]!.count as number; } else { // typeof weightedCount[objIdx]!.count === 'object' // number[] const possCounts = weightedCount[objIdx]!.count as number[]; [idx, this.state.rng] = prand.uniformIntDistribution(0, possCounts.length - 1, this.state.rng); return possCounts[idx]!; } } ``` Sources: [drizzle-seed/src/services/Generators.ts:141-167](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/Generators.ts#L141-L167) > [!NOTE] > `drizzle-seed` relies exclusively on `prand.xoroshiro128plus` combined with explicit numeric seeds passed into generator `init` methods, guaranteeing fully reproducible test data across execution runs and database engines. ## Primitive and Temporal Generators ### Integer and Numeric Generators The `drizzle-seed` engine handles primitive numeric types through dedicated generators designed to cover integer scalars, floating-point numbers, and coordinate systems. The `GeneratePoint` and `GenerateUniquePoint` classes instantiate underlying `GenerateNumber` and `GenerateUniqueNumber` instances with default precisions set to 10 decimal places, supporting coordinate bounds via `minXValue`, `maxXValue`, `minYValue`, and `maxYValue` parameters. Depending on the target column data type, point generators emit values as JSON objects, coordinate string tuples, or native arrays. ```typescript export class GeneratePoint extends AbstractGenerator<{ isUnique?: boolean; minXValue?: number; maxXValue?: number; minYValue?: number; maxYValue?: number; arraySize?: number; }> { static override readonly entityKind: string = 'GeneratePoint'; private state: { xCoordinateGen: GenerateNumber; yCoordinateGen: GenerateNumber; } | undefined; override uniqueVersionOfGen = GenerateUniquePoint; override init({ count, seed }: { count: number; seed: number }) { super.init({ count, seed }); const xCoordinateGen = new GenerateNumber({ minValue: this.params.minXValue, maxValue: this.params.maxXValue, precision: 10, }); xCoordinateGen.init({ count, seed }); const yCoordinateGen = new GenerateNumber({ minValue: this.params.minYValue, maxValue: this.params.maxYValue, precision: 10, }); yCoordinateGen.init({ count, seed }); this.state = { xCoordinateGen, yCoordinateGen }; } generate() { if (this.state === undefined) { throw new Error('state is not defined.'); } const x = this.state.xCoordinateGen.generate(); const y = this.state.yCoordinateGen.generate(); if (this.dataType === 'json') { return { x, y }; } else if (this.dataType === 'string') { return `[${x}, ${y}]`; } else { // if (this.dataType === "array") return [x, y]; } } } export class GenerateUniquePoint extends AbstractGenerator<{ minXValue?: number; maxXValue?: number; minYValue?: number; maxYValue?: number; isUnique?: boolean; }> { static override readonly entityKind: string = 'GenerateUniquePoint'; private state: { xCoordinateGen: GenerateUniqueNumber; yCoordinateGen: GenerateUniqueNumber; } | undefined; public override isUnique = true; override init({ count, seed }: { count: number; seed: number }) { const xCoordinateGen = new GenerateUniqueNumber({ minValue: this.params.minXValue, maxValue: this.params.maxXValue, precision: 10, }); xCoordinateGen.init({ count, seed }); const yCoordinateGen = new GenerateUniqueNumber({ minValue: this.params.minYValue, ``` Sources: [drizzle-seed/src/services/Generators.ts:2873-2978](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/Generators.ts#L2873-L2978) Geometric entity generation extends to linear equations via `GenerateLine`, which parameterizes linear coefficients across configurable minimum and maximum bounds for variables $A$, $B$, and $C$. ```typescript export class GenerateLine extends AbstractGenerator<{ isUnique?: boolean; minAValue?: number; maxAValue?: number; minBValue?: number; maxBValue?: number; minCValue?: number; maxCValue?: number; arraySize?: number; }> { static override readonly entityKind: string = 'GenerateLine'; private state: { aCoefficientGen: GenerateNumber; bCoefficientGen: GenerateNumber; cCoefficientGen: GenerateNumber; } | undefined; override uniqueVersionOfGen = GenerateUniqueLine; ``` Sources: [drizzle-seed/src/services/Generators.ts:2980-2998](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/Generators.ts#L2980-L2998) > [!NOTE] > Point generators inspect the target column's `dataType` property at runtime, switching output formats dynamically between `{ x, y }` for JSON columns, `[x, y]` strings for string columns, and JavaScript arrays for array columns. ### Text and Paragraph Generators Text-based primitive generation includes `GenerateLoremIpsum`, which builds multi-sentence lorem ipsum text blocks using predefined sentence datasets. The initialization phase computes the maximum possible string length based on the requested sentence count and compares it against database column length restrictions. ```typescript export class GenerateLoremIpsum extends AbstractGenerator<{ sentencesCount?: number; arraySize?: number; }> { static override readonly entityKind: string = 'GenerateLoremIpsum'; private state: { rng: prand.RandomGenerator; } | undefined; override init({ count, seed }: { count: number; seed: number }) { super.init({ count, seed }); const rng = prand.xoroshiro128plus(seed); if (this.params.sentencesCount === undefined) this.params.sentencesCount = 1; const maxLoremIpsumSentencesLength = maxLoremIpsumLength * this.params.sentencesCount + this.params.sentencesCount - 1; if (this.stringLength !== undefined && this.stringLength < maxLoremIpsumSentencesLength) { throw new Error( `You can't use lorem ipsum generator with a db column length restriction of ${this.stringLength}. Set the maximum string length to at least ${maxLoremIpsumSentencesLength}.`, ); } this.state = { rng }; } ``` Sources: [drizzle-seed/src/services/Generators.ts:2768-2793](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/Generators.ts#L2768-L2793) During generation, `GenerateLoremIpsum` samples uniform integer distributions across the dataset of lorem ipsum sentences using `prand.xoroshiro128plus`, concatenating the selected sentences into the final result string. ```typescript generate() { if (this.state === undefined) { throw new Error('state is not defined.'); } let idx, resultText: string = ''; for (let i = 0; i < this.params.sentencesCount!; i++) { [idx, this.state.rng] = prand.uniformIntDistribution(0, loremIpsumSentences.length - 1, this.state.rng); resultText += loremIpsumSentences[idx] + ' '; } return resultText; } } ``` Sources: [drizzle-seed/src/services/Generators.ts:2795-2808](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/Generators.ts#L2795-L2808) > [!CAUTION] > If a database column enforces a maximum string length that is smaller than the minimum required size for the requested lorem ipsum sentence count, `GenerateLoremIpsum` throws an explicit error during `init()`. Always verify column length constraints when configuring paragraph generators. ## Realistic Entity Datasets ### Static Corpora and Bounded String Lengths `drizzle-seed` incorporates static domain datasets to supply contextually accurate mock records for geographic, professional, and contact attributes. These corpora are paired with explicit string length constants to validate column schema boundaries before execution. The country dataset provides 170 recognized country names derived from census and geographical repositories, with a maximum string length boundary of 30 characters. ```typescript export default [ 'Afghanistan', 'Albania', 'Algeria', 'Angola', 'Antigua and Barbuda', 'Argentina', 'Armenia', 'Australia', 'Austria', 'Azerbaijan', 'Bahamas', 'Bahrain', 'Bangladesh', 'Barbados', 'Belgium', 'Belize', 'Benin', 'Bhutan', 'Bolivia', 'Bosnia and Herzegovina', 'Botswana', 'Brazil', 'Brunei', 'Bulgaria', 'Burkina Faso', 'Burundi', 'Cambodia', 'Cameroon', 'Canada', 'Cape Verde', 'Central African Republic', 'Chad', 'Chile', 'China', 'Colombia', 'Comoros', 'Congo, Dem. Rep.', 'Congo, Rep.', 'Costa Rica', "Cote d'Ivoire", 'Croatia', 'Cyprus', 'Czech Republic', 'Denmark', 'Dominican Republic', 'Ecuador', 'Egypt', 'El Salvador', 'Equatorial Guinea', 'Eritrea', 'Estonia', 'Fiji', 'Finland', 'France', 'Gabon', 'Gambia', 'Georgia', 'Germany', 'Ghana', 'Greece', 'Grenada', 'Guatemala', 'Guinea', 'Guinea-Bissau', 'Guyana', 'Haiti', 'Hungary', 'Iceland', 'India', 'Indonesia', 'Iran', 'Iraq', 'Ireland', 'Israel', 'Italy', 'Jamaica', 'Japan', 'Jordan', 'Kazakhstan', ``` Sources: [drizzle-seed/src/datasets/countries.ts:5-171](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/datasets/countries.ts#L5-L171), [drizzle-seed/src/datasets/countries.ts:173](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/datasets/countries.ts#L173) Email domains comprise 23 global messaging providers and regional top-level domains, accompanied by a maximum string length constraint of 14 characters. ```typescript export default [ 'gmail.com', 'yahoo.com', 'outlook.com', 'msn.com', 'hotmail.com', 'aol.com', 'hotmail.co.uk', 'hotmail.fr', 'yahoo.fr', 'wanadoo.fr', 'orange.fr', 'comcast.net', 'yahoo.co.uk', 'yahoo.com.br', 'yahoo.co.in', 'live.com', 'rediffmail.com', 'free.fr', 'gmx.de', 'web.de', 'ymail.com', 'libero.it', ]; … export const maxStringLength = 14; ``` Sources: [drizzle-seed/src/datasets/emailDomains.ts:1-24](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/datasets/emailDomains.ts#L1-L24), [drizzle-seed/src/datasets/emailDomains.ts:26](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/datasets/emailDomains.ts#L26) Professional titles encompass 152 distinct job roles spanning engineering, management, healthcare, and administrative specializations, bounded by a maximum string length of 35 characters. ```typescript export default [ 'Digital marketing specialist', 'Web developer', 'Operations manager', 'Network engineer', 'Event manager', 'Software tester', 'Teacher', 'Ux/ui designer', 'Wedding planner', 'Qa analyst', 'Litigation attorney', 'Mechanical engineer', 'Network administrator', 'Account manager', 'Brand manager', 'Social worker', 'Social media coordinator', 'Email marketing specialist', 'Hr generalist', 'Legal assistant', 'Nurse practitioner', 'Account director', 'Software engineer', 'Purchasing agent', 'Sales consultant', 'Civil engineer', 'Network security specialist', 'Ui developer', 'Financial planner', 'Event planner', 'Psychologist', 'Electrical designer', 'Data analyst', 'Technical writer', 'Tax consultant', 'Account executive', 'Systems administrator', 'Database administrator', 'Research analyst', 'Data entry clerk', 'Registered nurse', 'Investment analyst', 'Speech therapist', 'Sales manager', 'Landscape architect', 'Key account manager', 'Ux researcher', 'Investment banker', 'It support specialist', 'Art director', 'Software developer', 'Project manager', 'Customer service manager', 'Procurement manager', 'Substance abuse counselor', 'Supply chain analyst', 'Data engineer', 'Accountant', 'Sales representative', 'Environmental consultant', 'Electrical engineer', 'Systems engineer', 'Art teacher', 'Human resources manager', 'Inventory analyst', 'Legal counsel', 'Database developer', 'Procurement specialist', 'Systems analyst', 'Copywriter', 'Content writer', 'Hr coordinator', 'Business development manager', 'Java developer', 'Supply chain manager', 'Event coordinator', 'Family nurse practitioner', 'Front-end engineer', 'Customer success manager', ``` Sources: [drizzle-seed/src/datasets/jobsTitles.ts:4-152](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/datasets/jobsTitles.ts#L4-L152), [drizzle-seed/src/datasets/jobsTitles.ts:154](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/datasets/jobsTitles.ts#L154) > [!NOTE] > Specific geographic entries and administrative subdivisions are intentionally filtered out from standard datasets during curation to prevent inappropriate records from populating relational columns. ### Dataset Schema Summary | Dataset Module | Sample Entries / Categories | Maximum String Length | Primary Source Reference | | :--- | :--- | :--- | :--- | | `countries.ts` | Afghanistan, Albania, ..., Zambia | 30 | Kaggle `countrydatacsv` | | `emailDomains.ts` | gmail.com, yahoo.com, outlook.com, ..., libero.it | 14 | Native dataset corpus | | `jobsTitles.ts` | Digital marketing specialist, Web developer, ..., Market analyst | 35 | Kaggle `job-description-dataset` | Sources: [drizzle-seed/src/datasets/countries.ts:5-173](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/datasets/countries.ts#L5-L173), [drizzle-seed/src/datasets/emailDomains.ts:1-26](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/datasets/emailDomains.ts#L1-L26), [drizzle-seed/src/datasets/jobsTitles.ts:4-154](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/datasets/jobsTitles.ts#L4-L154) ## Unique Constraint Enforcement and Deduplication ### Replacement Strategies and Unique Versions `drizzle-seed` enforces column uniqueness using replacement mechanisms and specialized generator classes designed to prevent collisions. When a base generator detects that `isUnique` is set to `true`, `replaceIfUnique()` inspects the generator's `uniqueVersionOfGen` mapping and instantiates the specialized variant with preserved parameters and data types. ```typescript replaceIfUnique() { this.updateParams(); if ( this.uniqueVersionOfGen !== undefined && this.isUnique === true ) { const uniqueGen = new this.uniqueVersionOfGen({ ...this.params, }); uniqueGen.isUnique = this.isUnique; uniqueGen.dataType = this.dataType; return uniqueGen; } return; } ``` Sources: [drizzle-seed/src/services/Generators.ts:73-89](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/Generators.ts#L73-L89) For instance, `GeneratePoint` maps its `uniqueVersionOfGen` property directly to `GenerateUniquePoint`, ensuring that coordinates are generated through dedicated unique numeric generators for each axis. ```typescript override uniqueVersionOfGen = GenerateUniquePoint; ``` Sources: [drizzle-seed/src/services/Generators.ts:2887](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/Generators.ts#L2887) ```typescript public override isUnique = true; override init({ count, seed }: { count: number; seed: number }) { const xCoordinateGen = new GenerateUniqueNumber({ minValue: this.params.minXValue, maxValue: this.params.maxXValue, precision: 10, }); xCoordinateGen.init({ count, seed }); const yCoordinateGen = new GenerateUniqueNumber({ minValue: this.params.minYValue, maxValue: this.params.maxYValue, precision: 10, }); yCoordinateGen.init({ count, seed }); this.state = { xCoordinateGen, yCoordinateGen }; } ``` Sources: [drizzle-seed/src/services/Generators.ts:2941-2959](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/Generators.ts#L2941-L2959) > [!WARNING] > Specifying a non-unique generator class directly on a column marked with a unique constraint throws an immediate error during parameter updates via `updateParams()`, preventing invalid database seeding configurations before execution. ```typescript if ((this.params as any).isUnique !== undefined) { if ((this.params as any).isUnique === false && this.isUnique === true) { throw new Error('specifying non unique generator to unique column.'); } this.isUnique = (this.params as any).isUnique; } ``` Sources: [drizzle-seed/src/services/Generators.ts:57-63](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/Generators.ts#L57-L63) ### String and Temporal Uniqueness Deduplication String and temporal generators implement explicit boundary validations and collision-avoidance loops during initialization and record generation. `GenerateUniqueStringV2` converts the loop index `i` into a hexadecimal string (`i.toString(16)`) and pads it with randomly sampled character distributions to guarantee absolute uniqueness across requested row counts. ```typescript generate({ i }: { i: number }) { if (this.state === undefined) { throw new Error('state is not defined.'); } const minStringLength = this.state.minStringLength, maxStringLength = this.state.maxStringLength; const stringChars = '1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'; let idx: number, strLength: number; let currStr: string; currStr = ''; const uniqueStr = i.toString(16); [strLength, this.state.rng] = prand.uniformIntDistribution( minStringLength, maxStringLength - uniqueStr.length, this.state.rng, ); for (let j = 0; j < strLength - uniqueStr.length; j++) { [idx, this.state.rng] = prand.uniformIntDistribution( 0, stringChars.length - 1, this.state.rng, ); currStr += stringChars[idx]; } return uniqueStr + currStr; } ``` Sources: [drizzle-seed/src/services/versioning/v2.ts:202-231](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/versioning/v2.ts#L202-L231) If the requested count exceeds the combinatorial capacity of the maximum string length, `GenerateUniqueStringV2` throws a descriptive error. ```typescript if (maxStringLength < count.toString(16).length) { throw new Error( `You can't generate ${count} unique strings, with a maximum string length of ${maxStringLength}.`, ); } ``` Sources: [drizzle-seed/src/services/versioning/v2.ts:193-197](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/versioning/v2.ts#L193-L197) Similarly, `GenerateUniqueIntervalV2` calculates the maximum possible unique intervals using a configuration map of field boundaries spanning years down to seconds. If the requested record count exceeds this calculated ceiling, a `RangeError` is thrown. ```typescript private config: { [key: string]: { from: number; to: number } } = { year: { from: 0, to: 5, }, month: { from: 0, to: 11, }, day: { from: 0, to: 29, }, hour: { from: 0, to: 23, }, minute: { from: 0, to: 59, }, second: { from: 0, to: 59, }, }; override init({ count, seed }: { count: number; seed: number }) { const allFields = ['year', 'month', 'day', 'hour', 'minute', 'second']; let fieldsToGenerate: string[] = allFields; if (this.params.fields !== undefined && this.params.fields?.includes(' to ')) { const tokens = this.params.fields.split(' to '); const endIdx = allFields.indexOf(tokens[1]!); fieldsToGenerate = allFields.slice(0, endIdx + 1); } else if (this.params.fields !== undefined) { const endIdx = allFields.indexOf(this.params.fields); fieldsToGenerate = allFields.slice(0, endIdx + 1); } let maxUniqueIntervalsNumber = 1; for (const field of fieldsToGenerate) { const from = this.config[field]!.from, to = this.config[field]!.to; maxUniqueIntervalsNumber *= from - to + 1; } if (count > maxUniqueIntervalsNumber) { throw new RangeError(`count exceeds max number of unique intervals(${maxUniqueIntervalsNumber})`); } ``` Sources: [drizzle-seed/src/services/versioning/v2.ts:31-79](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/versioning/v2.ts#L31-L79) When generating records, `GenerateUniqueIntervalV2` populates an internal `Set` (`intervalSet`), retrying uniform distributions until an unrecorded unique interval string is secured. ```typescript generate() { if (this.state === undefined) { throw new Error('state is not defined.'); } let interval, numb: number; for (;;) { interval = ''; for (const field of this.state.fieldsToGenerate) { const from = this.config[field]!.from, to = this.config[field]!.to; [numb, this.state.rng] = prand.uniformIntDistribution(from, to, this.state.rng); interval += `${numb} ${field} `; } if (!this.state.intervalSet.has(interval)) { this.state.intervalSet.add(interval); break; } } return interval; } } ``` Sources: [drizzle-seed/src/services/versioning/v2.ts:86-110](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/versioning/v2.ts#L86-L110) > [!CAUTION] > Relying on retry loops with `Set` collections can introduce performance bottlenecks if the requested count approaches the total combinatorial limit of the underlying configuration domain. ## Weighted Random Distributions ### Weighted Array and Count Distribution Mechanics `drizzle-seed` implements non-uniform value selection using weighted distribution engines built on top of the `pure-rand` Xoroshiro128plus PRNG. The `GenerateWeightedCount` class manages counts associated with explicit weights, utilizing helper utilities to resolve index probabilities. During initialization, `GenerateWeightedCount` maps user-defined weights into an array of weighted indices via `getWeightedIndices`, allowing frequency-based selection during record generation. ```typescript override init({ seed, count }: { count: { weight: number; count: number | number[] }[]; seed: number }) { const rng = prand.xoroshiro128plus(seed); const weightedIndices = getWeightedIndices(count.map((val) => val.weight)); this.state = { rng, weightedIndices, weightedCount: count }; } ``` Sources: [drizzle-seed/src/services/Generators.ts:141-145](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/Generators.ts#L141-L145) When `generate()` is invoked, uniform integer distribution selects an index from the precomputed weighted array. If the target count entry contains a single numeric value, it is returned directly; if the entry defines an array of possible counts, a secondary uniform distribution resolves the specific integer count to return. ```typescript let idx: number; const weightedCount = this.state.weightedCount; [idx, this.state.rng] = prand.uniformIntDistribution(0, this.state.weightedIndices.length - 1, this.state.rng); const objIdx = this.state.weightedIndices[idx] as number; if (typeof weightedCount[objIdx]!.count === 'number') { return weightedCount[objIdx]!.count as number; } else { // typeof weightedCount[objIdx]!.count === 'object' // number[] const possCounts = weightedCount[objIdx]!.count as number[]; [idx, this.state.rng] = prand.uniformIntDistribution(0, possCounts.length - 1, this.state.rng); return possCounts[idx]!; } ``` Sources: [drizzle-seed/src/services/Generators.ts:153-166](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/Generators.ts#L166-L166) > [!NOTE] > If `GenerateWeightedCount` is called before its `init()` lifecycle method establishes the internal state object, an explicit runtime error is thrown to prevent unseeded execution. ```typescript if (this.state === undefined) { throw new Error('state is not defined.'); } ``` Sources: [drizzle-seed/src/services/Generators.ts:148-150](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/Generators.ts#L148-L150) ### WeightedRandomGenerator Configuration and Initialization The `WeightedRandomGenerator` class distributes generation tasks across multiple wrapped sub-generators based on assigned weighting parameters. During its initialization phase, it tabulates sample frequencies across the population count to size and initialize each underlying sub-generator properly. ```typescript override init({ count, seed }: { count: number; seed: number }) { const weights = this.params.map((weightedGen) => weightedGen.weight); const weightedIndices = getWeightedIndices(weights); let idx: number, valueIdx: number, tempRng = prand.xoroshiro128plus(seed); const indicesCounter: { [key: number]: number } = {}; for (let i = 0; i < count; i++) { [idx, tempRng] = prand.uniformIntDistribution(0, weightedIndices.length - 1, tempRng); valueIdx = weightedIndices[idx]!; if (!Object.hasOwn(indicesCounter, valueIdx)) indicesCounter[valueIdx] = 0; indicesCounter[valueIdx]! += 1; } for (const [idx, weightedGen] of this.params.entries()) { weightedGen.value.isUnique = this.isUnique; weightedGen.value.dataType = this.dataType; weightedGen.value.init({ count: indicesCounter[idx]!, seed }); ``` Sources: [drizzle-seed/src/services/Generators.ts:2818-2835](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/Generators.ts#L2835-L2835) | Generator Class | Entity Kind Identifier | Core State Parameters | Primary Purpose | | :--- | :--- | :--- | :--- | | `GenerateWeightedCount` | `GenerateWeightedCount` | `rng`, `weightedIndices`, `weightedCount` | Resolves non-uniform integer counts or ranges based on assigned weights | | `WeightedRandomGenerator` | `WeightedRandomGenerator` | `rng`, `weightedIndices` | Routes value generation across a weighted array of sub-generators | Sources: [drizzle-seed/src/services/Generators.ts:133-139](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/Generators.ts#L133-L139), [drizzle-seed/src/services/Generators.ts:2811-2816](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/Generators.ts#L2811-L2816) > [!TIP] > `WeightedRandomGenerator` automatically propagates column uniqueness flags and data types down to each weighted sub-generator, instantiating unique counterpart generator classes when unique constraints are active. ```typescript for (const [idx, weightedGen] of this.params.entries()) { weightedGen.value.isUnique = this.isUnique; weightedGen.value.dataType = this.dataType; weightedGen.value.init({ count: indicesCounter[idx]!, seed }); if ( weightedGen.value.uniqueVersionOfGen !== undefined && weightedGen.value.isUnique === true ) { const uniqueGen = new weightedGen.value.uniqueVersionOfGen({ ...weightedGen.value.params, }); uniqueGen.init({ count: indicesCounter[idx]!, seed, }); uniqueGen.isUnique = weightedGen.value.isUnique; uniqueGen.dataType = weightedGen.value.dataType; weightedGen.value = uniqueGen; } ``` Sources: [drizzle-seed/src/services/Generators.ts:2831-2851](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/Generators.ts#L2831-L2851) ## Versioned Generator Evolutions ### Versioning Interfaces and Generator Mappings `drizzle-seed` supports evolutionary versioning across generator implementations, allowing refined algorithms to be introduced without breaking legacy behavior. Generators declare their version via static properties on the `AbstractGenerator` base class and register variations in the global `generatorsMap` lookup structure. ```typescript export abstract class AbstractGenerator { static readonly entityKind: string = 'AbstractGenerator'; static readonly version: number = 1; ``` Sources: [drizzle-seed/src/services/Generators.ts:17-20](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/Generators.ts#L17-L20) | Generator Class | Entity Kind Identifier | Version | Core State Parameters / Mappings | | :--- | :--- | :--- | :--- | | `GenerateInterval` | `GenerateInterval` | 1 | Standard interval generator | | `GenerateUniqueIntervalV2` | `GenerateUniqueInterval` | 2 | `rng`, `fieldsToGenerate`, `intervalSet` | | `GenerateString` | `GenerateString` | 1 | Standard string generator | | `GenerateStringV2` | `GenerateString` | 2 | `rng`, `minStringLength`, `maxStringLength` | | `GenerateUniqueStringV2` | `GenerateUniqueString` | 2 | `rng`, `minStringLength`, `maxStringLength`, `isUnique` | Sources: [drizzle-seed/src/services/Generators.ts:816-830](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/Generators.ts#L816-L830), [drizzle-seed/src/services/versioning/v2.ts:22-29](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/versioning/v2.ts#L22-L29), [drizzle-seed/src/services/versioning/v2.ts:116-123](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/versioning/v2.ts#L116-L123), [drizzle-seed/src/services/versioning/v2.ts:172-179](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/versioning/v2.ts#L172-L179) > [!NOTE] > The `generatorsFuncsV2` object mirrors the standard generator function bindings, providing a uniform API surface for accessing updated version behaviors during schema refinement. ```typescript } if (this.state!.integersCount.get(numb) === undefined || this.state!.integersCount.get(numb) === 0) { if (numb === currMinNumb) { ``` Sources: [drizzle-seed/src/services/Generators.ts:760-763](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/Generators.ts#L760-L763) ### GenerateStringV2 and GenerateUniqueStringV2 Execution The `GenerateStringV2` class bounds random string lengths between 7 and 20 characters by default, adjusting parameters if a specific `stringLength` restriction is supplied. Its unique counterpart, `GenerateUniqueStringV2`, encodes the current iteration index `i` into a hexadecimal string prefix, appending randomly selected characters from a 62-character alphanumeric set (`stringChars`) to satisfy uniqueness constraints. ```typescript override init({ seed, count }: { seed: number; count: number }) { const rng = prand.xoroshiro128plus(seed); let minStringLength = 7; let maxStringLength = 20; // TODO: revise later if (this.stringLength !== undefined) { maxStringLength = this.stringLength; if (maxStringLength === 1 || maxStringLength < minStringLength) minStringLength = maxStringLength; } if (maxStringLength < count.toString(16).length) { throw new Error( `You can't generate ${count} unique strings, with a maximum string length of ${maxStringLength}.`, ); } this.state = { rng, minStringLength, maxStringLength }; } ``` Sources: [drizzle-seed/src/services/versioning/v2.ts:182-200](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/versioning/v2.ts#L182-L200) ```typescript generate({ i }: { i: number }) { if (this.state === undefined) { throw new Error('state is not defined.'); } const minStringLength = this.state.minStringLength, maxStringLength = this.state.maxStringLength; const stringChars = '1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'; let idx: number, strLength: number; let currStr: string; currStr = ''; const uniqueStr = i.toString(16); [strLength, this.state.rng] = prand.uniformIntDistribution( minStringLength, maxStringLength - uniqueStr.length, this.state.rng, ); for (let j = 0; j < strLength - uniqueStr.length; j++) { [idx, this.state.rng] = prand.uniformIntDistribution( 0, stringChars.length - 1, this.state.rng, ); currStr += stringChars[idx]; } return uniqueStr + currStr; } ``` Sources: [drizzle-seed/src/services/versioning/v2.ts:202-231](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/versioning/v2.ts#L202-L231) > [!WARNING] > `GenerateUniqueStringV2` throws an explicit error if the requested population `count` requires more hexadecimal characters than the allowed maximum string length permits. ```typescript if (maxStringLength < count.toString(16).length) { throw new Error( `You can't generate ${count} unique strings, with a maximum string length of ${maxStringLength}.`, ); } ``` Sources: [drizzle-seed/src/services/versioning/v2.ts:193-197](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/versioning/v2.ts#L193-L197) ## Related - [Seed Service Engine](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/ecosystem-packages/seed-service-engine) --- ## Technical docs: ESLint Plugin Drizzle URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/ecosystem-packages/eslint-plugin-drizzle
Relevant source files The following files were used as context for generating this wiki page: - [eslint-plugin-drizzle/src/enforce-update-with-where.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-update-with-where.ts) - [eslint-plugin-drizzle/src/enforce-delete-with-where.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-delete-with-where.ts) - [drizzle-kit/src/sqlgenerator.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/sqlgenerator.ts) - [eslint-plugin-drizzle/src/configs/all.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/configs/all.ts) - [drizzle-orm/src/gel-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/gel-core/dialect.ts) - [eslint-plugin-drizzle/src/configs/recommended.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/configs/recommended.ts) - [drizzle-kit/src/cli/commands/pgPushUtils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/pgPushUtils.ts) - [eslint-plugin-drizzle/src/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/index.ts) - [drizzle-orm/src/mysql-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/mysql-core/dialect.ts) - [drizzle-kit/src/serializer/gelSerializer.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/gelSerializer.ts) - [eslint-plugin-drizzle/src/utils/options.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/utils/options.ts) - [drizzle-kit/src/cli/commands/singlestorePushUtils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/singlestorePushUtils.ts) - [.eslintrc.yaml](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/.eslintrc.yaml) - [eslint-plugin-drizzle/src/utils/ast.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/utils/ast.ts) - [drizzle-orm/src/singlestore-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore-core/dialect.ts) - [drizzle-orm/type-tests/mysql/select.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/select.ts) - [drizzle-orm/type-tests/pg/select.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/select.ts) - [drizzle-orm/type-tests/mysql/delete.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/delete.ts) - [drizzle-orm/type-tests/geldb/select.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/select.ts) - [drizzle-orm/type-tests/pg/no-strict-null-checks/test.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/no-strict-null-checks/test.ts) - [drizzle-orm/type-tests/mysql/update.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/update.ts) - [drizzle-orm/type-tests/geldb/no-strict-null-checks/test.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/no-strict-null-checks/test.ts) - [drizzle-orm/type-tests/mysql/no-strict-null-checks/test.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/no-strict-null-checks/test.ts) - [drizzle-orm/type-tests/sqlite/delete.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/sqlite/delete.ts) - [drizzle-kit/src/cli/commands/mysqlPushUtils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/commands/mysqlPushUtils.ts) - [drizzle-orm/type-tests/pg/with.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/with.ts) - [drizzle-orm/type-tests/singlestore/delete.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/delete.ts) - [drizzle-orm/type-tests/sqlite/no-strict-null-checks/test.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/sqlite/no-strict-null-checks/test.ts)
## Overview The `eslint-plugin-drizzle` package provides static analysis rules for Drizzle ORM to prevent destructive, accidental database modifications during development. It exposes rule modules for enforcing conditional `where` clauses on both deletion and update operations, protecting against accidental whole-table wipes. Sources: [eslint-plugin-drizzle/src/index.ts:9-12](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/index.ts#L9-L12), [eslint-plugin-drizzle/src/enforce-delete-with-where.ts:16-17](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-delete-with-where.ts#L16-L17), [eslint-plugin-drizzle/src/enforce-update-with-where.ts:15-17](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-update-with-where.ts#L15-L17) The plugin bundles ready-to-use configuration presets, including `recommended` and `all`, which register rules such as `drizzle/enforce-delete-with-where` and `drizzle/enforce-update-with-where` as compilation errors. Sources: [eslint-plugin-drizzle/src/configs/recommended.ts:10-13](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/configs/recommended.ts#L10-L13), [eslint-plugin-drizzle/src/configs/all.ts:10-13](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/configs/all.ts#L10-L13), [eslint-plugin-drizzle/src/index.ts:14](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/index.ts#L14) By traversing abstract syntax tree (AST) member expressions and call chains via custom AST resolution utilities, the plugin matches configured database client identifiers and flags query builders missing explicit filter conditions. Sources: [eslint-plugin-drizzle/src/enforce-delete-with-where.ts:36-47](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-delete-with-where.ts#L36-L47), [eslint-plugin-drizzle/src/enforce-update-with-where.ts:35-54](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-update-with-where.ts#L35-L54), [eslint-plugin-drizzle/src/utils/ast.ts:3-35](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/utils/ast.ts#L3-L35), [eslint-plugin-drizzle/src/utils/options.ts:23-41](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/utils/options.ts#L23-L41) ## Plugin Architecture and Rule Exports ### Rule and Configuration Registrations The `eslint-plugin-drizzle` entry point exports rules, configuration presets, and package metadata directly from its main module definition. The `rules` export object registers two specific static analysis rules (`enforce-delete-with-where` and `enforce-update-with-where`), typed against `TSESLint.RuleModule` using TypeScript's `satisfies` operator. Package version and name details are dynamically imported from `package.json` into the `meta` export property. ```typescript import type { TSESLint } from '@typescript-eslint/utils'; import { name, version } from '../package.json'; import all from './configs/all'; import recommended from './configs/recommended'; import deleteRule from './enforce-delete-with-where'; import updateRule from './enforce-update-with-where'; import type { Options } from './utils/options'; export const rules = { 'enforce-delete-with-where': deleteRule, 'enforce-update-with-where': updateRule, } satisfies Record>; export const configs = { all, recommended }; export const meta = { name, version }; ``` Sources: [eslint-plugin-drizzle/src/index.ts:1-16](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/index.ts#L1-L16) | Export Name | Target Property / Source Module | Type / Definition | | :--- | :--- | :--- | | `rules` | `'enforce-delete-with-where'`, `'enforce-update-with-where'` | `Record>` | | `configs` | `all`, `recommended` | Presets object containing rulesets | | `meta` | `name`, `version` | Imported from `../package.json` | Sources: [eslint-plugin-drizzle/src/index.ts:9-16](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/index.ts#L9-L16) > [!NOTE] > The `rules` record satisfies `TSESLint.RuleModule`, binding rule implementations to custom option types defined in `./utils/options`. > Sources: [eslint-plugin-drizzle/src/index.ts:7-12](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/index.ts#L7-L12) ## Bundled Configuration Presets ### Preset Ruleset Configurations The plugin defines two prepackaged configuration files, `recommended.ts` and `all.ts`, which share identical environment and rule settings to enforce query safety constraints. Both configuration exports configure the parser and environment settings for modern JavaScript and TypeScript projects while registering the core safety rules as errors. ```typescript export default { env: { es2024: true, }, parserOptions: { ecmaVersion: 'latest', sourceType: 'module', }, plugins: ['drizzle'], rules: { 'drizzle/enforce-delete-with-where': 'error', 'drizzle/enforce-update-with-where': 'error', }, }; ``` Sources: [eslint-plugin-drizzle/src/configs/recommended.ts:1-14](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/configs/recommended.ts#L1-L14) | Configuration Property | Value / Setting | Purpose | | :--- | :--- | :--- | | `env.es2024` | `true` | Enables ES2024 global variables and syntax parsing | | `parserOptions.ecmaVersion` | `'latest'` | Sets the ECMAScript version to the latest standard | | `parserOptions.sourceType` | `'module'` | Treats files as ECMAScript modules | | `plugins` | `['drizzle']` | Registers the `drizzle` plugin namespace | | `rules['drizzle/enforce-delete-with-where']` | `'error'` | Flags table deletions lacking a `where` filter | | `rules['drizzle/enforce-update-with-where']` | `'error'` | Flags table updates lacking a `where` filter | Sources: [eslint-plugin-drizzle/src/configs/recommended.ts:1-14](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/configs/recommended.ts#L1-L14), [eslint-plugin-drizzle/src/configs/all.ts:1-14](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/configs/all.ts#L1-L14) > [!NOTE] > The `all.ts` preset mirrors `recommended.ts` completely, establishing identical strict error reporting for both configuration exports across the codebase. > Sources: [eslint-plugin-drizzle/src/configs/all.ts:1-14](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/configs/all.ts#L1-L14) ## Enforcing WHERE Clauses on Deletions ### Static Analysis and Rule Metadata The `enforce-delete-with-where` rule uses `@typescript-eslint/utils` to inspect Abstract Syntax Trees (AST) and prevent accidental execution of unconstrained table deletions [eslint-plugin-drizzle/src/enforce-delete-with-where.ts:1-18](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-delete-with-where.ts#L1-L18). Defined via `ESLintUtils.RuleCreator`, the rule classifies failures under the `problem` meta type, marks itself as fixable via code, and accepts an options schema restricting configuration to the `drizzleObjectName` property [eslint-plugin-drizzle/src/enforce-delete-with-where.ts:5-33](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-delete-with-where.ts#L5-L33). ```typescript const deleteRule = createRule({ defaultOptions: [{ drizzleObjectName: [] }], name: 'enforce-delete-with-where', meta: { type: 'problem', docs: { description: 'Enforce that `delete` method is used with `where` to avoid deleting all the rows in a table.', }, fixable: 'code', messages: { enforceDeleteWithWhere: "Without `.where(...)` you will delete all the rows in a table. If you didn't want to do it, please use `{{ drizzleObjName }}.delete(...).where(...)` instead. Otherwise you can ignore this rule here", }, schema: [{ type: 'object', properties: { drizzleObjectName: { type: ['string', 'array'], }, }, additionalProperties: false, }], }, ``` Sources: [eslint-plugin-drizzle/src/enforce-delete-with-where.ts:11-33](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-delete-with-where.ts#L11-L33) | Rule Metadata Property | Value / Setting | Description | | :--- | :--- | :--- | | `name` | `'enforce-delete-with-where'` | Registered rule identifier | | `meta.type` | `'problem'` | Categorizes the rule as detecting potential code errors | | `meta.fixable` | `'code'` | Indicates automatic fix capabilities exist | | `meta.messages.enforceDeleteWithWhere` | `"Without \`.where(...)\` you will delete all the rows..."` | Warning message reported when `where` is omitted | | `meta.schema` | Array containing option definitions | Validates `drizzleObjectName` as string or array | Sources: [eslint-plugin-drizzle/src/enforce-delete-with-where.ts:11-33](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-delete-with-where.ts#L11-L33) > [!WARNING] > Omitting `.where(...)` on a Drizzle delete builder generates an AST match that triggers an error report, preventing accidental truncation of entire database tables [eslint-plugin-drizzle/src/enforce-delete-with-where.ts:16-23](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-delete-with-where.ts#L16-L23). > Sources: [eslint-plugin-drizzle/src/enforce-delete-with-where.ts:16-23](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-delete-with-where.ts#L16-L23) ### Member Expression Traversal and State Tracking The rule traversal visitor evaluates `MemberExpression` nodes to verify whether a `.delete` call is immediately preceded by a `.where` method [eslint-plugin-drizzle/src/enforce-delete-with-where.ts:34-50](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-delete-with-where.ts#L34-L50). It maintains a module-scoped `lastNodeName` variable to track the previously visited property identifier in chained method calls [eslint-plugin-drizzle/src/enforce-delete-with-where.ts:9](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-delete-with-where.ts#L9), [eslint-plugin-drizzle/src/enforce-delete-with-where.ts:47](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-delete-with-where.ts#L47). When `node.property.name` equals `'delete'`, `lastNodeName` is checked to ensure it is not `'where'`, and `isDrizzleObj(node, options)` validates that the expression originates from a registered database instance [eslint-plugin-drizzle/src/enforce-delete-with-where.ts:37-38](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-delete-with-where.ts#L37-L38). ```typescript create(context, options) { return { MemberExpression: (node) => { if (node.property.type === 'Identifier') { if (node.property.name === 'delete' && lastNodeName !== 'where' && isDrizzleObj(node, options)) { context.report({ node, messageId: 'enforceDeleteWithWhere', data: { drizzleObjName: resolveMemberExpressionPath(node), }, }); } lastNodeName = node.property.name; } return; }, }; }, ``` Sources: [eslint-plugin-drizzle/src/enforce-delete-with-where.ts:34-52](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-delete-with-where.ts#L34-L52) > [!NOTE] > The module-scoped `lastNodeName` tracker relies on sequential AST visitor traversal order; if `lastNodeName` equals `'where'`, the preceding `.delete()` call is considered safe [eslint-plugin-drizzle/src/enforce-delete-with-where.ts:9](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-delete-with-where.ts#L9), [eslint-plugin-drizzle/src/enforce-delete-with-where.ts:38](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-delete-with-where.ts#L38). > Sources: [eslint-plugin-drizzle/src/enforce-delete-with-where.ts:9](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-delete-with-where.ts#L9), [eslint-plugin-drizzle/src/enforce-delete-with-where.ts:38](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-delete-with-where.ts#L38) ## Enforcing WHERE Clauses on Updates ### Rule Metadata and Configuration Schema The `enforce-update-with-where` rule checks that database update statements include a `.where(...)` filter, preventing accidental modification of all rows in a table. It is registered via `@typescript-eslint/utils` under the name `'enforce-update-with-where'` with metadata type `'problem'` and fixable status `'code'` [eslint-plugin-drizzle/src/enforce-update-with-where.ts:1-18](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-update-with-where.ts#L1-L18). ```typescript defaultOptions: [{ drizzleObjectName: [] }], name: 'enforce-update-with-where', meta: { type: 'problem', docs: { description: 'Enforce that `update` method is used with `where` to avoid deleting all the rows in a table.', }, fixable: 'code', messages: { enforceUpdateWithWhere: "Without `.where(...)` you will update all the rows in a table. If you didn't want to do it, please use `{{ drizzleObjName }}.update(...).set(...).where(...)` instead. Otherwise you can ignore this rule here", }, schema: [{ type: 'object', properties: { drizzleObjectName: { type: ['string', 'array'], }, }, additionalProperties: false, }], }, ``` Sources: [eslint-plugin-drizzle/src/enforce-update-with-where.ts:11-32](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-update-with-where.ts#L11-L32) | Rule Metadata Property | Value / Setting | Description | | :--- | :--- | :--- | | `name` | `'enforce-update-with-where'` | Registered rule identifier for update clause enforcement | | `meta.type` | `'problem'` | Categorizes the rule as detecting potential logic errors | | `meta.fixable` | `'code'` | Indicates code correction capabilities | | `meta.messages.enforceUpdateWithWhere` | `"Without \`.where(...)\` you will update all the rows..."` | Warning message reported when `where` is omitted from `update().set()` | | `meta.schema` | Array with `drizzleObjectName` property | Validates configuration options as a string or array, disallowing additional properties | Sources: [eslint-plugin-drizzle/src/enforce-update-with-where.ts:11-32](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-update-with-where.ts#L11-L32) > [!WARNING] > Omitting `.where(...)` when modifying records via `update(...).set(...)` triggers an AST violation warning, protecting entire database tables from unfiltered bulk updates [eslint-plugin-drizzle/src/enforce-update-with-where.ts:16-21](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-update-with-where.ts#L16-L21). > Sources: [eslint-plugin-drizzle/src/enforce-update-with-where.ts:16-21](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-update-with-where.ts#L16-L21) ### Member Expression Traversal and State Tracking The rule listener inspects `MemberExpression` nodes to verify that `.set()` calls on an `update()` builder are preceded by `.where()` [eslint-plugin-drizzle/src/enforce-update-with-where.ts:33-45](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-update-with-where.ts#L33-L45). It utilizes a module-scoped variable `lastNodeName` to remember the previous property identifier across visitor executions [eslint-plugin-drizzle/src/enforce-update-with-where.ts:8](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-update-with-where.ts#L8), [eslint-plugin-drizzle/src/enforce-update-with-where.ts:54](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-update-with-where.ts#L54). When the current property is `'set'`, `lastNodeName` is verified not to be `'where'`, and `node.object` must be a `CallExpression` whose callee is an `update` member expression originating from a recognized Drizzle object [eslint-plugin-drizzle/src/enforce-update-with-where.ts:37-45](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-update-with-where.ts#L37-L45). ```typescript create(context, options) { return { MemberExpression: (node) => { if (node.property.type === 'Identifier') { if ( lastNodeName !== 'where' && node.property.name === 'set' && node.object.type === 'CallExpression' && node.object.callee.type === 'MemberExpression' && node.object.callee.property.type === 'Identifier' && node.object.callee.property.name === 'update' && isDrizzleObj(node.object.callee, options) ) { context.report({ node, messageId: 'enforceUpdateWithWhere', data: { drizzleObjName: resolveMemberExpressionPath(node.object.callee), }, }); } lastNodeName = node.property.name; } return; }, }; }, ``` Sources: [eslint-plugin-drizzle/src/enforce-update-with-where.ts:33-59](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-update-with-where.ts#L33-L59) > [!NOTE] > Unlike `enforce-delete-with-where` which targets the `.delete` call directly, `enforce-update-with-where` targets the `.set` method node when verifying that `.where` was not the preceding call in the chain [eslint-plugin-drizzle/src/enforce-update-with-where.ts:38-39](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-update-with-where.ts#L38-L39). > Sources: [eslint-plugin-drizzle/src/enforce-update-with-where.ts:38-39](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/enforce-update-with-where.ts#L38-L39) ## AST Member Resolution Utilities ### Path Traversal and Drizzle Object Matching The plugin provides internal utility functions in `eslint-plugin-drizzle/src/utils/ast.ts` and `eslint-plugin-drizzle/src/utils/options.ts` to inspect Abstract Syntax Tree (AST) nodes for database instance matching and call-chain resolution. The `resolveMemberExpressionPath` function traverses a `TSESTree.MemberExpression` node upward through its object references, accumulating a dot-separated string representation of the call chain [eslint-plugin-drizzle/src/utils/ast.ts:3-37](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/utils/ast.ts#L3-L37). ```typescript export const resolveMemberExpressionPath = (node: TSESTree.MemberExpression) => { let objectExpression = node.object; let fullName = ''; const addToFullName = (name: string) => { const prefix = fullName ? '.' : ''; fullName = `${name}${prefix}${fullName}`; }; while (objectExpression) { if (objectExpression.type === 'MemberExpression') { if (objectExpression.property.type === 'Identifier') { addToFullName(objectExpression.property.name); } objectExpression = objectExpression.object; } else if (objectExpression.type === 'CallExpression' && objectExpression.callee.type === 'Identifier') { addToFullName(`${objectExpression.callee.name}(...)`); break; } else if (objectExpression.type === 'CallExpression' && objectExpression.callee.type === 'MemberExpression') { if (objectExpression.callee.property.type === 'Identifier') { addToFullName(`${objectExpression.callee.property.name}(...)`); } objectExpression = objectExpression.callee.object; } else if (objectExpression.type === 'Identifier') { addToFullName(objectExpression.name); break; } else if (objectExpression.type === 'ThisExpression') { addToFullName('this'); break; } else { break; } } return fullName; ``` Sources: [eslint-plugin-drizzle/src/utils/ast.ts:3-37](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/utils/ast.ts#L3-L37) > [!NOTE] > During AST traversal, `resolveMemberExpressionPath` specifically intercepts identifiers, `ThisExpression` nodes, member expressions, and call expressions, appending `(...)` syntax to method calls before breaking or continuing path reduction [eslint-plugin-drizzle/src/utils/ast.ts:12-35](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/utils/ast.ts#L12-L35). > Sources: [eslint-plugin-drizzle/src/utils/ast.ts:12-35](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/utils/ast.ts#L12-L35)] ### Configuration and Object Name Validation Configured database object names are validated against AST nodes using `isDrizzleObj` and `isDrizzleObjName` [eslint-plugin-drizzle/src/utils/options.ts:3-41](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/utils/options.ts#L3-L41). The rule options schema accepts a `drizzleObjectName` parameter configured as either a single string or an array of strings [eslint-plugin-drizzle/src/utils/options.ts:3-5](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/utils/options.ts#L3-L5). If the array is empty, all object names are matched by default [eslint-plugin-drizzle/src/utils/options.ts:12-15](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/utils/options.ts#L12-L15). ```typescript export type Options = readonly [{ drizzleObjectName: string[] | string; }]; const isDrizzleObjName = (name: string, drizzleObjectName: string[] | string) => { if (typeof drizzleObjectName === 'string') { return name === drizzleObjectName; } if (Array.isArray(drizzleObjectName)) { if (drizzleObjectName.length === 0) { return true; } return drizzleObjectName.includes(name); } return false; }; ``` Sources: [eslint-plugin-drizzle/src/utils/options.ts:3-21](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/utils/options.ts#L3-L21) The `isDrizzleObj` function evaluates the structure of a `MemberExpression` node's object property to determine if it originates from a recognized database instance identifier or chained expression [eslint-plugin-drizzle/src/utils/options.ts:23-41](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/utils/options.ts#L23-L41). ```typescript export const isDrizzleObj = ( node: TSESTree.MemberExpression, options: Options, ) => { const drizzleObjectName = options[0].drizzleObjectName; if (node.object.type === 'Identifier') { return isDrizzleObjName(node.object.name, drizzleObjectName); } else if (node.object.type === 'MemberExpression' && node.object.property.type === 'Identifier') { return isDrizzleObjName(node.object.property.name, drizzleObjectName); } else if (node.object.type === 'CallExpression') { if (node.object.callee.type === 'Identifier') { return isDrizzleObjName(node.object.callee.name, drizzleObjectName); } else if (node.object.callee.type === 'MemberExpression' && node.object.callee.property.type === 'Identifier') { return isDrizzleObjName(node.object.callee.property.name, drizzleObjectName); } } return false; ``` Sources: [eslint-plugin-drizzle/src/utils/options.ts:23-41](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/utils/options.ts#L23-L41) > [!TIP] > Setting `drizzleObjectName` to an empty array (`[]`) in rule configurations bypasses strict name filtering, causing the plugin to evaluate query builder methods across all matching member expressions regardless of the base variable name [eslint-plugin-drizzle/src/utils/options.ts:12-15](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/utils/options.ts#L12-L15). > Sources: [eslint-plugin-drizzle/src/utils/options.ts:12-15](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/src/utils/options.ts#L12-L15) ## Related - [Query Builder Foundation](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/query-builder-foundation) --- ## Technical docs: Monorepo Build Pipeline URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/testing-and-tooling/monorepo-build-pipeline
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-arktype/scripts/fix-imports.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/scripts/fix-imports.ts) - [drizzle-typebox/scripts/fix-imports.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/scripts/fix-imports.ts) - [drizzle-zod/scripts/fix-imports.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/scripts/fix-imports.ts) - [drizzle-valibot/scripts/fix-imports.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/scripts/fix-imports.ts) - [drizzle-orm/scripts/fix-imports.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/scripts/fix-imports.ts) - [drizzle-orm/scripts/build.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/scripts/build.ts) - [drizzle-valibot/scripts/build.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/scripts/build.ts) - [drizzle-arktype/scripts/build.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/scripts/build.ts) - [drizzle-zod/scripts/build.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/scripts/build.ts) - [drizzle-typebox/scripts/build.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/scripts/build.ts) - [drizzle-seed/scripts/build.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/scripts/build.ts) - [drizzle-kit/build.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/build.ts) - [turbo.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/turbo.json) - [drizzle-orm/tsup.config.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/tsup.config.ts) - [drizzle-kit/build.dev.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/build.dev.ts) - [drizzle-kit/imports-checker/checker.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/imports-checker/checker.ts) - [package.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/package.json) - [drizzle-kit/src/serializer/pgImports.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/pgImports.ts) - [drizzle-typebox/rollup.config.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/rollup.config.ts) - [drizzle-valibot/rollup.config.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/rollup.config.ts) - [drizzle-kit/src/serializer/singlestoreImports.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/singlestoreImports.ts) - [drizzle-kit/src/serializer/studio.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/studio.ts) - [drizzle-zod/rollup.config.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/rollup.config.ts) - [drizzle-seed/rollup.config.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/rollup.config.ts) - [drizzle-arktype/rollup.config.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/rollup.config.ts) - [drizzle-kit/imports-checker/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/imports-checker/index.ts) - [tsconfig.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/tsconfig.json) - [integration-tests/vitest-ci.config.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/vitest-ci.config.ts) - [drizzle-seed/tsconfig.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/tsconfig.json) - [integration-tests/sst-env.d.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/sst-env.d.ts)
## Overview The monorepo build pipeline coordinates task execution, multi-entry compilation, bundling, and distribution packaging across packages like `drizzle-orm`, `drizzle-kit`, `drizzle-seed`, and schema validation adapters using [Project Structure](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/getting-started/project-structure). Powered by Turborepo task orchestration, the pipeline resolves package dependencies and build caching rules at the repository root [turbo.json:1-253](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/turbo.json#L1-L253). Individual packages compile source files into production-ready CommonJS and ESM formats through `tsup`, Rollup, and esbuild workflows while rewriting path aliases and verifying bundle boundaries [drizzle-orm/scripts/build.ts:1-76](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/scripts/build.ts#L1-L76), [drizzle-kit/build.ts:1-150](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/build.ts#L1-L150), [drizzle-kit/imports-checker/checker.ts:1-296](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/imports-checker/checker.ts#L1-L296). Sources: [turbo.json:1-253](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/turbo.json#L1-L253), [drizzle-orm/scripts/build.ts:1-76](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/scripts/build.ts#L1-L76), [drizzle-kit/build.ts:1-150](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/build.ts#L1-L150), [drizzle-kit/imports-checker/checker.ts:1-296](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/imports-checker/checker.ts#L1-L296) ## Turborepo Task Orchestration Task orchestration across the monorepo root is defined in `turbo.json`, which governs pipeline topology, package-level dependencies, input file sets, and build caching behavior [turbo.json:1-254](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/turbo.json#L1-L254). The pipeline executes tasks such as building, type-checking, linting, packaging, and testing by tracking precise dependencies between packages [turbo.json:3-253](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/turbo.json#L3-L253). For instance, `drizzle-orm#build` acts as the foundational primitive upon which all companion library builds, CLI tooling, and test harnesses depend [turbo.json:32-209](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/turbo.json#L32-L209). ```mermaid graph TD A["drizzle-orm#build"] --> B["drizzle-kit#build"] A --> C["drizzle-zod#build"] A --> D["drizzle-typebox#build"] A --> E["drizzle-valibot#build"] A --> F["drizzle-arktype#build"] A --> G["eslint-plugin-drizzle#build"] A --> H["drizzle-seed#build"] H --> I["integration-tests#build"] A --> I B --> J["pack"] C --> J D --> J E --> J F --> J G --> J H --> J I --> J J --> K["test"] ``` Sources: [turbo.json:32-240](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/turbo.json#L32-L240) The root task definitions govern specific execution parameters and file watch patterns. The root configuration specifies inputs, outputs, and logging levels to optimize remote and local caching [turbo.json:1-254](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/turbo.json#L1-L254). | Task Name | Depends On | Inputs | Outputs | Output Logs | | :--- | :--- | :--- | :--- | :--- | | `//#lint` | `^test:types`, `drizzle-orm#build` | `**/*.ts`, `!**/node_modules`, `!**/dist`, `!**/dist-dts` | None | `new-only` | | `test:types` | `^test:types`, `drizzle-orm#build`, `drizzle-seed#build` | `src/**/*.ts`, `tests/**/*.ts`, `tsconfig.json`, `tests/tsconfig.json`, `../tsconfig.json` | None | `new-only` | | `drizzle-orm#build` | None | `src/**/*.ts`, `package.json`, `README.md`, `../README.md`, `tsconfig.json`, `tsconfig.*.json`, `tsup.config.ts`, `scripts/build.ts`, `scripts/fix-imports.ts`, `../tsconfig.json` | `dist/**`, `dist-dts/**` | `new-only` | | `drizzle-kit#build` | `drizzle-orm#build` | `src/**/*.ts`, `package.json`, `README.md`, `../README.md`, `tsconfig.json`, `tsconfig.*.json`, `tsup.config.ts`, `scripts/build.ts`, `scripts/fix-imports.ts`, `../tsconfig.json` | `dist/**`, `dist-dts/**` | `new-only` | | `drizzle-zod#build` | `drizzle-orm#build` | `src/**/*.ts`, `package.json`, `README.md`, `../README.md`, `tsconfig.json`, `tsconfig.*.json`, `tsup.config.ts`, `scripts/build.ts`, `scripts/fix-imports.ts`, `../tsconfig.json` | `dist/**`, `dist-dts/**` | `new-only` | | `drizzle-typebox#build` | `drizzle-orm#build` | `src/**/*.ts`, `package.json`, `README.md`, `../README.md`, `tsconfig.json`, `tsconfig.*.json`, `tsup.config.ts`, `scripts/build.ts`, `scripts/fix-imports.ts`, `../tsconfig.json` | `dist/**`, `dist-dts/**` | `new-only` | | `drizzle-valibot#build` | `drizzle-orm#build` | `src/**/*.ts`, `package.json`, `README.md`, `../README.md`, `tsconfig.json`, `tsconfig.*.json`, `tsup.config.ts`, `scripts/build.ts`, `scripts/fix-imports.ts`, `../tsconfig.json` | `dist/**`, `dist-dts/**` | `new-only` | | `drizzle-arktype#build` | `drizzle-orm#build` | `src/**/*.ts`, `package.json`, `README.md`, `../README.md`, `tsconfig.json`, `tsconfig.*.json`, `tsup.config.ts`, `scripts/build.ts`, `scripts/fix-imports.ts`, `../tsconfig.json` | `dist/**`, `dist-dts/**` | `new-only` | | `eslint-plugin-drizzle#build` | `drizzle-orm#build` | `src/**/*.ts`, `package.json`, `README.md`, `../README.md`, `tsconfig.json`, `tsconfig.*.json`, `tsup.config.ts`, `scripts/build.ts`, `scripts/fix-imports.ts`, `../tsconfig.json` | `dist/**`, `dist-dts/**` | `new-only` | | `drizzle-seed#build` | `drizzle-orm#build` | `src/**/*.ts`, `package.json`, `README.md`, `../README.md`, `tsconfig.json`, `tsconfig.*.json`, `tsup.config.ts`, `scripts/build.ts`, `scripts/fix-imports.ts`, `../tsconfig.json` | `dist/**`, `dist-dts/**` | `new-only` | | `integration-tests#build` | `drizzle-orm#build`, `drizzle-seed#build` | `src/**/*.ts`, `package.json`, `README.md`, `../README.md`, `tsconfig.json`, `tsconfig.*.json`, `tsup.config.ts`, `scripts/build.ts`, `scripts/fix-imports.ts`, `../tsconfig.json` | `dist/**`, `dist-dts/**` | `new-only` | | `pack` | `build`, `test:types` | `dist/**` | `package.tgz` | `new-only` | | `test` | `build`, `test:types` | `tests/**/*.test.ts`, `tests/**/*.test.cjs`, `tests/**/*.test.mjs` | None | `new-only` | Sources: [turbo.json:3-252](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/turbo.json#L3-L252) > [!NOTE] > All build tasks across companion validation packages (`drizzle-zod`, `drizzle-typebox`, `drizzle-valibot`, `drizzle-arktype`), tooling (`drizzle-kit`, `eslint-plugin-drizzle`), and test suites explicitly require `drizzle-orm#build` to complete first, establishing core runtime outputs before dependent compilation phases run [turbo.json:51-182](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/turbo.json#L51-L182). > [!TIP] > The root `package.json` maps short aliases to Turborepo invocations, allowing developers to execute full pipeline builds via `pnpm build` or target specific packages using filters such as `pnpm build:orm` [package.json:4-14](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/package.json#L4-L14). Sources: [turbo.json:51-182](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/turbo.json#L51-L182), [package.json:4-14](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/package.json#L4-L14) ## Core Package tsup Compilation The compilation of `drizzle-orm` relies on a multi-entry configuration processed by `tsup` alongside custom build orchestration scripts. Every TypeScript source file under `src/` serves as an independent compilation entry point without bundling or splitting enabled, maintaining individual file structures for both CommonJS and ESM module outputs. | Option | Value | Purpose | | :--- | :--- | :--- | | `entry` | `entries` (`src/**/*.ts`) | Discovers all source files to compile as individual entry points | | `outDir` | `'dist.new'` | Directs initial compilation output to a staging directory before atomic replacement | | `format` | `['cjs', 'esm']` | Generates both CommonJS and ESM distribution formats simultaneously | | `bundle` | `false` | Disables bundling to preserve module file boundaries | | `splitting` | `false` | Disables code splitting across entries | | `sourcemap` | `true` | Emits source maps for debugging compiled artifacts | | `tsconfig` | `'tsconfig.build.json'` | Specifies the TypeScript build configuration file | Sources: [drizzle-orm/tsup.config.ts:1-19](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/tsup.config.ts#L1-L19) > [!WARNING] > Because `bundle: false` and `splitting: false` are configured in `tsup.config.ts`, relative import specifiers in compiled output lack file extensions unless post-processed, which would break native Node.js ESM resolution rules. Sources: [drizzle-orm/tsup.config.ts:10-11](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/tsup.config.ts#L10-L11) The complete build script orchestrated by `scripts/build.ts` executes parallel compilation tasks, declaration file generation, and import path rewriting before finalizing the distribution directory. ```mermaid flowchart TD A["Remove dist.new"] --> B1["Run tsup (JS compilation)"] A --> B2["Run tsc -p tsconfig.dts.json"] B2 --> C1["Copy dist-dts to dist.new (.d.cts)"] B2 --> C2["Copy dist-dts to dist.new (.d.ts)"] B1 --> D["Compile src/version.ts (esm & cjs)"] C1 --> D C2 --> D D --> E["Run scripts/fix-imports.ts"] E --> F["Copy README.md"] F --> G["Update & Copy package.json exports"] G --> H["Remove old dist & rename dist.new to dist"] ``` Sources: [drizzle-orm/scripts/build.ts:49-76](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/scripts/build.ts#L49-L76) To resolve path aliases and ensure proper extension mapping for both ESM and CJS outputs, `scripts/fix-imports.ts` parses generated files using `recast` and visits import declarations, export declarations, require calls, and dynamic imports. ```typescript function resolvePathAlias(importPath: string, file: string) { if (importPath.startsWith('~/')) { const relativePath = path.relative(path.dirname(file), path.resolve('dist.new', importPath.slice(2))); importPath = relativePath.startsWith('.') ? relativePath : './' + relativePath; } return importPath; } function fixImportPath(importPath: string, file: string, ext: string) { importPath = resolvePathAlias(importPath, file); if (!/\..*\.(js|ts)$/.test(importPath)) { return importPath; } return importPath.replace(/\.(js|ts)$/, ext); } ``` Sources: [drizzle-orm/scripts/fix-imports.ts:8-25](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/scripts/fix-imports.ts#L8-L25) > [!NOTE] > The import fixer script processes `dist.new` by targeting `cjsFiles` (`*.{cjs,d.cts}`) with `.cjs` extensions and `esmFiles` (`*.{js,d.ts}`) with `.js` extensions, updating `import`, `export`, `require()`, type-only imports, and dynamic `await import()` expressions. Sources: [drizzle-orm/scripts/fix-imports.ts:27-101](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/scripts/fix-imports.ts#L27-L101) ## Companion Validation Package Bundling ### Rollup and Build Orchestration Companion validation packages (`drizzle-zod`, `drizzle-typebox`, `drizzle-valibot`, and `drizzle-arktype`) share an identical build pipeline architecture. Each package build begins by removing the existing `dist` directory, then invokes Rollup with the TypeScript compiler plugin referencing `tsconfig.build.json`. Following bundling, path resolution utilities execute, `README.md` and `package.json` are copied into the distribution folder, declaration files are duplicated with `.d.mts` and `.d.cts` extensions via `cpy`, and a recast-based import rewriting script standardizes module specifiers. | Companion Package | External Dependencies | Entry Point | | :--- | :--- | :--- | | `drizzle-zod` | `/^drizzle-orm\/?/`, `zod` | `src/index.ts` | | `drizzle-typebox` | `/^drizzle-orm\/?/`, `@sinclair/typebox` | `src/index.ts` | | `drizzle-valibot` | `/^drizzle-orm\/?/`, `valibot` | `src/index.ts` | | `drizzle-arktype` | `/^drizzle-orm\/?/`, `arktype` | `src/index.ts` | Sources: [drizzle-zod/rollup.config.ts:6-26](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/rollup.config.ts#L6-L26), [drizzle-typebox/rollup.config.ts:6-26](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/rollup.config.ts#L6-L26), [drizzle-valibot/rollup.config.ts:6-26](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/rollup.config.ts#L6-L26), [drizzle-arktype/rollup.config.ts:6-26](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/rollup.config.ts#L6-L26), [drizzle-zod/scripts/build.ts:5-16](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/scripts/build.ts#L5-L16) > [!NOTE] > All four validation adapters configure Rollup outputs for both ESM and CommonJS formats simultaneously, emitting `.mjs` entry files, `.cjs` entry files, corresponding chunk files with content hashes, and enabled sourcemaps. Sources: [drizzle-zod/rollup.config.ts:7-22](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/rollup.config.ts#L7-L22), [drizzle-typebox/rollup.config.ts:7-22](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/rollup.config.ts#L7-L22), [drizzle-valibot/rollup.config.ts:7-22](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/rollup.config.ts#L7-L22), [drizzle-arktype/rollup.config.ts:7-22](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/rollup.config.ts#L7-L22) ### Import Rewriting and Path Aliasing The build process concludes by executing a post-processing script using `recast` to traverse compiled output files in the `dist` directory. This script resolves path aliases beginning with `~/` relative to `dist.new` and normalizes explicit file extensions across CommonJS, ESM, and modern module variants. ```typescript function resolvePathAlias(importPath: string, file: string) { if (importPath.startsWith('~/')) { const relativePath = path.relative(path.dirname(file), path.resolve('dist.new', importPath.slice(2))); importPath = relativePath.startsWith('.') ? relativePath : './' + relativePath; } return importPath; } function fixImportPath(importPath: string, file: string, ext: string) { importPath = resolvePathAlias(importPath, file); if (!/\..*\.(js|ts)$/.test(importPath)) { return importPath; } return importPath.replace(/\.(js|ts)$/, ext); } ``` Sources: [drizzle-zod/scripts/fix-imports.ts:8-25](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/scripts/fix-imports.ts#L8-L25), [drizzle-typebox/scripts/fix-imports.ts:8-25](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/scripts/fix-imports.ts#L8-L25), [drizzle-valibot/scripts/fix-imports.ts:8-25](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/scripts/fix-imports.ts#L8-L25), [drizzle-arktype/scripts/fix-imports.ts:8-25](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/scripts/fix-imports.ts#L8-L25) > [!WARNING] > The import fixer inspects import declarations, export declarations, named export sources, require call expressions, TypeScript import types, and dynamic `await import()` expressions, replacing extensions with `.cjs`, `.js`, or `.mjs` depending on the target file set. Sources: [drizzle-zod/scripts/fix-imports.ts:27-135](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/scripts/fix-imports.ts#L27-L135), [drizzle-typebox/scripts/fix-imports.ts:27-135](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/scripts/fix-imports.ts#L27-L135), [drizzle-valibot/scripts/fix-imports.ts:27-135](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/scripts/fix-imports.ts#L27-L135), [drizzle-arktype/scripts/fix-imports.ts:27-135](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/scripts/fix-imports.ts#L27-L135) ## Seed Package Distribution Setup The distribution pipeline for `drizzle-seed` relies on an execution script built with `zx`, combined with a Rollup configuration that targets dual-format outputs. The build sequence begins by removing the existing `dist` directory, executing Rollup with the TypeScript compiler plugin referencing `tsconfig.build.json`, running `resolve-tspaths` for path alias resolution, and copying `README.md` and `package.json` into the distribution folder. ```typescript #!/usr/bin/env -S pnpm tsx import 'zx/globals'; import cpy from 'cpy'; await fs.remove('dist'); await $`rollup --config rollup.config.ts --configPlugin typescript`; await $`resolve-tspaths`; await fs.copy('README.md', 'dist/README.md'); await cpy('dist/**/*.d.ts', 'dist', { rename: (basename) => basename.replace(/\.d\.ts$/, '.d.mts'), }); await cpy('dist/**/*.d.ts', 'dist', { rename: (basename) => basename.replace(/\.d\.ts$/, '.d.cts'), }); await fs.copy('package.json', 'dist/package.json'); ``` Sources: [drizzle-seed/scripts/build.ts:1-15](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/scripts/build.ts#L1-L15) > [!NOTE] > Following declaration generation, `cpy` duplicates all generated `.d.ts` declaration files within the `dist` folder into `.d.mts` and `.d.cts` extensions to support both ESM and CommonJS TypeScript consumers. Sources: [drizzle-seed/scripts/build.ts:9-14](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/scripts/build.ts#L9-L14) | Rollup Property / Option | Target Value / Setting | Purpose | | :--- | :--- | :--- | | `input` | `src/index.ts` | Primary entry point for bundling | | ESM Format Output | format: `'esm'`, dir: `'dist'`, `[name].mjs` | ECMAScript module distribution bundle | | CJS Format Output | format: `'cjs'`, dir: `'dist'`, `[name].cjs` | CommonJS module distribution bundle | | `external` | `/^drizzle-orm\/?/`, `'pure-rand'` | Externalized packages excluded from the bundle | | TypeScript Plugin Config | `tsconfig: 'tsconfig.build.json'` | Compiler configuration utilized during Rollup bundling | Sources: [drizzle-seed/rollup.config.ts:4-28](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/rollup.config.ts#L4-L28) > [!WARNING] > The TypeScript configuration (`tsconfig.json`) sets `"noEmit": true` for local type checking and development, whereas Rollup invokes the compiler plugin referencing `tsconfig.build.json` to emit compilation outputs. Sources: [drizzle-seed/rollup.config.ts:25-27](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/rollup.config.ts#L25-L27), [drizzle-seed/tsconfig.json:37-37](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/tsconfig.json#L37-L37) ## CLI esbuild Pipeline ### Production and Development Bundling Production and development workflows for `drizzle-kit` leverage `esbuild` and `tsup` to bundle utilities, API endpoints, and CLI binaries targeting Node.js environments. The production workflow executed in `build.ts` invokes `esbuild.buildSync` to bundle `./src/utils.ts` into CommonJS and ESM targets (`dist/utils.js` and `dist/utils.mjs`), alongside compiling the CLI entry point `./src/cli/index.ts` into `dist/bin.cjs` with version injection via `process.env.DRIZZLE_KIT_VERSION`. ```typescript esbuild.buildSync({ entryPoints: ['./src/utils.ts'], bundle: true, outfile: 'dist/utils.js', format: 'cjs', target: 'node16', platform: 'node', external: [ 'commander', 'json-diff', 'glob', 'esbuild', 'drizzle-orm', ...driversPackages, ], banner: { js: `#!/usr/bin/env node`, }, }); esbuild.buildSync({ entryPoints: ['./src/utils.ts'], bundle: true, outfile: 'dist/utils.mjs', format: 'esm', target: 'node16', platform: 'node', external: [ 'commander', 'json-diff', 'glob', 'esbuild', 'drizzle-orm', ...driversPackages, ], banner: { js: `#!/usr/bin/env node`, }, }); esbuild.buildSync({ entryPoints: ['./src/cli/index.ts'], bundle: true, outfile: 'dist/bin.cjs', format: 'cjs', target: 'node16', platform: 'node', define: { 'process.env.DRIZZLE_KIT_VERSION': `"${pkg.version}"`, }, external: [ 'esbuild', 'drizzle-orm', ...driversPackages, ], banner: { js: `#!/usr/bin/env node`, }, }); ``` Sources: [drizzle-kit/build.ts:23-81](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/build.ts#L23-L81) > [!NOTE] > The production compiler injects executable shebang banners (`#!/usr/bin/env node`) into the generated distribution files while leaving external driver packages, `drizzle-orm`, `esbuild`, `commander`, `json-diff`, and `glob` unbundled. Sources: [drizzle-kit/build.ts:30-41](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/build.ts#L30-L41), [drizzle-kit/build.ts:50-61](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/build.ts#L50-L61), [drizzle-kit/build.ts:73-80](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/build.ts#L73-L80) | Driver Category | Externalized Package Identifiers | | :--- | :--- | | PostgreSQL Drivers | `pg`, `postgres`, `@vercel/postgres`, `@neondatabase/serverless`, `@electric-sql/pglite` | | MySQL Drivers | `mysql2`, `@planetscale/database` | | SQLite Drivers | `@libsql/client`, `better-sqlite3`, `bun:sqlite` | Sources: [drizzle-kit/build.ts:7-21](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/build.ts#L7-L21) ### API Compilation and Post-Processing The asynchronous `main` function in the production build script utilizes `tsup` to compile the library entry points `./src/index.ts` and `./src/api.ts` into dual-format CommonJS and ESM outputs with generated TypeScript declarations. ```typescript const main = async () => { await tsup.build({ entryPoints: ['./src/index.ts'], outDir: './dist', external: [ 'esbuild', 'drizzle-orm', ...driversPackages, ], splitting: false, dts: true, format: ['cjs', 'esm'], outExtension: (ctx) => { if (ctx.format === 'cjs') { return { dts: '.d.ts', js: '.js', }; } return { dts: '.d.mts', js: '.mjs', }; }, }); await tsup.build({ entryPoints: ['./src/api.ts'], outDir: './dist', external: [ 'esbuild', 'drizzle-orm', ...driversPackages, ], splitting: false, dts: true, format: ['cjs', 'esm'], ``` Sources: [drizzle-kit/build.ts:83-119](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/build.ts#L83-L119) > [!WARNING] > Post-processing reads `./dist/api.js` and replaces dynamic `await import(` expressions with synchronous `require(` calls to resolve dynamic require issues involving the `glob` and `fs` modules in CommonJS outputs. Sources: [drizzle-kit/build.ts:120-147](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/build.ts#L120-L147) ### Development Workflow Script The development bundling script defined in `build.dev.ts` configures `esbuild` to target local debugging workflows by emitting development binaries and copying runtime loader scripts. ```typescript esbuild.buildSync({ entryPoints: ['./src/utils.ts'], bundle: true, outfile: 'dist/utils.js', format: 'cjs', target: 'node16', platform: 'node', external: ['drizzle-orm', 'esbuild', ...driversPackages], banner: { js: `#!/usr/bin/env -S node --loader @esbuild-kit/esm-loader --no-warnings`, }, }); esbuild.buildSync({ entryPoints: ['./src/cli/index.ts'], bundle: true, outfile: 'dist/index.cjs', format: 'cjs', target: 'node16', platform: 'node', external: [ 'commander', 'json-diff', 'glob', 'esbuild', 'drizzle-orm', ...driversPackages, ], banner: { js: `#!/usr/bin/env -S node --loader ./dist/loader.mjs --no-warnings`, }, }); cpSync('./src/loader.mjs', 'dist/loader.mjs'); ``` Sources: [drizzle-kit/build.dev.ts:18-51](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/build.dev.ts#L18-L51) > [!TIP] > The development build configures custom shebang banners referencing `@esbuild-kit/esm-loader` and `./dist/loader.mjs` alongside syncing `./src/loader.mjs` directly into the `dist` directory via `cpSync`. Sources: [drizzle-kit/build.dev.ts:26-28](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/build.dev.ts#L26-L28), [drizzle-kit/build.dev.ts:46-51](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/build.dev.ts#L46-L51) ## Import Analysis and Boundary Enforcement ### Static Import Analysis Engine The `drizzle-kit` module includes a static import checker and boundary enforcement system designed to validate allowed module boundaries, track access chains, and detect forbidden external dependencies across codebase files. The `ImportAnalyzer` class processes an entry point file (such as `./drizzle-kit/src/cli/index.ts`), recursively inspecting import declarations using custom resolvers and micromatch pattern matching against defined whitelists or blacklists. ```typescript class ImportAnalyzer { private localImportRegex = /^(\.?\.?\/|\.\.?$)/; private importedFileFormatRegex = /^.*\.(ts|tsx|mts|cts|js|jsx|mjs|cjs|json)$/i; private visited: Set = new Set(); private externals: External[] = []; private accessChains: Record = {}; constructor( private basePath: string, private entry: string, private listMode: ListMode, private readonly wantedList: string[], private localPaths: string[], private logger?: boolean, private ignoreTypes?: boolean, ) {} ``` Sources: [drizzle-kit/imports-checker/checker.ts:30-47](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/imports-checker/checker.ts#L30-L47) > [!NOTE] > The analyzer recognizes custom local paths configured via `localPaths` (such as `src`) and resolves target files across TypeScript and JavaScript extensions including `.ts`, `.mts`, `.cts`, `.tsx`, `.js`, `.mjs`, `.cjs`, and `.jsx`, as well as checking directory `index` files. Sources: [drizzle-kit/imports-checker/checker.ts:67-109](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/imports-checker/checker.ts#L67-L109) | Config Field | Type | Purpose | | :--- | :--- | :--- | | `basePath` | `string` | Base directory path for resolving modules | | `entry` | `string` | Entry point file path for analysis | | `whiteList` | `string[]` (optional) | Permitted external import patterns (whitelist mode) | | `blackList` | `string[]` (optional) | Forbidden external import patterns (blacklist mode) | | `localPaths` | `string[]` (optional) | Custom path prefixes treated as local source files | | `ignoreTypes` | `boolean` (optional) | Skip analysis of type-only imports | | `logger` | `boolean` (optional) | Enable console logging during file traversal | Sources: [drizzle-kit/imports-checker/checker.ts:245-260](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/imports-checker/checker.ts#L245-L260) ### Whitelist Boundary Enforcement The CLI verification script initializes `analyzeImports` pointing to `./drizzle-kit` with `localPaths` set to `src`, ignoring type imports and enforcing a strict whitelist of permitted external modules and built-in Node.js libraries. Any external package imported outside this whitelist generates a reported issue containing the file path, violating import name, and full access chains. ```typescript const issues = analyzeImports({ basePath: './drizzle-kit', localPaths: ['src'], whiteList: [ '@drizzle-team/brocli', 'json-diff', 'path', 'fs', 'fs/*', 'url', 'zod', 'node:*', 'hono', 'glob', 'hono/*', 'hono/**/*', '@hono/*', 'crypto', 'hanji', ], entry: './drizzle-kit/src/cli/index.ts', logger: true, ignoreTypes: true, }).issues; ``` Sources: [drizzle-kit/imports-checker/index.ts:4-27](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/imports-checker/index.ts#L4-L27) > [!WARNING] > The default import checker whitelist explicitly restricts external dependencies to the approved packages listed below; introducing unlisted third-party packages causes build and validation check failures. Sources: [drizzle-kit/imports-checker/index.ts:7-23](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/imports-checker/index.ts#L7-L23) | Whitelisted Package / Pattern | Category / Purpose | | :--- | :--- | | `@drizzle-team/brocli` | CLI command parser framework | | `json-diff` | JSON structure comparison utility | | `path`, `fs`, `fs/*`, `url`, `crypto`, `node:*` | Node.js standard libraries and path utilities | | `zod` | Schema validation and parsing library | | `hono`, `hono/*`, `hono/**/*`, `@hono/*` | Lightweight web application framework and routing | | `glob` | File pattern matching utility | | `hanji` | Terminal UI rendering or prompt utility | Sources: [drizzle-kit/imports-checker/index.ts:8-22](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/imports-checker/index.ts#L8-L22) ## Related - [Project Structure](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/getting-started/project-structure) - [Integration Test Harness](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/testing-and-tooling/integration-test-harness) --- ## Technical docs: Integration Test Harness URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/testing-and-tooling/integration-test-harness
Relevant source files The following files were used as context for generating this wiki page: - [integration-tests/vitest.config.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/vitest.config.ts) - [integration-tests/package.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/package.json) - [drizzle-kit/src/cli/connections.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/cli/connections.ts) - [drizzle-orm/type-tests/singlestore/tables.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/tables.ts) - [drizzle-seed/vitest.config.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/vitest.config.ts) - [drizzle-kit/src/api.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/api.ts) - [drizzle-kit/vitest.config.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/vitest.config.ts) - [integration-tests/vitest-ci.config.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/vitest-ci.config.ts) - [integration-tests/sst.config.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/sst.config.ts) - [drizzle-arktype/vitest.config.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/vitest.config.ts) - [drizzle-orm/type-tests/sqlite/db.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/sqlite/db.ts) - [drizzle-orm/src/singlestore/session.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore/session.ts) - [drizzle-valibot/vitest.config.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/vitest.config.ts) - [drizzle-orm/vitest.config.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/vitest.config.ts) - [eslint-plugin-drizzle/vitest.config.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/vitest.config.ts) - [drizzle-typebox/vitest.config.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/vitest.config.ts) - [drizzle-kit/src/serializer/studio.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/studio.ts) - [drizzle-zod/vitest.config.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/vitest.config.ts) - [drizzle-kit/src/sqlgenerator.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/sqlgenerator.ts) - [drizzle-orm/src/pglite/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pglite/driver.ts) - [drizzle-orm/src/singlestore/driver.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/singlestore/driver.ts) - [drizzle-seed/type-tests/pg.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/type-tests/pg.ts) - [drizzle-orm/type-tests/singlestore/db.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/db.ts) - [drizzle-seed/type-tests/sqlite.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/type-tests/sqlite.ts) - [integration-tests/drizzle2/sqlite/meta/_journal.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/drizzle2/sqlite/meta/_journal.json) - [integration-tests/drizzle2/pg/meta/_journal.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/drizzle2/pg/meta/_journal.json) - [integration-tests/sst-env.d.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/sst-env.d.ts) - [integration-tests/drizzle2/singlestore/meta/_journal.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/drizzle2/singlestore/meta/_journal.json) - [integration-tests/drizzle2/pg-proxy/first/meta/_journal.json](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/drizzle2/pg-proxy/first/meta/_journal.json) - [drizzle-orm/type-tests/singlestore/select.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/select.ts)
## Overview The integration test harness coordinates multi-dialect validation suites across local environments and continuous integration pipelines, verifying database driver behavior, schema migrations, and query execution semantics. By combining Vitest runner configurations, AWS SST infrastructure fixtures, and multi-dialect snapshot journals, the suite validates database interactions across SQLite, PostgreSQL, MySQL, SingleStore, and Gel. Sources: [integration-tests/vitest.config.ts:6-24](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/vitest.config.ts#L6-L24), [integration-tests/package.json:74-74](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/package.json#L74-L74), [integration-tests/drizzle2/sqlite/meta/_journal.json:1-13](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/drizzle2/sqlite/meta/_journal.json#L1-L13) ## Vitest runner configuration across environments ### Local and CI configuration structures The integration test suite utilizes distinct Vitest runner configurations for local execution and continuous integration environments. Local runs are governed by `integration-tests/vitest.config.ts`, which loads environment variables via `dotenv/config` and resolves TypeScript path mappings through `vite-tsconfig-paths`. The local configuration explicitly defines inclusion globs covering relational tests, dialect-specific test suites, driver initializations, and vector or spatial extensions. ```typescript test: { include: [ 'tests/seeder/**/*.test.ts', 'tests/extensions/postgis/**/*', 'tests/relational/**/*.test.ts', 'tests/pg/**/*.test.ts', 'tests/mysql/**/*.test.ts', 'tests/singlestore/**/*.test.ts', 'tests/sqlite/**/*.test.ts', 'tests/replicas/**/*', 'tests/imports/**/*', 'tests/extensions/vectors/**/*', 'tests/version.test.ts', 'tests/pg/node-postgres.test.ts', 'tests/utils/is-config.test.ts', 'js-tests/driver-init/commonjs/*.test.cjs', 'js-tests/driver-init/module/*.test.mjs', 'tests/gel/**/*.test.ts', ], ``` Sources: [integration-tests/vitest.config.ts:6-24](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/vitest.config.ts#L6-L24) > [!NOTE] > When `SKIP_EXTERNAL_DB_TESTS` is active in the environment, local execution automatically filters out tests requiring remote or external database services such as PlanetScale, Neon, TiDB, LibSQL, and Vercel. Continuous integration runs are directed by `integration-tests/vitest-ci.config.ts`, which omits the verbose `include` and `exclude` pattern arrays to streamline execution while retaining core test timeouts, single-thread pool options, and type checking constraints. ```typescript export default defineConfig({ test: { typecheck: { tsconfig: 'tsconfig.json', }, testTimeout: 100000, hookTimeout: 200000, isolate: true, poolOptions: { threads: { singleThread: true, }, }, maxWorkers: 1, fileParallelism: false, }, ``` Sources: [integration-tests/vitest-ci.config.ts:5-20](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/vitest-ci.config.ts#L5-L20) ### Execution parameter matrix Both local and CI runner configurations enforce strict concurrency controls and execution boundaries to prevent race conditions against shared or local database instances. The parameter configuration defines explicit timeouts, worker limits, and isolation rules. | Parameter | Configuration Key | Value | Purpose | | :--- | :--- | :--- | :--- | | Test Timeout | `testTimeout` | `100000` | Maximum execution time in milliseconds allotted to an individual test case. | | Hook Timeout | `hookTimeout` | `200000` | Maximum execution time in milliseconds allotted to setup and teardown hooks. | | Test Isolation | `isolate` | `true` | Ensures test files run in isolated environments to avoid state leakage. | | Single Thread | `poolOptions.threads.singleThread` | `true` | Forces test execution onto a single thread within the pool. | | Max Workers | `maxWorkers` | `1` | Restricts parallel worker processes to prevent database connection contention. | | File Parallelism | `fileParallelism` | `false` | Disables concurrent test file execution across workers. | Sources: [integration-tests/vitest.config.ts:70-83](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/vitest.config.ts#L70-L83), [integration-tests/vitest-ci.config.ts:7-19](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/vitest-ci.config.ts#L7-L19) ## Infrastructure provisioning with SST fixtures ### Cloud stack orchestration and AWS Postgres configuration The integration test suite utilizes SST (Serverless Stack) to orchestrate cloud infrastructure stacks for serverless database validation. The configuration file `integration-tests/sst.config.ts` includes a triple-slash reference to `./.sst/platform/config.d.ts` for type safety and is exported via the `$config` function block. ```typescript // eslint-disable-next-line @typescript-eslint/triple-slash-reference /// export default $config({ app(_input) { return { name: 'awsdataapi', removal: 'remove', home: 'aws', }; }, async run() { new sst.aws.Postgres('Postgres', { scaling: { min: '0.5 ACU', max: '1 ACU', }, }); }, ``` Sources: [integration-tests/sst.config.ts:1-19](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/sst.config.ts#L1-L19) | Configuration Property | Target Value / Setting | Context | | :--- | :--- | :--- | | App Name | `awsdataapi` | Defined within the `app` hook callback. | | Removal Policy | `remove` | Specifies stack teardown behavior upon destruction. | | Home Provider | `aws` | Designates AWS as the infrastructure provider. | | Postgres Resource ID | `Postgres` | Instantiated via `new sst.aws.Postgres('Postgres', ...)`. | | Minimum ACU | `0.5 ACU` | Serverless scaling lower bound for the Postgres instance. | | Maximum ACU | `1 ACU` | Serverless scaling upper bound for the Postgres instance. | Sources: [integration-tests/sst.config.ts:4-19](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/sst.config.ts#L4-L19) > [!NOTE] > The serverless PostgreSQL resource scales dynamically between 0.5 and 1 Aurora Capacity Units (ACU) to accommodate AWS Data API integration tests without maintaining idle compute overhead. ### Generated environment bindings Environment binding synchronization for the SST stack is managed through generated type definition files. The file `integration-tests/sst-env.d.ts` establishes type references for runtime resource bindings generated during stack deployment. ```typescript // eslint-disable-next-line @typescript-eslint/triple-slash-reference /// ``` Sources: [integration-tests/sst-env.d.ts:1-2](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/sst-env.d.ts#L1-L2) > [!WARNING] > Manual modifications to `sst-env.d.ts` will be overwritten when SST generates new environment type definitions from the active stack state. ## Cross dialect migration journal fixtures ### Migration journal schema and dialect variants Integration tests validate schema change tracking and snapshot generation by utilizing multi-dialect migration journal fixtures. Each migration journal is defined inside a `meta/_journal.json` configuration file, specifying the schema metadata version, target SQL dialect, and sequential entries detailing individual migration steps. The journal format records metadata such as transaction timestamps, unique tags, and breakpoint configurations. ```json { "version": "5", "dialect": "sqlite", "entries": [ { "idx": 0, "version": "5", "when": 1680202256473, "tag": "0000_fancy_bug", "breakpoints": true } ] ``` Sources: [integration-tests/drizzle2/sqlite/meta/_journal.json:1-12](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/drizzle2/sqlite/meta/_journal.json#L1-L12) The migration journals capture differences across database engines. For example, PostgreSQL journal configurations accommodate single and multi-step migration histories, whereas SQLite and SingleStore maintain target-specific format versions. ```json { "version": "5", "dialect": "pg", "entries": [ { "idx": 0, "version": "5", "when": 1680271923328, "tag": "0000_puzzling_flatman", "breakpoints": true }, { "idx": 1, "version": "5", "when": 1680271923329, "tag": "0001_test", "breakpoints": true } ] ``` Sources: [integration-tests/drizzle2/pg/meta/_journal.json:1-19](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/drizzle2/pg/meta/_journal.json#L1-L19) | Dialect | Journal File Path | Version | Entry Count | Dialect Identifier | | :--- | :--- | :--- | :--- | :--- | | SQLite | `integration-tests/drizzle2/sqlite/meta/_journal.json` | `5` | `1` | `sqlite` | | PostgreSQL | `integration-tests/drizzle2/pg/meta/_journal.json` | `5` | `2` | `pg` | | SingleStore | `integration-tests/drizzle2/singlestore/meta/_journal.json` | `1` | `1` | `singlestore` | | PostgreSQL Proxy | `integration-tests/drizzle2/pg-proxy/first/meta/_journal.json` | `5` | `1` | `pg` | Sources: [integration-tests/drizzle2/sqlite/meta/_journal.json:1-12](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/drizzle2/sqlite/meta/_journal.json#L1-L12), [integration-tests/drizzle2/pg/meta/_journal.json:1-19](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/drizzle2/pg/meta/_journal.json#L1-L19), [integration-tests/drizzle2/singlestore/meta/_journal.json:1-13](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/drizzle2/singlestore/meta/_journal.json#L1-L13), [integration-tests/drizzle2/pg-proxy/first/meta/_journal.json:1-13](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/drizzle2/pg-proxy/first/meta/_journal.json#L1-L13) ### Proxy configurations and isolated entrysets Proxy integration tests use specialized journal directories such as `pg-proxy/first/meta/_journal.json` to validate driver-agnostic query and migration proxy layers. These proxy setups mirror standard PostgreSQL version schemas while restricting entrysets to initial baseline migrations. ```json { "version": "5", "dialect": "pg", "entries": [ { "idx": 0, "version": "5", "when": 1680271923328, "tag": "0000_puzzling_flatman", "breakpoints": true } ] } ``` Sources: [integration-tests/drizzle2/pg-proxy/first/meta/_journal.json:1-13](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/drizzle2/pg-proxy/first/meta/_journal.json#L1-L13) > [!NOTE] > SingleStore migration journals specify format version `1` and dialect identifier `singlestore`, differing from the version `5` format utilized across PostgreSQL and SQLite fixtures. > [!CAUTION] > Altering migration entry indices (`idx`) or timestamp values (`when`) within active journal fixtures causes migration parser validation checks to fail during test harness startup. ## In memory SQLite and embedded PostgreSQL execution ### SQLite driver instantiation across runtimes SQLite test harnesses instantiate local in-memory databases by invoking engine-specific constructors, such as `Database` from `better-sqlite3` or `Database` from `bun:sqlite`, paired with the `':memory:'` connection string. These client instances are passed directly to dialect-specific initialization helpers like `drizzleBetterSqlite3`, `drizzleBun`, `drizzleD1`, and `durableSqlite` to construct fully typed database instances for test execution and seeding utilities. ```typescript import Database from 'better-sqlite3'; import { Database as BunDatabase } from 'bun:sqlite'; import { drizzle as drizzleBetterSqlite3 } from '~/better-sqlite3/index.ts'; import { drizzle as drizzleBun } from '~/bun-sqlite/index.ts'; import { drizzle as drizzleD1 } from '~/d1/index.ts'; import { drizzle as durableSqlite } from '~/durable-sqlite/index.ts'; const client = new Database(':memory:'); const bunClient = new BunDatabase(':memory:'); declare const d1: D1Database; declare const durableSql: DurableObjectStorage; export const db = drizzleBetterSqlite3(client); export const bunDb = drizzleBun(bunClient); export const d1Db = drizzleD1(d1); export const durableSqliteDb = durableSqlite(durableSql); ``` Sources: [drizzle-orm/type-tests/sqlite/db.ts:1-16](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/sqlite/db.ts#L1-L16) > [!TIP] > SQLite seeding utilities support both standard table definitions and foreign key relational references using in-memory connections, allowing rapid fixture resets via `reset` and `seed` function calls. Sources: [drizzle-seed/type-tests/sqlite.ts:1-17](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/type-tests/sqlite.ts#L1-L17) ### Embedded PGlite driver and session configuration Embedded PostgreSQL execution relies on the `PgliteDriver` class and the `@electric-sql/pglite` package to spin up zero-dependency PostgreSQL instances within test environments. The `drizzle` entry point handles multiple parameter overload signatures, accepting either an existing `PGlite` client instance, a connection string, a data directory path with options, or a configuration object containing `logger` and `cache` parameters. ```typescript export function drizzle< TSchema extends Record = Record, TClient extends PGlite = PGlite, >( ...params: | [] | [ TClient | string, ] | [ TClient | string, DrizzleConfig, ] | [ ( & DrizzleConfig & ({ connection?: (PGliteOptions & { dataDir?: string }) | string; } | { client: TClient; }) ), ] ): PgliteDatabase & { $client: TClient; } { if (params[0] === undefined || typeof params[0] === 'string') { const instance = new PGlite(params[0]); return construct(instance, params[1]) as any; } if (isConfig(params[0])) { const { connection, client, ...drizzleConfig } = params[0] as { connection?: PGliteOptions & { dataDir: string }; client?: TClient; } & DrizzleConfig; if (client) return construct(client, drizzleConfig) as any; if (typeof connection === 'object') { const { dataDir, ...options } = connection; const instance = new PGlite(dataDir, options); return construct(instance, drizzleConfig) as any; } const instance = new PGlite(connection); return construct(instance, drizzleConfig) as any; } return construct(params[0] as TClient, params[1] as DrizzleConfig | undefined) as any; } ``` Sources: [drizzle-orm/src/pglite/driver.ts:98-151](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pglite/driver.ts#L98-L151) The internal `construct` function initializes the PostgreSQL dialect with optional casing configurations, parses user-provided loggers and schema definitions using `extractTablesRelationalConfig`, and attaches client reference properties `$client` and `$cache` to the resulting `PgliteDatabase` instance. ```typescript function construct = Record>( client: PgliteClient, config: DrizzleConfig = {}, ): PgliteDatabase & { $client: PgliteClient; } { const dialect = new PgDialect({ casing: config.casing }); let logger; if (config.logger === true) { logger = new DefaultLogger(); } else if (config.logger !== false) { logger = config.logger; } let schema: RelationalSchemaConfig | undefined; if (config.schema) { const tablesConfig = extractTablesRelationalConfig( config.schema, createTableRelationsHelpers, ); schema = { fullSchema: config.schema, schema: tablesConfig.tables, tableNamesMap: tablesConfig.tableNamesMap, }; } const driver = new PgliteDriver(client, dialect, { logger, cache: config.cache }); const session = driver.createSession(schema); const db = new PgliteDatabase(dialect, session, schema as any) as PgliteDatabase; ( db).$client = client; ( db).$cache = config.cache; if (( db).$cache) { ( db).$cache['invalidate'] = config.cache?.onMutate; } // ( db).$cache = { invalidate: ( config).cache?.onMutate }; // if (config.cache) { // for ( // const key of Object.getOwnPropertyNames(Object.getPrototypeOf(config.cache)).filter((key) => // key !== 'constructor' // ) // ) { // ( db).$cache[key as keyof typeof config.cache] = ( config).cache[key]; // } // } return db as any; } ``` Sources: [drizzle-orm/src/pglite/driver.ts:49-96](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pglite/driver.ts#L49-L96) | Overload Signature | Primary Parameter Type | Description | | :--- | :--- | :--- | | Client or String | `TClient \| string \| undefined` | Instantiates a new `PGlite` with an optional connection string or data path. | | Configuration Object | `DrizzleConfig & (connection \| client)` | Configures PGlite using explicit connection options or a passed client instance. | | Mock Instance | `DrizzleConfig` via `drizzle.mock()` | Returns a mock database instance where `$client` is marked as unavailable. | Sources: [drizzle-orm/src/pglite/driver.ts:98-160](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/src/pglite/driver.ts#L98-L160) > [!WARNING] > Calling `drizzle.mock()` provides a database instance without an active client connection, returning the string literal `'\\$client is not available on drizzle.mock()'` for any access to the `$client` property. ## SingleStore connection pooling and query execution ### Connection pool instantiation and session setup SingleStore integration tests establish database connections and connection pools by utilizing the `mysql2/promise` package. The test harness creates a connection pool through the `createPool` function and passes the resulting pool object into the `drizzle` factory function to construct a typed SingleStore database instance for query execution. ```typescript import { createPool } from 'mysql2/promise'; import { drizzle } from '~/singlestore/index.ts'; const pool = createPool({}); export const db = drizzle(pool); ``` Sources: [drizzle-orm/type-tests/singlestore/db.ts:1-7](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/db.ts#L1-L7) The `drizzle` function accepts various configuration combinations, including passing the pool directly, providing a schema object alongside the pool, or supplying empty options configurations during initialization. ```typescript { drizzle(pool); drizzle(pool, { schema: {} }); drizzle(pool, { schema: {} }); drizzle(pool, {}); } ``` Sources: [drizzle-orm/type-tests/singlestore/db.ts:8-13](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/db.ts#L8-L13) > [!NOTE] > SingleStore database instances support optional schema definitions passed via the initialization configuration object to bind tables directly to targeted named schemas. ### Dialect query lifecycle and locking modifiers Query execution test suites validate complex join operations, subqueries, and table aliasing across the SingleStore dialect. Queries support explicit locking clauses such as `.for('update')` and `.for('share')`, with configuration options including `noWait` and `skipLocked` flags. ```typescript await db.select().from(users).for('update'); await db.select().from(users).for('share', { skipLocked: true }); await db.select().from(users).for('update', { noWait: true }); ``` Sources: [drizzle-orm/type-tests/singlestore/select.ts:615-617](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/select.ts#L615-L617) | Locking Clause | Modifier Option | Description | | :--- | :--- | :--- | | `for('update')` | None | Locks selected rows for update operations. | | `for('share')` | `{ skipLocked: true }` | Shares selected rows while skipping locked records. | | `for('update')` | `{ noWait: true }` | Attempts to lock rows for update without waiting for locks to release. | Sources: [drizzle-orm/type-tests/singlestore/select.ts:615-617](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/select.ts#L615-L617) > [!CAUTION] > Combining both `noWait` and `skipLocked` within the same locking modifier options object triggers a type-level compilation error to prevent conflicting locking behaviors. ```typescript /* await db .select() .from(users) // @ts-expect-error - can't use both skipLocked and noWait .for('share', { noWait: true, skipLocked: true }); ``` Sources: [drizzle-orm/type-tests/singlestore/select.ts:619-623](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/select.ts#L619-L623) ## Ecosystem package test harnesses ### Schema validation and seeding test parameters Test configuration parity across ecosystem packages is maintained through dedicated Vitest runner settings in `drizzle-zod`, `drizzle-typebox`, `drizzle-valibot`, `drizzle-arktype`, and `drizzle-seed`. Schema validator packages exclude runtime bun-specific test folders (`tests/bun/**/*`) while configuring test timeouts to `100000` milliseconds, hook timeouts to `100000` milliseconds, and running tests with `isolate: false` and `singleThread: true` via thread pool options. ```typescript test: { include: [ 'tests/**/*.test.ts', ], exclude: [ 'tests/bun/**/*', ], typecheck: { tsconfig: 'tsconfig.json', }, testTimeout: 100000, hookTimeout: 100000, isolate: false, poolOptions: { threads: { singleThread: true, }, }, }, ``` Sources: [drizzle-zod/vitest.config.ts:5-23](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/vitest.config.ts#L5-L23) | Package Configuration | Test Isolation (`isolate`) | Thread Mode (`singleThread`) | Test Timeout (ms) | Excluded Patterns | | :--- | :--- | :--- | :--- | :--- | | `drizzle-zod` | `false` | `true` | `100000` | `tests/bun/**/*` | | `drizzle-typebox` | `false` | `true` | `100000` | `tests/bun/**/*` | | `drizzle-valibot` | `false` | `true` | `100000` | `tests/bun/**/*` | | `drizzle-arktype` | `false` | `true` | `100000` | `tests/bun/**/*` | | `drizzle-seed` | `true` | `true` | `100000` | None | Sources: [drizzle-seed/vitest.config.ts:4-24](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/vitest.config.ts#L4-L24), [drizzle-arktype/vitest.config.ts:5-23](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-arktype/vitest.config.ts#L5-L23), [drizzle-valibot/vitest.config.ts:5-23](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-valibot/vitest.config.ts#L5-L23), [drizzle-typebox/vitest.config.ts:5-23](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-typebox/vitest.config.ts#L5-L23), [drizzle-zod/vitest.config.ts:5-23](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-zod/vitest.config.ts#L5-L23) > [!NOTE] > `drizzle-seed` enforces strict test isolation (`isolate: true`) across postgres, mysql, and sqlite test directories while explicitly setting `maxWorkers: 1` and `fileParallelism: false`. ### Linting tool verification and path resolution The `eslint-plugin-drizzle` test suite relies on a simplified Vitest setup enabling global test APIs and excluding `**/dist/**` build output paths. Meanwhile, parser configurations across `drizzle-kit`, `drizzle-arktype`, `drizzle-valibot`, `drizzle-typebox`, and `drizzle-zod` utilize `vite-tsconfig-paths` plugins to map internal path aliases directly against local `tsconfig.json` definitions. ```typescript import { defineConfig } from 'vitest/config'; export default defineConfig({ test: { globals: true, exclude: ['**/dist/**'], }, ``` Sources: [eslint-plugin-drizzle/vitest.config.ts:1-7](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/eslint-plugin-drizzle/vitest.config.ts#L1-L7) > [!WARNING] > Omitting `vite-tsconfig-paths` plugin registration in ecosystem package test files causes module resolution failures when test suites import internal workspace dependencies using path aliases. ## Related - [Monorepo Build Pipeline](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/testing-and-tooling/monorepo-build-pipeline) - [Type System Verification](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/testing-and-tooling/type-system-verification) --- ## Technical docs: Type System Verification URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/testing-and-tooling/type-system-verification
Relevant source files The following files were used as context for generating this wiki page: - [drizzle-orm/type-tests/geldb/tables.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/tables.ts) - [drizzle-orm/type-tests/mysql/tables.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/tables.ts) - [drizzle-orm/type-tests/geldb/no-strict-null-checks/test.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/no-strict-null-checks/test.ts) - [drizzle-orm/type-tests/geldb/select.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/select.ts) - [drizzle-orm/type-tests/singlestore/tables.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/tables.ts) - [drizzle-orm/type-tests/sqlite/tables.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/sqlite/tables.ts) - [drizzle-orm/type-tests/pg/select.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/select.ts) - [drizzle-orm/type-tests/mysql/db-rel.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/db-rel.ts) - [drizzle-orm/type-tests/singlestore/select.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/select.ts) - [drizzle-orm/type-tests/pg/no-strict-null-checks/test.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/no-strict-null-checks/test.ts) - [drizzle-orm/type-tests/sqlite/select.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/sqlite/select.ts) - [drizzle-orm/type-tests/singlestore/no-strict-null-checks/test.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/no-strict-null-checks/test.ts) - [drizzle-orm/type-tests/mysql/select.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/select.ts) - [drizzle-orm/type-tests/mysql/no-strict-null-checks/test.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/no-strict-null-checks/test.ts) - [drizzle-orm/type-tests/mysql/1000columns.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/1000columns.ts) - [drizzle-orm/type-tests/sqlite/no-strict-null-checks/test.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/sqlite/no-strict-null-checks/test.ts) - [drizzle-orm/type-tests/pg/db-rel.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/db-rel.ts) - [drizzle-orm/type-tests/mysql/subquery.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/subquery.ts) - [integration-tests/type-tests/join-nodenext/singlestore.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/type-tests/join-nodenext/singlestore.ts) - [drizzle-orm/type-tests/common/aliased-table.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/common/aliased-table.ts) - [drizzle-orm/type-tests/pg/subquery.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/subquery.ts) - [drizzle-orm/type-tests/geldb/db-rel.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/db-rel.ts) - [integration-tests/type-tests/join-nodenext/gel.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/integration-tests/type-tests/join-nodenext/gel.ts) - [drizzle-orm/type-tests/mysql/db.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/db.ts) - [drizzle-orm/type-tests/singlestore/set-operators.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/set-operators.ts) - [drizzle-orm/type-tests/singlestore/1000columns.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/1000columns.ts) - [drizzle-orm/type-tests/geldb/subquery.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/subquery.ts) - [drizzle-orm/type-tests/knex/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/knex/index.ts) - [drizzle-orm/type-tests/geldb/db.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/db.ts) - [drizzle-orm/type-tests/pg/db.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/db.ts)
## Overview Type system verification validates compile-time correctness across Drizzle's table definitions, query builders, and database drivers. It uses assertion utilities such as `Expect` and `Equal` to verify that inferred types match expected shapes for PostgreSQL, MySQL, SQLite, SingleStore, and Gel databases. Sources: [drizzle-orm/type-tests/mysql/db-rel.ts:2-2](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/db-rel.ts#L2-L2), [drizzle-orm/type-tests/pg/db-rel.ts:2-2](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/db-rel.ts#L2-L2), [drizzle-orm/type-tests/geldb/db-rel.ts:2-2](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/db-rel.ts#L2-L2), [drizzle-orm/type-tests/singlestore/set-operators.ts:1-2](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/set-operators.ts#L1-L2), [drizzle-orm/type-tests/common/aliased-table.ts:1-1](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/common/aliased-table.ts#L1-L1) ## Type Testing Assertions and Harness ### Test Harness Mechanics and Assertion Utilities Type tests across dialects utilize the `Expect` and `Equal` utility types imported from `type-tests/utils.ts` to enforce precise type checking at compile time. These assertions validate query execution results, relational queries, and schema projections without emitting runtime code. ```typescript import { type Equal, Expect } from 'type-tests/utils.ts'; ``` Sources: [drizzle-orm/type-tests/mysql/db-rel.ts:2-2](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/db-rel.ts#L2-L2), [drizzle-orm/type-tests/pg/db-rel.ts:2-2](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/db-rel.ts#L2-L2), [drizzle-orm/type-tests/geldb/db-rel.ts:2-2](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/db-rel.ts#L2-L2), [drizzle-orm/type-tests/common/aliased-table.ts:1-1](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/common/aliased-table.ts#L1-L1) Query results and builder inferences are wrapped inside block scopes to isolate variable declarations across different test cases. Each test block executes a database query or schema operation using dialect-specific drivers and schema modules. ```typescript { const res = db('test').select(); Expect, typeof test.$inferSelect[]>>; } ``` Sources: [drizzle-orm/type-tests/knex/index.ts:20-23](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/knex/index.ts#L20-L23) > [!NOTE] > Type test files do not execute queries against a live database during standard type-checking passes; instead, drivers are frequently instantiated using `.mock()` or connection pool stubs to verify AST builder output and inference boundaries. Sources: [drizzle-orm/type-tests/common/aliased-table.ts:16-18](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/common/aliased-table.ts#L16-L18) ### Cross-Dialect Test Structure The type-testing harness organizes suites by database dialect and common utility modules. Each directory contains dedicated schema definitions and query verification scripts that test relational finders, table aliases, view integration, and third-party query builder typings like Knex. | Dialect / Module | Source File Path | Primary Verification Target | | :--- | :--- | :--- | | PostgreSQL Relational | `drizzle-orm/type-tests/pg/db-rel.ts` | Relational query builder, `findMany`, `with`, `columns`, and `extras` inference | | MySQL Relational | `drizzle-orm/type-tests/mysql/db-rel.ts` | Cross-dialect driver integration, `placeholder` typing, and nested relations | | Gel Database | `drizzle-orm/type-tests/geldb/db-rel.ts` | Gel client driver initialization and relational schema projections | | Common Aliases | `drizzle-orm/type-tests/common/aliased-table.ts` | Table aliases, view joins, and multi-dialect select structure validation | | Knex Integration | `drizzle-orm/type-tests/knex/index.ts` | `Knexify` table declaration augmentation and `PromiseOf` resolution | Sources: [drizzle-orm/type-tests/mysql/db-rel.ts:1-104](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/db-rel.ts#L1-L104), [drizzle-orm/type-tests/pg/db-rel.ts:1-121](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/db-rel.ts#L1-L121), [drizzle-orm/type-tests/common/aliased-table.ts:1-232](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/common/aliased-table.ts#L1-L232), [drizzle-orm/type-tests/geldb/db-rel.ts:1-118](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/db-rel.ts#L1-L118), [drizzle-orm/type-tests/knex/index.ts:1-23](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/knex/index.ts#L1-L23) ## Column and Table Schema Verification ### Builder Column Configurations and Defaults Compile-time verification ensures that table column builders properly enforce type safety across scalar types, default values, and custom type definitions. In MySQL, SQLite, Gel, and SingleStore type tests, column defaults accept static values or callbacks via `$default` and `$defaultFn`, rejecting mismatched value types at compile time. ```typescript { mysqlTable('test', { id: int('id').$default(() => 1), id2: int('id').$defaultFn(() => 1), // @ts-expect-error - should be number id3: int('id').$default(() => '1'), // @ts-expect-error - should be number id4: int('id').$defaultFn(() => '1'), }); } ``` Sources: [drizzle-orm/type-tests/mysql/tables.ts:746-754](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/tables.ts#L746-L754), [drizzle-orm/type-tests/sqlite/tables.ts:425-433](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/sqlite/tables.ts#L425-L433), [drizzle-orm/type-tests/geldb/tables.ts:853-861](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/tables.ts#L853-L861) > [!CAUTION] > Using `$default` with a factory function that returns a type conflicting with the underlying column data type bypasses runtime type guards and triggers `@ts-expect-error` compiler errors during schema declaration tests. Sources: [drizzle-orm/type-tests/mysql/tables.ts:749-752](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/tables.ts#L749-L752), [drizzle-orm/type-tests/geldb/tables.ts:856-859](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/tables.ts#L856-L859) Custom column configurations validate required and optional parameters through generic constraints on `customType`. When `configRequired: true` is specified, the builder requires configuration arguments to be supplied. ```typescript { const customRequiredConfig = customType<{ data: string; driverData: string; config: { length: number }; configRequired: true; }>({ dataType(config) { Expect>; return `varchar(${config.length})`; }, toDriver(value) { Expect>(); return value; }, fromDriver(value) { Expect>(); return value; }, }); customRequiredConfig('t', { length: 10 }); customRequiredConfig({ length: 10 }); // @ts-expect-error - config is required customRequiredConfig('t'); // @ts-expect-error - config is required customRequiredConfig(); } ``` Sources: [drizzle-orm/type-tests/mysql/tables.ts:803-831](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/tables.ts#L803-L831), [drizzle-orm/type-tests/singlestore/tables.ts:792-837](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/tables.ts#L792-L837), [drizzle-orm/type-tests/sqlite/tables.ts:476-506](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/sqlite/tables.ts#L476-L506) ### Enum Array and Scalar Type Inference Column definitions containing enumerated values verify tuple inference for both standard and `as const` assertions. In SQLite and SingleStore table tests, enum types correctly surface their allowed string literals on `.enumValues`. ```typescript { const test = sqliteTable('test', { test1: text('test', { length: 255, enum: ['a', 'b', 'c'] as const }).notNull(), test2: text('test', { length: 255, enum: ['a', 'b', 'c'] }).notNull(), test3: text('test', { enum: ['a', 'b', 'c'] as const }).notNull(), test4: text('test', { enum: ['a', 'b', 'c'] }).notNull(), }); Expect>; Expect>; Expect>; Expect>; } ``` Sources: [drizzle-orm/type-tests/sqlite/tables.ts:450-460](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/sqlite/tables.ts#L450-L460), [drizzle-orm/type-tests/singlestore/tables.ts:633-633](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/tables.ts#L633-L633) > [!TIP] > When defining columns without explicitly providing column names as the first argument, Drizzle infers the table property key as the database column name, verified via `typeof table['id']['_']['name']`. Sources: [drizzle-orm/type-tests/geldb/tables.ts:901-908](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/tables.ts#L901-L908), [drizzle-orm/type-tests/singlestore/tables.ts:930-937](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/tables.ts#L930-L937) ## Query Result Inference and Nullability ### Projection Shapes and Operator Mappings Type inference validation for `SELECT` projection shapes ensures that raw SQL expressions, column selections, and operator results resolve to exact TypeScript types across all database dialects. When executing projections with `db.select()`, expressions mapped via template literals or custom mapping functions propagate their types directly to the resulting tuple array. For instance, `sql` templates combined with `.mapWith()` map raw driver values into structured objects or specific scalar types such as numbers, booleans, or custom record shapes. ```typescript const allOperators = await db .select({ col2: sql`5 - ${users.id} + 1`, // unknown col3: sql`${users.id} + 1`, // number col33: sql`${users.id} + 1`.mapWith(users.id), // number col34: sql`${users.id} + 1`.mapWith(mapFunkyFuncResult), // number col4: sql`one_or_another(${users.id}, ${users.class})`, // string | number col5: sql`true`, // unknown col6: sql`true`, // boolean col7: sql`random()`, // number col8: sql`some_funky_func(${users.id})`.mapWith(mapFunkyFuncResult), // { foo: string } col9: sql`greatest(${users.createdAt}, ${sql.param(new Date(), users.createdAt)})`, // unknown col10: sql`date_or_false(${users.createdAt}, ${ sql.param( new Date(), users.createdAt, ) })`, // Date | boolean col11: sql`${users.age1} + ${age}`, // unknown col12: sql`${users.age1} + ${sql.param(age, users.age1)}`, // unknown col13: sql`lower(${users.class})`, // unknown col14: sql`length(${users.class})`, // number count: sql`count(*)::int`, // number }) .from(users) ``` Sources: [drizzle-orm/type-tests/geldb/select.ts:412-436](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/select.ts#L412-L436), [drizzle-orm/type-tests/pg/select.ts:411-435](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/select.ts#L411-L435), [drizzle-orm/type-tests/singlestore/select.ts:354-373](https://github.com/blade-47/drizzle-orm/blob/HEAD/drizzle-orm/type-tests/singlestore/select.ts#L354-L373) > [!NOTE] > Unannotated `sql`` template expressions without explicit type generics or `.mapWith()` calls resolve to `unknown` rather than defaulting to `any` or primitive types. Sources: [drizzle-orm/type-tests/geldb/select.ts:414-414](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/select.ts#L414-L414), [drizzle-orm/type-tests/pg/select.ts:413-413](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/select.ts#L413-L413), [drizzle-orm/type-tests/sqlite/select.ts:367-367](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/sqlite/select.ts#L367-L367) ### Conditional SPREAD Properties and Optional Fields Conditional object spreading inside select projections correctly introduces optional property modifiers into the resulting row type. When an object property is conditionally included using a boolean flag, the resulting type infers an optional field modifier rather than an explicit `undefined` union type. ```typescript { const authenticated = false as boolean; const result = await db .select({ id: users.id, ...(authenticated ? { city: users.homeCity } : {}), }) .from(users); Expect< Equal< { id: number; city?: number; }[], typeof result > >; } ``` Sources: [drizzle-orm/type-tests/mysql/select.ts:526-545](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/select.ts#L526-L545) > [!WARNING] > Choking query modifiers such as `.where()` or `.for()` enforce strict AST builder constraints: invoking `.where()` multiple times or chaining configuration options like `.for('share', { noWait: true, skipLocked: true })` triggers compilation errors via `@ts-expect-error`. Sources: [drizzle-orm/type-tests/mysql/select.ts:547-608](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/select.ts#L547-L608) ## Relational Joins and Aliased Scopes ### Subquery Type Inference and Constraint Validation Type definitions for derived tables and subqueries enforce strict structural verification across dialect implementations, ensuring that joined scopes, set operators, and inline selections preserve correct nullability and projection shapes. When queries are aliased via `.as('aliasName')`, their exported shape maps precisely to the columns selected within the builder block. For example, subqueries built with explicit grouping or aggregation correctly propagate column types and handle nullable projections resulting from outer or left join operations. ```typescript const n1 = db .select({ id: users.id, name: users.name, authorId: users.managerId, count1: sql`count(1)::int`.as('count1'), }) .from(users) .groupBy(users.id, users.name, users.managerId) .as('n1'); ``` Sources: [drizzle-orm/type-tests/mysql/subquery.ts:21-30](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/subquery.ts#L21-L30), [drizzle-orm/type-tests/pg/subquery.ts:21-30](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/subquery.ts#L21-L30) > [!WARNING] > Attempting to project multiple columns inside a scalar subquery passed to `.select()` triggers a compile-time `DrizzleTypeError` containing the message `'You can only select one column in the subquery'`, preventing invalid multi-column scalar expansions. Sources: [drizzle-orm/type-tests/mysql/subquery.ts:118-124](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/subquery.ts#L118-L124), [drizzle-orm/type-tests/pg/subquery.ts:118-124](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/subquery.ts#L118-L124) ### Aliased Table Scopes and NodeNext Join Resolution Aliasing tables using the dialect-specific `alias()` helper enables self-joins and complex graph relationships while maintaining distinct object keys in result tuples. Under NodeNext module resolution and mock configurations across SingleStore, Gel, PostgreSQL, MySQL, and SQLite, table joins against aliased references correctly namespace the resulting row objects. | Dialect Module | Alias Helper Import Path | View Constructor | Mock Driver Method | | :--- | :--- | :--- | :--- | | **PostgreSQL** | `~/pg-core/alias.ts` | `pgView('name')` | `pgd.mock()` | | **MySQL / SingleStore** | `~/mysql-core/alias.ts` | `mysqlView('name')` | `mysqld.mock()` | | **SQLite** | `~/sqlite-core/alias.ts` | `sqliteView('name')` | `sqlited.mock()` | | **Gel / GelDB** | `~/gel-core/index.ts` | — | `drizzle.mock()` | Sources: [drizzle-orm/type-tests/common/aliased-table.ts:1-31](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/common/aliased-table.ts#L1-L31), [integration-tests/type-tests/join-nodenext/gel.ts:1-21](https://github.com/blade47/type-tests/join-nodenext/gel.ts#L1-L21), [integration-tests/type-tests/join-nodenext/singlestore.ts:1-20](https://github.com/blade47/type-tests/join-nodenext/singlestore.ts#L1-L20) When performing an `innerJoin` or `leftJoin` between a primary table and an aliased table or view, the inferred result structure indexes both the base table and the alias or view identifier as separate properties, with left-joined secondary relations correctly typed as nullable unions (`T | null`). ```typescript const pgRes = await pg.select().from(pgUsers).leftJoin(pgAlias, eq(pgAlias.id, pgUsers.id)); ``` Sources: [drizzle-orm/type-tests/common/aliased-table.ts:32-32](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/common/aliased-table.ts#L32-L32) > [!NOTE] > View definitions created via `.as((qb) => qb.select().from(...))` inherit the complete column schema of their underlying source tables, allowing view aliases to participate in joins identically to base table aliases. Sources: [drizzle-orm/type-tests/common/aliased-table.ts:20-22](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/common/aliased-table.ts#L20-L22), [drizzle-orm/type-tests/common/aliased-table.ts:36-38](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/common/aliased-table.ts#L36-L38) ## Strict Null Check Compiler Compatibility ### Column Builder Schema under Relaxed Null Settings To verify type correctness when TypeScript's `strictNullChecks` flag is disabled, the test suite defines standard table structures across PostgreSQL, MySQL, SQLite, SingleStore, and GelDB. Each table specification includes primary keys, generated columns, default functions, not-null constraints, nullable descriptions, and database default values. | Column Name | Data Type | Constraint / Modifier | | :--- | :--- | :--- | | `id` | `text` | Primary Key, Generated Always (`.generatedAlwaysAs('genstr')`) | | `intId` | `integer` | Primary Key, Generated Identity (`.generatedAlwaysAsIdentity()`) | | `int2Id` | `integer` | Generated Default Identity (`.generatedByDefaultAsIdentity()`) | | `name` | `text` | Default Function (`.$defaultFn(() => '' as string)`) | | `title` | `text` | Not Null (`.notNull()`) | | `description` | `text` | Nullable (implicit) | | `dbdef` | `text` | Database Default (`.default('dbdefval')`) | Sources: [drizzle-orm/type-tests/geldb/no-strict-null-checks/test.ts:4-19](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/no-strict-null-checks/test.ts#L4-L19), [drizzle-orm/type-tests/pg/no-strict-null-checks/test.ts:4-19](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/no-strict-null-checks/test.ts#L4-L19), [drizzle-orm/type-tests/mysql/no-strict-null-checks/test.ts:4-15](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/no-strict-null-checks/test.ts#L4-L15), [drizzle-orm/type-tests/singlestore/no-strict-null-checks/test.ts:4-15](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/no-strict-null-checks/test.ts#L4-L15), [drizzle-orm/type-tests/sqlite/no-strict-null-checks/test.ts:4-15](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/sqlite/no-strict-null-checks/test.ts#L4-L15) > [!WARNING] > Attempting to pass explicit values to generated columns such as `id` or `intId` during update and insert operations correctly triggers compiler errors guarded by `// @ts-expect-error`, verifying that database-generated fields remain protected even when strict null checks are turned off. Sources: [drizzle-orm/type-tests/geldb/no-strict-null-checks/test.ts:23-28](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/no-strict-null-checks/test.ts#L23-L28), [drizzle-orm/type-tests/pg/no-strict-null-checks/test.ts:33-41](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/no-strict-null-checks/test.ts#L33-L41), [drizzle-orm/type-tests/mysql/no-strict-null-checks/test.ts:37-44](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/no-strict-null-checks/test.ts#L37-L44), [drizzle-orm/type-tests/sqlite/no-strict-null-checks/test.ts:37-44](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/sqlite/no-strict-null-checks/test.ts#L37-L44) ### Mutation Validation and Partial Inserts Mock database instances created via `drizzle.mock()` evaluate insert and update payloads against the column definitions. Omitting optional fields, nullable attributes, and default-backed properties is permitted across all supported dialects. ```typescript db.insert(test).values({ title: 'title', }); ``` Sources: [drizzle-orm/type-tests/geldb/no-strict-null-checks/test.ts:104-105](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/geldb/no-strict-null-checks/test.ts#L104-L105), [drizzle-orm/type-tests/pg/no-strict-null-checks/test.ts:104-105](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/pg/no-strict-null-checks/test.ts#L104-L105), [drizzle-orm/type-tests/mysql/no-strict-null-checks/test.ts:64-65](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/no-strict-null-checks/test.ts#L64-L65), [drizzle-orm/type-tests/singlestore/no-strict-null-checks/test.ts:66-67](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/no-strict-null-checks/test.ts#L66-L67), [drizzle-orm/type-tests/sqlite/no-strict-null-checks/test.ts:64-65](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/sqlite/no-strict-null-checks/test.ts#L64-L65) ## Compiler Stress and Set Operators ### Large-Scale Schema Inference Type checking scalability under extreme column counts is verified using generated schemas containing up to 1,000 columns per table. Both MySQL and SingleStore definitions declare extensive numeric and identifier fields with primary keys, autoincrement flags, and default values to validate compiler overhead and memory consumption during type instantiation. ```typescript mysqlTable('test', { col0: double('col1').primaryKey().autoincrement().default(0), col1: double('col1').primaryKey().autoincrement().default(0), col2: double('col1').primaryKey().autoincrement().default(0), col3: double('col1').primaryKey().autoincrement().default(0), col4: double('col1').primaryKey().autoincrement().default(0), col5: double('col1').primaryKey().autoincrement().default(0), col6: double('col1').primaryKey().autoincrement().default(0), col8: double('col1').primaryKey().autoincrement().default(0), col9: double('col1').primaryKey().autoincrement().default(0), col10: double('col1').primaryKey().autoincrement().default(0), col11: double('col1').primaryKey().autoincrement().default(0), col12: double('col1').primaryKey().autoincrement().default(0), col13: double('col1').primaryKey().autoincrement().default(0), col14: double('col1').primaryKey().autoincrement().default(0), col15: double('col1').primaryKey().autoincrement().default(0), col16: double('col1').primaryKey().autoincrement().default(0), col18: double('col1').primaryKey().autoincrement().default(0), col19: double('col1').primaryKey().autoincrement().default(0), col20: double('col1').primaryKey().autoincrement().default(0), col21: double('col1').primaryKey().autoincrement().default(0), ``` Sources: [drizzle-orm/type-tests/mysql/1000columns.ts:3-23](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/1000columns.ts#L3-L23) ```typescript singlestoreTable('test', { col0: double('col1').primaryKey().autoincrement().default(0), col1: double('col1').primaryKey().autoincrement().default(0), col2: double('col1').primaryKey().autoincrement().default(0), col3: double('col1').primaryKey().autoincrement().default(0), col4: double('col1').primaryKey().autoincrement().default(0), col5: double('col1').primaryKey().autoincrement().default(0), col6: double('col1').primaryKey().autoincrement().default(0), col8: double('col1').primaryKey().autoincrement().default(0), col9: double('col1').primaryKey().autoincrement().default(0), col10: double('col1').primaryKey().autoincrement().default(0), col11: double('col1').primaryKey().autoincrement().default(0), col12: double('col1').primaryKey().autoincrement().default(0), col13: double('col1').primaryKey().autoincrement().default(0), col14: double('col1').primaryKey().autoincrement().default(0), col15: double('col1').primaryKey().autoincrement().default(0), col16: double('col1').primaryKey().autoincrement().default(0), col18: double('col1').primaryKey().autoincrement().default(0), col19: double('col1').primaryKey().autoincrement().default(0), col20: double('col1').primaryKey().autoincrement().default(0), col21: double('col1').primaryKey().autoincrement().default(0), ``` Sources: [drizzle-orm/type-tests/singlestore/1000columns.ts:3-23](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/1000columns.ts#L3-L23) > [!NOTE] > These stress files do not execute runtime queries; their sole purpose is to push the TypeScript type engine to its limits when evaluating massive object types and union structures generated by dialect builders. Sources: [drizzle-orm/type-tests/mysql/1000columns.ts:1-23](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/mysql/1000columns.ts#L1-L23), [drizzle-orm/type-tests/singlestore/1000columns.ts:1-23](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/1000columns.ts#L1-L23) ### Set Operator Combinations and Type Safety SingleStore set operators (`union`, `unionAll`, `intersect`, `except`, and `minus`) enforce strict compile-time validation of column counts and compatible data types across combining statements. Mismatched selections are intercepted by `// @ts-expect-error` assertions. | Set Operator Method / Function | Associated Type Constraint | Error Handling for Column / Type Mismatches | | :--- | :--- | :--- | | `.union()` / `union()` | Equivalent projection count and compatible types | Intercepted via `// @ts-expect-error` | | `.unionAll()` / `unionAll()` | Equivalent projection count and compatible types | Intercepted via `// @ts-expect-error` | | `.intersect()` / `intersect()` | Equivalent projection count and compatible types | Intercepted via `// @ts-expect-error` | | `.except()` / `.minus()` | Equivalent projection count and compatible types | Intercepted via `// @ts-expect-error` | Sources: [drizzle-orm/type-tests/singlestore/set-operators.ts:8-66](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/set-operators.ts#L8-L66), [drizzle-orm/type-tests/singlestore/set-operators.ts:159-234](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/set-operators.ts#L159-L234) > [!WARNING] > Combining statements that alter column order or omit fields between queries will fail type verification; the engine requires identical tuple shapes or explicitly compatible mapped types across every branch of a set operation. Sources: [drizzle-orm/type-tests/singlestore/set-operators.ts:162-181](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/set-operators.ts#L162-L181), [drizzle-orm/type-tests/singlestore/set-operators.ts:201-234](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-orm/type-tests/singlestore/set-operators.ts#L201-L234) ## Related - [Table and Column Models](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/table-and-column-models) - [Query Builder Foundation](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/query-builder-foundation) - [Integration Test Harness](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/testing-and-tooling/integration-test-harness) --- ## User guide: Quickstart Guide URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/getting-started/quickstart-guide ## Overview ### Introduction The Quickstart Guide helps you get up and running with Drizzle ORM by setting up your project, installing the necessary packages, and establishing your first database connection. Drizzle ORM connects to your database using specific database drivers, allowing you to run queries safely and efficiently in TypeScript or JavaScript. > [!NOTE] > Before you begin, make sure you have Node.js installed on your computer and a running database instance ready to connect to. --- ### Step-by-Step Installation and Configuration #### Introduction Follow these steps to install Drizzle ORM and configure your database connection. #### 1. Install Drizzle ORM and Your Database Driver Install the core Drizzle ORM package along with the appropriate driver for your database. Drizzle supports many different database engines and client libraries. Supported database drivers and packages: - PostgreSQL: `node-postgres`, `postgres`, `neon-serverless`, `neon-http`, `vercel-postgres`, `bun-sql`, `pqlite`, `xata-http` - MySQL: `mysql2`, `@planetscale/database`, `@tidbcloud/serverless` - SQLite: `@libsql/client/http`, `@libsql/client/ws`, `@op-engineering/op-sqlite`, `sql.js` - Other: `gel` Run the installation command for your chosen setup using your preferred package manager (for example, npm): ```bash npm install drizzle-orm mysql2 ``` #### 2. Configure Your Database Connection Import the `drizzle` function from the module matching your driver and pass in either your database connection string, an existing connection client, or a configuration object. Here is an example using PostgreSQL with `node-postgres`: ```typescript import pg from 'pg'; import { drizzle } from 'drizzle-orm/node-postgres'; // Option A: Pass a connection string directly const db = drizzle('postgres://user:password@localhost:5432/dbname'); // Option B: Pass a pre-configured client pool const pool = new pg.Pool({ connectionString: 'postgres://user:password@localhost:5432/dbname', }); const db = drizzle({ client: pool }); ``` #### 3. Verify the Connection You can now use your `db` instance to perform queries and interact with your database tables. --- ### Key Concepts #### Introduction Review these essential concepts to better understand how Drizzle connects to your data. * **Database Driver:** A library that enables Node.js to communicate with a specific database server (such as PostgreSQL, MySQL, or SQLite). Drizzle sits on top of these drivers to provide type safety and query building. * **Connection String:** A standard URL containing your database credentials, host, port, and database name (for example, `mysql://user:password@localhost:3306/database`). * **Client / Pool:** An active session manager or connection pool provided by your database driver that handles network communication with your database server. --- ### Configuration Options #### Introduction When initializing Drizzle with the `drizzle()` function, you can pass an optional configuration object alongside your connection. | Option | Type | Description | | :--- | :--- | :--- | | `schema` | `Record` | An object containing your database tables and relations for relational queries. | | `logger` | `boolean \| Logger` | Enables default query logging or accepts a custom logger implementation. | | `casing` | `string` | Defines automatic casing transformation for column and table names. | | `cache` | `Cache` | Optional caching configuration for query results. | > [!TIP] > When providing a `schema` for MySQL databases using the `mysql2` driver, you must also specify the `mode` property in your configuration (either `mode: 'default'` or `mode: 'planetscale'`). > [!WARNING] > Always verify that your database name is explicitly included in your connection string or configuration object. Omitting the database name will cause connection initialization to fail. ## Related - [Connecting Databases](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/getting-started/connecting-databases) - [Declaring Schemas](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/core-features/declaring-schemas) --- ## User guide: Connecting Databases URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/getting-started/connecting-databases ## Overview To start querying and managing your database with Drizzle ORM, you need to connect it using a driver. Drizzle supports a wide variety of relational databases — including PostgreSQL, MySQL, SQLite, SingleStore, and Gel — alongside numerous serverless drivers, cloud data APIs, and object-relational mapping extensions. Connecting your database typically involves passing a connection string, a configuration object, or an existing database client instance into Drizzle's initialization function. --- ## Supported Drivers and Providers Drizzle provides specialized integration packages for different database engines and execution environments. Supported database dialects: `postgresql`, `mysql`, `sqlite`, `singlestore`, `gel`. Supported driver and provider package names: - **PostgreSQL / Serverless Postgres:** `@aws-sdk/client-rds-data`, `@electric-sql/pglite`, `pg`, `postgres`, `@vercel/postgres`, `@neondatabase/serverless` - **MySQL / Serverless MySQL:** `mysql2`, `@planetscale/database`, `@tidbcloud/serverless` - **SQLite / LibSQL:** `@libsql/client`, `@libsql/client/sqlite3`, `@libsql/client/node`, `@libsql/client/ws`, `@libsql/client/http`, `@libsql/client-wasm`, `better-sqlite3` - **Other Environments:** `gel`, `netlify-db`, `cloudflare/workers-types` (Durable Objects SQLite), `@prisma/client` (via Prisma extensions) --- ## How to Connect Your Database ### Connecting via Connection String The simplest way to connect to most databases is by passing the connection string directly as a string parameter. ```typescript import { drizzle } from 'drizzle-orm/node-postgres'; const db = drizzle('postgres://user:password@host:port/database_name'); ``` ### Connecting via Configuration Object You can pass a configuration object containing connection details (such as a URL, host, user, password, or driver-specific options) along with optional schema definitions or loggers. ```typescript import { drizzle } from 'drizzle-orm/node-postgres'; const db = drizzle({ connection: { connectionString: process.env.DATABASE_URL, ssl: true, }, }); ``` ### Connecting via an Existing Client Instance If your application already manages a database connection pool or client, you can pass that pre-configured client directly into Drizzle. ```typescript import { drizzle } from 'drizzle-orm/node-postgres'; import { Pool } from 'pg'; const pool = new Pool({ connectionString: process.env.DATABASE_URL }); const db = drizzle({ client: pool }); ``` --- ## Key Concepts * **Driver:** A software package or layer that allows Drizzle to communicate with your specific database engine or serverless environment. * **Dialect:** The specific flavor of SQL spoken by your database system (e.g., PostgreSQL, MySQL, SQLite). * **Connection String:** A URI containing your database credentials, host, port, and database name. * **Mock Database:** A simulated database instance generated via `drizzle.mock()` that lets you build queries or initialize schemas without an active network connection to a live database. --- ## Tips and Warnings > [!TIP] > When working with serverless environments or edge functions (such as Neon, Vercel Postgres, or LibSQL), prefer HTTP-based or serverless drivers to handle fast connection cold starts and stateless requests efficiently. > [!NOTE] > If you are using MySQL or SQLite with database migrations, Drizzle automatically manages SQL statement breakpoints to ensure that statements which cannot run together in a single transaction execute safely one-by-one. > [!WARNING] > When supplying a schema object alongside `mysql2` or `singlestore` drivers, you must explicitly specify the `mode` parameter (e.g., `mode: 'default'` or `mode: 'planetscale'`) in your configuration to avoid runtime errors. ## Related - [Quickstart Guide](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/getting-started/quickstart-guide) - [Configuring Drizzle Kit](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/configuration/configuring-drizzle-kit) --- ## User guide: Declaring Schemas URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/core-features/declaring-schemas ## Overview ### Introduction Defining database schemas in TypeScript allows you to structure your tables, columns, primary keys, indexes, and constraints with full type safety. By declaring your schema using table functions, you gain automatic type inference for both querying and inserting records. --- ### Defining Tables and Columns To declare a table, use the table creation function corresponding to your database engine, such as `pgTable`, `mysqlTable`, `sqliteTable`, `gelTable`, or `singlestoreTable`. Pass the database table name as the first argument and an object containing your columns as the second argument. ```typescript import { pgTable, serial, text, integer } from 'drizzle-orm/pg-core'; export const users = pgTable('users_table', { id: serial('id').primaryKey(), name: text('name').notNull(), age: integer('age1').notNull(), }); ``` --- ### Adding Primary Keys Primary keys uniquely identify each row in a table. You can define them directly on an individual column or configure composite primary keys using an extra configuration callback (the third argument of the table function). ```typescript import { pgTable, text, primaryKey } from 'drizzle-orm/pg-core'; export const users = pgTable( 'users_table', { class: text('class').notNull(), subClass: text('sub_class').notNull(), name: text('name'), }, (users) => [ primaryKey({ columns: [users.class, users.subClass] }), ] ); ``` --- ### Creating Indexes and Unique Constraints Indexes speed up data retrieval, while unique constraints ensure that column values remain distinct across rows. You can declare indexes and unique constraints inside the extra configuration function. ```typescript import { pgTable, text, index, uniqueIndex, unique } from 'drizzle-orm/pg-core'; export const users = pgTable( 'users_table', { id: serial('id').primaryKey(), email: text('email').notNull(), role: text('role'), }, (users) => [ index('user_role_idx').on(users.role), uniqueIndex('user_email_idx').on(users.email), unique('custom_unique_name').on(users.email, users.role), ] ); ``` --- ### Setting Up Constraints and Foreign Keys Constraints enforce rules on your data, such as check conditions or relationships between tables using foreign keys. ```typescript import { pgTable, serial, integer, text, check, foreignKey } from 'drizzle-orm/pg-core'; export const users = pgTable( 'users_table', { id: serial('id').primaryKey(), age: integer('age').notNull(), classSubClass: text('sub_class'), }, (users) => [ check('legal_age', sql`${users.age} > 18`), foreignKey({ columns: [users.classSubClass], foreignColumns: [classes.subClass], }).onUpdate('cascade').onDelete('cascade'), ] ); ``` > [!TIP] > Use `.notNull()` on columns that are required, and `.default()` or `.defaultNow()` for automatic values. > [!NOTE] > Depending on your chosen dialect, extra configuration callbacks accept either arrays or objects. Ensure you match the syntax expected by your database module. ## Related - [Custom Column Types](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/how-to-guides/custom-column-types) - [Managing Migrations](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/how-to-guides/managing-migrations) --- ## User guide: Querying Records URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/core-features/querying-records ## Overview Querying records allows you to select, filter, sort, join, and aggregate data from your database using a fluent, SQL-like syntax directly in TypeScript. Drizzle provides powerful query builders that give you full control over how you retrieve and shape your data while maintaining complete type safety. > [!NOTE] Casting expressions to specific types (such as numbers or dates) ensures your query results match your expected TypeScript types. --- ## Selecting Data You can fetch all columns from a table or specify exactly which columns and custom expressions you want to include in your result set. ```ts // Select all columns and all rows from the 'cars' table const allCars = await db.select().from(cars); // Select specific columns from the 'cars' table const carsIdsAndBrands = await db.select({ id: cars.id, brand: cars.brand }).from(cars); // Select specific columns along with an expression const carsIdsAndLowerNames = await db.select({ id: cars.id, lowerBrand: sql`lower(${cars.brand})`, }).from(cars); ``` --- ## Filtering Records ### Basic Filtering Use the `.where()` clause combined with conditional operators to retrieve only the rows that match specific criteria. ```ts // Select all cars with a green color await db.select().from(cars).where(eq(cars.color, 'green')); ``` ### Combining Conditions You can group multiple filters together using logical operators like `and()` or `or()`: ```ts // Select all BMW cars with a green color await db.select().from(cars).where(and(eq(cars.color, 'green'), eq(cars.brand, 'BMW'))); // Select all cars with green or blue color await db.select().from(cars).where(or(eq(cars.color, 'green'), eq(cars.color, 'blue'))); ``` --- ## Sorting and Pagination You can organize your query results by ordering them, limiting the total count, or skipping rows with an offset. ```ts // Select cars ordered by year in ascending order await db.select().from(cars).orderBy(cars.year); // Select cars ordered by year in descending order, then by price await db.select().from(cars).orderBy(desc(cars.year), asc(cars.price)); // Limit results and apply an offset for pagination await db.select().from(people).offset(10).limit(10); ``` --- ## Joining Tables Combine rows from multiple tables or queries to retrieve related data across datasets. ```ts // Combine user records with city data const usersAndCities = await db.select({ userId: users.id, cityName: cities.name, }) .from(users); ``` When building relational queries, table relationships can also be traversed and loaded hierarchically using query configs with the `with` property. --- ## Aggregations and Grouping Group rows with shared values into summary rows and filter aggregated data using `.groupBy()` and `.having()`. ```ts // Group and count cars by their brand, keeping only brands with more than one car await db.select({ brand: cars.brand, count: sql`cast(count(${cars.id}) as int)`, }) .from(cars) .groupBy(cars.brand) .having(({ count }) => gt(count, 1)); ``` > [!TIP] Use `.having()` to filter aggregated results (like counts or sums) just like you use `.where()` to filter individual table rows. ## Related - [Relational Queries](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/core-features/relational-queries) - [Modifying Data](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/core-features/modifying-data) --- ## User guide: Relational Queries URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/core-features/relational-queries ## Overview ### Understanding Relational Queries Relational Queries allow you to fetch nested relations and related records in a structured, hierarchical format without writing manual SQL `JOIN` statements. Instead of manually stitching together rows from multiple tables and mapping them in your application code, you can use the built-in query syntax to query related tables cleanly. > [!NOTE] > Relational queries use the schema and relations defined using the `relations()` helper function alongside your database tables. --- ### Key Concepts To use relational queries effectively, you should understand the following core components: * **`findMany()`**: Retrieves a list of records matching your query criteria, returning an array of nested objects. * **`findFirst()`**: Retrieves a single record (the first match), returning an object or `undefined`. * **`with`**: A configuration property used to specify which related records or nested relations to include in the result. * **`columns`**: A property used to include or exclude specific columns from the selected table. * **`extras`**: Allows you to add custom computed fields or SQL expressions to your query selection. --- ### Querying Nested Relations You can fetch related records at multiple levels of nesting using the `with` property. The query builder fully preserves type safety and returns neatly structured objects that reflect your relational tree. ```typescript const result = await db.query.users.findMany({ where: (users, { sql }) => sql`char_length(${users.name} > 1)`, limit: 10, orderBy: (users, { asc, desc }) => [asc(users.name), desc(users.id)], with: { posts: { with: { author: true, comments: { with: { author: true, }, }, }, }, }, }); ``` --- ### Selecting Specific Columns and Extras By default, all table columns are selected. You can customize which columns to retrieve, or add computed fields using `extras`. ```typescript const result = await db.query.users.findMany({ columns: { id: true, name: true, }, with: { posts: { columns: { authorId: true, }, extras: { lowerTitle: sql`lower(${posts.title})`.as('lower_title'), }, }, }, }); ``` > [!IMPORTANT] > When using the `columns` property in include mode, at least one item must be set to `true`, or the `columns` key can be omitted entirely if you want to select all columns. --- ### Configuration Options Reference The following options can be passed to `findMany` and `findFirst` query configurations: | Option | Type | Description | | :--- | :--- | :--- | | `columns` | Object | Choose specific columns to include or exclude (`true` or `false`). | | `with` | Object | Specify related tables and nested query configurations to fetch. | | `where` | Function / SQL | Filter records using conditions and operator helpers. | | `orderBy` | Function / Array | Sort results using ascending or descending helpers. | | `limit` | Number / Placeholder | Restrict the maximum number of returned rows. | | `offset` | Number / Placeholder | Skip a specified number of rows (available on `findMany`). | | `extras` | Object / Function | Define custom SQL expressions or aliases to include in the result. | > [!TIP] > You can pass SQL placeholders to options like `limit` and `offset` for reusable prepared queries. ## Related - [Querying Records](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/core-features/querying-records) - [Declaring Schemas](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/core-features/declaring-schemas) --- ## User guide: Modifying Data URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/core-features/modifying-data ## Overview ### Modifying Database Records Modifying data involves inserting, updating, upserting, and deleting records across database tables. You can perform these operations safely and expressively using type-safe query builders across PostgreSQL, MySQL, SQLite, Gel, and SingleStore databases. ### Inserting Records To create new rows in a database table, use the `insert` method combined with `.values()`. You can insert a single record, multiple records at once, or use subqueries and returning clauses where supported. ```ts // Insert one row await db.insert(cars).values({ brand: 'BMW' }); // Insert multiple rows await db.insert(cars).values([{ brand: 'BMW' }, { brand: 'Porsche' }]); // Insert with a returning clause to retrieve inserted data const insertedCar = await db.insert(cars) .values({ brand: 'BMW' }) .returning(); ``` > [!TIP] > When working with databases that support returning clauses (like PostgreSQL, SQLite, and Gel), you can immediately fetch the newly created rows or specific columns by chaining `.returning()`. ### Updating Records To modify existing records, use the `update` method along with `.set()` to specify the new values and `.where()` to target specific rows. ```ts // Update rows matching a condition await db.update(cars) .set({ color: 'red' }) .where(eq(cars.brand, 'BMW')); // Update with a returning clause const updatedCar = await db.update(cars) .set({ color: 'red' }) .where(eq(cars.id, 1)) .returning(); ``` > [!WARNING] > Omitting the `.where()` clause on an update query will modify **every single row** in the table. Always double-check your filters before running bulk updates. ### Handling Upserts and Conflicts #### PostgreSQL, SQLite, and Gel Use `.onConflictDoNothing()` or `.onConflictDoUpdate()` to handle key collisions gracefully: ```ts // Skip the insert if a conflict occurs on the target column await db.insert(cars) .values({ id: 1, brand: 'BMW' }) .onConflictDoNothing({ target: cars.id }); // Update the existing record if a conflict occurs await db.insert(cars) .values({ id: 1, brand: 'BMW' }) .onConflictDoUpdate({ target: cars.id, set: { brand: 'Porsche' } }); ``` #### MySQL and SingleStore Use `.onDuplicateKeyUpdate()` when inserting data into tables with unique or primary key constraints: ```ts import { sql } from 'drizzle-orm'; await db.insert(cars) .values({ id: 1, brand: 'BMW' }) .onDuplicateKeyUpdate({ set: { brand: 'Porsche' } }); ``` ### Deleting Records To remove rows from a table, use the `delete` method with an optional `.where()` filter. ```ts // Delete specific rows matching a condition await db.delete(cars).where(eq(cars.color, 'green')); // Delete with a returning clause const deletedCar = await db.delete(cars) .where(eq(cars.id, 1)) .returning(); ``` > [!CAUTION] > Running `db.delete(table)` without a `.where()` clause deletes all records in the table. Ensure you include a filter unless you intend to clear the entire table. ## Related - [Querying Records](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/core-features/querying-records) --- ## User guide: Managing Migrations URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/how-to-guides/managing-migrations ## Overview Managing migrations allows you to safely evolve your database schema as your application changes. Drizzle Kit handles the process of inspecting your code-defined schema, comparing it to previous versions, and generating the necessary database statements. You can then review these changes and apply them to your live database. ```mermaid flowchart LR A[Define/Update Schema] --> B[Generate Migration] B --> C[Review SQL & Snapshots] C --> D[Apply Migrations] ``` --- ## Key Concepts Before working with migrations, it helps to understand a few core terms: * **Schema:** The TypeScript description of your database tables, columns, relations, and views. * **Migration:** A generated file containing SQL statements that update your database structure. * **Snapshot:** A JSON record of your schema state at a specific point in time, used by the tooling to calculate what has changed. * **Journal:** An internal tracking file (`_journal.json`) that keeps an organized history of all generated migrations. * **Database Dialect:** The specific database engine your application uses. Supported database dialects: `gel`, `postgresql`, `mysql`, `sqlite`, `turso`, or `singlestore`. *(Sources: `drizzle-kit/src/cli/schema.ts`)* Supported database drivers: `aws-data-api`, `d1-http`, `d1`, `turso`, or `pglite`. *(Sources: `drizzle-kit/src/cli/schema.ts`, `drizzle-kit/src/serializer/studio.ts`)* --- ## Generating Migrations ### Running the Generator When you modify your TypeScript schema definition, you need to generate a new migration file so your database can catch up. 1. Open your terminal in your project directory. 2. Run the generation command, specifying your options such as the schema path and output folder: ```bash npx drizzle-kit generate ``` ### Available Generation Options | Option | Description | | :--- | :--- | | `config` | Path to your configuration file. | | `dialect` | Database dialect: `gel`, `postgresql`, `mysql`, `sqlite`, `turso`, or `singlestore`. | | `driver` | Database driver. | | `casing` | Casing style for serialization: `camelCase` or `snake_case`. | | `schema` | Path to a schema file or folder. | | `out` | Output folder for migrations (`drizzle` by default). | | `name` | Custom migration file name. | | `breakpoints` | Prepare SQL statements with breakpoints. | | `custom` | Prepare an empty migration file for custom SQL (`false` by default). | | `prefix` | Prefix mode for files: `index`. | *(Sources: `drizzle-kit/src/cli/schema.ts`)* > [!NOTE] > The `generate` command cannot be used with the `gel` dialect. Attempting to do so will result in an error and exit. > *(Sources: `drizzle-kit/src/cli/schema.ts`)* --- ## Reviewing and Updating Migrations ### Updating Snapshot Versions As your project grows, your migration folders and snapshots must remain up to date. > [!IMPORTANT] > If your migration folder uses an outdated format (such as older V1 folder structures), the tool will detect it and require you to update. > *(Sources: `drizzle-kit/src/utils.ts`)* To upgrade your migration snapshots to the latest version compatible with your tooling, run: ```bash npx drizzle-kit up ``` *(Sources: `drizzle-kit/src/cli/index.ts`, `drizzle-kit/src/cli/commands/pgUp.ts`, `drizzle-kit/src/utils.ts`)* --- ## Applying Migrations ### Running the Migrator Once you have generated and reviewed your migration files, you can apply them to your database using the migration runner command. 1. Ensure your connection details and configuration file are properly set up. 2. Run the migration command: ```bash npx drizzle-kit migrate ``` This command inspects your database, checks the internal migration tracking table (typically created automatically as `__drizzle_migrations`), and runs any pending SQL statements in the correct order. > [!WARNING] > Certain database drivers (such as Neon HTTP and Xata HTTP) do not support transactions. If any part of a migration fails when using these drivers, automatic rollbacks will not occur, and you will need to handle incomplete or unsuccessful migrations manually. > *(Sources: `drizzle-orm/src/neon-http/migrator.ts`, `drizzle-orm/src/xata-http/migrator.ts`)* ## Related - [Configuring Drizzle Kit](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/configuration/configuring-drizzle-kit) - [Declaring Schemas](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/core-features/declaring-schemas) --- ## User guide: Introspecting Databases URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/how-to-guides/introspecting-databases ## Overview Database introspection inspects an existing database structure and automatically generates corresponding TypeScript schema and relation code for your project. This saves you from writing schema definitions by hand when working with an already established database. > [!NOTE] > Introspection analyzes your database tables, columns, constraints, and relationships to produce TypeScript files ready for use in your application. ## How It Works When you run an introspection command, the system connects to your database, reads the system catalog and information schema, and compiles the layout into TypeScript code. ```mermaid flowchart TD A[Connect to existing database] --> B[Analyze tables, columns & constraints] B --> C[Generate TypeScript schema code] C --> D[Save schema files to project output directory] ``` ## Supported Database Dialects Introspection supports multiple database providers and dialects. Supported dialects: `postgresql`, `mysql`, `sqlite`, `turso`, `singlestore`, `gel`. *(Sources: `drizzle-kit/src/cli/schema.ts`)* ## Outputs Depending on the database dialect and configuration, introspection typically generates: * **Schema file (`schema.ts`)**: Contains table definitions, columns, data types, and constraints. * **Relations file (`relations.ts`)**: Contains table relationships when applicable. > [!TIP] > If your project already contains migration history snapshots, introspection will recognize them and avoid duplicating migration files. ## Related - [Declaring Schemas](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/core-features/declaring-schemas) - [Configuring Drizzle Kit](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/configuration/configuring-drizzle-kit) --- ## User guide: Custom Column Types URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/how-to-guides/custom-column-types ## Overview ### Introduction Sometimes your application needs to store data types that are specific to your business logic or not natively supported out of the box. **Custom Column Types** let you define your own data types and map them directly to database columns. This feature bridges the gap between your application's TypeScript data models and how values are represented, serialized, and retrieved from your database. By defining a custom column type, you can control the exact database data type string used for migrations, automatically serialize JavaScript or TypeScript objects into driver-accepted parameters before writing to the database, and deserialize incoming database values back into your desired runtime format. --- ### Defining a Custom Type To create a custom column type, use the `customType` function. You provide configuration parameters that dictate how the column behaves during database interactions and type-checking. ```typescript import { customType } from 'drizzle-orm/pg-core'; const customVarchar = customType<{ data: string; driverData: string; config: { length: number }; configRequired: true; }>({ dataType(config) { return `varchar(${config.length})`; }, toDriver(value) { return value; }, fromDriver(value) { return value; }, }); ``` --- ### Configuration Options When defining a custom type, you configure its parameters using standard type definitions: | Option | Description | Default | | :--- | :--- | :--- | | `data` | The TypeScript type used in your application after selecting or when inserting. | `unknown` | | `driverData` | The type accepted by the database driver for this database type. | `unknown` | | `config` | The configuration object type passed into `dataType` generation. | `Record` | | `configRequired` | Whether the configuration argument is mandatory when defining the column. | `false` | | `notNull` | Marks the custom data type as non-nullable by default. | `false` | | `default` | Marks the custom data type as having a default value by default. | `false` | --- ### Mapping Values Between Application and Driver Custom types allow you to transform data seamlessly as it travels between your TypeScript code and the database driver using two main mapping functions: 1. **`toDriver`**: Converts your application data model into a format accepted by the database driver right before an insert or update query executes (for example, serializing an object into a JSON string). 2. **`fromDriver`**: Converts raw database values coming from the driver back into your application's preferred runtime data type (for example, parsing a date string into a real JavaScript `Date` object). > [!TIP] > The `toDriver` function can return either the expected driver parameter type or a custom raw SQL expression object when advanced query manipulation is needed. --- ### Working with Optional and Required Configurations You can configure your custom types to accept optional settings or enforce required parameters depending on your database schema needs. ```typescript // Example with an optional configuration const flexibleString = customType<{ data: string; driverData: string; config: { length: number }; }>({ dataType(config) { return config ? `varchar(${config.length})` : 'text'; }, toDriver(value) { return value; }, fromDriver(value) { return value; }, }); // Usage with config const col1 = flexibleString('col1', { length: 50 }); // Usage without config (falls back to text) const col2 = flexibleString('col2'); ``` > [!WARNING] > If you set `configRequired: true` in your custom type definition, omitting the configuration object when declaring the column will trigger a TypeScript compilation error. ## Related - [Declaring Schemas](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/core-features/declaring-schemas) --- ## User guide: Configuring Drizzle Kit URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/configuration/configuring-drizzle-kit ## Overview ### Introduction to Configuration Configuring Drizzle Kit allows you to define how database commands—such as generating migrations, pushing schema updates, and running Drizzle Studio—interact with your database. By setting up a configuration file, you can specify your database dialect, connection credentials, file paths, and advanced options in one centralized place. --- ### Creating a Configuration File To get started, create a configuration file named in your project's root directory. 1. Create a file named `drizzle.config.ts` in your project root. 2. Define and export your configuration object using the required `dialect`, `schema`, and credential settings. Here is a sample configuration file for a PostgreSQL database: ```typescript import type { Config } from 'drizzle-kit'; export default { dialect: 'postgresql', schema: './src/schema.ts', out: './drizzle', dbCredentials: { url: process.env.DATABASE_URL!, }, } satisfies Config; ``` > [!NOTE] > Make sure you have installed the required database driver packages in your project before running commands with your configuration file. --- ### Configuration Options Reference The configuration options available for your setup control how Drizzle Kit connects to and processes your database schema. | Option | Type | Description | | :--- | :--- | :--- | | `dialect` | string | Mandatory database dialect. Supported dialects: `postgresql`, `mysql`, `sqlite`, `singlestore`, `gel`, `turso`. | | `schema` | string \| string[] | Path or glob pattern to your database schema file or files. | | `out` | string | Output folder for generated migration files and database snapshots. Defaults to `./drizzle`. | | `driver` | string | Optional driver used when accessing specific services. Supported drivers: `aws-data-api`, `d1-http`, `expo`, `turso`, `pglite`. | | `dbCredentials` | object | Connection credentials required to connect to your database (such as connection strings or host details). | | `breakpoints` | boolean | Enables or disables SQL statement breakpoints in generated migrations. True by default. | | `verbose` | boolean | Prints all statements that will be executed during push commands. | | `strict` | boolean | Always asks for confirmation before executing statements to sync your schema with the database. | | `casing` | string | Controls column casing for serialization. Supported values: `camelCase`, `snake_case`. | | `tablesFilter` | string \| string[] | Glob pattern or array of patterns to filter tables during push commands. | | `schemaFilter` | string \| string[] | Defines which schema in PostgreSQL to use for introspection or push commands. | --- ### Database Credentials by Dialect Depending on the chosen `dialect`, the `dbCredentials` object expects specific properties: * **PostgreSQL:** Can use a connection URL (`url`) OR individual fields (`host`, `port`, `user`, `password`, `database`, `ssl`). Alternatively, when using the `aws-data-api` driver, it requires `database`, `secretArn`, and `resourceArn`. * **MySQL:** Can use a connection URL (`url`) OR individual fields (`host`, `port`, `user`, `password`, `database`, `ssl`). * **SQLite:** Requires a database file path or URL (`url`). * **Turso / LibSQL:** Requires a database URL (`url`) and an optional authentication token (`authToken`). * **SingleStore:** Can use a connection URL (`url`) OR individual fields (`host`, `port`, `user`, `password`, `database`). > [!TIP] > Use environment variables (via `process.env.DATABASE_URL`) inside your configuration file to keep sensitive credentials secure and out of version control. ## Related - [Managing Migrations](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/how-to-guides/managing-migrations) - [Connecting Databases](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/getting-started/connecting-databases) --- ## User guide: Schema Validation URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/integrations/schema-validation ## Overview ### What is Schema Validation? Schema validation allows you to automatically generate validation rules and types from your database table definitions. Instead of manually writing validation code for inserts, updates, and data queries, you can generate schemas directly using popular validation libraries. Supported validation libraries: Zod, Valibot, TypeBox, ArkType. > [!NOTE] > Schema generation works for both database tables and views, automatically respecting column constraints such as nullability, default values, and generated columns. --- ## Generating Schemas ### Understanding Schema Generation Functions To generate a validation schema, import the relevant creation functions for your chosen validation library. There are three main schema generation functions available: - `createSelectSchema`: Generates a schema for validating records fetched from the database (all fields are present, nullable columns allow nulls). - `createInsertSchema`: Generates a schema for validating new records before insertion (fields with defaults or auto-incrementing values become optional). - `createUpdateSchema`: Generates a schema for updating records (all fields become optional). ### Code Example ```typescript import { pgTable, serial, text, integer } from 'drizzle-orm/pg-core'; import { createSelectSchema, createInsertSchema, createUpdateSchema } from 'drizzle-zod'; export const users = pgTable('users', { id: serial('id').primaryKey(), name: text('name').notNull(), email: text('email'), }); // Generate validation schemas export const selectUserSchema = createSelectSchema(users); export const insertUserSchema = createInsertSchema(users); export const updateUserSchema = createUpdateSchema(users); ``` --- ## Customizing and Refining Schemas ### Adding Custom Field Rules You can refine individual fields when generating schemas by passing a second argument containing your custom rules. ```typescript import { z } from 'zod'; const insertUserSchema = createInsertSchema(users, { email: (schema) => schema.email().email(), // Add email format validation name: z.string().min(2), // Override the name schema entirely }); ``` --- ## Advanced Configuration Options ### Enabling Type Coercion (Zod) When using Zod, you can use a schema factory to enable automatic type coercion for primitive values like numbers, booleans, dates, strings, and bigints. Supported coercion types: `bigint`, `boolean`, `date`, `number`, `string`. ```typescript import { createSchemaFactory } from 'drizzle-zod'; const { createInsertSchema } = createSchemaFactory({ coerce: { number: true, boolean: true, }, }); export const insertSchema = createInsertSchema(users); ``` > [!TIP] > Setting `coerce: true` enables type coercion for all supported primitive types simultaneously. ## Related - [Declaring Schemas](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/core-features/declaring-schemas) - [Modifying Data](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/core-features/modifying-data) --- ## User guide: Seeding Test Data URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/integrations/seeding-test-data ## Overview ### Database Seeding Essentials Populating your database with realistic dummy data for testing and development is easy using the built-in seeding tools. Instead of writing manual insert scripts, you can automatically generate rows of realistic names, emails, addresses, numbers, and more that respect your table structures and relationships. To quickly populate your database with default dummy data, pass your database connection and schema object to the seeding function. ```ts import { seed } from 'drizzle-seed'; // Basic seeding with default row counts await seed(db, schema); ``` > [!NOTE] > The database seeding features currently support PostgreSQL, MySQL, and SQLite databases. ### Controlling Row Counts and Reproducibility You can customize how many rows are generated and ensure your test data is reproducible by providing an options object. ```ts // Generate 100,000 rows per table await seed(db, schema, { count: 100000 }); // Generate data with a fixed seed so it is identical every time you run it await seed(db, schema, { count: 100000, seed: 1 }); ``` | Option | Description | | :--- | :--- | | `count` | The number of rows you want to generate per table. | | `seed` | A number controlling the pseudo-random state. Using the same seed number produces the exact same generated data on every run. | | `version` | Selects the generator version (`1` or `2`). | --- ### Customizing Data with Refinements You can tailor the generated data for specific tables and columns by chaining a refinement function onto your seed call. This lets you apply specific generators, set unique constraints, or use custom value lists. ```ts await seed(db, schema, { count: 1000 }).refine((funcs) => ({ users: { columns: { name: funcs.firstName({ isUnique: true }), email: funcs.email(), phone: funcs.phoneNumber({ template: "+380 99 ###-##-##" }), password: funcs.string({ isUnique: true }), }, count: 10000, }, posts: { columns: { title: funcs.valuesFromArray({ values: ["Title1", "Title2", "Title3", "Title4", "Title5"], }), content: funcs.loremIpsum({ sentencesCount: 3 }), }, }, })); ``` --- ### Available Data Generators You can use various generator functions inside your refinement callbacks to populate columns with specific types of realistic data. | Generator Function | Description | | :--- | :--- | | `funcs.city()` | Generates realistic city names. | | `funcs.streetAddress()` | Generates realistic street addresses. | | `funcs.jobTitle()` | Generates realistic job titles. | | `funcs.postcode()` | Generates postal codes. | | `funcs.state()` | Generates US state names. | | `funcs.companyName()` | Generates company names. | | `funcs.loremIpsum()` | Generates placeholder text sentences. | | `funcs.point()` | Generates 2D coordinate points. | | `funcs.line()` | Generates 2D line parameters. | | `funcs.weightedRandom()` | Calls different generators based on assigned probability weights. | > [!TIP] > Many generators accept options like `isUnique: true` to ensure all generated values in that column are unique, or `arraySize` to generate lists of values. --- ### Clearing Existing Data If you need to clear out existing data before running your seeds, you can use the reset utility. This safely clears all data from the specified tables while handling foreign key constraints automatically. ```ts import { reset } from 'drizzle-seed'; // Remove all data from the specified tables await reset(db, { users, posts }); ``` ## Related - [Declaring Schemas](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/core-features/declaring-schemas) - [Modifying Data](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/core-features/modifying-data) --- ## User guide: Common Troubleshooting URL: https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/troubleshooting/common-troubleshooting ## Overview ### About Common Troubleshooting When working with database schemas, migrations, and connectivity, you may occasionally run into issues such as snapshot collisions, out-of-date migration formats, connection configuration problems, or safety warnings during schema updates. This guide covers how to diagnose and resolve these common scenarios effectively. > [!NOTE] > Always ensure your tooling is up-to-date before troubleshooting migration version mismatches. --- ### Migration Conflicts and Outdated Snapshots #### Conflict Types and Migration Formatting Migration conflicts typically occur when multiple migration files point to the same parent snapshot, or when your project uses an older version of snapshot formats that need upgrading. #### Outdated Migration Folders or Non-Latest Snapshots If your migrations folder or individual snapshots are using an outdated version, you will see a notice indicating that snapshots are not of the latest version or that your folder format is legacy. * **Fix for legacy folders:** Run `drizzle-kit up`. * **Fix for version upgrades:** Depending on your dialect, run the appropriate update command to bring your snapshots up to the latest specification (such as upgrading PostgreSQL snapshots or migrating older V4/V5 snapshot schemas). #### Snapshot Collisions A snapshot collision happens when two or more distinct snapshot files point to the exact same parent snapshot ID. * To check for collisions and malformed files in your migrations directory, run `drizzle-kit check` for your specific database dialect. * If a collision is detected, review the generated report output to identify which child snapshots share the same parent path, and resolve the conflicting migration branches in your version control history. --- ### Diagnosing Connection and Configuration Issues #### Configuration and Connection Constraints Connection issues often arise when required driver parameters are missing, or when using unsupported commands with specific database drivers. #### Driver-Specific Restrictions and Missing Parameters Certain drivers have strict limitations regarding which commands (`migrate`, `push`, `pull`, `studio`) they support. If you supply invalid parameters or use an unsupported command, the tool will report an error and list the required configuration parameters. | Driver / Environment | Unsupported Commands | Required Parameters / Notes | | :--- | :--- | :--- | | **Expo SQLite** | `migrate`, `studio`, `pull`, `push` | Follow the specific Expo SQLite setup guide in the documentation. | | **SQLite Durable Objects** | `migrate`, `studio`, `pull`, `push` | Not supported for these management commands. | | **D1 HTTP** | *Varies by context* | Requires `accountId`, `databaseId`, and `token`. | > [!WARNING] > Attempting to run unsupported commands like `drizzle-kit migrate` or `drizzle-kit studio` with Expo SQLite or SQLite Durable Objects will terminate the process with an error message guiding you to the appropriate plugin or workflow. --- ### Handling Data Loss Warnings and Safety Prompts #### Understanding Safety Prompts When pushing schema changes directly to a database, safety checks analyze pending statements to protect existing data (such as dropping tables, removing columns, or changing primary keys). #### Common Warnings and Safeguards * **Dropping tables or columns:** If you attempt to drop a table or column that contains existing rows, a warning displays the exact table or column name along with the item count. * **Not-null columns without defaults:** Adding a `NOT_NULL` column to a table that already contains data without providing a default value will prompt a warning. Depending on the database engine, this may require truncating the table or aborting the operation. * **Primary key alterations:** Changing or dropping a primary key on a table with existing data can cause statements to fail or leave the table without a primary key. * **Auto-increment conflicts:** In MySQL and SingleStore, removing a primary key from a table while leaving an `autoincrement` property on a column will trigger an error because auto-increment columns must be defined as a key: > *Error:* `There can be only one auto column, and it must be defined as a key. Make sure to remove autoincrement from your table.` > [!CAUTION] > Operations that truncate tables or drop populated columns will result in permanent data loss. Always back up your database before confirming destructive schema updates. ## Related - [Managing Migrations](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/how-to-guides/managing-migrations) - [Connecting Databases](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/getting-started/connecting-databases) ---