@rebasepro/server-postgres 0.17.3 → 0.18.1

package/dist/schema/doctor.d.ts

@@ -41,6 +41,17 @@ export interface DoctorPhase {
      * a comparison, and no comparison happened.
      */
     notApplicable?: string;
+    /**
+     * The phase was skipped by a fault rather than by a choice.
+     *
+     * `skipped` covers both: "no DATABASE_URL, so nothing to compare against"
+     * is a local situation a developer may be perfectly happy with, and "the
+     * DATABASE_URL you set refuses connections" is not. The report renders them
+     * the same way — a check that did not run is a check that did not run — but
+     * the exit code must not, or `rebase doctor` in CI goes green against a
+     * database it never reached.
+     */
+    blocked?: boolean;
 }
 export interface DoctorReport {
     collectionsToSchema: DoctorPhase;
@@ -64,6 +75,37 @@ export declare function getExpectedColumnType(prop: Property): string | null;
 export declare function loadCollections(collectionsPath: string): Promise<CollectionConfig[]>;
 export declare function checkCollectionsVsSchema(collections: CollectionConfig[], schemaFilePath: string): Promise<DoctorPhase>;
 export declare function checkCollectionsVsSdk(collections: CollectionConfig[], sdkFilePath: string): Promise<DoctorPhase>;
+/**
+ * Extensions the collections need, that the database does not have installed.
+ *
+ * Only `vector` today, and only because a `{ type: "vector" }` property plans a
+ * column of a type that will not exist. Rebase installs it only where a project
+ * has said it may (`database({ extensions: ["vector"] })`), so the absence is
+ * often correct configuration and a wrong deployment — which is exactly why the
+ * report has to name it rather than the first failing INSERT.
+ *
+ * Exported for its test.
+ */
+export declare function missingExtensionIssues(collections: CollectionConfig[], installed: ReadonlySet<string>): DoctorIssue[];
+/**
+ * The stamp the runtime wrote, against the collections on disk.
+ *
+ * A stamp that disagrees means this database was provisioned from a different
+ * set of collections than the ones in this checkout — a colleague's branch, an
+ * older deploy, a tenant somebody else migrated. Everything else in this report
+ * is then describing a schema somebody else created, which is worth knowing
+ * before acting on any of it.
+ *
+ * A warning, not an error, and never a direction: the stamp is a hash, so it
+ * can say the two disagree and never which is ahead. `null` — never stamped —
+ * is not a finding: every database provisioned before the stamp existed reads
+ * that way, and so does every fresh one.
+ */
+export declare function schemaStampIssues(pool: {
+    query<T>(text: string): Promise<{
+        rows: T[];
+    }>;
+}, collections: CollectionConfig[]): Promise<DoctorIssue[]>;
 export declare function checkCollectionsVsDatabase(collections: CollectionConfig[], databaseUrl: string): Promise<DoctorPhase>;
 export declare function renderReport(report: DoctorReport): void;
 export declare function runDoctor(options: {

package/dist/schema/ensure-collection-tables.d.ts

@@ -27,6 +27,7 @@
  */
 import { type CollectionConfig } from "@rebasepro/types";
 import { type SkippedVectorIndex } from "./vector-index.js";
+import { type ColumnTypeDrift } from "./column-type-drift.js";
 /**
  * The subset of a database handle this needs: run a statement, get rows back.
  *
@@ -75,6 +76,15 @@ export interface ExistingSchema {
     enumValues?: Map<string, string[]>;
     /** `schema.table.column` for every column the database marks NOT NULL. */
     notNullColumns?: Set<string>;
+    /**
+     * `schema.table.column` → the column's `udt_name` as the database reports
+     * it (`int4`, `jsonb`, `_numeric` for an array of numeric).
+     *
+     * The only evidence that a column's declared type and its real type have
+     * parted company. Absent is read as "unknown", which reports no drift —
+     * see `column-type-drift.ts` for why silence is the right unknown here.
+     */
+    columnTypes?: Map<string, string>;
     /**
      * Tables known to hold at least one row.
      *
@@ -85,6 +95,14 @@ export interface ExistingSchema {
      * constraint rather than attempting one that aborts the boot.
      */
     populatedTables?: Set<string>;
+    /**
+     * `schema.table.column` for every column the database gives a DEFAULT.
+     *
+     * Paired with {@link notNullColumns} to decide whether a column no property
+     * declares can still accept a write: NOT NULL with a default can, NOT NULL
+     * without one cannot. Absent is read as "unknown", which reports nothing.
+     */
+    columnDefaults?: Set<string>;
 }
 /**
  * How far the planner may go in making the database's constraints match the
@@ -179,6 +197,52 @@ export interface EnsurePlan {
      * to read.
      */
     withheldConstraints: WithheldConstraint[];
+    /**
+     * Columns whose type in the database is in a different family from the one
+     * the collection declares.
+     *
+     * Reported and never acted on — see `column-type-drift.ts`. This is the one
+     * divergence that presents as a *working* deploy: the statement was never
+     * planned, so nothing failed, and the first evidence is a write rejected
+     * hours later by whichever end validates first.
+     */
+    columnTypeDrift: ColumnTypeDrift[];
+    /**
+     * Columns that are NOT NULL, have no default, and that no property declares
+     * any more — so every insert through the API is rejected for a field the
+     * author cannot name, because they already deleted it.
+     *
+     * This is what a **rename** looks like to an additive provisioner. Rename
+     * `title` to `headline` and boot does exactly what it promises: it adds
+     * `headline` (nullable, correctly, and says why) and leaves `title` alone,
+     * because dropping a column is destructive and this runs unattended. The
+     * table is then unwritable:
+     *
+     *     POST /api/data/posts -> 400 PG_23502
+     *     Missing required field: "title" in "posts" cannot be empty.
+     *
+     * naming a field that is no longer in the collection at all. On the default
+     * first-run path there is no way out inside the product either: the managed
+     * database is PGlite, and `db push` — the documented repair — refuses there
+     * because Atlas needs a second database to diff against.
+     *
+     * Reported, never acted on. Dropping the column is the right fix roughly
+     * always and destructive exactly once, which is not a decision to take
+     * unattended.
+     */
+    orphanedRequiredColumns: OrphanedRequiredColumn[];
+}
+/**
+ * A NOT NULL column with no default that no property declares.
+ * @see EnsurePlan.orphanedRequiredColumns
+ */
+export interface OrphanedRequiredColumn {
+    /** `schema.table`. */
+    table: string;
+    /** The column left behind. */
+    column: string;
+    /** The collection that no longer declares it. */
+    slug: string;
 }
 /** A constraint the configuration asks for that the planner is not applying. */
 export interface WithheldConstraint {
@@ -276,3 +340,29 @@ export declare function readSchemaFactsFor(client: Queryable, collections: Colle
  * The error is surfaced with the statement that caused it.
  */
 export declare function ensureCollectionTables(client: Queryable, collections: CollectionConfig[], log?: (message: string) => void, options?: EnsureOptions): Promise<EnsureOutcome>;
+/**
+ * What actually went wrong, rather than what the ORM said about it.
+ *
+ * Drizzle wraps every driver error, and its `message` is literally
+ * ``Failed query: ${sql}\nparams: ${params}`` — the statement we already know,
+ * and not one word of Postgres's answer. Reporting `err.message` therefore
+ * produced a failure that named the statement twice and the *reason* zero
+ * times, so four unrelated boot failures — a missing extension, a wrong
+ * privilege, a bad index method, a constraint the rows violate — all read
+ * identically to whoever had to fix them.
+ *
+ * Two consequences, both observed in the field before this existed:
+ *
+ *  1. On a managed deployment the reason never reaches anybody. Boot dies, the
+ *     pod never goes ready, and the deploy reports a readiness timeout — so the
+ *     one line that says why is the one line that was thrown away here.
+ *  2. {@link vectorExtensionHint} matches on the error text. Against the
+ *     wrapper it matched nothing, so the hint written specifically to explain a
+ *     missing pgvector never fired on the path that raises it.
+ *
+ * `detail` and `hint` come along because they are the fields Postgres uses to
+ * say which object it meant and what to do about it — `CREATE EXTENSION` names
+ * the missing library there, and a rejected constraint names the row. This
+ * writes into the tenant's own boot log, about the tenant's own database.
+ */
+export declare function describeDriverError(err: unknown): string;

package/dist/schema/generate-drizzle-schema.d.ts

@@ -1 +1 @@
-export {};
+export declare const main: () => Promise<void>;

package/dist/schema/generate-drizzle-schema.js

@@ -0,0 +1,24 @@
+import { createRequire as __createRequire } from "module";
+__createRequire(import.meta.url);
+import { t as main } from "../generate-drizzle-schema-CwEgVyjO.js";
+//#region src/schema/bin/generate-drizzle-schema.ts
+/**
+* The built entry point for `generate-drizzle-schema`.
+*
+* `generate-drizzle-schema.ts` guards its own `main()` with
+* `import.meta.url.endsWith(process.argv[1])`, because `src/index.ts` re-exports
+* the module and importing the driver must not run the generator. That guard is
+* correct when the file IS the process entry — which is how it runs from source
+* under tsx — and silently false once the module is bundled: the executed file
+* is a stub, the code lives in a shared chunk, and the chunk's `import.meta.url`
+* is not the stub's path. The generator then did nothing, exited 0, and the
+* caller reported success over an unwritten schema.
+*
+* So the built path gets an entry that says what it means.
+*/
+main().catch(() => {
+	process.exitCode = 1;
+});
+//#endregion
+
+//# sourceMappingURL=generate-drizzle-schema.js.map

package/dist/schema/generate-drizzle-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-drizzle-schema.js","names":[],"sources":["../../src/schema/bin/generate-drizzle-schema.ts"],"sourcesContent":["/**\n * The built entry point for `generate-drizzle-schema`.\n *\n * `generate-drizzle-schema.ts` guards its own `main()` with\n * `import.meta.url.endsWith(process.argv[1])`, because `src/index.ts` re-exports\n * the module and importing the driver must not run the generator. That guard is\n * correct when the file IS the process entry — which is how it runs from source\n * under tsx — and silently false once the module is bundled: the executed file\n * is a stub, the code lives in a shared chunk, and the chunk's `import.meta.url`\n * is not the stub's path. The generator then did nothing, exited 0, and the\n * caller reported success over an unwritten schema.\n *\n * So the built path gets an entry that says what it means.\n */\nimport { main } from \"../generate-drizzle-schema\";\n\nmain().catch(() => {\n    process.exitCode = 1;\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;AAgBA,KAAK,CAAC,CAAC,YAAY;CACf,QAAQ,WAAW;AACvB,CAAC"}

package/dist/schema/generate-next-step.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The line `rebase schema generate` ends on.
+ *
+ * Its own module because `generate-drizzle-schema.ts` uses `import.meta` to
+ * decide whether it was executed directly, which the driver's jest suite cannot
+ * load at all — so the one sentence in that file with a decision in it had no
+ * test and could not have one where it stood.
+ */
+export declare const formatTerminalText: (text: string, options?: {
+    bold?: boolean;
+    backgroundColor?: "blue" | "green" | "red" | "yellow" | "cyan" | "magenta";
+    textColor?: "white" | "black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan";
+}) => string;
+/**
+ * What to do with the file that was just generated.
+ *
+ * Not the same answer on the managed development database: `rebase db generate`
+ * plans with Atlas, Atlas needs a second empty database to diff against, and
+ * PGlite serves exactly one — so the CLI refuses that command outright there.
+ * This line recommended it unconditionally, which meant every stock scaffold
+ * was told, by the tool itself, to run something the same tool would refuse.
+ *
+ * The kind arrives as `REBASE_DEV_DATABASE_KIND`, set by the CLI from the
+ * ordered resolution in `dev-db/resolve.ts`. It is a pure decision — nothing is
+ * started to make it — and the driver cannot make it for itself: on the managed
+ * path `DATABASE_URL` is a perfectly ordinary connection string to a Postgres
+ * on loopback. Absent (the driver run directly, outside the CLI) keeps the
+ * original wording.
+ */
+export declare const nextStepAfterGenerate: () => string;

package/dist/schema/generate-postgres-ddl-logic.d.ts

@@ -9,6 +9,34 @@ export declare const isNumericId: (collection: CollectionConfig) => boolean;
 export declare const getPrimaryKeyName: (collection: CollectionConfig) => string;
 export declare const isIdProperty: (propName: string, prop: Property, collection: CollectionConfig) => boolean;
 type ResolveCollection = (slug: string) => CollectionConfig | undefined;
+/**
+ * The `ON DELETE` a foreign key gets when the author did not say.
+ *
+ * One rule for every property that emits one — `belongsTo` relations and
+ * `reference` properties alike. `reference` kept its own `CASCADE` default for
+ * a release after this rule was written, which is exactly the split this
+ * function exists to prevent: two spellings of the same link, two data-retention
+ * behaviours, and only one of them documented.
+ *
+ * An optional link is `SET NULL`: the column can hold NULL, so dropping the
+ * parent leaves the child row with an empty pointer, which is what "optional"
+ * already means.
+ *
+ * A required link is **`RESTRICT`**, not `CASCADE`. `NOT NULL` says the child
+ * cannot exist without a parent; it does not say deleting the parent should
+ * take the child with it. That second claim is a data-retention decision, and
+ * defaulting to it meant `onDelete` — a field nobody has to write — silently
+ * turned every `DELETE FROM authors` into a cascade through posts, comments and
+ * anything else that hung off them. `RESTRICT` fails the delete instead and
+ * names the constraint, so the author chooses `cascade` on purpose or clears
+ * the children first.
+ *
+ * Both DDL paths — the `CREATE TABLE` generator and {@link planRelationalColumns},
+ * which boot-ensure compares the live database against — call this, so a
+ * default that appears in one and not the other cannot make `db push` plan a
+ * constraint rewrite on every run.
+ */
+export declare const defaultBelongsToOnDelete: (required: boolean | undefined) => "RESTRICT" | "SET NULL";
 /**
  * The individual SQL statements a single security rule compiles to: a
  * `DROP POLICY IF EXISTS` / `CREATE POLICY` pair per operation, each a complete

package/dist/schema/generate-postgres-ddl.d.ts

@@ -1 +1 @@
-export {};
+export declare const main: () => Promise<void>;

package/dist/schema/generate-postgres-ddl.js

@@ -0,0 +1,138 @@
+import { createRequire as __createRequire } from "module";
+__createRequire(import.meta.url);
+import { a as generatePostgresVectorDdl, i as generatePostgresSearchDdl, n as generatePostgresDdl, r as generatePostgresPoliciesDdl } from "../generate-postgres-ddl-logic-CtnpIBVv.js";
+import { n as outError, t as out } from "../cli-output-CNdMql-L.js";
+import { loadCollectionsFromDirectory } from "@rebasepro/server";
+import { declaredDatabaseExtensions } from "@rebasepro/types";
+import * as fs$1 from "fs";
+import { promises } from "fs";
+import path from "path";
+import { pathToFileURL } from "url";
+//#region src/schema/generate-postgres-ddl.ts
+/** Where a project declares its resources, relative to the config directory. */
+var RESOURCE_ENTRIES = [
+	"resources.ts",
+	"resources.js",
+	"resources/index.ts",
+	"resources/index.js"
+];
+/**
+* Evaluate the project's `resources.ts`, so `declaredDatabaseExtensions()` can
+* answer.
+*
+* This generator runs as its own tsx subprocess and loads only the collections
+* directory, so nothing else in it would ever import the resources module — and
+* a permission that reads as absent because nobody loaded it is the worst shape
+* this could take: the push succeeds, `vector.sql` quietly omits the
+* `CREATE EXTENSION`, and the failure lands one statement later looking like a
+* database problem.
+*
+* Imported directly rather than through the config index, for the reason
+* `boot/resource-loading.ts` gives: re-exporting from the index would work only
+* for projects that remember to.
+*
+* A project with no resources module is the normal case and declares nothing.
+* An import that *throws* is not swallowed — a resources module that does not
+* evaluate is a configuration error, and treating it as "declared nothing"
+* would turn it into a silently missing extension.
+*/
+async function loadDeclaredResources(configDir) {
+	const entry = RESOURCE_ENTRIES.map((name) => path.join(configDir, name)).find((candidate) => fs$1.existsSync(candidate));
+	if (!entry) return;
+	await import(pathToFileURL(entry).href);
+}
+var runGeneration = async (collectionsFilePath, outputPath) => {
+	try {
+		if (!collectionsFilePath) throw new Error("No collections file path provided.");
+		const resolvedPath = path.resolve(collectionsFilePath);
+		await loadDeclaredResources(path.dirname(resolvedPath));
+		let collections = await loadCollectionsFromDirectory(resolvedPath);
+		if (!collections || !Array.isArray(collections)) collections = [];
+		collections.sort((a, b) => a.slug.localeCompare(b.slug));
+		const ddlContent = await generatePostgresDdl(collections, {
+			includePolicies: false,
+			includeSearch: false,
+			includeVector: false
+		});
+		const policiesContent = generatePostgresPoliciesDdl(collections);
+		const searchContent = generatePostgresSearchDdl(collections);
+		const vectorContent = generatePostgresVectorDdl(collections, { extensions: declaredDatabaseExtensions() });
+		if (outputPath) {
+			const outputDir = path.dirname(outputPath);
+			await promises.mkdir(outputDir, { recursive: true });
+			await promises.writeFile(outputPath, ddlContent);
+			out(`✅ PostgreSQL DDL generated successfully at ${outputPath}`);
+			const policiesPath = path.join(outputDir, "policies.sql");
+			await promises.writeFile(policiesPath, policiesContent);
+			out(`✅ PostgreSQL Policies DDL generated successfully at ${policiesPath}`);
+			const searchPath = path.join(outputDir, "search.sql");
+			if (searchContent) {
+				await promises.writeFile(searchPath, searchContent);
+				out(`✅ PostgreSQL search DDL generated successfully at ${searchPath}`);
+			} else if (fs$1.existsSync(searchPath)) await promises.rm(searchPath);
+			const vectorPath = path.join(outputDir, "vector.sql");
+			if (vectorContent) {
+				await promises.writeFile(vectorPath, vectorContent);
+				out(`✅ PostgreSQL vector DDL generated successfully at ${vectorPath}`);
+			} else if (fs$1.existsSync(vectorPath)) await promises.rm(vectorPath);
+		} else {
+			out("✅ PostgreSQL DDL generated successfully.");
+			out(String(ddlContent));
+			out("\n✅ PostgreSQL Policies DDL generated successfully.");
+			out(String(policiesContent));
+		}
+	} catch (error) {
+		outError(`Error generating DDL schema: ${error instanceof Error ? error.stack ?? error.message : String(error)}`);
+		process.exitCode = 1;
+		throw error;
+	}
+};
+var main = async () => {
+	const collectionsFilePathArg = process.argv.find((arg) => arg.startsWith("--collections="));
+	const collectionsFilePath = collectionsFilePathArg ? collectionsFilePathArg.split("=")[1] : process.argv[2];
+	const outputPathArg = process.argv.find((arg) => arg.startsWith("--output="));
+	const outputPath = outputPathArg ? outputPathArg.split("=")[1] : void 0;
+	const watch = process.argv.includes("--watch");
+	if (!collectionsFilePath) {
+		out("Usage: ts-node generate-postgres-ddl.ts <path-to-collections-file> [--output <path-to-output-file>] [--watch]");
+		return;
+	}
+	const resolvedPath = path.resolve(process.cwd(), collectionsFilePath);
+	const resolvedOutputPath = outputPath ? path.resolve(process.cwd(), outputPath) : void 0;
+	if (watch) {
+		out(`Watching for changes in ${resolvedPath}...`);
+		const { default: chokidar } = await import("chokidar");
+		chokidar.watch(resolvedPath, {
+			persistent: true,
+			ignoreInitial: false
+		}).on("all", (event, filePath) => {
+			out(`[${event}] ${filePath}. Regenerating DDL schema...`);
+			runGeneration(resolvedPath, resolvedOutputPath).catch(() => void 0);
+		});
+	} else await runGeneration(resolvedPath, resolvedOutputPath);
+};
+if (import.meta.url.endsWith(process.argv[1])) main().catch(() => {
+	process.exitCode = 1;
+});
+//#endregion
+//#region src/schema/bin/generate-postgres-ddl.ts
+/**
+* The built entry point for `generate-postgres-ddl`.
+*
+* `generate-postgres-ddl.ts` guards its own `main()` with
+* `import.meta.url.endsWith(process.argv[1])`, because `src/index.ts` re-exports
+* the module and importing the driver must not run the generator. That guard is
+* correct when the file IS the process entry — which is how it runs from source
+* under tsx — and silently false once the module is bundled: the executed file
+* is a stub, the code lives in a shared chunk, and the chunk's `import.meta.url`
+* is not the stub's path. The generator then did nothing, exited 0, and the
+* caller reported success over an unwritten schema.
+*
+* So the built path gets an entry that says what it means.
+*/
+main().catch(() => {
+	process.exitCode = 1;
+});
+//#endregion
+
+//# sourceMappingURL=generate-postgres-ddl.js.map

package/dist/schema/generate-postgres-ddl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-postgres-ddl.js","names":[],"sources":["../../src/schema/generate-postgres-ddl.ts","../../src/schema/bin/generate-postgres-ddl.ts"],"sourcesContent":["import { promises as fsPromises } from \"fs\";\nimport * as fs from \"fs\";\nimport path from \"path\";\nimport { pathToFileURL } from \"url\";\nimport {\n    generatePostgresDdl,\n    generatePostgresPoliciesDdl,\n    generatePostgresSearchDdl,\n    generatePostgresVectorDdl\n} from \"./generate-postgres-ddl-logic\";\nimport { CollectionConfig, declaredDatabaseExtensions } from \"@rebasepro/types\";\nimport { loadCollectionsFromDirectory } from \"@rebasepro/server\";\nimport { out, outError } from \"../cli-output\";\n\n/** Where a project declares its resources, relative to the config directory. */\nconst RESOURCE_ENTRIES = [\"resources.ts\", \"resources.js\", \"resources/index.ts\", \"resources/index.js\"];\n\n/**\n * Evaluate the project's `resources.ts`, so `declaredDatabaseExtensions()` can\n * answer.\n *\n * This generator runs as its own tsx subprocess and loads only the collections\n * directory, so nothing else in it would ever import the resources module — and\n * a permission that reads as absent because nobody loaded it is the worst shape\n * this could take: the push succeeds, `vector.sql` quietly omits the\n * `CREATE EXTENSION`, and the failure lands one statement later looking like a\n * database problem.\n *\n * Imported directly rather than through the config index, for the reason\n * `boot/resource-loading.ts` gives: re-exporting from the index would work only\n * for projects that remember to.\n *\n * A project with no resources module is the normal case and declares nothing.\n * An import that *throws* is not swallowed — a resources module that does not\n * evaluate is a configuration error, and treating it as \"declared nothing\"\n * would turn it into a silently missing extension.\n */\nasync function loadDeclaredResources(configDir: string): Promise<void> {\n    const entry = RESOURCE_ENTRIES\n        .map(name => path.join(configDir, name))\n        .find(candidate => fs.existsSync(candidate));\n    if (!entry) return;\n    await import(pathToFileURL(entry).href);\n}\n\nconst runGeneration = async (collectionsFilePath?: string, outputPath?: string) => {\n    try {\n        if (!collectionsFilePath) {\n            throw new Error(\"No collections file path provided.\");\n        }\n\n        const resolvedPath = path.resolve(collectionsFilePath);\n\n        // `<config>/collections` is the path this is given, so the config\n        // directory is its parent — the same relationship `rebase resources`\n        // and the boot loader assume.\n        await loadDeclaredResources(path.dirname(resolvedPath));\n\n        // Shared with the runtime and the doctor: what gets generated here must\n        // be exactly what the server serves, including directory-level defaults.\n        let collections: CollectionConfig[] = await loadCollectionsFromDirectory(resolvedPath);\n\n\n        if (!collections || !Array.isArray(collections)) {\n            collections = [];\n        }\n\n        // Sort collections by slug alphabetically to ensure deterministic DDL generation\n        collections.sort((a, b) => a.slug.localeCompare(b.slug));\n\n        // `schema.sql` is Atlas's desired state, and it carries neither the RLS\n        // policies, nor the search apparatus, nor the vector columns: Atlas\n        // manages none of them, and in the search and vector cases cannot. All\n        // three are written beside it and applied by the CLI in their own right.\n        const ddlContent = await generatePostgresDdl(collections, {\n            includePolicies: false,\n            includeSearch: false,\n            includeVector: false\n        });\n        const policiesContent = generatePostgresPoliciesDdl(collections);\n        const searchContent = generatePostgresSearchDdl(collections);\n        const vectorContent = generatePostgresVectorDdl(collections, {\n            extensions: declaredDatabaseExtensions()\n        });\n\n        if (outputPath) {\n            const outputDir = path.dirname(outputPath);\n            await fsPromises.mkdir(outputDir, { recursive: true });\n            await fsPromises.writeFile(outputPath, ddlContent);\n            out(`✅ PostgreSQL DDL generated successfully at ${outputPath}`);\n\n            const policiesPath = path.join(outputDir, \"policies.sql\");\n            await fsPromises.writeFile(policiesPath, policiesContent);\n            out(`✅ PostgreSQL Policies DDL generated successfully at ${policiesPath}`);\n\n            // Removed when the last `search` block goes: the CLI applies this\n            // file whenever it exists, and a stale one would keep re-creating\n            // functions for collections that no longer want them.\n            const searchPath = path.join(outputDir, \"search.sql\");\n            if (searchContent) {\n                await fsPromises.writeFile(searchPath, searchContent);\n                out(`✅ PostgreSQL search DDL generated successfully at ${searchPath}`);\n            } else if (fs.existsSync(searchPath)) {\n                await fsPromises.rm(searchPath);\n            }\n\n            // Removed when the last `vector` property goes, for the same reason\n            // `search.sql` is: the CLI applies whichever of these files exists,\n            // and a stale one would keep re-adding a column the collections no\n            // longer declare — which Atlas, no longer told to exclude it, would\n            // then plan a DROP for on the very next push.\n            const vectorPath = path.join(outputDir, \"vector.sql\");\n            if (vectorContent) {\n                await fsPromises.writeFile(vectorPath, vectorContent);\n                out(`✅ PostgreSQL vector DDL generated successfully at ${vectorPath}`);\n            } else if (fs.existsSync(vectorPath)) {\n                await fsPromises.rm(vectorPath);\n            }\n        } else {\n            out(\"✅ PostgreSQL DDL generated successfully.\");\n            out(String(ddlContent));\n            out(\"\\n✅ PostgreSQL Policies DDL generated successfully.\");\n            out(String(policiesContent));\n        }\n\n    } catch (error) {\n        outError(`Error generating DDL schema: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);\n        // Step 1 of `rebase db push` is this process, and its exit code is the\n        // only thing the push reads. Printing and exiting 0 made a resources\n        // module that does not evaluate — the single most common cause here —\n        // report `✓ rebase db push completed successfully` while Atlas applied\n        // whatever `drizzle/schema.sql` happened to be on disk, sometimes\n        // minutes old. With no prior file the same run died inside Atlas on\n        // `stat drizzle/schema.sql: no such file or directory`, which hides the\n        // real cause two screens up.\n        process.exitCode = 1;\n        throw error;\n    }\n};\n\nexport const main = async () => {\n    const collectionsFilePathArg = process.argv.find(arg => arg.startsWith(\"--collections=\"));\n    const collectionsFilePath = collectionsFilePathArg ? collectionsFilePathArg.split(\"=\")[1] : process.argv[2];\n\n    const outputPathArg = process.argv.find(arg => arg.startsWith(\"--output=\"));\n    const outputPath = outputPathArg ? outputPathArg.split(\"=\")[1] : undefined;\n\n    const watch = process.argv.includes(\"--watch\");\n\n    if (!collectionsFilePath) {\n        out(\"Usage: ts-node generate-postgres-ddl.ts <path-to-collections-file> [--output <path-to-output-file>] [--watch]\");\n        return;\n    }\n\n    const resolvedPath = path.resolve(process.cwd(), collectionsFilePath);\n    const resolvedOutputPath = outputPath ? path.resolve(process.cwd(), outputPath) : undefined;\n\n    if (watch) {\n        out(`Watching for changes in ${resolvedPath}...`);\n        // Imported here rather than at module scope, and this is not a style\n        // choice: chokidar is needed only by `--watch`, which is a\n        // schema-authoring path that never runs inside the runtime image. A\n        // top-level import puts it on the boot path of the published driver\n        // bundle, and the image installs a hand-listed set of runtime\n        // dependencies that does not include it — so the whole driver failed to\n        // load with \"Cannot find package 'chokidar'\", and every self-hosted\n        // container answered 500 with a stack trace about a file watcher.\n        //\n        // Same reasoning the image already applies to @ariga/atlas: an\n        // authoring-only dependency does not belong on a boot path.\n        const { default: chokidar } = await import(\"chokidar\");\n        const watcher = chokidar.watch(resolvedPath, {\n            persistent: true,\n            ignoreInitial: false\n        });\n\n        watcher.on(\"all\", (event, filePath) => {\n            out(`[${event}] ${filePath}. Regenerating DDL schema...`);\n            // A watch session outlives a bad edit: the cause is already on\n            // stderr, and the next save is the retry. Only the one-shot run\n            // below turns a failure into an exit code.\n            void runGeneration(resolvedPath, resolvedOutputPath).catch(() => undefined);\n        });\n    } else {\n        await runGeneration(resolvedPath, resolvedOutputPath);\n    }\n};\n\n// This check ensures the script only runs when executed directly\nif (import.meta.url.endsWith(process.argv[1])) {\n    // `runGeneration` has already printed the cause and set the exit code; the\n    // handler is here so the last thing on the terminal is that message rather\n    // than Node's unhandled-rejection dump of the same stack.\n    main().catch(() => {\n        process.exitCode = 1;\n    });\n}\n","/**\n * The built entry point for `generate-postgres-ddl`.\n *\n * `generate-postgres-ddl.ts` guards its own `main()` with\n * `import.meta.url.endsWith(process.argv[1])`, because `src/index.ts` re-exports\n * the module and importing the driver must not run the generator. That guard is\n * correct when the file IS the process entry — which is how it runs from source\n * under tsx — and silently false once the module is bundled: the executed file\n * is a stub, the code lives in a shared chunk, and the chunk's `import.meta.url`\n * is not the stub's path. The generator then did nothing, exited 0, and the\n * caller reported success over an unwritten schema.\n *\n * So the built path gets an entry that says what it means.\n */\nimport { main } from \"../generate-postgres-ddl\";\n\nmain().catch(() => {\n    process.exitCode = 1;\n});\n"],"mappings":"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"}

