Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.
TypeScript ai-agentsbill-of-materialserpinventory-managementleanmanufacturingmanufacturing-execution-systemmcp-servermesmrpopen-source-erppostgresqlproduction-planningqmsquality-management-systemreact-routerself-hostedsupabasetraceabilitytypescript
// SPDX-License-Identifier: AGPL-3.0-only
// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
// including ports, remain AGPLv3; serving them over a network requires releasing their source.
/**
* Checks that the backups customers already hold would still restore against the
* current schema.
*
* A migration can make an existing backup unrestorable without the backup changing
* at all — add a NOT NULL column with no DEFAULT and every backup taken before today
* stops loading. Nobody finds out until someone clicks Restore, which is the worst
* possible moment. So the question gets asked here, at commit time.
*
* The baseline is `packages/jobs/manifests/schema.json` AS IT STANDS ON `main` —
* the schema real customer backups were taken against. The copy in the working tree
* is not the baseline: it is regenerated from the live database on every successful
* `--stage` run, so comparing against it would compare today with today.
*
* Runs from the pre-commit hook when `packages/database/supabase/migrations/**` is
* touched; set CARBON_SKIP_BACKUP_CHECK=1 to skip it there.
*
* Usage:
* pnpm db:check:backups # check only — writes nothing
* pnpm db:check:backups -- --stage # ...then update and stage schema.json
*/
import { execFileSync } from "node:child_process";
import { mkdirSync, readdirSync, writeFileSync } from "node:fs";
import { dirname, join } from "node:path";
import process from "node:process";
import { parseArgs } from "node:util";
import type { KyselyDatabase } from "@carbon/database/client";
import { now } from "@internationalized/date";
import { Kysely, PostgresDialect, sql } from "kysely";
import pg from "pg";
import type { Catalog, Manifest } from "../backups/schema";
import {
BACKUP_KIND,
BACKUP_VERSION,
exportableColumns,
getCompanyTableCatalog,
reportBackupCompatibility,
selectExportableTables
} from "../backups/schema";
import {
BASELINE_BRANCH,
BaselineError,
resolveBaseline,
SCHEMA_REPO_PATH
} from "./backup-baseline";
const REPO_ROOT = join(import.meta.dirname, "../../../..");
const SCHEMA_FILE = join(REPO_ROOT, SCHEMA_REPO_PATH);
/** A hook that hangs is a hook people bypass. */
const FETCH_TIMEOUT_MS = 3000;
const FIX_HINT =
"Fix: give the new column a DEFAULT (or make it nullable and backfill), or — " +
"if a table was renamed — add an entry to TABLE_RENAMES in " +
"packages/jobs/src/backups/renames.ts";
const RERUN_HINT =
"Re-run on its own with: pnpm db:check:backups\n" +
"Commit anyway with: CARBON_SKIP_BACKUP_CHECK=1 git commit ...";
/**
* A Kysely client built here rather than borrowed from `src/db.ts`.
*
* `getJobDatabaseClient` named-imports `@carbon/database/client`, which resolves as
* CJS from this package's ESM — fine under Vite and vitest, a hard `SyntaxError`
* under plain `tsx`. Owning the pool is also what lets this script close it and exit.
*/
function connect(): { db: Kysely<KyselyDatabase>; pool: pg.Pool } {
const connectionString = process.env.SUPABASE_DB_URL;
if (!connectionString) {
skip("SUPABASE_DB_URL is not set (is your local stack up?)");
}
const pool = new pg.Pool({ connectionString, max: 1 });
return {
db: new Kysely<KyselyDatabase>({ dialect: new PostgresDialect({ pool }) }),
pool
};
}
/** Environmental problems must not fail the check — a hook that fails for reasons
* you can't fix is a hook you learn to bypass. */
function skip(reason: string): never {
console.log(`⚠ Backup compatibility check skipped — ${reason}`);
process.exit(0);
}
/** A missing baseline is NOT environmental — see `resolveBaseline`. */
function fail(message: string): never {
console.error(`✗ ${message}`);
process.exit(1);
}
/**
* How many migrations exist on disk but have not been applied here.
*
* This is the one place this check diverges from `check-datasets.ts`, which uses the
* same count only as a hint when something already failed. Here an unapplied
* migration is a FALSE PASS: the live schema does not yet contain the change being
* committed, so the baseline looks fine. Refusing to give a verdict is the only
* honest option, so a count that cannot be established returns -1 and also refuses.
*/
async function countPendingMigrations(
db: Kysely<KyselyDatabase>
): Promise<number> {
try {
const dir = join(
import.meta.dirname,
"../../../database/supabase/migrations"
);
const onDisk = readdirSync(dir)
.filter((f) => f.endsWith(".sql"))
.map((f) => f.split("_")[0] ?? "");
const applied = await sql<{ version: string }>`
SELECT version FROM supabase_migrations.schema_migrations
`.execute(db);
const seen = new Set(applied.rows.map((r) => r.version));
return onDisk.filter((v) => !seen.has(v)).length;
} catch {
return -1;
}
}
/**
* A manifest describing a schema rather than a backup: every exportable table with
* its column list and no rows.
*
* Which tables and columns those are is `selectExportableTables` /
* `exportableColumns` — the exporter's own rule, not a copy of it. That is the whole
* reason this file can stand in for a customer's backup.
*/
function catalogAsManifest(catalog: Catalog, exportedAt: string): Manifest {
const { exportable, excludedTables } = selectExportableTables(catalog);
return {
kind: BACKUP_KIND,
version: BACKUP_VERSION,
schemaVersion: catalog.schemaVersion,
sourceCompanyId: "schema-baseline",
sourceCompanyGroupId: null,
sourceCompanyName: null,
exportedAt,
exportedBy: "schema-baseline",
label: "schema baseline",
includeStorage: "none",
tables: exportable.map((t) => ({
name: t.name,
rows: 0,
columns: exportableColumns(t).map((c) => c.name)
})),
storage: [],
excludedTables
};
}
/** Print the blocking findings; returns whether any were found. */
function reportBlocking(
label: string,
catalog: Catalog,
manifest: Manifest
): boolean {
const { findings, blocked } = reportBackupCompatibility(catalog, manifest);
if (!blocked) {
console.log(` ✓ ${label}: restorable`);
return false;
}
const blocking = findings.filter((f) => f.kind === "blocked");
console.error(` ✗ ${label}: ${blocking.length} blocking change(s)`);
for (const f of blocking) {
console.error(
` ${f.table}${f.column ? `.${f.column}` : ""} — ${f.reason}`
);
}
return true;
}
// Run from the repo root: a pre-commit hook in a linked worktree exports GIT_DIR
// without GIT_WORK_TREE, so git takes the current directory (packages/jobs) as
// the worktree top and `git add` would stage the file at the wrong path.
function git(args: string[]): string {
// Always from the repo root. A git hook exports GIT_DIR without GIT_WORK_TREE,
// and git then takes the CURRENT directory as the work tree — so `git add` of
// the absolute manifest path, run from packages/jobs by `pnpm --filter`,
// indexed it as a root-level `manifests/schema.json` on every migration commit.
return execFileSync("git", args, {
cwd: REPO_ROOT,
encoding: "utf8",
stdio: ["ignore", "pipe", "pipe"]
}).trim();
}
/** The I/O `resolveBaseline` needs, kept here so the decision itself stays pure. */
const baselineSources = {
remoteUrl: () => {
try {
return git(["remote", "get-url", "origin"]);
} catch {
return null;
}
},
fetchText: async (url: string) => {
const res = await fetch(url, {
signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
});
if (res.status === 404) return null;
if (!res.ok) throw new Error(`HTTP ${res.status}`);
return await res.text();
},
localText: () => {
try {
return git(["show", `origin/${BASELINE_BRANCH}:${SCHEMA_REPO_PATH}`]);
} catch {
return null;
}
}
};
/** Generated output, like a lockfile — announced, never silent. */
function writeSchemaFile(catalog: Catalog): void {
// @internationalized/date, never JS Date (.claude/rules/date-handling.md), and UTC
// rather than the machine's zone — this stamp labels a schema, not a business day.
const manifest = catalogAsManifest(catalog, now("UTC").toAbsoluteString());
mkdirSync(dirname(SCHEMA_FILE), { recursive: true });
writeFileSync(SCHEMA_FILE, `${JSON.stringify(manifest, null, 2)}\n`);
// lint-staged has already run by the time the pre-commit hook stages this file,
// so format it here or it never sees Biome at all.
try {
execFileSync("pnpm", ["exec", "biome", "format", "--write", SCHEMA_FILE], {
stdio: "pipe"
});
} catch {
// Cosmetic only — never block a commit on the formatter.
}
try {
git(["add", SCHEMA_FILE]);
console.log(
`Updated and staged ${SCHEMA_REPO_PATH} (${manifest.tables.length} tables) — the baseline the next migration is checked against.`
);
} catch (err) {
console.warn(
`⚠ Wrote ${SCHEMA_REPO_PATH} but could not stage it — ${
err instanceof Error ? err.message : String(err)
}\n Run: git add ${SCHEMA_REPO_PATH}`
);
}
}
function printUsage() {
console.log(`
Usage: pnpm db:check:backups [-- --stage]
Asks whether the backups customers already hold would still restore against your
current schema, comparing packages/jobs/manifests/schema.json AS IT STANDS ON main
with your live schema. Writes nothing to your database.
Arguments:
--stage On success, regenerate schema.json from your live schema and git-add
it. The pre-commit hook passes this; a manual run stays read-only.
`);
}
async function main(db: Kysely<KyselyDatabase>) {
const { values } = parseArgs({
args: process.argv.slice(2).filter((a) => a !== "--"),
options: {
stage: { type: "boolean", default: false },
help: { type: "boolean", short: "h", default: false }
},
strict: true
});
if (values.help) {
printUsage();
return;
}
// Probed separately from the queries below so a stack that isn't up reads as
// "skipped", not as a failed check the developer is expected to act on.
try {
await sql`SELECT 1`.execute(db);
} catch (err) {
skip(
`no database connection (is your local stack up?)\n ${
err instanceof Error ? err.message : String(err)
}`
);
}
// Meaningless against a stale database: checking gives a false pass, and staging
// records a baseline missing the very change being committed — which then becomes
// what everything after it is judged by.
const pending = await countPendingMigrations(db);
if (pending !== 0) {
skip(
pending < 0
? "the applied-migration list could not be read (is this a Carbon database?)"
: `your database is ${pending} migration(s) behind, so it cannot see the change you are committing.\n Run pnpm db:migrate and try again.`
);
}
const catalog = await getCompanyTableCatalog(db);
const baseline = await resolveBaseline(baselineSources);
for (const warning of baseline.warnings) console.warn(warning);
console.log(`Checking your schema against ${baseline.source}...`);
if (reportBlocking(SCHEMA_REPO_PATH, catalog, baseline.manifest)) {
console.error(
`\nBackups taken against ${baseline.source} would no longer restore.\n${FIX_HINT}\n\n${RERUN_HINT}`
);
// A blocked commit stages nothing: the baseline must keep describing the schema
// that is actually shipped.
process.exitCode = 1;
return;
}
if (values.stage) writeSchemaFile(catalog);
}
const { db, pool } = connect();
main(db)
.catch((err) => {
if (err instanceof BaselineError) fail(err.message);
console.error(err instanceof Error ? err.message : err);
process.exitCode = 1;
})
.finally(async () => {
// Without this the pool keeps the event loop alive and the script never exits.
await db.destroy().catch(() => pool.end());
});