Skip to main content
doc0blade47/drizzle-ormdocumentation home
Sign in

Project Structure

Last updated Oct 12, 2026
Relevant source files

The following files were used as context for generating this wiki page:

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 MemberDescription
drizzle-ormCore ORM runtime and query builder library
drizzle-kitMigration CLI and tooling suite
drizzle-zodZod schema generation companion
drizzle-typeboxTypeBox schema generation companion
drizzle-valibotValibot schema generation companion
drizzle-arktypeArkType schema generation companion
drizzle-seedDatabase mock seeding engine
integration-testsComprehensive database integration tests
eslint-plugin-drizzleCustom 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 NameCommandPurpose
build:ormturbo run build --filter drizzle-orm --colorBuilds only the core drizzle-orm package via Turbo
buildturbo run build test:types //#lint --colorExecutes full monorepo build, type tests, and linting
bpnpm buildShorthand alias for full monorepo build
packturbo run pack --colorPacks workspace packages into distributable archives
testturbo run test --colorRuns test suites across all workspace members
tpnpm testShorthand alias for test execution
test:typesturbo run test:types --colorExecutes type-checking across workspace packages
lintdprint check --list-differentChecks code formatting using dprint
lint:fixdprint fmtAuto-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 ModuleSource FilePurpose
Table alias definitions./alias.tsProvides mechanisms for aliasing database tables and relational expressions
Column builders./column-builder.tsDefines fluent builders and configuration APIs for table columns
Column primitives./column.tsImplements core column properties, data types, and mapping logic
Entity abstractions./entity.tsBase definitions for relational entities and schema components
Error handling./errors.tsCore library exceptions and runtime error types
Logging infrastructure./logger.tsQuery logging abstractions and formatting interfaces
Query operations./operations.tsUniversal operator contracts and filter expression builders
Query promises./query-promise.tsThenable query objects supporting async execution and chaining
Relations mapping./relations.tsRelational schema definitions, foreign key links, and relation helpers
SQL AST subsystem./sql/index.tsAbstract syntax tree nodes, SQL template literal tags, and token serialization
Subqueries./subquery.tsDerived table wrappers and subquery construction contracts
Table primitives./table.tsCore table definition structures and schema metadata containers
Utilities./utils.tsInternal helper functions and shared type utilities
View abstractions./view-common.tsCommon 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 ExportPostgreSQL (pg-core)MySQL (mysql-core)SingleStore (singlestore-core)Gel (gel-core)
Table aliasexport * from './alias.ts'export * from './alias.ts'export * from './alias.ts'export * from './alias.ts'
Check constraintsexport * from './checks.ts'export * from './checks.ts'—export * from './checks.ts'
Column definitionsexport * from './columns/index.ts'export * from './columns/index.ts'export * from './columns/index.ts'export * from './columns/index.ts'
Database instanceexport * from './db.ts'export * from './db.ts'export * from './db.ts'export * from './db.ts'
Dialect implementationexport * from './dialect.ts'export * from './dialect.ts'export * from './dialect.ts'export * from './dialect.ts'
Foreign keysexport * from './foreign-keys.ts'export * from './foreign-keys.ts'—export * from './foreign-keys.ts'
Index definitionsexport * from './indexes.ts'export * from './indexes.ts'export * from './indexes.ts'export * from './indexes.ts'
Access policiesexport * from './policies.ts'——export * from './policies.ts'
Primary keysexport * from './primary-keys.ts'export * from './primary-keys.ts'export * from './primary-keys.ts'export * from './primary-keys.ts'
Query buildersexport * from './query-builders/index.ts'export * from './query-builders/index.ts'export * from './query-builders/index.ts'export * from './query-builders/index.ts'
Rolesexport * from './roles.ts'——export * from './roles.ts'
Schema containerexport * from './schema.ts'export * from './schema.ts'export * from './schema.ts'export * from './schema.ts'
Sequencesexport * from './sequence.ts'——export * from './sequence.ts'
Session interfaceexport * from './session.ts'export * from './session.ts'export * from './session.ts'export * from './session.ts'
Subqueriesexport * from './subquery.ts'export * from './subquery.ts'export * from './subquery.ts'export * from './subquery.ts'
Table structuresexport * from './table.ts'export * from './table.ts'export * from './table.ts'export * from './table.ts'
Unique constraintsexport * from './unique-constraint.ts'export * from './unique-constraint.ts'export * from './unique-constraint.ts'export * from './unique-constraint.ts'
Utilitiesexport * from './utils.ts', export * from './utils/index.ts'export * from './utils.ts'export * from './utils.ts'export * from './utils.ts'
Views and common view typesexport * from './view-common.ts', export * from './view.ts'export * from './view-common.ts', export * from './view.ts'Commented out / disabledexport * 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.

DialectValidator FunctionVersionSources
postgresqlbackwardCompatiblePgSchema7drizzle-kit/src/utils.ts:117-118
sqlitebackwardCompatibleSqliteSchema6drizzle-kit/src/utils.ts:119-120
tursobackwardCompatibleSqliteSchema6drizzle-kit/src/utils.ts:121-122
mysqlbackwardCompatibleMysqlSchema5drizzle-kit/src/utils.ts:123-124
singlestorebackwardCompatibleSingleStoreSchema1drizzle-kit/src/utils.ts:125-126
gelbackwardCompatibleGelSchema1drizzle-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

Was this page helpful?