drizzle-kit up with out option example
To specify a custom migrations folder with drizzle-kit up, use the --out flag: npx drizzle-kit up --dialect=postgresql --out=./migrations-folder
Drizzle · PostgreSQL · all subjects
drizzle-kit
119 notes in this subject, read out of this brain and free to use. This is page 2 of 2.
drizzle-kit up requires dialect parameter
The drizzle-kit up command requires the dialect parameter to be specified. The dialect can be provided either via the drizzle.config.ts config file or via CLI options using --dialect=.
drizzle-kit up with config file example
To run drizzle-kit up using a config file, define the dialect in drizzle.config.ts using defineConfig with dialect set to the database type (e.g., 'postgresql'), then run 'npx drizzle-kit up' without arguments.
drizzle-kit up command purpose
The drizzle-kit up command upgrades 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 needs to be upgraded.
drizzle-kit up with CLI dialect option example
To run drizzle-kit up with dialect as a CLI option, use: npx drizzle-kit up --dialect=postgresql
drizzle-kit up multiple config files
Multiple config files can be specified in a single project, which is useful for managing multiple database stages or multiple databases on the same project. Use the --config flag to specify which config file to use, for example: 'npx drizzle-kit up --config=drizzle-dev.config.ts' or 'npx drizzle-kit up --config=drizzle-prod.config.ts'.
drizzle-kit up CLI options reference
The drizzle-kit up command accepts the following CLI options: dialect (required, the database dialect being used, can be one of multiple supported values), out (optional, migrations folder path, defaults to ./drizzle), and config (optional, configuration file path, defaults to drizzle.config.ts).
extensionsFilters config option for PostGIS
When using introspect or push commands with the PostGIS extension, use the extensionsFilters option in the Drizzle config file to exclude PostGIS tables from being included. This prevents PostGIS system tables from being processed.
Use cases for custom migrations in Drizzle Kit
Custom migrations are used for DDL alterations not currently supported by Drizzle Kit, and for data seeding operations. These custom SQL files can then be executed using the `drizzle-kit migrate` command.
Generate custom migration files with drizzle-kit
Use the command `drizzle-kit generate --custom --name=<migration-name>` to generate empty migration files for writing custom SQL migrations. For example, `drizzle-kit generate --custom --name=seed-users` creates a migration file that you can populate with custom SQL DDL or data seeding operations.
Custom migration files location and naming
Custom migration files are stored in the drizzle folder with a timestamp prefix followed by the migration name. For example, `20242409135510_seed-users.sql` is a custom migration file where the timestamp format is used for ordering migrations chronologically.
JavaScript and TypeScript migrations not yet supported
As of the documentation date, Drizzle Kit does not yet support running custom JavaScript and TypeScript migration or seeding scripts. This feature is planned for an upcoming release, with discussion tracked at https://github.com/drizzle-team/drizzle-orm/discussions/2832.
drizzle-kit export command
drizzle-kit export is used to convert a TypeScript schema into raw SQL DDL and print it out.
Multiple Drizzle Kit configs for different database stages
You can provide Drizzle Kit config path via CLI param using --config flag, which is useful when you have multiple database stages or multiple databases or different databases on the same project. For example: drizzle-kit push --config=drizzle-dev.config.ts or drizzle-kit push --config=drizzle-prod.config.ts
Drizzle Kit configuration requires dialect and schema path
Drizzle Kit is configured through drizzle.config.ts configuration file or via CLI params. It is required to at least provide SQL dialect and schema path for Drizzle Kit to know how to generate migrations.
Drizzle Kit is a CLI tool for managing migrations
Drizzle Kit is a CLI tool for managing SQL database migrations with Drizzle. It lets you generate and run SQL migration files, push schema directly to the database, pull schema from database, spin up drizzle studio, and run utility commands.
drizzle-kit generate command
drizzle-kit generate lets you generate SQL migration files based on your Drizzle schema either upon declaration or on subsequent changes.
drizzle-kit migrate command
drizzle-kit migrate lets you apply generated SQL migration files to your database.
drizzle-kit pull command
drizzle-kit pull lets you pull (introspect) database schema, convert it to Drizzle schema and save it to your codebase.
drizzle-kit push command
drizzle-kit push lets you push your Drizzle schema to database either upon declaration or on subsequent schema changes.
drizzle-kit studio command
drizzle-kit studio will connect to your database and spin up proxy server for Drizzle Studio which you can use for convenient database browsing.
drizzle-kit check command
drizzle-kit check will walk through all generated migrations and check for any race conditions (collisions) of generated migrations.
drizzle-kit up command
drizzle-kit up is used to upgrade snapshots of previously generated migrations.
Simple Drizzle Kit config for PostgreSQL
A minimal Drizzle Kit configuration for PostgreSQL requires: import { defineConfig } from 'drizzle-kit'; export default defineConfig({ dialect: 'postgresql', schema: './src/schema.ts', });
Extended Drizzle Kit config options
An extended Drizzle Kit configuration for PostgreSQL can include: out (output directory for migrations), dialect, schema, entities (with exclude/include/provider options), driver (e.g., 'pglite'), dbCredentials (url), extensionsFilters, schemaFilter, tablesFilter, introspect (with casing option), migrations (with table and schema), breakpoints, and verbose flags.
Option 3: Codebase-first with drizzle-kit generate and drizzle-kit migrate
Use drizzle-kit generate to create SQL migration files based on schema changes in your TypeScript Drizzle schema, then use drizzle-kit migrate to apply those migrations to the database. drizzle-kit generate reads previous migration folders, finds the diff between current and previous schema, prompts for renames if necessary, and generates SQL migration files persisted in a migrations folder with a snapshot.json file.
Database-first vs codebase-first migration approaches
Database-first is when your database schema is the source of truth. You manage your database schema directly on the database or via database migration tools, then pull your database schema into your codebase. Codebase-first is when your TypeScript/JavaScript Drizzle schema in your codebase is the source of truth and is under version control. You declare and manage your database schema in code, then apply that schema to the database.
drizzle-kit CLI commands for migrations
drizzle-kit provides five commands: drizzle-kit migrate (apply generated SQL migrations to database), drizzle-kit generate (generate SQL migration files based on schema changes), drizzle-kit push (push schema changes directly to database without generating SQL files), drizzle-kit pull (pull database schema and save as TypeScript schema file), and drizzle-kit export (output SQL representation of Drizzle schema to console).
Option 1: Database-first with drizzle-kit pull
Use drizzle-kit pull when you manage database schema using external migration tools or by running SQL migrations directly on your database. This command pulls your database schema and generates a TypeScript Drizzle schema file from it. The database schema is your source of truth.
Option 2: Codebase-first with drizzle-kit push
Use drizzle-kit push when you have your TypeScript Drizzle schema as source of truth and want Drizzle to push schema changes directly to the database without generating SQL migration files. This approach is best for rapid prototyping and is successfully used as a primary migrations flow in production applications.
Option 4: Runtime migrations with drizzle-kit generate and migrate function
Use drizzle-kit generate to create SQL migration files, then apply them during runtime using the migrate function from drizzle-orm. Import migrate from your driver package (e.g., 'drizzle-orm/node-postgres/migrator'), call await migrate(db) in your application code. This approach is used for monolithic applications during zero downtime deployment and for serverless deployments where migrations run in custom resources during deployment.
Option 5: Codebase-first with manual migration application
Use drizzle-kit generate to create SQL migration files based on your TypeScript Drizzle schema changes, then apply them to the database yourself or via external migration tools like Bytebase, Liquibase, or Atlas. The database schema is not your source of truth; your TypeScript schema is.
Option 6: Schema export with drizzle-kit export
Use drizzle-kit export to output the SQL representation of your Drizzle schema to the console. You can then apply the SQL to your database via Atlas or other external SQL migration tools. This approach is codebase-first where your TypeScript Drizzle schema is the source of truth.
Runtime migrations example with node-postgres
To apply migrations at runtime, import drizzle from 'drizzle-orm/node-postgres' and migrate from 'drizzle-orm/node-postgres/migrator'. Create a database connection with const db = drizzle(process.env.DATABASE_URL), then call await migrate(db) to apply all unapplied migrations from the migrations folder.
Migration file structure
Generated migrations are stored in a drizzle folder with a timestamped subdirectory (e.g., drizzle/20242409125510_premium_mister_fear) containing two files: migration.sql with the SQL statements and snapshot.json with the schema state after migration.
SQL database schema migrations definition
SQL databases require you to specify a strict schema of entities upfront. When you need to change the shape of those entities, you must do it via schema migrations. There are multiple production-grade ways to manage database migrations.
drizzle-kit pull generates relations.ts in v2 syntax
The drizzle-kit pull command now supports generating a relations.ts file in the new v2 syntax. After pulling, transfer the generated relations code to your project's relations file and update the import paths to reference your schema files.
Enable role management in drizzle.config.ts
By default, drizzle-kit does not manage roles. To enable role management, set entities.roles: true in drizzle.config.ts. You can also use entities.roles.exclude to exclude specific roles, entities.roles.include to include specific roles, or entities.roles.provider to exclude provider-defined roles ('neon' or 'supabase').
Export all schema models for Drizzle-Kit migrations
All models defined in schema files must be exported so that Drizzle-Kit can import them and use them in the migration diff process. This applies to tables, enums, sequences, views, materialized views, and schemas.
Single schema file configuration in drizzle.config.ts
In drizzle.config.ts, set schema: './src/db/schema.ts' to specify a single file containing all table definitions. Drizzle reads this file during migration generation.
Multiple schema files configuration in drizzle.config.ts
In drizzle.config.ts, set schema: './src/db/schema' (a folder path) to specify a directory. Drizzle recursively reads all files in this folder to find all table, enum, sequence, and other model definitions.
Schema file naming flexibility
Schema files can be named anything, not just schema.ts. Common alternatives include models.ts or any other descriptive name the developer prefers.
drizzle-kit up command for migration
To upgrade from pre-v1 to v1 Drizzle structure, run the drizzle-kit up command. This command automatically migrates from the old migration folder structure to the new one.
drizzle-kit architectural redesign in v1
The drizzle-kit has been architecturally redesigned, migrating from database snapshots to DDL snapshots. Commutativity checks were added to detect non-commutative migrations across branches.
New migration folder structure v3 in drizzle-kit v1.0
Migration folder structure has been redesigned in v1.0: the `journal.json` file is removed, SQL files and snapshots are grouped into separate migration folders, and the `drizzle-kit drop` command is removed. These changes eliminate Git conflicts from the journal file and simplify migration management.
schemaFilter default behavior changed in v1.0
In drizzle-kit v1.0, `drizzle-kit push` and `drizzle-kit pull` now manage all schemas by default, not just the `public` schema. Glob patterns are now supported in `schemaFilter` (e.g., `['public', 'app_*']`). In v0.x, only the `public` schema was managed by default.
drizzle-kit push --strict flag removed in v1.0
The `--strict` flag for `drizzle-kit push` has been removed in v1.0. Its behavior is now the default: `drizzle-kit push` always prompts for confirmation for data-loss statements unless the `--force` flag is passed. Use `drizzle-kit push --explain` to preview SQL before executing.
Full drizzle-kit rewrite in v1.0
Drizzle-kit has been architecturally redesigned in v1.0: migrated from database snapshots to DDL snapshots, reworked diff detection and application, reduced schema introspection from ~10s to <1s, and added query hints and explain support for push.
drizzle-kit pull --init command in v1.0
The `drizzle-kit pull --init` command creates the drizzle migration table and marks the first pulled migration as applied.
drizzle-kit push --explain command in v1.0
The `drizzle-kit push --explain` command shows the SQL that would be executed without actually running it, allowing users to preview changes before applying them.
drizzle-kit check commutativity detection in v1.0
The `drizzle-kit check` command detects non-commutative migrations across branches (e.g., two branches altering the same column or renaming a table that another branch is altering). It builds a DAG from snapshot `prevIds`, finds fork points, computes DDL diffs, and checks for conflicts using a footprint map. If conflicts are found, the report identifies which migrations on which branches are incompatible.
drizzle-kit --ignore-conflicts flag in v1.0
The `--ignore-conflicts` flag can be used with drizzle-kit to bypass commutativity checks when expected conflicts are known.
drizzle-kit generate migration conflict detection in v1.0
`drizzle-kit generate` now identifies incompatible changes across migration branches. The `--ignore-conflicts` flag can be used to bypass these checks.
Migration table new columns in v1.0
The migration table in v1.0 has been updated with two new columns: `name` (text, the full migration folder name like '20250220153045_brave_wolverine') and `applied_at` (timestamp with time zone, when the migration was executed, backfilled with NULL for pre-existing rows). The migration table now has columns: `id` (serial, yes), `hash` (text, yes), `created_at` (bigint, yes, legacy), `name` (text, new), `applied_at` (timestamp with time zone, new). Migrations are matched by full folder name instead of timestamps, ensuring uniqueness even if generated in the same second.
Migration table upgrade strategy in v1.0
During upgrade to v1.0, existing migration rows are backfilled using a multi-step strategy: (1) Millis match - truncate stored millis to seconds and match against local folder timestamps, (2) Hash tiebreaker - if multiple migrations share the same second, disambiguate via SQL hash, (3) Hash-only fallback - if millis matching fails, match by hash alone. This handles normal single-developer projects, teams with closely-timed migrations, and cases where old journal data doesn't align with new folder names.
Migrator applies all missing migrations in v1.0
In v1.0, the migrator detects and applies every missing migration regardless of timestamp ordering. Previously it only looked for migrations with creation dates later than the last applied one. All migrations are matched against the full folder name (14-digit UTC timestamp plus name suffix).
Top-level await support in drizzle config files in v1.0
Top-level `await` is now supported in `drizzle.config.ts` and schema files on Node.js.
Drizzle-kit build system improvements in v1.0
Drizzle-kit v1.0 improvements: migrated from `esbuild-register` to `tsx` loader for seamless ESM and CJS support, native Bun and Deno launch support added.
TS schema file processing in v1.0
In drizzle-kit v1.0, only schema files with these extensions are processed: `.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.mts`, `.cts`, `.tsx`. All other file types are ignored.