Relevant source files
The following files were used as context for generating this wiki page:
- drizzle-kit/src/api.ts
- turbo.json
- drizzle-kit/src/utils.ts
- drizzle-orm/src/d1/index.ts
- pnpm-workspace.yaml
- drizzle-kit/src/serializer/studio.ts
- drizzle-orm/src/neon/index.ts
- package.json
- drizzle-seed/src/index.ts
- drizzle-orm/src/gel-core/index.ts
- drizzle-kit/src/index.ts
- drizzle-orm/src/singlestore-core/index.ts
- drizzle-kit/package.json
- drizzle-orm/src/singlestore/index.ts
- drizzle-orm/src/gel/index.ts
- drizzle-orm/src/durable-sqlite/index.ts
- drizzle-orm/src/libsql/index.ts
- drizzle-seed/package.json
- drizzle-orm/src/pg-core/index.ts
- drizzle-kit/src/serializer/index.ts
- drizzle-orm/src/index.ts
- drizzle-orm/src/mysql-proxy/index.ts
- drizzle-orm/src/prisma/sqlite/index.ts
- drizzle-orm/src/prisma/pg/index.ts
- drizzle-orm/src/sqlite-proxy/index.ts
- drizzle-orm/src/pglite/index.ts
- drizzle-orm/src/pg-proxy/index.ts
- drizzle-orm/src/singlestore-proxy/index.ts
- drizzle-orm/src/mysql-core/index.ts
- 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, pnpm-workspace.yaml:1-11, package.json:1-42
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.
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
| 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
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
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.
"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
| 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
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
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.
"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
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, drizzle-seed/package.json:90-90
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
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
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, drizzle-orm/src/mysql-core/index.ts:1-17, drizzle-orm/src/singlestore-core/index.ts:1-14, drizzle-orm/src/gel-core/index.ts:1-20
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
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
Runtime Driver Bindings
LibSQL Driver and Session Exports
export * from './driver.ts';
export * from './session.ts';Sources: drizzle-orm/src/libsql/index.ts:1-2
The LibSQL runtime integration layer re-exports all binding declarations from its constituent driver and session modules.
export * from './driver.ts';
export * from './session.ts';Sources: drizzle-orm/src/libsql/index.ts:1-2
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
PGlite Driver and Session Exports
export * from './driver.ts';
export * from './session.ts';Sources: drizzle-orm/src/pglite/index.ts:1-2
Similarly, the PGlite in-memory and embedded PostgreSQL runtime integration aggregates its entry point by consuming module exports from local driver and session sources.
export * from './driver.ts';
export * from './session.ts';Sources: drizzle-orm/src/pglite/index.ts:1-2
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, drizzle-orm/src/pglite/index.ts:1-2
Tooling and Utility Infrastructure
CLI Validation Layers and Migration Utilities
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
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 |
sqlite | backwardCompatibleSqliteSchema | 6 | drizzle-kit/src/utils.ts:119-120 |
turso | backwardCompatibleSqliteSchema | 6 | drizzle-kit/src/utils.ts:121-122 |
mysql | backwardCompatibleMysqlSchema | 5 | drizzle-kit/src/utils.ts:123-124 |
singlestore | backwardCompatibleSingleStoreSchema | 1 | drizzle-kit/src/utils.ts:125-126 |
gel | backwardCompatibleGelSchema | 1 | drizzle-kit/src/utils.ts:127-128 |
Sources: drizzle-kit/src/utils.ts:115-130
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
Shared Runtime Configuration Boundaries
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
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, drizzle-kit/src/index.ts:113
Related
On This Page
OverviewMonorepo Workspace OrganizationWorkspace Members and ConfigurationBuild and Test ScriptsPackage Isolation and Entry PointsDrizzle ORM Core SubsystemCore Subsystem Module ExportsDialect Specialization BoundariesEngine-Specific Core ModulesRuntime Driver BindingsLibSQL Driver and Session ExportsPGlite Driver and Session ExportsTooling and Utility InfrastructureCLI Validation Layers and Migration UtilitiesShared Runtime Configuration BoundariesRelated