package/dist/schema/generated-schema-staleness.d.ts

@@ -56,3 +56,40 @@ export interface MissingGeneratedName {
 export declare function findMissingGeneratedNames(generatedSource: string, collections: CollectionConfig[]): MissingGeneratedName[];
 /** One-line summary for a log or a CLI notice. */
 export declare function describeMissingGeneratedNames(missing: MissingGeneratedName[]): string;
+/** What `rebase schema stale` found, and what that costs. */
+export interface StaleVerdict {
+    /** The lines to print, in order. Empty only under `--fix` with nothing to fix. */
+    lines: string[];
+    /** Non-zero only when the reader must act before the server will boot. */
+    exitCode: 0 | 1;
+    /** True when `--fix` should regenerate. */
+    regenerate: boolean;
+}
+/**
+ * The whole of `schema stale`'s decision, separated from doing it.
+ *
+ * Separated because of what the command used to do on the clean path: **exit 0
+ * having written zero bytes to stdout and zero to stderr.** For a command the
+ * top-level help describes as "Report generated schema files the collections
+ * have moved past", that is indistinguishable from a no-op, a crash, and a
+ * subcommand the driver does not implement. Three of its four paths were
+ * silent, and none of them could be tested where they stood: `cli.ts` uses
+ * `import.meta`, which the driver's jest suite cannot load at all.
+ *
+ * `--fix` is the exception, and stays silent when there is nothing to fix.
+ * `rebase dev` runs `schema stale --fix` before every boot with inherited
+ * stdio, and "nothing was wrong" is not news a hundred lines into a start-up
+ * transcript. The flag is the automated caller's; its silence is the point.
+ */
+export declare function staleVerdict(input: {
+    /** `--output`, as the reader typed it. */
+    outputPath: string;
+    /** Whether the generated schema exists at all. */
+    generatedExists: boolean;
+    /** The legacy foreign-key names found in it, if it was read. */
+    stale: LegacyForeignKeyName[];
+    /** Why the comparison could not be made, when it could not. */
+    unreadable?: string;
+    /** Whether `--fix` was given. */
+    fix: boolean;
+}): StaleVerdict;

package/dist/schema/introspect-db-queries.d.ts

@@ -16,6 +16,40 @@ export interface QueryableClient {
         rows: R[];
     }>;
 }
