After upgrading the history, the migrator applies every local migration whose full folder name is missing from the database, even if its timestamp is older than the latest applied migration. Keep folder names stable after this upgrade.
Upgrading to Drizzle v1
Upgrade from Drizzle 0.x or an earlier v1 beta or RC to drizzle-orm@rc and drizzle-kit@rc.
Upgrade with an AI agent
Let your coding agent prepare the upgrade without applying database changes.
View prompt
Upgrade this project to Drizzle v1 using drizzle-orm@rc and drizzle-kit@rc. Fetch and follow the instructions at https://orm.drizzle.team/agent-upgrade/v1/prompt.md Read upgrade instructions 1. Update your packages
Back up your database and migration files before converting the history.
Update both packages:
npm i drizzle-orm@rc
npm i -D drizzle-kit@rc
2. Convert your migration files
npx drizzle-kit up
up converts local files without changing the database. Each migration gets its own folder, named from the old journal’s timestamp and migration name:
# Before: Drizzle 0.x
drizzle/
├ 0000_create_users.sql
└ meta/
├ 0000_snapshot.json
└ _journal.json
# After: Drizzle v1
drizzle/
└ 20260101120000_create_users/
├ migration.sql
└ snapshot.jsonThe SQL is preserved, snapshots move to a DDL-based format and meta/_journal.json is removed. Removing the shared journal avoids Git conflicts in that file and makes migration conflicts easier to resolve. drizzle-kit drop has been removed.
See the v3 migration folder discussion for the design and background.
If conversion reports missing SQL files or snapshots, restore them from Git instead of deleting applied migrations.
3. Update your application code
Review the breaking changes for your dialect and update the affected code.
If you use Relational Queries, migrate your relation definitions and queries to v2.
4. Check the converted history
npx drizzle-kit check
Review the Git diff: every previous migration should have its converted folder, with unchanged SQL. check validates the local history and detects non-commutative migrations across branches, such as one branch renaming a table that another alters. It does not verify the applied history in your database.
See the commutativity discussion for the reasoning behind these checks.
Resolve reported conflicts before migrating. Deleting or regenerating an already-applied migration can require resetting the database that ran it.
5. Run your migrations
Run your migrations as usual, using your application’s migrate() function or the Kit CLI:
npx drizzle-kit migrate
On the first run after upgrading, the migrator updates the existing migration history table. It adds name and applied_at and associates previously applied migrations with their converted folders. applied_at remains NULL for older migrations because their execution date was not recorded.
Previously applied migrations are marked as applied in the updated history. Their SQL is not executed a second time. Any pending migrations are then applied.
If a database history entry cannot be matched, the upgrade stops. Restore the corresponding local migration rather than deleting the database history or creating a new initial migration.
Verify that previously applied migrations were not rerun and only expected pending migrations ran.