drizzle-kit

157 notes in this subject, read out of this brain and free to use. This is page 2 of 3.

dialect configuration option

The dialect option specifies the database type being used. For CockroachDB, the value is "cockroach". It is a required field with no default value and is used by commands: generate, push, pull, studio, migrate, up, export.

dbCredentials configuration for CockroachDB

The dbCredentials option accepts either a connection string URL or individual connection parameters. For CockroachDB, parameters include: host (string), port (number, typically 26257), user (string), password (string), database (string), and ssl (boolean or "require" | "allow" | "prefer" | "verify-full" or options from node:tls). Used by commands: push, pull, migrate, studio.

Migrations folder structure

The out parameter defines the folder where migrations are stored. The migration folder contains subdirectories with .sql migration files used by drizzle-kit. This allows you to have many separate schemas for different databases in the same project with different migration folders for each.

drizzle-kit check with CLI options

To use drizzle-kit check with CLI options, run 'npx drizzle-kit check --dialect=cockroach'.

drizzle-kit export required parameters

The drizzle-kit export command requires two parameters: dialect (required, specifies the database dialect such as cockroach) and schema (required, path to TypeScript schema file(s) or folder(s) with multiple schema files). These can be set via drizzle.config.ts config file or via CLI options.

drizzle-kit export with CLI options

To use drizzle-kit export via CLI options, run 'npx drizzle-kit export --dialect=cockroach --schema=./src/schema.ts' to specify dialect and schema path directly.

drizzle-kit export schema file paths

You can specify a single schema.ts file or multiple schema files spread across the project. Schema paths are specified as glob patterns via the schema configuration option in the drizzle.config.ts file.

drizzle-kit export full example

Example showing drizzle-kit export with config file in configs folder and schema in src folder. Config file at configs/drizzle.config.ts defines dialect: 'cockroach' and schema: './src/schema.ts'. Schema file at src/schema.ts exports a users table with id, email, and name columns. Running 'npx drizzle-kit export --config=./configs/drizzle.config.ts' outputs: CREATE TABLE "users" ("id" int4 PRIMARY KEY, "email" string NOT NULL, "name" string);

drizzle-kit export can be used with external tools

The SQL representation exported by drizzle-kit export can be used with external tools like Atlas to handle migrations for you.

drizzle-kit pull with CLI options example

You can run drizzle-kit pull directly from the CLI without a config file: npx drizzle-kit pull --dialect=cockroach --url=postgresql://user:password@host:port/dbname

tablesFilter configuration option

The tablesFilter option is a glob-based table names filter, for example ['users', 'user_info'] or 'user*'. Default is '*'.

schemaFilter configuration option

The schemaFilter option is a glob-based schema names filter, for example ['public', 'drizzle'] or 'drizzle*'. Default is '*'.

drizzle-kit pull CLI examples

Example drizzle-kit pull commands: npx drizzle-kit pull --dialect=cockroach --url=postgresql://user:password@host:port/dbname, npx drizzle-kit pull --dialect=cockroach --driver=pglite url=database/, npx drizzle-kit pull --dialect=cockroach --tablesFilter='user*' url=postgresql://user:password@host:port/dbname

drizzle-kit push CLI-only options

drizzle-kit push has the following CLI-only options: verbose (print all SQL statements prior to execution), explain (print the planned SQL changes without applying them, dry run), and force (auto-accept all data-loss statements). Example: npx drizzle-kit push --explain --verbose --force

drizzle-kit push command overview

The drizzle-kit push command lets you push your schema and subsequent schema changes directly to the database while omitting SQL files generation. It is designed to cover the code-first approach of Drizzle migrations. It reads through your Drizzle schema file(s) and composes a JSON snapshot of your schema, pulls (introspects) the database schema, generates SQL migrations based on differences between the two, and applies SQL migrations to the database.

drizzle-kit push use cases

drizzle-kit push is the best approach for rapid prototyping. It pairs exceptionally well with blue/green deployment strategy and serverless databases like PlanetScale, Neon, and Turso.

drizzle-kit push required configuration

drizzle-kit push requires you to specify dialect, path to schema file(s), and either a database connection URL or user:password@host:port/db parameters. You can provide these via drizzle.config.ts config file or via CLI options.

drizzle-kit push database driver selection

Drizzle Kit does not come with a pre-bundled database driver. It will automatically pick an available database driver from your current project based on the dialect.

drizzle-kit push table and schema filtering

drizzle-kit push manages all tables and schemas by default. You can configure list of tables and schemas via tablesFilter and schemaFilter options. tablesFilter uses glob-based table names filter (default is "*"). schemaFilter filters schema names (default is "*").

drizzle-kit push configuration parameters table

The drizzle-kit push command accepts the following configuration parameters: dialect (required, database dialect such as cockroach), schema (required, path to typescript schema file(s) or folder(s)), tablesFilter (table name filter), schemaFilter (schema name filter, default "*"), url (database connection string), user (database user), password (database password), host (host), port (port), database (database name), config (configuration file path, default drizzle.config.ts).

