A migrations folder is the only part of a codebase that cannot be rewritten by a refactor. Everything else is the current state of the project's opinions. The migrations are a ledger: what was true, in what order, and how long each thing lasted.
Ours is 15 files. I read all of them in one sitting and the folder turned out to be a better history of the product than the commit log.
The ledger
Drizzle numbers its migrations, records them in meta/_journal.json with a millisecond timestamp, and separates statements inside a file with a --> statement-breakpoint comment. Counting those gives the shape:
| # | bytes | statements | applied (UTC) |
|---|---|---|---|
| 0000 | 232 | 1 | 2025-06-03 10:43 |
| 0001 | 6,511 | 26 | 2026-06-02 18:50 |
| 0002 | 177 | 2 | 2026-06-02 19:35 |
| 0003 | 85 | 1 | 2026-06-02 19:54 |
| 0004 | 357 | 2 | 2026-06-03 18:27 |
| 0005 | 694 | 6 | 2026-06-03 18:44 |
| 0006 | 377 | 3 | 2026-06-06 21:47 |
| 0007 | 90 | 1 | 2026-06-07 18:10 |
| 0008 | 571 | 3 | 2026-06-13 07:40 |
| 0009 | 74 | 1 | 2026-06-13 08:48 |
| 0010 | 93 | 1 | 2026-06-15 13:18 |
| 0011 | 2,198 | 12 | 2026-06-18 11:13 |
| 0012 | 35 | 1 | 2026-06-18 11:31 |
| 0013 | 785 | 5 | 2026-09-06 13:49 |
| 0014 | 83 | 1 | 2026-11-04 22:08 |
Totals: 12,362 bytes, 174 lines, 66 statements. The schema those 66 statements build is 12 tables, 95 columns, 20 indexes and 21 foreign keys.
Three things in that table are worth more than the totals.
The gap is 364 days, and it is visible in the SQL
Migration 0000 is dated June 2025 and migration 0001 is dated June 2026. Everything after that happens in weeks. A year of nothing sits between the first file and the second.
You do not need the timestamps to see it. Migration 0000 says:
CREATE TABLE IF NOT EXISTS "users_table" ( "id" text PRIMARY KEY NOT NULL, "name" text NOT NULL, "email" text NOT NULL, "plan" text NOT NULL, "stripe_id" text NOT NULL, CONSTRAINT "users_table_email_unique" UNIQUE("email") ); Every later migration says CREATE TABLE with no IF NOT EXISTS, because the generator stopped emitting that clause in the versions released during the year nobody touched this repo. The folder dates itself twice, once in the journal and once in its dialect.
The content of 0000 dates it a third time. Five columns, all NOT NULL, including plan and stripe_id, which means the very first version of this product already assumed everyone had a plan and a Stripe customer. That assumption is the thing migrations 0002 through 0010 spend June 2026 unpicking.
A table that lived 18 minutes, and 80 days later came back
Migration 0011 is the biggest of the recent ones: two tables, four foreign keys, six indexes, 12 statements. One of the tables is user_sessions.
Migration 0012, timestamped 18 minutes later, is the shortest file in the folder. The entire migration is 35 bytes:
DROP TABLE "user_sessions" CASCADE; Then nothing for 80 days. Migration 0013, in September, creates user_sessions again, with the same five columns, the same foreign key and the same two indexes, and adds one unrelated statement:
ALTER TABLE "questions" ALTER COLUMN "time_limit_seconds" SET DEFAULT 15; Drizzle writes a full snapshot of the schema next to each migration, which makes this checkable rather than a story. Diffing snapshot 0011 against snapshot 0013, with the ids stripped out, produces exactly one changed line:
763c763 < "default": 30, --- > "default": 15, So across three migrations and 80 days, the net effect on the schema is a single default going from 30 to 15. The table was dropped because it was built ahead of the feature that needed it, and nothing in the product read it for eleven weeks. The default is the only durable change, and unlike most column defaults it is a product decision you can read on the site: fifteen seconds is the question timer's documented ceiling and its default.
The snapshot table counts tell the same story in one column: 1, 9, 9, 9, 9, 9, 9, 9, 10, 10, 10, 12, 11, 12, 12.
410 KB of metadata for 12 KB of SQL
The meta/ folder holds one snapshot per migration plus the journal:
- 15 snapshots, 410,292 bytes
- the SQL they describe, 12,362 bytes
- a ratio of 33 to 1
This is not waste, it is the mechanism. Drizzle generates each migration by diffing your TypeScript schema against the last snapshot, which is why drizzle-kit generate never needs to connect to a database and why it can run in a pre-commit hook or on a plane. The snapshots are the previous state, serialised.
The cost is paid in review. Our most recent schema change is 83 bytes of SQL:
ALTER TABLE "users_table" ADD COLUMN "email_updates" boolean DEFAULT true NOT NULL; One line, one column, for an email preference. It arrived in a commit alongside a 38,321-byte snapshot JSON, so the diff that a reviewer opens is dominated by machine output in which the single meaningful line is somewhere around line 763. If you review schema changes by reading diffs, review the .sql file and ignore meta/ entirely. It is generated, it is not advisory, and it is never the thing that ran against your database.
A small bonus oddity in that file: wc -l reports 0 lines, because Drizzle writes the statement with no trailing newline. The shortest and the newest migration in the folder are both files that technically contain no lines of text.
The build does not run them, on purpose
package.json has the usual four:
"db:generate": "drizzle-kit generate", "db:migrate": "drizzle-kit migrate", "db:push": "drizzle-kit push", "db:studio": "drizzle-kit studio" db:migrate used to be part of the build command, and a commit earlier this year took it out. The reason is that a build is not a deploy, and on a platform that builds per push, per branch and per preview, "the build migrates the database" means every preview build migrates the production database, concurrently, from whichever commit it happens to be on. The failure modes are not subtle: two builds racing the same ALTER, or a preview from an old branch running an older journal against a newer schema.
So migrations are now a human action: someone runs pnpm db:migrate against the database, deliberately, once, and then the deploy goes out. That is slower, and it is the correct kind of slower.
db:push is the one to be careful with. It diffs your TypeScript against the live database and applies the difference without writing a migration file, which is wonderful on a local database and is exactly how the journal and the production schema start disagreeing. It stays in the scripts because it is genuinely useful in development, and nothing in our deploy pipeline can reach it.
Check it yourself
The product side of the one change that survived those three migrations is documented at pub-trivia.app/features/question-timer, down to the three-second read before the clock starts and the second of grace after the buzzer. The membership tables that migration 0011 added are what make pub-trivia.app/features/multi-venue possible, and if you want to see the schema in use rather than on paper, the free tier at pub-trivia.app/signup needs no card.
If you run Drizzle yourself, two commands worth stealing:
# statements per migration, without trusting semicolons for f in drizzle/*.sql; do echo "$f $(( $(grep -c 'statement-breakpoint' "$f") + 1 ))" done # what actually changed between two snapshots diff <(jq 'del(.id, .prevId)' meta/0011_snapshot.json) \ <(jq 'del(.id, .prevId)' meta/0013_snapshot.json) The second one is the useful habit. A snapshot diff answers "what is the state difference" where the SQL answers "what did we run", and when those two disagree, something has been pushed rather than migrated.