Add error handling for outdated clients running against newer DB schemas

grfwings · grfwings · commit 4c9c3eb521c2 · 2026-05-09T21:02:03.000-07:00
diff --git a/apps/cli/release-notes/next.md b/apps/cli/release-notes/next.md
@@ -78,6 +78,7 @@ Tool dispatch, plugins, storage, schema, and transport are now fully instrumente
 - Upgrade: preserve legacy OAuth connection backfills after the `connection.kind` column is removed.
 - OpenAPI: refreshing or editing sources with legacy inline secret/OAuth config now materializes the new source binding rows instead of dropping credentials.
 - Keychain: skip provider registration when the OS backend is unreachable (no more startup failure when running headless on Linux without a keyring).
+- Local database: fail early with guidance when an older Executor build opens a data directory migrated by a newer build, instead of surfacing a low-level SQLite schema error.
 - Local server: return 404 for missing static assets instead of serving HTML.
 - Tests: Windows compatibility across the suite.
 
diff --git a/apps/local/src/server/executor-schema-compat.test.ts b/apps/local/src/server/executor-schema-compat.test.ts
@@ -0,0 +1,181 @@
+import { Database } from "bun:sqlite";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "@effect/vitest";
+import { drizzle } from "drizzle-orm/bun-sqlite";
+import { migrate } from "drizzle-orm/bun-sqlite/migrator";
+
+import {
+  LocalDatabaseMigrationHistoryMismatch,
+  LocalDatabaseSchemaTooNew,
+  checkDrizzleMigrationCompatibility,
+  readAppliedDrizzleMigrationHashes,
+  readBundledDrizzleMigrationHashes,
+} from "./executor";
+
+const MIGRATIONS_FOLDER = join(import.meta.dirname, "../../drizzle");
+
+const workDirs: string[] = [];
+
+const tempDb = (): { db: Database; path: string } => {
+  const dir = mkdtempSync(join(tmpdir(), "executor-schema-compat-"));
+  workDirs.push(dir);
+  const path = join(dir, "data.db");
+  return { db: new Database(path), path };
+};
+
+const createMigrationTable = (db: Database): void => {
+  db.exec(`
+    CREATE TABLE __drizzle_migrations (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      hash TEXT NOT NULL,
+      created_at NUMERIC
+    )
+  `);
+};
+
+const insertMigrationHashes = (db: Database, hashes: ReadonlyArray<string>): void => {
+  const stmt = db.prepare("INSERT INTO __drizzle_migrations (hash, created_at) VALUES (?, ?)");
+  for (const [index, hash] of hashes.entries()) {
+    stmt.run(hash, index + 1);
+  }
+};
+
+afterEach(() => {
+  for (const dir of workDirs.splice(0)) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe("Drizzle migration compatibility preflight", () => {
+  it("allows a fresh DB without __drizzle_migrations", () => {
+    const { db, path } = tempDb();
+    try {
+      expect(() =>
+        checkDrizzleMigrationCompatibility({
+          sqlite: db,
+          dbPath: path,
+          migrationsFolder: MIGRATIONS_FOLDER,
+        }),
+      ).not.toThrow();
+    } finally {
+      db.close();
+    }
+  });
+
+  it("allows an existing but empty __drizzle_migrations table", () => {
+    const { db, path } = tempDb();
+    try {
+      createMigrationTable(db);
+
+      expect(() =>
+        checkDrizzleMigrationCompatibility({
+          sqlite: db,
+          dbPath: path,
+          migrationsFolder: MIGRATIONS_FOLDER,
+        }),
+      ).not.toThrow();
+    } finally {
+      db.close();
+    }
+  });
+
+  it("computes bundled hashes that exactly match hashes written by Drizzle", () => {
+    const { db } = tempDb();
+    try {
+      migrate(drizzle(db), { migrationsFolder: MIGRATIONS_FOLDER });
+
+      expect(readAppliedDrizzleMigrationHashes(db)).toEqual(
+        readBundledDrizzleMigrationHashes(MIGRATIONS_FOLDER),
+      );
+    } finally {
+      db.close();
+    }
+  });
+
+  it("throws LocalDatabaseSchemaTooNew when the DB has more migrations than the binary", () => {
+    const { db, path } = tempDb();
+    try {
+      const bundled = readBundledDrizzleMigrationHashes(MIGRATIONS_FOLDER);
+      createMigrationTable(db);
+      insertMigrationHashes(db, [...bundled, "future-migration-hash"]);
+
+      expect(() =>
+        checkDrizzleMigrationCompatibility({
+          sqlite: db,
+          dbPath: path,
+          migrationsFolder: MIGRATIONS_FOLDER,
+        }),
+      ).toThrow(LocalDatabaseSchemaTooNew);
+
+      try {
+        checkDrizzleMigrationCompatibility({
+          sqlite: db,
+          dbPath: path,
+          migrationsFolder: MIGRATIONS_FOLDER,
+        });
+      } catch (error) {
+        expect(error).toBeInstanceOf(LocalDatabaseSchemaTooNew);
+        expect((error as Error).message).toContain(
+          "This Executor binary is older than the schema",
+        );
+        expect((error as Error).message).toContain("Use a newer Executor binary");
+      }
+    } finally {
+      db.close();
+    }
+  });
+
+  it("throws LocalDatabaseMigrationHistoryMismatch when hashes diverge", () => {
+    const { db, path } = tempDb();
+    try {
+      const bundled = readBundledDrizzleMigrationHashes(MIGRATIONS_FOLDER);
+      createMigrationTable(db);
+      insertMigrationHashes(db, ["different-migration-hash", ...bundled.slice(1)]);
+
+      expect(() =>
+        checkDrizzleMigrationCompatibility({
+          sqlite: db,
+          dbPath: path,
+          migrationsFolder: MIGRATIONS_FOLDER,
+        }),
+      ).toThrow(LocalDatabaseMigrationHistoryMismatch);
+
+      try {
+        checkDrizzleMigrationCompatibility({
+          sqlite: db,
+          dbPath: path,
+          migrationsFolder: MIGRATIONS_FOLDER,
+        });
+      } catch (error) {
+        expect(error).toBeInstanceOf(LocalDatabaseMigrationHistoryMismatch);
+        expect((error as Error).message).toContain(
+          "does not match this Executor build",
+        );
+        expect((error as Error).message).toContain("restore a backup");
+      }
+    } finally {
+      db.close();
+    }
+  });
+
+  it("allows an older DB whose migration history is a bundled prefix", () => {
+    const { db, path } = tempDb();
+    try {
+      const bundled = readBundledDrizzleMigrationHashes(MIGRATIONS_FOLDER);
+      createMigrationTable(db);
+      insertMigrationHashes(db, bundled.slice(0, 1));
+
+      expect(() =>
+        checkDrizzleMigrationCompatibility({
+          sqlite: db,
+          dbPath: path,
+          migrationsFolder: MIGRATIONS_FOLDER,
+        }),
+      ).not.toThrow();
+    } finally {
+      db.close();
+    }
+  });
+});
diff --git a/apps/local/src/server/executor.ts b/apps/local/src/server/executor.ts
@@ -97,6 +97,23 @@ class LocalExecutorTag extends Context.Service<LocalExecutorTag, LocalExecutorBu
 
 export type LocalExecutor = LocalExecutorBundle["executor"];
 
+export class LocalDatabaseSchemaTooNew extends Data.TaggedError("LocalDatabaseSchemaTooNew")<{
+  readonly message: string;
+  readonly dbPath: string;
+  readonly appliedMigrationCount: number;
+  readonly knownMigrationCount: number;
+}> {}
+
+export class LocalDatabaseMigrationHistoryMismatch extends Data.TaggedError(
+  "LocalDatabaseMigrationHistoryMismatch",
+)<{
+  readonly message: string;
+  readonly dbPath: string;
+  readonly migrationIndex: number;
+  readonly appliedHash: string | undefined;
+  readonly knownHash: string | undefined;
+}> {}
+
 class LocalExecutorDisposeError extends Data.TaggedError("LocalExecutorDisposeError")<{
   readonly operation: "createHandle" | "disposeExecutor" | "disposeRuntime";
   readonly cause: unknown;
@@ -127,6 +144,100 @@ const handleOrNull = (promise: ReturnType<typeof createExecutorHandle>) =>
     ),
   );
 
+export const drizzleMigrationsTableExists = (sqlite: Database): boolean => {
+  const row = sqlite
+    .query<{ name: string }, [string]>(
+      "SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?",
+    )
+    .get("__drizzle_migrations");
+
+  return row !== null;
+};
+
+export const readAppliedDrizzleMigrationHashes = (sqlite: Database): ReadonlyArray<string> => {
+  if (!drizzleMigrationsTableExists(sqlite)) return [];
+
+  // Drizzle inserts one row per applied migration. `id` is the stable
+  // application order; `created_at` comes from migration metadata and can tie.
+  return sqlite
+    .query<{ hash: string }, []>("SELECT hash FROM __drizzle_migrations ORDER BY id ASC")
+    .all()
+    .map((row) => row.hash);
+};
+
+interface DrizzleJournal {
+  readonly entries: ReadonlyArray<{
+    readonly idx: number;
+    readonly tag: string;
+  }>;
+}
+
+export const readBundledDrizzleMigrationHashes = (
+  migrationsFolder: string,
+): ReadonlyArray<string> => {
+  // Keep this in sync with drizzle-orm/src/migrator.ts: Drizzle hashes the raw
+  // migration file contents before splitting on statement breakpoints.
+  const journal = JSON.parse(
+    fs.readFileSync(join(migrationsFolder, "meta", "_journal.json")).toString(),
+  ) as DrizzleJournal;
+
+  return [...journal.entries]
+    .sort((left, right) => left.idx - right.idx)
+    .map((entry) => {
+      const query = fs.readFileSync(join(migrationsFolder, `${entry.tag}.sql`)).toString();
+      return createHash("sha256").update(query).digest("hex");
+    });
+};
+
+const schemaTooNewMessage = (dbPath: string): string =>
+  [
+    `This Executor binary is older than the schema in ${process.env.EXECUTOR_DATA_DIR ?? dirname(dbPath)}.`,
+    "The database was likely opened by a newer Executor build.",
+    "Use a newer Executor binary or set EXECUTOR_DATA_DIR to a different data directory.",
+  ].join("\n");
+
+const migrationHistoryMismatchMessage = (dbPath: string): string =>
+  [
+    `The migration history in ${process.env.EXECUTOR_DATA_DIR ?? dirname(dbPath)} does not match this Executor build.`,
+    "The database may have been created by a different development branch, manually modified, or corrupted.",
+    "Use the matching Executor build, set EXECUTOR_DATA_DIR to a different data directory, or restore a backup.",
+  ].join("\n");
+
+export const checkDrizzleMigrationCompatibility = (input: {
+  readonly sqlite: Database;
+  readonly dbPath: string;
+  readonly migrationsFolder: string;
+}): void => {
+  // Before running migrations, ensure the DB history is a prefix of the
+  // migrations bundled with this binary. This catches newer or divergent schemas
+  // before startup reaches arbitrary schema-dependent queries.
+  if (!drizzleMigrationsTableExists(input.sqlite)) return;
+
+  const applied = readAppliedDrizzleMigrationHashes(input.sqlite);
+  const bundled = readBundledDrizzleMigrationHashes(input.migrationsFolder);
+
+  if (applied.length > bundled.length) {
+    throw new LocalDatabaseSchemaTooNew({
+      message: schemaTooNewMessage(input.dbPath),
+      dbPath: input.dbPath,
+      appliedMigrationCount: applied.length,
+      knownMigrationCount: bundled.length,
+    });
+  }
+
+  for (let index = 0; index < applied.length; index += 1) {
+    if (applied[index] !== bundled[index]) {
+      throw new LocalDatabaseMigrationHistoryMismatch({
+        message: migrationHistoryMismatchMessage(input.dbPath),
+        dbPath: input.dbPath,
+        migrationIndex: index,
+        appliedHash: applied[index],
+        knownHash: bundled[index],
+      });
+    }
+  }
+};
+
 const createLocalExecutorLayer = () => {
   const { path: dbPath, legacySecrets } = resolveDbPath();
 
@@ -136,6 +247,11 @@ const createLocalExecutorLayer = () => {
         Effect.sync(() => new Database(dbPath)),
         (conn) => Effect.sync(() => conn.close()),
       );
+      checkDrizzleMigrationCompatibility({
+        sqlite,
+        dbPath,
+        migrationsFolder: MIGRATIONS_FOLDER,
+      });
       sqlite.exec("PRAGMA journal_mode = WAL");
 
       const db = drizzle(sqlite, { schema: executorSchema });