drizzle-kit push example with CockroachDB

Example configuration and schema for drizzle-kit push with CockroachDB: drizzle.config.ts sets dialect to "cockroach", schema to "./src/schema.ts", and dbCredentials.url to a PostgreSQL connection string. Schema file imports from "drizzle-orm/cockroach-core" and defines a users table with id (int4 primary key) and name (string) columns. Running npx drizzle-kit push generates and applies a CREATE TABLE statement.

drizzle-kit up dialect parameter requirement

The drizzle-kit up command requires you to specify the dialect parameter. You can provide it either via the drizzle.config.ts config file or via CLI options.

drizzle-kit up configuration with config file

To use drizzle-kit up with a config file, set the dialect parameter in drizzle.config.ts (e.g., dialect: "cockroach") and then run: npx drizzle-kit up

drizzle-kit up configuration with CLI options

To use drizzle-kit up with CLI options, run: npx drizzle-kit up --dialect=cockroach

drizzle-kit up multiple config files

You can have multiple config files in a single project, which is useful when you have multiple database stages or multiple databases in the same project. Use the --config parameter to specify which config file to use, for example: drizzle-kit up --config=drizzle-dev.config.ts or drizzle-kit up --config=drizzle-prod.config.ts

drizzle-kit up CLI options reference

The drizzle-kit up command accepts the following CLI options: (1) dialect - required - database dialect you are using, can be one of multiple supported dialects; (2) out - optional, default ./drizzle - migrations folder; (3) config - optional, default drizzle.config.ts - configuration file path.

drizzle-kit up command purpose

The drizzle-kit up command lets you upgrade drizzle schema snapshots to a newer version. It is required whenever breaking changes are introduced to the json snapshots of the schema and the internal version is upgraded.

drizzle-kit up with custom out folder example

To specify a custom migrations folder with drizzle-kit up, use the --out option: npx drizzle-kit up --dialect=cockroach --out=./migrations-folder

Export all models for Drizzle-Kit migration process

When using Drizzle-Kit for the migration process, all models defined in schema files must be exported so that Drizzle-Kit can import them and use them in the migration diff process.

drizzle.config.ts schema path configuration

In drizzle.config.ts, set the schema property to either a single file path like './src/db/schema.ts' or a folder path like './src/db/schema'. When pointing to a folder, Drizzle recursively finds all files and imports all drizzle tables from them.

drizzle.config.ts basic structure

The drizzle-kit configuration file is named drizzle.config.ts or drizzle.config.js and is placed in the project root. The basic configuration requires three fields: dialect (the database type), schema (path to schema file or folder), and out (output folder for migrations). The configuration is exported from the drizzle-kit package using defineConfig().

dialect config option

The dialect option specifies the database type being used. Type is string, no default value. Used in commands: generate, push, pull, studio, migrate, up, export.

extensionsFilters config option

The extensionsFilters option declares a list of installed database extensions (like 'postgis') for drizzle-kit to ignore their tables in the schema during push or pull commands. Type is array of strings. Default is empty array []. Used in commands: push, pull.

entities.roles config option

The entities.roles option configures role management in drizzle-kit. Type is boolean or object with properties: provider ('neon' | 'supabase'), include (string[]), exclude (string[]). Default is false (roles not managed). Allows enabling/disabling role management, excluding specific roles, including specific roles, and enabling provider-specific modes for Neon and Supabase. Used in commands: push, pull, generate.

breakpoints config option

The breakpoints option controls automatic embedding of '--> statement-breakpoint' in generated SQL migration files. This is necessary for databases that do not support multiple DDL alternation statements in one transaction (MySQL and SQLite). Type is boolean. Default is true. Used in commands: generate, pull.

drizzle-kit generates MySQL migrations automatically

Run drizzle-kit generate:mysql --schema=src/schema.ts --out=migrations/ to automatically generate all needed SQL migrations for your MySQL schema definitions.

Drizzle Kit v0.20.0 new features

Drizzle Kit v0.20.0 introduces: defineConfig function for defining drizzle.config, Cloudflare D1 access through Drizzle Studio using wrangler.toml, Drizzle Studio migration to https://local.drizzle.studio/, bigint unsigned support, custom names for primaryKeys and foreignKeys, automatic environment variable fetching, and various bug fixes.

Expo SQLite drizzle.config.ts configuration

Create a drizzle.config.ts file in the project root for Expo SQLite migrations. Set schema to the path of your schema file (e.g., './db/schema.ts'), out to the migrations output directory (e.g., './drizzle'), dialect to 'sqlite', and driver to 'expo'.

AWS Data API migrator fixed in v0.30.9

Drizzle v0.30.9 fixed a bug in the migrator for AWS Data API.

