feat(FN-193): rewrite migrate.ts with hash-based runner (+4 more)
Some checks failed
Sync dev → Gitea / Mirror dev to Gitea (push) Has been cancelled
Some checks failed
Sync dev → Gitea / Mirror dev to Gitea (push) Has been cancelled
Commits merged: - docs(FN-193): update migration runner docs - fix(FN-193): lint/typecheck fixes - test(FN-193): rewrite migrate tests for runMigrations - feat(FN-193): make baseline migration idempotent (IF NOT EXISTS) - feat(FN-193): rewrite migrate.ts with hash-based runner Files changed: apps/api/drizzle/0000_brief_guardian.sql | 364 ++++++++++++------------ apps/api/src/database/__tests__/migrate.spec.ts | 354 ++++++++++++----------- apps/api/src/database/migrate.ts | 173 +++++------ docs/INDEX.md | 17 +- 4 files changed, 466 insertions(+), 442 deletions(-) Fusion-Task-Id: FN-193
This commit is contained in:
Fusion
@@ -1,251 +1,287 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import { readFileSync } from "node:fs";
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
/**
|
||||
* Unit tests for the migration runner's bootstrap logic.
|
||||
* Unit tests for the hash-based migration runner (runMigrations).
|
||||
*
|
||||
* We test bootstrapExistingDb() directly with a mock postgres.Sql client
|
||||
* and mock the filesystem via vi.mock("node:fs").
|
||||
* We test runMigrations() with a mock postgres.Sql client and mock
|
||||
* the filesystem (readFileSync) to control journal and SQL content.
|
||||
*/
|
||||
|
||||
// ── Mock SQL content matching the baseline migration ──
|
||||
const MOCK_JOURNAL = {
|
||||
// ── Test data ──
|
||||
|
||||
const SQL_0000 = `CREATE TABLE IF NOT EXISTS "users" (id uuid PRIMARY KEY);\n--> statement-breakpoint\nCREATE TABLE IF NOT EXISTS "brands" (id uuid PRIMARY KEY);\n`;
|
||||
const SQL_0001 = `ALTER TABLE "users" ADD COLUMN "email" varchar(255);\n`;
|
||||
|
||||
const HASH_0000 = createHash("sha256").update(SQL_0000).digest("hex");
|
||||
const HASH_0001 = createHash("sha256").update(SQL_0001).digest("hex");
|
||||
|
||||
const JOURNAL_1_ENTRY = {
|
||||
version: "7",
|
||||
dialect: "postgresql",
|
||||
entries: [
|
||||
{ idx: 0, version: "7", when: 1778535325959, tag: "0000_brief_guardian", breakpoints: true },
|
||||
],
|
||||
};
|
||||
|
||||
const JOURNAL_2_ENTRIES = {
|
||||
version: "7",
|
||||
dialect: "postgresql",
|
||||
entries: [
|
||||
{ idx: 0, version: "7", when: 1778535325959, tag: "0000_brief_guardian", breakpoints: true },
|
||||
{
|
||||
idx: 0,
|
||||
idx: 1,
|
||||
version: "7",
|
||||
when: 1778535325959,
|
||||
tag: "0000_brief_guardian",
|
||||
when: 1747039600000,
|
||||
tag: "0001_charming_quicksand",
|
||||
breakpoints: true,
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
const MOCK_BASELINE_SQL = [
|
||||
'CREATE TABLE "users" (id uuid PRIMARY KEY);',
|
||||
'CREATE TABLE "changelog_entries" (id uuid PRIMARY KEY);',
|
||||
'CREATE TABLE "brands" (id uuid PRIMARY KEY);',
|
||||
].join("\n--> statement-breakpoint\n");
|
||||
|
||||
const MOCK_BASELINE_TABLES = ["users", "changelog_entries", "brands"];
|
||||
// Journal with non-monotonic `when` values — idx determines order, not `when`
|
||||
const JOURNAL_RANDOM_WHEN = {
|
||||
version: "7",
|
||||
dialect: "postgresql",
|
||||
entries: [
|
||||
{ idx: 2, version: "7", when: 1000, tag: "0002_late", breakpoints: true },
|
||||
{ idx: 0, version: "7", when: 9999999999999, tag: "0000_brief_guardian", breakpoints: true },
|
||||
{ idx: 1, version: "7", when: 500, tag: "0001_charming_quicksand", breakpoints: true },
|
||||
],
|
||||
};
|
||||
|
||||
// ── FS mock ──
|
||||
|
||||
// The mock file system is configured per-test. readFileSync throws by default
|
||||
// for any unmapped path.
|
||||
let mockFiles: Record<string, string> = {};
|
||||
|
||||
vi.mock("node:fs", async () => {
|
||||
const actual = await vi.importActual<typeof import("node:fs")>("node:fs");
|
||||
return {
|
||||
...actual,
|
||||
readFileSync: vi.fn((path: string, _encoding: string) => {
|
||||
throw new Error(`ENOENT: mock file not set up: ${path}`);
|
||||
// Match by path suffix — migrate.ts uses join(migrationsFolder, ...)
|
||||
// which produces absolute paths, while mockFiles uses relative keys.
|
||||
const normalizedPath = String(path).replace(/\\/g, "/");
|
||||
for (const [key, content] of Object.entries(mockFiles)) {
|
||||
if (normalizedPath.endsWith(key)) return content;
|
||||
}
|
||||
throw new Error(`ENOENT: mock file not set up: ${normalizedPath}`);
|
||||
}),
|
||||
};
|
||||
});
|
||||
|
||||
import { bootstrapExistingDb } from "../../database/migrate";
|
||||
// Import under test after mock is set up
|
||||
import { runMigrations } from "../../database/migrate";
|
||||
|
||||
// ── Helpers ──
|
||||
// ── Mock SQL client helpers ──
|
||||
|
||||
interface TrackingTx {
|
||||
unsafe: ReturnType<typeof vi.fn>;
|
||||
__unsafeCalls: string[];
|
||||
}
|
||||
|
||||
interface MockSqlClient {
|
||||
(queryParts: TemplateStringsArray, ...values: unknown[]): Promise<unknown[]>;
|
||||
(template: TemplateStringsArray, ...values: unknown[]): Promise<unknown[]>;
|
||||
unsafe: ReturnType<typeof vi.fn>;
|
||||
begin: ReturnType<typeof vi.fn>;
|
||||
end: ReturnType<typeof vi.fn>;
|
||||
__inserts: string[];
|
||||
__unsafeCalls: string[];
|
||||
_setQueryHandler: (handler: (template: string) => unknown[]) => void;
|
||||
__appliedHashes: string[];
|
||||
__beginCallback: ((tx: TrackingTx) => Promise<void>) | null;
|
||||
_setBeginError: (err: Error) => void;
|
||||
}
|
||||
|
||||
function createMockSqlClient(): MockSqlClient {
|
||||
let queryHandler: (template: string) => unknown[] = () => [];
|
||||
let beginError: Error | null = null;
|
||||
const beginCallback: ((tx: TrackingTx) => Promise<void>) | null = null;
|
||||
|
||||
const sql = vi.fn(async (queryParts: TemplateStringsArray, ..._values: unknown[]) => {
|
||||
const queryText = queryParts.join(" ").trim();
|
||||
// Capture INSERT queries directly
|
||||
if (queryText.includes("INSERT INTO")) {
|
||||
(sql as any).__inserts.push(queryText);
|
||||
return [];
|
||||
const sql = vi.fn(async (template: TemplateStringsArray, ..._values: unknown[]) => {
|
||||
const queryText = template.join(" ").trim();
|
||||
// Handle SELECT hash query
|
||||
if (queryText.includes("SELECT hash FROM")) {
|
||||
return (sql as any).__appliedHashes.map((h: string) => ({ hash: h }));
|
||||
}
|
||||
return queryHandler(queryText);
|
||||
return [];
|
||||
}) as unknown as MockSqlClient;
|
||||
|
||||
(sql as any).unsafe = vi.fn(async (q: string) => {
|
||||
((sql as any).__unsafeCalls as string[]).push(q);
|
||||
(sql as any).unsafe = vi.fn(async (_q: string) => {
|
||||
((sql as any).__unsafeCalls as string[]).push(_q);
|
||||
});
|
||||
(sql as any).begin = vi.fn(async (cb: (tx: TrackingTx) => Promise<void>) => {
|
||||
(sql as any).__beginCallback = cb;
|
||||
|
||||
const tx: TrackingTx = {
|
||||
unsafe: vi.fn(async (_q: string) => {
|
||||
tx.__unsafeCalls.push(_q);
|
||||
// Inject error if configured (for rollback test)
|
||||
if (beginError) throw beginError;
|
||||
}),
|
||||
__unsafeCalls: [],
|
||||
};
|
||||
|
||||
await cb(tx);
|
||||
});
|
||||
(sql as any).end = vi.fn().mockResolvedValue(undefined);
|
||||
(sql as any).__inserts = [];
|
||||
(sql as any).__unsafeCalls = [];
|
||||
|
||||
(sql as any)._setQueryHandler = (handler: typeof queryHandler) => {
|
||||
queryHandler = handler;
|
||||
(sql as any).__appliedHashes = [];
|
||||
(sql as any).__beginCallback = null;
|
||||
(sql as any)._setBeginError = (err: Error) => {
|
||||
beginError = err;
|
||||
};
|
||||
|
||||
return sql;
|
||||
}
|
||||
|
||||
/**
|
||||
* Set up the readFileSync mock to return journal + baseline SQL content.
|
||||
* Set up the mock file system for a journal and its SQL files.
|
||||
*/
|
||||
function mockFsForBootstrap() {
|
||||
const mockRFS = readFileSync as ReturnType<typeof vi.fn>;
|
||||
mockRFS.mockImplementation((path: string, _encoding: string) => {
|
||||
if (path.includes("_journal.json")) {
|
||||
return JSON.stringify(MOCK_JOURNAL);
|
||||
}
|
||||
if (path.includes("0000_brief_guardian.sql")) {
|
||||
return MOCK_BASELINE_SQL;
|
||||
}
|
||||
throw new Error(`Unexpected readFileSync: ${path}`);
|
||||
});
|
||||
function setMockFiles(journal: Record<string, unknown>, sqlFiles: Record<string, string>) {
|
||||
mockFiles = {};
|
||||
// Normalize paths
|
||||
mockFiles["drizzle/meta/_journal.json"] = JSON.stringify(journal);
|
||||
for (const [tag, content] of Object.entries(sqlFiles)) {
|
||||
mockFiles[`drizzle/${tag}.sql`] = content;
|
||||
}
|
||||
}
|
||||
|
||||
// ── Tests ──
|
||||
|
||||
describe("bootstrapExistingDb", () => {
|
||||
describe("runMigrations", () => {
|
||||
let sqlClient: MockSqlClient;
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
let exitMock: any;
|
||||
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
mockFiles = {};
|
||||
sqlClient = createMockSqlClient();
|
||||
exitMock = vi.spyOn(process, "exit").mockImplementation(() => undefined as never);
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
exitMock.mockRestore();
|
||||
});
|
||||
// ── Test a: Empty DB + 1 migration → applies it, inserts hash ──
|
||||
|
||||
// ── Group 1: __drizzle_migrations already exists ──
|
||||
describe("empty DB with 1 migration", () => {
|
||||
it("should apply the migration and record its hash", async () => {
|
||||
setMockFiles(JOURNAL_1_ENTRY, { "0000_brief_guardian": SQL_0000 });
|
||||
// No applied hashes (empty DB)
|
||||
(sqlClient as any).__appliedHashes = [];
|
||||
|
||||
describe("when __drizzle_migrations already exists", () => {
|
||||
it("should skip bootstrap (no CREATE, no INSERT)", async () => {
|
||||
(sqlClient as any)._setQueryHandler((queryText: string) => {
|
||||
if (
|
||||
queryText.includes("information_schema") &&
|
||||
queryText.includes("__drizzle_migrations")
|
||||
) {
|
||||
return [{ table_name: "__drizzle_migrations" }];
|
||||
}
|
||||
return [];
|
||||
});
|
||||
await runMigrations(sqlClient as any);
|
||||
|
||||
await bootstrapExistingDb(sqlClient as any);
|
||||
// Should create schema and tracking table
|
||||
const unsafeAll = (sqlClient as any).__unsafeCalls as string[];
|
||||
expect(unsafeAll.some((c: string) => c.includes("CREATE SCHEMA"))).toBe(true);
|
||||
expect(unsafeAll.some((c: string) => c.includes("CREATE TABLE IF NOT EXISTS"))).toBe(true);
|
||||
// Migration was applied (begin was called)
|
||||
expect((sqlClient as any).begin).toHaveBeenCalledTimes(1);
|
||||
|
||||
// Should NOT create schema or table
|
||||
expect((sqlClient as any).__unsafeCalls).toEqual([]);
|
||||
|
||||
// Should NOT insert any migration records
|
||||
expect((sqlClient as any).__inserts).toEqual([]);
|
||||
// The tx inside begin should have executed the 2 statements + INSERT
|
||||
const beginCallback = (sqlClient as any).__beginCallback;
|
||||
expect(beginCallback).not.toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
// ── Group 2: All baseline tables present → bootstrap ──
|
||||
// ── Test b: Existing DB + matching hash → skips ──
|
||||
|
||||
describe("when all baseline tables exist (existing DB with no tracking)", () => {
|
||||
it("should create schema, create table, and mark baseline entries as applied", async () => {
|
||||
mockFsForBootstrap();
|
||||
describe("existing DB with matching hash", () => {
|
||||
it("should skip the migration (appliedCount=0, skippedCount=1)", async () => {
|
||||
setMockFiles(JOURNAL_1_ENTRY, { "0000_brief_guardian": SQL_0000 });
|
||||
(sqlClient as any).__appliedHashes = [HASH_0000];
|
||||
|
||||
(sqlClient as any)._setQueryHandler((queryText: string) => {
|
||||
if (
|
||||
queryText.includes("information_schema") &&
|
||||
queryText.includes("__drizzle_migrations")
|
||||
) {
|
||||
return []; // __drizzle_migrations does NOT exist
|
||||
}
|
||||
// The baseline-tables check uses information_schema.tables with ANY
|
||||
if (queryText.includes("information_schema") && queryText.includes("ANY(")) {
|
||||
return MOCK_BASELINE_TABLES.map((t) => ({ table_name: t }));
|
||||
}
|
||||
return [];
|
||||
});
|
||||
await runMigrations(sqlClient as any);
|
||||
|
||||
await bootstrapExistingDb(sqlClient as any);
|
||||
|
||||
// Verify CREATE SCHEMA was called
|
||||
expect((sqlClient as any).__unsafeCalls).toContain('CREATE SCHEMA IF NOT EXISTS "drizzle"');
|
||||
|
||||
// Verify CREATE TABLE was called
|
||||
const createTableCall = (sqlClient as any).__unsafeCalls.find((c: string) =>
|
||||
c.includes("CREATE TABLE IF NOT EXISTS"),
|
||||
);
|
||||
expect(createTableCall).toBeDefined();
|
||||
expect(createTableCall).toContain("__drizzle_migrations");
|
||||
|
||||
// Verify INSERT was called with a hash
|
||||
expect((sqlClient as any).__inserts.length).toBe(1);
|
||||
// begin should NOT have been called (no migration applied)
|
||||
expect((sqlClient as any).begin).not.toHaveBeenCalled();
|
||||
// Schema/table creation still happens
|
||||
const unsafeAll = (sqlClient as any).__unsafeCalls as string[];
|
||||
expect(unsafeAll.some((c: string) => c.includes("CREATE SCHEMA"))).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
// ── Group 3: No baseline tables exist → fresh DB ──
|
||||
// ── Test c: 2 migrations, 1 applied + 1 new → applies only the new one ──
|
||||
|
||||
describe("when no baseline tables exist (fresh DB)", () => {
|
||||
it("should skip bootstrap entirely", async () => {
|
||||
mockFsForBootstrap();
|
||||
|
||||
(sqlClient as any)._setQueryHandler((queryText: string) => {
|
||||
if (
|
||||
queryText.includes("information_schema") &&
|
||||
queryText.includes("__drizzle_migrations")
|
||||
) {
|
||||
return []; // __drizzle_migrations does NOT exist
|
||||
}
|
||||
if (queryText.includes("information_schema") && queryText.includes("ANY(")) {
|
||||
return []; // no baseline tables exist
|
||||
}
|
||||
return [];
|
||||
describe("2 migrations, 1 already applied", () => {
|
||||
it("should apply only the new migration", async () => {
|
||||
setMockFiles(JOURNAL_2_ENTRIES, {
|
||||
"0000_brief_guardian": SQL_0000,
|
||||
"0001_charming_quicksand": SQL_0001,
|
||||
});
|
||||
// Only 0000's hash is already applied
|
||||
(sqlClient as any).__appliedHashes = [HASH_0000];
|
||||
|
||||
await bootstrapExistingDb(sqlClient as any);
|
||||
await runMigrations(sqlClient as any);
|
||||
|
||||
// No schema creation
|
||||
expect((sqlClient as any).__unsafeCalls).toEqual([]);
|
||||
// No inserts
|
||||
expect((sqlClient as any).__inserts).toEqual([]);
|
||||
// begin should be called exactly once (for 0001)
|
||||
expect((sqlClient as any).begin).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
});
|
||||
|
||||
// ── Group 4: Partial baseline state → error ──
|
||||
// ── Test d: Statement breakpoint parsing ──
|
||||
|
||||
describe("when some but not all baseline tables exist (partial state)", () => {
|
||||
it("should call process.exit(1) with a clear error message", async () => {
|
||||
mockFsForBootstrap();
|
||||
describe("statement breakpoint parsing", () => {
|
||||
it("should split on '--> statement-breakpoint' and execute each statement", async () => {
|
||||
setMockFiles(JOURNAL_1_ENTRY, { "0000_brief_guardian": SQL_0000 });
|
||||
(sqlClient as any).__appliedHashes = [];
|
||||
|
||||
(sqlClient as any)._setQueryHandler((queryText: string) => {
|
||||
if (
|
||||
queryText.includes("information_schema") &&
|
||||
queryText.includes("__drizzle_migrations")
|
||||
) {
|
||||
return []; // __drizzle_migrations does NOT exist
|
||||
}
|
||||
if (queryText.includes("information_schema") && queryText.includes("ANY(")) {
|
||||
// Only users and brands exist — changelog_entries is missing
|
||||
return [{ table_name: "users" }, { table_name: "brands" }];
|
||||
}
|
||||
return [];
|
||||
await runMigrations(sqlClient as any);
|
||||
|
||||
expect((sqlClient as any).begin).toHaveBeenCalledTimes(1);
|
||||
|
||||
// The tx unsafe calls should include the 2 CREATE TABLE statements and 1 INSERT
|
||||
// We can verify by checking the begin callback's tx had exactly 3 unsafe calls
|
||||
const beginCallback = (sqlClient as any).__beginCallback;
|
||||
expect(beginCallback).not.toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
// ── Test e: Transaction rollback ──
|
||||
|
||||
describe("transaction rollback on error", () => {
|
||||
it("should not insert migration hash when a statement fails", async () => {
|
||||
setMockFiles(JOURNAL_2_ENTRIES, {
|
||||
"0000_brief_guardian": SQL_0000,
|
||||
"0001_charming_quicksand": SQL_0001,
|
||||
});
|
||||
// 0000 already applied, 0001 will be attempted
|
||||
(sqlClient as any).__appliedHashes = [HASH_0000];
|
||||
// Make the begin callback throw on first tx.unsafe call
|
||||
(sqlClient as any)._setBeginError(new Error("syntax error"));
|
||||
|
||||
await bootstrapExistingDb(sqlClient as any);
|
||||
await expect(runMigrations(sqlClient as any)).rejects.toThrow("syntax error");
|
||||
|
||||
// Should exit with code 1
|
||||
expect(exitMock).toHaveBeenCalledWith(1);
|
||||
// Note: __unsafeCalls / __inserts may be populated after process.exit
|
||||
// because the mock doesn't actually terminate execution.
|
||||
// begin WAS called, but the inner callback threw — no INSERT should have run
|
||||
expect((sqlClient as any).begin).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
});
|
||||
|
||||
// ── Test f: Journal ordering by idx, not when ──
|
||||
|
||||
describe("journal ordering", () => {
|
||||
it("should sort entries by idx regardless of 'when' values", async () => {
|
||||
const sqlFiles: Record<string, string> = {
|
||||
"0000_brief_guardian": SQL_0000,
|
||||
"0001_charming_quicksand": SQL_0001,
|
||||
"0002_late": 'CREATE INDEX IF NOT EXISTS "idx_test" ON "users" ("email");\n',
|
||||
};
|
||||
setMockFiles(JOURNAL_RANDOM_WHEN, sqlFiles);
|
||||
(sqlClient as any).__appliedHashes = [];
|
||||
|
||||
await runMigrations(sqlClient as any);
|
||||
|
||||
// All 3 migrations should be applied (begin called 3 times)
|
||||
expect((sqlClient as any).begin).toHaveBeenCalledTimes(3);
|
||||
});
|
||||
});
|
||||
|
||||
// ── Test: Empty journal → no-op ──
|
||||
|
||||
describe("empty journal", () => {
|
||||
it("should exit early with no errors", async () => {
|
||||
setMockFiles({ version: "7", dialect: "postgresql", entries: [] }, {});
|
||||
|
||||
await runMigrations(sqlClient as any);
|
||||
|
||||
// begin should NOT have been called
|
||||
expect((sqlClient as any).begin).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe("hash computation", () => {
|
||||
it("should produce the expected SHA256 hash for a known input", () => {
|
||||
const input = "SELECT 1";
|
||||
const hash = createHash("sha256").update(input).digest("hex");
|
||||
expect(hash).toBe("e004ebd5b5532a4b85984a62f8ad48a81aa3460c1ca07701f386135d72cdecf5");
|
||||
});
|
||||
|
||||
it("should produce a different hash for different input", () => {
|
||||
const hashA = createHash("sha256").update("SELECT 1").digest("hex");
|
||||
const hashB = createHash("sha256").update("SELECT 2").digest("hex");
|
||||
expect(hashA).not.toBe(hashB);
|
||||
});
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user