+/**
+ * A Postgres identifier, quoted so that whatever is inside it stays inside it.
+ *
+ * Introspection reads table and schema names out of `pg_class` and puts them
+ * straight back into SQL, and wrapping a name in double quotes is not the same
+ * as escaping it: a table named `x" ; DROP TABLE users; --` closes the quote
+ * and then the statement. Postgres's own escape for a quote inside a quoted
+ * identifier is to double it, which is what this does.
+ *
+ * "The catalogue is trusted" is true of your own database, and is exactly the
+ * assumption this tool cannot make. Introspection exists to be pointed at
+ * databases somebody else built, and it runs with the privileges of whoever
+ * ran it — which is usually a superuser, because that is who has a connection
+ * string to a database they are adopting.
+ */
+export declare function quoteIdentifier(name: string): string;
+/** `"schema"."table"`, both halves quoted. */
+export declare function quoteRelation(schema: string, table: string): string;
+/**
+ * Can this table's name be the name of the file describing it?
+ *
+ * Introspection writes `<collectionsDir>/<tableName>.ts`, and the table name
+ * came from a database this tool did not create. Postgres will hold a table
+ * called `../../../etc/cron.d/x`, and `path.join` resolves it — so without this
+ * the generator writes a file wherever the name points, as whoever ran the
+ * command.
+ *
+ * Deliberately narrow, and deliberately not a blocklist of `..` and `/`: the
+ * question is "is this a plain file name?", and every answer that is not
+ * obviously yes is a table better written by hand. NUL and the Windows
+ * separator are in scope because a collections directory is checked out on
+ * whatever machine the developer has.
+ */
+export declare function isUsableFileName(name: string): boolean;
 /**
  * Base tables, excluding partitions.
  *