extensionsFilters parameter in drizzle.config

New extensionsFilters parameter in drizzle.config.ts to skip extension-internal tables during push and introspect operations. Usage: extensionsFilters: ['postgis']. Currently supports 'postgis' option which skips geography_columns, geometry_columns, and spatial_ref_sys tables.

MySQL and SQLite index expressions behavior updated

In drizzle-kit v0.22.0, MySQL and SQLite index expressions are properly mapped to SQL. Expressions are not escaped as strings but columns are. Example: uniqueIndex('emailUniqueIndex').on(sql`lower(${table.email})`) generates CREATE UNIQUE INDEX `emailUniqueIndex` ON `users` (lower(`email`)) instead of escaping the expression.

drizzle-kit v0.22.0 supports new PostgreSQL types

drizzle-kit v0.22.0 now supports point and line types from PostgreSQL, vector type from pg_vector extension, and geometry type from PostGIS extension.

drizzle-kit SSL configuration options

Index must have explicit name if using expressions

If an index uses at least one expression in .on() or .using(), you must specify an explicit name for the index. index().on(sql`lower(${table.email})`) will error; you must use index('my_name').on(sql`lower(${table.email})`)

Push workflow limitations for changing index properties

When using push command, Drizzle won't generate statements if these fields in an existing index were changed: expressions inside .on() and .using(), .where() statements, or operator classes .op(). To change these fields in push workflow: comment out the index, push, uncomment and modify the index, then push again. The generate command has no such limitations.

drizzle-kit migrations prefix flag options

The migrations configuration accepts a prefix flag to customize migration file name formats: 'index' (default) produces 0001_name.sql format; 'supabase' and 'timestamp' (equivalent) produce 20240627123900_name.sql format; 'unix' produces unix seconds prefix format like 1719481298_name.sql; 'none' omits the prefix completely.

drizzle-kit migrations prefix configuration example

import { defineConfig } from 'drizzle-kit'; export default defineConfig({ dialect: 'postgresql', migrations: { prefix: 'supabase' } });

drizzle-kit push command --force flag

The drizzle-kit push command accepts a --force flag that automatically accepts all data-loss statements. This flag is only available as a CLI parameter and should be used with caution only when data loss is acceptable.

drizzle-kit pull --init flag

The --init flag for drizzle-kit pull creates a drizzle migration table in the database and marks the first pulled migration as applied, allowing continuation of iterations from that point.

Folders v3 migrations structure

Drizzle v1.0.0-beta.2 updates migration folder structure by: removing journal.json, grouping SQL files and snapshots into separate migration folders, and removing the drizzle-kit drop command. These changes eliminate potential Git conflicts with the journal file. To migrate previous folders to v3 format, run: drizzle-kit up

schemaFilter behavior update in drizzle-kit

In v1.0.0-beta.2, drizzle-kit starts managing all schemas defined in code by default. Use schemaFilter to filter schemas. schemaFilter now supports glob patterns for flexible schema filtering.

Full drizzle-kit rewrite in v1.0.0-beta.2

Drizzle v1.0.0-beta.2 includes a complete architecture rewrite of drizzle-kit. Changes include: migration from database snapshots to database DDL snapshots, reworked architecture for detecting and applying diffs, improved defaults/expressions/types detection, reduced schema introspection time from 10 seconds to under 1 second, added query hints and explain support for push, and expanded test coverage with each test case running up to 6 different scenarios.

Custom migrations command syntax

To generate an empty custom migration file, use the command `drizzle-kit generate --custom --name=<migration-name>`. This creates a migration file that you can write your own custom SQL into.

Custom migration file location

Custom migration files are generated in the drizzle folder and are organized by timestamp prefix, for example `./drizzle/20242409135510_seed-users.sql`.

schema configuration property

The schema property accepts glob-based paths to drizzle schema file(s) or folders containing schema files. Type: string or string[]. Default: none (required). Commands: generate, push, export, studio.

tablesFilter configuration property

The tablesFilter property lets you specify glob-based table names filter for drizzle-kit push and pull commands. By default, all tables are managed. Type: string or string[]. Default: none. Commands: push, pull. Example: ['users', 'posts', 'project1_*'].

Drizzle Kit configuration file location and name

The Drizzle Kit configuration file should be named drizzle.config.ts or drizzle.config.js and placed in the project root directory alongside package.json.

defineConfig function for drizzle-kit

Use the defineConfig function imported from 'drizzle-kit' to declare Drizzle Kit configuration options in TypeScript or JavaScript.

Minimal drizzle.config.ts for MSSQL

A minimal MSSQL configuration requires: dialect set to 'mssql', schema path to the schema file(s), and out path for migrations folder.

dialect configuration property for MSSQL

The dialect property specifies the database dialect. For MSSQL, set it to 'mssql'. Type: string. Default: none (required). Commands: generate, push, pull, studio, migrate, up, export.

Give your agent this brain