Apply generated migrations
A schema change has been converted into SQL migration files and must be deployed to a database.
Drizzle ORM · Function
migrate
drizzle-kit migrate applies SQL migrations generated by drizzle-kit generate. It consults migration history, runs only new migrations, and records successful applications.
How it works
The command scans the migration directory for SQL files, reads the database migration history, selects migrations that have not yet been applied, executes them, and records successful applications in the migration log. Connection settings and the SQL dialect can come from drizzle.config.ts or command-line options.
Syntax
npx drizzle-kit migrate --dialect=<dialect> --url=<database-url>Parameters
| Name | Type | Description |
|---|---|---|
dialect | string | SQL dialect for the target database, supplied in configuration or with the CLI. |
connection | configuration or CLI options | Database connection credentials or URL, supplied in configuration or with the CLI. |
Returns
Applies pending SQL migrations and records successful applications in the database migration log.
Key points
- Use migrate to execute SQL migration files created by the generate command.
- The command reads every SQL migration file in the configured migration directory.
- It connects to the database and loads the existing migration history.
- Migration history determines which files are still eligible for execution.
- After selection, it executes the SQL and records the applied migrations.
Common mistakes
- Provide both the SQL dialect and database connection credentials, either in drizzle.config.ts or through CLI options.
- Successful migration records are stored in the
__drizzle_migrationstable within thedrizzleschema.
Example: Generate and apply migrations
npx drizzle-kit generate
npx drizzle-kit migrate --dialect=postgresql --url=postgresql://user:password@host:port/dbnameGenerate SQL migration files from schema changes, then apply them to the database.
When to use it
Run only pending migrations
A deployment needs to continue from the database's recorded migration state.
Implement codebase-first schema changes
A team uses the codebase-first workflow with version-controlled schema and migration files.
Interview questions
QWhat does drizzle-kit migrate do?
drizzle-kit migrate applies SQL files previously produced by drizzle-kit generate. It checks the migration directory and database history, runs only migrations that have not already been applied, and logs successful applications.
Follow-up: How does it avoid rerunning migrations? It compares the files in the migration directory with entries in the database migration log and selects only unapplied migrations.
QWhat configuration does the command require?
The command needs a database dialect and connection credentials. These may be supplied in drizzle.config.ts or directly with CLI options such as --dialect and --url.
Follow-up: What would you verify first if the command fails to connect? Check that the dialect and credentials are present and match the target database.
QWhere does Drizzle Kit record applied migrations?
After executing migrations, Drizzle Kit records successful applications in the database migration log. The documented log table is named __drizzle_migrations and is located in the drizzle schema.
Follow-up: Why is that record useful? It provides the history used to determine which migration files still need to run.
Related
drizzle-kit generatedrizzle-kit pushdrizzle-kit pulldrizzle-kit export