Configuration and Validations

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, drizzle-kit/src/index.ts:23-349, drizzle-kit/src/cli/validations/common.ts:30-116, drizzle-kit/src/cli/validations/outputs.ts:4-91

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.

Copy	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

Sources: drizzle-kit/src/cli/commands/utils.ts:251-260

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.

Copyconst 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

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.

Copyexport 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<typeof dialect>;

Sources: drizzle-kit/src/schemaValidator.ts:7-11

The supported dialects and core driver options are formally structured via validation literals and enums across the validation modules.

Sources: drizzle-kit/src/cli/validations/common.ts:64-91, drizzle-kit/src/schemaValidator.ts:7-8

Sources: drizzle-kit/src/index.ts:347-349

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.

Copyexport 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

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.

Copyexport 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

Sources: drizzle-kit/src/cli/validations/common.ts:111-111, drizzle-kit/src/cli/validations/cli.ts:23-25

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.

Sources: drizzle-kit/src/cli/validations/postgres.ts:5-42, drizzle-kit/src/cli/validations/mysql.ts:6-30, drizzle-kit/src/cli/validations/singlestore.ts:6-30

Sources: drizzle-kit/src/cli/validations/mysql.ts:6-30, drizzle-kit/src/cli/validations/singlestore.ts:6-30

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.

Copyssl: 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

The MySQL and SingleStore SSL option object supports specific cryptographic properties for secure socket establishment:

Sources: drizzle-kit/src/cli/validations/mysql.ts:15-24, drizzle-kit/src/cli/validations/singlestore.ts:15-24

Sources: drizzle-kit/src/cli/validations/postgres.ts:13-20

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.

Sources: drizzle-kit/src/cli/validations/sqlite.ts:6-25

LibSQL credentials share a dedicated validation object requiring a url string with an optional authToken string.

Copyexport const libSQLCredentials = object({
	url: string().min(1),
	authToken: string().min(1).optional(),
});

Sources: drizzle-kit/src/cli/validations/libsql.ts:6-9

Sources: drizzle-kit/src/cli/validations/sqlite.ts:18-24

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.

Sources: drizzle-orm/src/better-sqlite3/driver.ts:15-22, drizzle-orm/src/better-sqlite3/driver.ts:68-123

Sources: drizzle-orm/src/better-sqlite3/driver.ts:125-133

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

Sources: drizzle-kit/src/cli/commands/utils.ts:331-334

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.

Sources: drizzle-kit/src/cli/commands/utils.ts:336-349

Sources: drizzle-kit/src/cli/commands/utils.ts:351-351

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.

Sources: drizzle-kit/src/serializer/pgImports.ts:16-67, drizzle-kit/src/serializer/pgImports.ts:70-109

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.

Sources: drizzle-kit/src/cli/validations/outputs.ts:4-11

Sources: drizzle-kit/src/cli/validations/common.ts:170-188

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.

Copyexport 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

Sources: drizzle-kit/src/cli/validations/common.ts:30-62, drizzle-kit/src/cli/validations/outputs.ts:32-38

Related

• CLI Command Architecture