Overview
Managing migrations allows you to safely evolve your database schema as your application changes. Drizzle Kit handles the process of inspecting your code-defined schema, comparing it to previous versions, and generating the necessary database statements. You can then review these changes and apply them to your live database.
Key Concepts
Before working with migrations, it helps to understand a few core terms:
- Schema: The TypeScript description of your database tables, columns, relations, and views.
- Migration: A generated file containing SQL statements that update your database structure.
- Snapshot: A JSON record of your schema state at a specific point in time, used by the tooling to calculate what has changed.
- Journal: An internal tracking file (
_journal.json) that keeps an organized history of all generated migrations. - Database Dialect: The specific database engine your application uses.
Supported database dialects: gel, postgresql, mysql, sqlite, turso, or singlestore.
(Sources: drizzle-kit/src/cli/schema.ts)
Supported database drivers: aws-data-api, d1-http, d1, turso, or pglite.
(Sources: drizzle-kit/src/cli/schema.ts, drizzle-kit/src/serializer/studio.ts)
Generating Migrations
Running the Generator
When you modify your TypeScript schema definition, you need to generate a new migration file so your database can catch up.
- Open your terminal in your project directory.
- Run the generation command, specifying your options such as the schema path and output folder:
npx drizzle-kit generate
Available Generation Options
| Option | Description |
|---|---|
config | Path to your configuration file. |
dialect | Database dialect: gel, postgresql, mysql, sqlite, turso, or singlestore. |
driver | Database driver. |
casing | Casing style for serialization: camelCase or snake_case. |
schema | Path to a schema file or folder. |
out | Output folder for migrations (drizzle by default). |
name | Custom migration file name. |
breakpoints | Prepare SQL statements with breakpoints. |
custom | Prepare an empty migration file for custom SQL (false by default). |
prefix | Prefix mode for files: index. |
(Sources: drizzle-kit/src/cli/schema.ts)
Note
The generate command cannot be used with the gel dialect. Attempting to do so will result in an error and exit.
(Sources: drizzle-kit/src/cli/schema.ts)
Reviewing and Updating Migrations
Updating Snapshot Versions
As your project grows, your migration folders and snapshots must remain up to date.
Important
If your migration folder uses an outdated format (such as older V1 folder structures), the tool will detect it and require you to update.
(Sources: drizzle-kit/src/utils.ts)
To upgrade your migration snapshots to the latest version compatible with your tooling, run:
npx drizzle-kit up(Sources: drizzle-kit/src/cli/index.ts, drizzle-kit/src/cli/commands/pgUp.ts, drizzle-kit/src/utils.ts)
Applying Migrations
Running the Migrator
Once you have generated and reviewed your migration files, you can apply them to your database using the migration runner command.
- Ensure your connection details and configuration file are properly set up.
- Run the migration command:
npx drizzle-kit migrate
This command inspects your database, checks the internal migration tracking table (typically created automatically as __drizzle_migrations), and runs any pending SQL statements in the correct order.
Warning
Certain database drivers (such as Neon HTTP and Xata HTTP) do not support transactions. If any part of a migration fails when using these drivers, automatic rollbacks will not occur, and you will need to handle incomplete or unsuccessful migrations manually.
(Sources: drizzle-orm/src/neon-http/migrator.ts, drizzle-orm/src/xata-http/migrator.ts)