fix(db): migrate isolated preview databases

Run migrations for each Vercel preview as well as production. Reject mismatched runtime and migration database targets so schema changes cannot silently land on a different branch.

Author: avatarneil

README.md

@@ -73,11 +73,13 @@ Account brackets use Postgres, Drizzle migrations, and Clerk user IDs. Set `DATA
 to a pooled connection for the app and `DATABASE_URL_UNPOOLED` to a direct connection
 for migrations. Keep both in your environment manager; never commit connection strings.
 
-Vercel Production builds automatically apply committed migrations before building the app.
+Vercel Production and Preview builds automatically apply committed migrations before building the app.
 Configure both variables in Vercel's **Production** environment using the Neon `main` branch.
+For **Preview**, let the Neon integration supply both URLs for that preview's branch.
+The migration and runtime URLs must target the same database branch.
 Missing migration credentials or a failed migration stops deployment. A direct-connection
 advisory lock serializes concurrent builds; Drizzle records applied migrations for safe retries.
-Preview and local builds skip this step and use an independently migrated development branch.
+Local builds skip this step; run `bun run db:migrate` to update your local development database.
 
 Migrations run before traffic switches, so schema changes must remain compatible with the
 currently deployed app. Use additive changes first; remove old columns in a later release.

scripts/migrate-on-deploy.mjs

@@ -5,21 +5,30 @@ import { migrate } from "drizzle-orm/node-postgres/migrator";
 
 class MigrationConfigurationError extends Error {}
 
-async function migrateProduction() {
-  if (process.env.VERCEL_ENV !== "production") {
-    console.log("Skipping production migrations outside a Vercel production build.");
+async function migrateDeployment() {
+  const environment = process.env.VERCEL_ENV;
+  if (!["production", "preview"].includes(environment)) {
+    console.log("Skipping deployment migrations outside Vercel production and preview builds.");
     return;
   }
   const connectionString = process.env.DATABASE_URL_UNPOOLED;
-  if (!connectionString) {
+  if (!connectionString || !process.env.DATABASE_URL) {
     throw new MigrationConfigurationError(
-      "Set DATABASE_URL_UNPOOLED in Vercel Production before deploying.",
+      `Set DATABASE_URL and DATABASE_URL_UNPOOLED in Vercel ${environment} before deploying.`,
     );
   }
   const connection = new URL(connectionString);
   if (connection.hostname.includes("-pooler.")) {
     throw new MigrationConfigurationError(
-      "Production migrations require a direct, unpooled connection.",
+      "Deployment migrations require a direct, unpooled connection.",
+    );
+  }
+  const runtime = new URL(process.env.DATABASE_URL);
+  const databaseTarget = (url) =>
+    `${url.hostname.replace(/-pooler(?=\.)/, "")}:${url.port || "5432"}${url.pathname}`;
+  if (databaseTarget(connection) !== databaseTarget(runtime)) {
+    throw new MigrationConfigurationError(
+      "DATABASE_URL and DATABASE_URL_UNPOOLED must target the same database branch.",
     );
   }
   const client = new pg.Client({ connectionString, connectionTimeoutMillis: 10000 });
@@ -32,13 +41,13 @@ async function migrateProduction() {
     await migrate(drizzle(client), {
       migrationsFolder: fileURLToPath(new URL("../drizzle", import.meta.url)),
     });
-    console.log("Production schema is up to date.");
+    console.log(`${environment} schema is up to date.`);
   } finally {
     await client.end();
   }
 }
 
-migrateProduction().catch((error) => {
+migrateDeployment().catch((error) => {
   // Driver errors can contain connection details; do not print credentials to
   // public build logs. Configuration errors above contain only our own text.
   const message =

scripts/migrate-on-deploy.test.mjs

@@ -9,7 +9,7 @@ function run(overrides) {
       process.execPath,
       [fileURLToPath(new URL("./migrate-on-deploy.mjs", import.meta.url))],
       {
-        env: { ...process.env, DATABASE_URL_UNPOOLED: "", ...overrides },
+        env: { ...process.env, DATABASE_URL_UNPOOLED: "", DATABASE_URL: "", ...overrides },
         stdio: ["ignore", "pipe", "pipe"],
       },
     );
@@ -25,28 +25,44 @@ function run(overrides) {
   });
 }
 
-test("local and preview builds never require or connect to production storage", async () => {
-  for (const VERCEL_ENV of ["", "preview", "development"]) {
+test("local builds never require or connect to deployment storage", async () => {
+  for (const VERCEL_ENV of ["", "development"]) {
     assert.equal((await run({ VERCEL_ENV, DATABASE_URL_UNPOOLED: "invalid" })).code, 0);
   }
 });
 
-test("production fails closed without a direct connection", async () => {
-  assert.equal((await run({ VERCEL_ENV: "production" })).code, 1);
-  const result = await run({
-    VERCEL_ENV: "production",
-    DATABASE_URL_UNPOOLED: "postgres://user:secret@ep-example-pooler.neon.tech/neondb",
-  });
-  assert.equal(result.code, 1);
-  assert.ok(!result.output.includes("secret"));
+test("deployment builds fail closed without matching direct and runtime connections", async () => {
+  for (const VERCEL_ENV of ["production", "preview"]) {
+    assert.equal((await run({ VERCEL_ENV })).code, 1);
+    const result = await run({
+      VERCEL_ENV,
+      DATABASE_URL_UNPOOLED: "postgres://user:secret@ep-example-pooler.neon.tech/neondb",
+      DATABASE_URL: "postgres://user:secret@ep-example-pooler.neon.tech/neondb",
+    });
+    assert.equal(result.code, 1);
+    assert.ok(!result.output.includes("secret"));
+    const mismatch = await run({
+      VERCEL_ENV,
+      DATABASE_URL: "postgres://user:secret@ep-preview-pooler.neon.tech/neondb",
+      DATABASE_URL_UNPOOLED: "postgres://user:secret@ep-main.neon.tech/neondb",
+    });
+    assert.equal(mismatch.code, 1);
+    assert.match(mismatch.output, /same database branch/);
+  }
 });
 
 test(
-  "production migration retries and concurrent builds are idempotent",
+  "preview and production migration retries are idempotent",
   { skip: !process.env.TEST_DATABASE_URL },
   async () => {
-    const env = { VERCEL_ENV: "production", DATABASE_URL_UNPOOLED: process.env.TEST_DATABASE_URL };
-    for (const result of await Promise.all([run(env), run(env)])) {
+    const env = {
+      DATABASE_URL: process.env.TEST_DATABASE_URL,
+      DATABASE_URL_UNPOOLED: process.env.TEST_DATABASE_URL,
+    };
+    for (const result of await Promise.all([
+      run({ ...env, VERCEL_ENV: "preview" }),
+      run({ ...env, VERCEL_ENV: "production" }),
+    ])) {
       assert.equal(result.code, 0, result.output);
       assert.match(result.output, /schema is up to date/);
     }