[Neziahtech]

Closes #233

---

What & why (#233)

prisma/ shipped only schema.prisma — no migrations/, so every schema change went through prisma db push, which diffs the live DB and applies whatever it decides. Nothing was reviewable, reproducible, or roll-backable. This adopts prisma migrate.

Acceptance criteria

• Baseline reproduces the current production schema exactly — prisma/migrations/0_init/migration.sql, generated via migrate diff --from-empty --to-schema-datamodel --script. Verified byte-for-byte against a regenerated diff.
• CI fails on drift between schema and migrations — new db-migrations job boots Postgres and runs scripts/db-drift-check.sh (migrate diff … --exit-code), plus scripts/db-migration-cycle.sh which also proves the guard fires on an un-migrated schema edit.
• Deploy docs use migrate deploy; db push called out as unsafe — new docs/database-migrations.md; README / CONTRIBUTING / backup-restore / load.yml updated; startup src/index.ts now runs migrate deploy; db:push removed.
• A new migration can be generated, applied and rolled back on a clean DB — scripts/db-migration-cycle.sh (reset → generate canary migration → deploy → assert table → reset → assert gone).

Proven with a test that fails first

tests/prisma-migrations.test.ts is DB-free and locks schema.prisma to the baseline. Ran both ways: with prisma/migrations hidden it fails (4/4); with the baseline present it passes (4/4).

Scope notes

Baseline generated from main (production shape); it does not include the un-merged #237 unique index — that PR should ship its own migration. No unrelated files touched.

Not verified locally

The DB-backed drift + generate/apply/rollback jobs need a live Postgres; the docker daemon was unreachable on my box. Their logic and bash -n are validated and they run in CI.

[drips-wave]

@Neziahtech Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[Miracle656]

Fails one test on its own branch — and it is this PR's own test:

× #233 Prisma migration history replaces db push > has an init/baseline migration that reproduces schema.prisma exactly

tsc --noEmit is clean and the other 1149 tests pass, so the baseline in prisma/migrations/0_init/migration.sql does not reproduce schema.prisma exactly. Most likely something landed in the schema after you generated it — several PRs added models today, including a WebhookDeliveryFailure in #388.

Worth getting exactly right rather than close. This repo has been bitten by prisma db push ignoring committed migrations and half-applying a schema, and a baseline that does not match is how that recurs: the migration history claims to describe the database and quietly does not.

Regenerate the baseline against current schema.prisma, confirm your own test passes, and re-request. The change itself — replacing db push with a real migration history — is one I want.

[Miracle656]

Merged as 2abf7b3. This is a strong piece of work and the right shape for #233: a generated baseline rather than a hand-written one, a CI job that replays migrations against a real Postgres rather than trusting a file comparison, a DB-free test so npm test catches a forgotten migration with no database present, and the db push path removed from startup, the load workflow, CONTRIBUTING and the README together instead of one of them. docs/database-migrations.md is genuinely good documentation — the "Why not db push" section is the argument, not a restatement of the change.

Your drift test also earned its keep immediately: it failed on merge because main has gained webhook_delivery_failures and oracle_publications since you generated the baseline. I regenerated it.

Four things I changed on the way in.

---

1. Startup would have crash-looped on every database we have (blocking, fixed)

This is the one that mattered. Every Lens database that exists was created by db push, so it carries the full schema and no _prisma_migrations table. Prisma's baselining docs are explicit about what migrate deploy does from there — it runs the baseline's CREATE TABLEs against tables that are already present, and errors.

From src/index.ts that is not a failed migration. It is:

main().catch(err => {
  log.error({ err }, 'fatal startup error')
  process.exit(1)
})

So: CREATE TABLE "price_points" → 42P07 relation already exists → execSync throws → exit(1) → Render restarts → same thing again. A crash loop, with the API down.

Your own doc has the fix (npx prisma migrate resolve --applied 0_init), under "Adopting the baseline on an EXISTING production database" — and that is the right command. But as a runbook step it means the deploy survives or not depending on whether a human ran something first, and the window between the merge and the next redeploy can be days. That is not a safe thing to leave to ordering.

So I moved the adoption into code, in a new src/db/migrate.ts:

export async function applyMigrations(options: ApplyMigrationsOptions): Promise<void> {
  const baseline = options.baseline === undefined ? baselineMigration() : options.baseline

  if (baseline) {
    const state = await readMigrationState(db)
    if (needsBaselineAdoption(state)) {
      warn?.({ baseline }, 'database predates the migration history; recording the baseline as applied without running it')
      run(`${PRISMA_CLI} migrate resolve --applied ${baseline}`)
    }
  }

  run(`${PRISMA_CLI} migrate deploy`)
}

One query decides it:

select to_regclass('_prisma_migrations') is not null as has_history,
       to_regclass('price_points')       is not null as has_schema

Three states, all three now pinned by tests/db-migrate-baseline.test.ts (11 tests):

database	_prisma_migrations	schema	what runs
empty (CI, fresh local)	absent	absent	deploy only — creates everything
pre-migrate (ours today)	absent	present	resolve --applied <baseline>, then deploy applies nothing
already adopted	present	present	deploy only

A few details that are deliberate rather than incidental:

• The baseline name is read from disk, not hard-coded as 0_init. baselineMigration() takes the first migration folder by sort order, so renaming or replacing the baseline cannot leave a stale name in a resolve call, and a second migration later is unaffected — resolve adopts the first, deploy applies the rest.
• The probe is price_points, not indexer_state. Both Lens and wraith have a model mapped to indexer_state; a probe that asks "is there a schema here" has to be unambiguous about whose. The identifier is left unqualified so it follows the connection's search_path rather than assuming public.
• A half-created database is adopted too, and then fails in assertSchemaValid() with the list of what is missing. That is the better of the two errors — a named missing column beats relation already exists on whichever table the baseline happened to reach first.
• The pool and the command runner are injected, which is why the tests are DB-free and assert the command sequence (resolve strictly before deploy, exactly once) rather than mocking Prisma.

2. Dropping db push means drift is no longer self-healed — and that was undocumented

This is the subtler cost of the change, and it is worth being plain about because it is permanent.

db push ran on every boot and converged the live schema to schema.prisma, silently. After this PR nothing does. Concretely: api_keys.expires_at is in schema.prisma (line 334) and in the baseline (line 195). If it is missing from a live database — and we have had exactly this, a merged ALTER TABLE that never reached the database — then after adoption migrate deploy has nothing pending to apply, so the column stays missing forever. And assertSchemaValid() will not catch it: EXPECTED_SCHEMA in src/db/schemaVerify.ts covers five tables (price_points, pool_snapshots, price_aggregates, price_snapshots, indexer_state) and api_keys is not one of them. It surfaces as 500s on the authenticated routes, not as a failed boot.

I added a "One-time check before the first deploy" section to your doc with the command to run against each live database:

DIRECT_DATABASE_URL='<direct url for that environment>' \
  npx prisma migrate diff \
    --from-schema-datasource prisma/schema.prisma \
    --to-schema-datamodel prisma/schema.prisma \
    --script

Empty output means the database matches the baseline and is safe to adopt. Statements mean it is not, and they should become a committed migration first.

Two notes in there on why this is a person's job and not the code's:

• It is not wired into startup on purpose. Lens shares a Postgres instance with wraith, and if the two ever land in the same schema this diff reports wraith's eighteen tables as drift. A false positive there would be a refusal to boot, which is worse than the problem.
• CI cannot do it either. scripts/db-drift-check.sh replays the migrations into an empty Postgres and diffs that against schema.prisma. It never sees a live database. So the doc's line about this being "the check that would have caught a half-applied db push" is not quite right — a half-applied push leaves production drifted, and this guard does not look at production. I left the guard (it is the right guard for migrations-vs-schema) and moved that claim to the live check.

3. The operational docs still described the old boot

docs/RUNBOOK.md is the doc someone reads at 2am, and it had:

• db push --accept-data-loss as boot step 1, with the "may change destructively, automatically" warning attached to it;
• a rollback procedure telling the operator to run npx prisma db push from the old checkout — a command that no longer exists as a script, and which would now leave the database and the migration history disagreeing.

Both rewritten: step 1 is applyMigrations(), the destructive-change warning now says a destructive change reaches production because someone merged the SQL rather than because a diff decided it, and rollback is roll-forward with a reversing migration or a restore. I also added the "drift is no longer self-healing" corollary there, since that is where an operator will look.

Also: docs/database-schema.md still opened with "## Current State: prisma db push" (now marked superseded, with the early-development rationale kept as history), and docs/sep40-oracle-publisher.md pointed at npm run db:push, which this PR deletes.

4. *.sql pinned to LF

.gitattributes already pins *.json, *.yaml, *.csv and *.graphql for exactly this reason — each one after a byte-compare guard failed on a Windows checkout over line endings and nothing else. normalizeSql() strips trailing whitespace so your test survives CRLF today, but the baseline is a generated artifact compared against generated output, so it belongs in that list.

---

Operational note for whoever deploys this

The Render service is currently suspended, so nothing is live to break and the merge is safe as it stands. Before un-suspending, run the live-diff command from "One-time check before the first deploy" against the production database. If it prints statements, that drift needs a committed migration first — migrate deploy will not fix it for you any more.

123 test files / 1,472 tests pass. tsc --noEmit and npm run build clean.