What the agent does
The agent reads how the schema reaches the database today before it generates anything, because in a repository like VArtzy/Bun-Book-Management-API the answer is contradictory. drizzle.config.ts names ./src/database/schema.ts as the schema, ./src/database/migration as out, dialect sqlite and ./src/database/db.sqlite as the database. .gitignore excludes src/database/meta, src/database/migration and src/database/db.sqlite, yet src/database/meta/0000_snapshot.json, src/database/meta/_journal.json and db.sqlite itself are committed, while no .sql file is. src/application/database.ts opens that file with bun:sqlite through drizzle-orm/bun-sqlite and never calls migrate; package.json has one script, dev, with drizzle-kit 0.22.1 and drizzle-orm 0.31.0 in dependencies; the workflow runs bun install and bun test with a Redis service.
The committed database tells the history. Its __drizzle_migrations table holds one row with a hash and created_at 1717413098786, the same when the committed _journal.json records for a migration tagged 0000_sloppy_swarm, so a migration was generated and applied once, with out pointing somewhere else, and only its metadata survived. Running bun x drizzle-kit generate now finds no journal under src/database/migration/meta, treats the project as unmigrated, and writes a fresh 0000_<name>.sql with four tables (books, collections and reviews with their foreign keys, and users) plus its own meta/, all ignored by git. Its hash matches the row in the committed database exactly, so the SQL is the same; only the timestamp differs, and the migrator compares timestamps.
That difference is the trap the agent proves before it writes a line. With a src/database/migrate.ts that calls migrate(db, { migrationsFolder }) from drizzle-orm/bun-sqlite/migrator, a fresh empty file gets all four tables and the __drizzle_migrations row; the committed db.sqlite fails with SQLiteError: table "books" already exists, because its row is older than the new file. The fix is a baseline: one row inserted into __drizzle_migrations with the new file's hash and timestamp, after which migrate is a no-op on the existing database and a fresh one builds the identical schema, which the agent checks by diffing .schema output of both.
The pull request then makes migrations the source of truth. .gitignore stops excluding src/database/migration; the stale src/database/meta is deleted; the generated 0000_*.sql and its meta/ are committed; src/database/migrate.ts is added with db:generate and db:migrate scripts in package.json; and the workflow runs bun run db:migrate before bun test against a database the job creates from nothing, so the committed db.sqlite is no longer what CI tests. A short src/database/baseline.ts records the baseline row for any copy of the old database, and the description says when to run it.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add database migrations to this Bun, Hono and Drizzle app. Read package.json, drizzle.config.ts, .gitignore, src/database/schema.ts, src/database/meta/_journal.json, src/application/database.ts, test/test-util.ts and .github/workflows/main.yml first, and inspect the committed src/database/db.sqlite with sqlite3, including its __drizzle_migrations rows. Run bun x drizzle-kit generate and compare the file it writes with that table. Add src/database/migrate.ts using drizzle-orm/bun-sqlite/migrator with a db:migrate script, and a db:generate script; stop ignoring the migration folder, remove the stale meta folder, and commit the generated SQL and meta. Prove in your sandbox that migrate builds a fresh database identical to the committed one and that running it against a copy of the committed database needs a baseline row, then add a small script that inserts that row and document when to run it. Make the workflow create the database with db:migrate before bun test instead of using the committed file. Open a pull request that pastes the generate, migrate and test output.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request that adds src/database/migration/0000_<name>.sql with its meta/_journal.json and meta/0000_snapshot.json, src/database/migrate.ts and src/database/baseline.ts, changes .gitignore, package.json and .github/workflows/main.yml, and deletes the orphaned src/database/meta/. src/database/schema.ts and the controllers are untouched. The description pastes the drizzle-kit generate summary, the bun run db:migrate line against an empty file, the .schema diff showing the two databases agree, and the bun test run that follows.
The description also states the one operational fact a reviewer must act on: any existing copy of db.sqlite made before this change has tables but an older __drizzle_migrations row, so db:migrate fails on it with table "books" already exists until baseline.ts has been run once against that copy. The committed db.sqlite is left in place for now and named as a follow-up to drop, since CI no longer needs it.
Before merging, a reviewer checks that the committed snapshot is the one generate will diff against next time, runs baseline.ts on any shared development database, and reads the workflow's first run on the pull request, where the database is created from the migration alone.
Run it on every pull request that changes the schema
An automation in the Project with a github trigger on pull_request.opened and pull_request.synchronize runs a shorter prompt against a pull request that touches src/database/schema.ts: run bun run db:generate, commit the new migration if one is produced, run db:migrate on a fresh database, and report on the pull request. The trigger adds the pull request to the prompt, and pull requests from forks never start a run.
A team with several Drizzle services still on drizzle-kit push sends one POST /o/{org}/sessions per repository from a script, with this prompt and the repository in resources, and a request_id that is a UUID v5 of the repository's full name so a retried call returns the run already started. Each run opens at most one pull request.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The dangerous part of adding migrations to a project that already has a database is the first migrate against that database: Drizzle's migrator decides by timestamp, so a regenerated migration with the same SQL still tries to create tables that exist. On a laptop that failure usually hits the one copy of the database someone cares about. The agent hits it on a throwaway copy in its own sandbox, works out the baseline row from the hash and timestamp it can read, and proves both the fresh and the existing path before the pull request exists.
Every command and its output stays on the run, so a reviewer reads the generate summary, the failing migrate on the old copy and the passing one after the baseline without opening SQLite. Several Drizzle repositories can get the same treatment at once, each in its own sandbox, and a database the agent could not reconcile is reported rather than regenerated from scratch.
Frequently asked questions
Why does migrate fail on the committed database?
Its __drizzle_migrations row carries the timestamp of the original 0000_sloppy_swarm migration, and the regenerated file carries a new one. drizzle-orm's migrator applies every journal entry newer than the last recorded row, so it tries to run the new 0000 and stops at table "books" already exists. The SQL hash is identical, which is how the agent knows the schema did not drift.
What does the baseline script do?
It inserts one row into __drizzle_migrations with the new migration's hash and its when from _journal.json, so the migrator considers it applied. After that, db:migrate on the old copy does nothing, and a later migration applies normally. It is run once per existing database copy, never in CI, where the database starts empty.
Why not keep using drizzle-kit push?
push diffs the schema against a live database and alters it in place, which is fine for a local file and has no record. A committed migration is the record: it says what changed, applies the same way in CI and in production, and drizzle-kit generate refuses to produce one when the snapshot and schema agree, which is itself a check.
Why delete the committed meta folder?
It belongs to a migration whose SQL was never committed, and it lives under src/database/meta while drizzle.config.ts points out at src/database/migration, so drizzle-kit never reads it. Leaving it would suggest a history that cannot be replayed. The new migration/meta/ is the snapshot generate diffs against from now on.
Will the tests still pass?
Yes. test/test-util.ts creates and deletes its own test user, book, review and collection rows through the app, so it needs the tables, not the rows that happen to be in the committed file. In the sandbox, bun test against a database built by db:migrate gave the same result as against the committed file: every test passed except the login test, which needs the Redis the workflow's service container provides and the sandbox did not run. The workflow creates the database with db:migrate and then runs bun test with that service.