Skip to content

The open-source app everyone uses to manage agents at work

Repair the drizzle snapshot so generate emits no spurious migration (#12333)

Devin Foleybdd8f1bedb11
diff --git a/doc/DATABASE.md b/doc/DATABASE.md
index 3f0a2ce57e..5fa9c9487a 100644
--- a/doc/DATABASE.md
+++ b/doc/DATABASE.md
@@ -167,6 +167,14 @@ When authoring migrations or one-time backfills:
- Split schema changes, index creation, and data backfill into separate phases so each step has clear locking and rollback behavior.
- Treat the `check:migrations` CI gate as the enforcement backstop for these rules. If it flags a migration, rewrite the migration or add a suppression comment with the indexed predicate, batch bound, and reason the remaining scan is safe.
+## Migration snapshots
+
+`drizzle-kit generate` diffs `packages/db/src/schema/` against the newest snapshot in `packages/db/src/migrations/meta/`. That snapshot must describe the schema that every migration produces when they run in order. A snapshot that drifts from the schema makes the *next* migration wrong, because `generate` folds the drift into it. The drift can add a column that an earlier migration already created, which makes that migration fail on a fresh database. It can also drop a column that the schema still uses.
+
+- Create every migration with `pnpm --filter @paperclipai/db generate`. Do not hand-write a snapshot.
+- Do not hand-edit a snapshot to resolve a merge conflict. Renumber your migration and run `generate` again, as `packages/db/.gitattributes` describes.
+- `packages/db/src/migration-snapshot-drift.test.ts` is the enforcement backstop. It repeats the diff that `generate` performs and fails when the newest snapshot no longer matches `packages/db/src/schema/`.
+
## Resource membership tables
Paperclip stores current-user sidebar membership state in:
diff --git a/packages/db/src/migration-snapshot-drift.test.ts b/packages/db/src/migration-snapshot-drift.test.ts
new file mode 100644
index 0000000000..b67c985698
--- /dev/null
+++ b/packages/db/src/migration-snapshot-drift.test.ts
@@ -0,0 +1,74 @@
+import { readdir, readFile } from "node:fs/promises";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { generateDrizzleJson, generateMigration } from "drizzle-kit/api";
+
+// The newest snapshot in `src/migrations/meta` is the state `drizzle-kit
+// generate` diffs the schema against. When it drifts from the schema, the next
+// generated migration silently carries the drift: it re-adds a column an
+// earlier migration already created (which fails on a fresh database) and drops
+// a column the schema never had. This test reproduces the diff `generate`
+// performs — schema modules versus newest snapshot — and fails when it is not
+// empty, so drift is caught in CI instead of inside someone else's migration.
+
+const migrationsDir = fileURLToPath(new URL("./migrations", import.meta.url));
+const schemaDir = fileURLToPath(new URL("./schema", import.meta.url));
+
+type JournalEntry = { idx: number; tag: string };
+
+async function readNewestSnapshot(): Promise<{ file: string; snapshot: Record<string, unknown> }> {
+ const journal = JSON.parse(
+ await readFile(path.join(migrationsDir, "meta", "_journal.json"), "utf8"),
+ ) as { entries: JournalEntry[] };
+ const newest = journal.entries.at(-1);
+ if (!newest) throw new Error("migration journal has no entries");
+ const file = `${String(newest.idx).padStart(4, "0")}_snapshot.json`;
+ const snapshot = JSON.parse(await readFile(path.join(migrationsDir, "meta", file), "utf8")) as Record<
+ string,
+ unknown
+ >;
+ return { file, snapshot };
+}
+
+// drizzle.config.ts points drizzle-kit at every module in the schema directory,
+// so the test imports the same set rather than the hand-maintained barrel — a
+// table missing from the barrel must not hide from this check.
+async function importSchemaModules(): Promise<Record<string, unknown>> {
+ const files = (await readdir(schemaDir)).filter((file) => file.endsWith(".ts")).sort();
+ const exports: Record<string, unknown> = {};
+ // The barrel re-exports the same table objects the per-table modules export,
+ // so dedupe by identity: serializing one table twice trips drizzle-kit's
+ // duplicate-index guard.
+ const seen = new Set<unknown>();
+ for (const file of files) {
+ const module = (await import(pathToFileURL(path.join(schemaDir, file)).href)) as Record<
+ string,
+ unknown
+ >;
+ for (const [name, value] of Object.entries(module)) {
+ if (typeof value === "object" && value !== null) {
+ if (seen.has(value)) continue;
+ seen.add(value);
+ }
+ exports[`${file}#${name}`] = value;
+ }
+ }
+ return exports;
+}
+
+describe("migration snapshot drift", () => {
+ it("keeps the newest snapshot in sync with the drizzle schema", async () => {
+ const { file, snapshot } = await readNewestSnapshot();
+ const current = generateDrizzleJson(await importSchemaModules(), snapshot.id as string);
+ const statements = await generateMigration(
+ snapshot as Parameters<typeof generateMigration>[0],
+ current as Parameters<typeof generateMigration>[1],
+ );
+
+ expect(
+ statements,
+ `${file} no longer matches src/schema. Run \`pnpm --filter @paperclipai/db generate\` and commit the migration it emits; do not hand-edit the snapshot.`,
+ ).toEqual([]);
+ });
+});
diff --git a/packages/db/src/migrations/meta/0228_snapshot.json b/packages/db/src/migrations/meta/0228_snapshot.json
index 9f002ba8ba..17d4d2e41e 100644
--- a/packages/db/src/migrations/meta/0228_snapshot.json
+++ b/packages/db/src/migrations/meta/0228_snapshot.json
@@ -9471,13 +9471,6 @@
"notNull": true,
"default": 0
},
- "error_count": {
- "name": "error_count",
- "type": "integer",
- "primaryKey": false,
- "notNull": true,
- "default": 0
- },
"last_attempt_at": {
"name": "last_attempt_at",
"type": "timestamp with time zone",
@@ -21193,6 +21186,13 @@
"notNull": true,
"default": 0
},
+ "error_count": {
+ "name": "error_count",
+ "type": "integer",
+ "primaryKey": false,
+ "notNull": true,
+ "default": 0
+ },
"last_attempt_at": {
"name": "last_attempt_at",
"type": "timestamp with time zone",
diff --git a/packages/db/src/migrations/meta/0229_snapshot.json b/packages/db/src/migrations/meta/0229_snapshot.json
index a548f47cdf..d01518af6c 100644
--- a/packages/db/src/migrations/meta/0229_snapshot.json
+++ b/packages/db/src/migrations/meta/0229_snapshot.json
@@ -9458,13 +9458,6 @@
"notNull": true,
"default": 0
},
- "error_count": {
- "name": "error_count",
- "type": "integer",
- "primaryKey": false,
- "notNull": true,
- "default": 0
- },
"last_attempt_at": {
"name": "last_attempt_at",
"type": "timestamp with time zone",
@@ -21180,6 +21173,13 @@
"notNull": true,
"default": 0
},
+ "error_count": {
+ "name": "error_count",
+ "type": "integer",
+ "primaryKey": false,
+ "notNull": true,
+ "default": 0
+ },
"last_attempt_at": {
"name": "last_attempt_at",
"type": "timestamp with time zone",