@rebasepro/server-postgres 0.17.3 → 0.18.0

package/src/schema/generate-postgres-ddl.ts

@@ -1,180 +0,0 @@
-import { promises as fsPromises } from "fs";
-import * as fs from "fs";
-import path from "path";
-import { pathToFileURL } from "url";
-import {
-    generatePostgresDdl,
-    generatePostgresPoliciesDdl,
-    generatePostgresSearchDdl,
-    generatePostgresVectorDdl
-} from "./generate-postgres-ddl-logic";
-import { CollectionConfig, declaredDatabaseExtensions } from "@rebasepro/types";
-import { loadCollectionsFromDirectory } from "@rebasepro/server";
-import { out, outError } from "../cli-output";
-
-/** Where a project declares its resources, relative to the config directory. */
-const 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: string): Promise<void> {
-    const entry = RESOURCE_ENTRIES
-        .map(name => path.join(configDir, name))
-        .find(candidate => fs.existsSync(candidate));
-    if (!entry) return;
-    await import(pathToFileURL(entry).href);
-}
-
-const runGeneration = async (collectionsFilePath?: string, outputPath?: string) => {
-    try {
-        if (!collectionsFilePath) {
-            outError("Error: No collections file path provided. Skipping schema generation.");
-            return;
-        }
-
-        const resolvedPath = path.resolve(collectionsFilePath);
-
-        // `<config>/collections` is the path this is given, so the config
-        // directory is its parent — the same relationship `rebase resources`
-        // and the boot loader assume.
-        await loadDeclaredResources(path.dirname(resolvedPath));
-
-        // Shared with the runtime and the doctor: what gets generated here must
-        // be exactly what the server serves, including directory-level defaults.
-        let collections: CollectionConfig[] = await loadCollectionsFromDirectory(resolvedPath);
-
-
-        if (!collections || !Array.isArray(collections)) {
-            collections = [];
-        }
-
-        // Sort collections by slug alphabetically to ensure deterministic DDL generation
-        collections.sort((a, b) => a.slug.localeCompare(b.slug));
-
-        // `schema.sql` is Atlas's desired state, and it carries neither the RLS
-        // policies, nor the search apparatus, nor the vector columns: Atlas
-        // manages none of them, and in the search and vector cases cannot. All
-        // three are written beside it and applied by the CLI in their own right.
-        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 fsPromises.mkdir(outputDir, { recursive: true });
-            await fsPromises.writeFile(outputPath, ddlContent);
-            out(`✅ PostgreSQL DDL generated successfully at ${outputPath}`);
-
-            const policiesPath = path.join(outputDir, "policies.sql");
-            await fsPromises.writeFile(policiesPath, policiesContent);
-            out(`✅ PostgreSQL Policies DDL generated successfully at ${policiesPath}`);
-
-            // Removed when the last `search` block goes: the CLI applies this
-            // file whenever it exists, and a stale one would keep re-creating
-            // functions for collections that no longer want them.
-            const searchPath = path.join(outputDir, "search.sql");
-            if (searchContent) {
-                await fsPromises.writeFile(searchPath, searchContent);
-                out(`✅ PostgreSQL search DDL generated successfully at ${searchPath}`);
-            } else if (fs.existsSync(searchPath)) {
-                await fsPromises.rm(searchPath);
-            }
-
-            // Removed when the last `vector` property goes, for the same reason
-            // `search.sql` is: the CLI applies whichever of these files exists,
-            // and a stale one would keep re-adding a column the collections no
-            // longer declare — which Atlas, no longer told to exclude it, would
-            // then plan a DROP for on the very next push.
-            const vectorPath = path.join(outputDir, "vector.sql");
-            if (vectorContent) {
-                await fsPromises.writeFile(vectorPath, vectorContent);
-                out(`✅ PostgreSQL vector DDL generated successfully at ${vectorPath}`);
-            } else if (fs.existsSync(vectorPath)) {
-                await fsPromises.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)}`);
-    }
-};
-
-const 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] : undefined;
-
-    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) : undefined;
-
-    if (watch) {
-        out(`Watching for changes in ${resolvedPath}...`);
-        // Imported here rather than at module scope, and this is not a style
-        // choice: chokidar is needed only by `--watch`, which is a
-        // schema-authoring path that never runs inside the runtime image. A
-        // top-level import puts it on the boot path of the published driver
-        // bundle, and the image installs a hand-listed set of runtime
-        // dependencies that does not include it — so the whole driver failed to
-        // load with "Cannot find package 'chokidar'", and every self-hosted
-        // container answered 500 with a stack trace about a file watcher.
-        //
-        // Same reasoning the image already applies to @ariga/atlas: an
-        // authoring-only dependency does not belong on a boot path.
-        const { default: chokidar } = await import("chokidar");
-        const watcher = chokidar.watch(resolvedPath, {
-            persistent: true,
-            ignoreInitial: false
-        });
-
-        watcher.on("all", (event, filePath) => {
-            out(`[${event}] ${filePath}. Regenerating DDL schema...`);
-            runGeneration(resolvedPath, resolvedOutputPath);
-        });
-    } else {
-        runGeneration(resolvedPath, resolvedOutputPath);
-    }
-};
-
-// This check ensures the script only runs when executed directly
-if (import.meta.url.endsWith(process.argv[1])) {
-    main();
-}

package/src/schema/generate-schema-commit.ts

@@ -1,267 +0,0 @@
-/**
- * Everything a schema change has to write, as file contents.
- *
- * A live schema editor that only edits the collection source produces a repo
- * that does not build: `backend/src/schema.generated.ts` is a committed
- * artifact, and a stale one has broken every deploy at least once. So the unit
- * of a schema change is not a file, it is a **commit** — and this module
- * produces one, without touching a disk, a database or a network.
- *
- * Pure on purpose. The risky half of "commit, then apply" is generating a
- * correct commit; keeping it a function from collections to file contents is
- * what lets that half be tested by building a database from the result and
- * comparing it to the one the change describes.
- *
- * ## Where the migration comes from, and why not from Atlas
- *
- * `rebase db generate` mints migrations by running Atlas over the generated
- * `schema.sql`. Atlas is an external binary, it wants a dev database, and it
- * maintains an `atlas.sum` integrity file whose hash this module would have to
- * reproduce byte-for-byte to stay valid.
- *
- * None of that is necessary here, because of what the editor is allowed to do.
- * `classify-change.ts` refuses anything the boot-time ensure path cannot
- * express, which leaves only additive statements — and those are computable as
- * a plain difference between two ensure plans:
- *
- *     plan(after, nothing) − plan(before, nothing)
- *
- * Both plans are pure functions of the collections, every statement is
- * idempotent, and the difference is exactly what the change adds. No diff
- * engine, no database, no binary.
- *
- * The statements are *returned* rather than written into a migration file. A
- * project provisioned by boot-ensure needs no migration at all — its
- * collections are the schema — while a project provisioned by migrations needs
- * the file to carry an Atlas hash, which only Atlas can mint. Writing a
- * migration this module cannot make valid would be worse than handing the
- * statements to a caller who knows which kind of project it is.
- */
-import {
-    DEFAULT_COMMIT_PATHS,
-    declaredDatabaseExtensions,
-    type CollectionConfig,
-    type SchemaCommitPaths
-} from "@rebasepro/types";
-import {
-    generatePostgresDdl,
-    generatePostgresPoliciesDdl,
-    generatePostgresSearchDdl,
-    generatePostgresVectorDdl
-} from "./generate-postgres-ddl-logic";
-import { generateSchema } from "./generate-drizzle-schema-logic";
-import {
-    planCollectionSchemaEnsure,
-    type EnsureOptions,
-    type ExistingSchema,
-    type WithheldConstraint
-} from "./ensure-collection-tables";
-import { classifyCollectionChanges, type ClassifiedChanges } from "./classify-change";
-
-/**
- * Re-exported from the shared kernel. `@rebasepro/server` derives these for a
- * project in a subdirectory and cannot import a driver to do it, so the shape
- * and the defaults live in `@rebasepro/types`.
- */
-export { DEFAULT_COMMIT_PATHS, type SchemaCommitPaths } from "@rebasepro/types";
-
-export interface SchemaCommitFile {
-    path: string;
-    contents: string;
-}
-
-export interface SchemaCommitInput {
-    /** What the running database was built from. */
-    before: CollectionConfig[];
-    /** What the editor is proposing. */
-    after: CollectionConfig[];
-    /**
-     * Files the caller has already produced — in practice the rewritten
-     * collection source from the AST editor. Carried through unchanged so the
-     * commit is complete in one object.
-     */
-    sourceFiles?: SchemaCommitFile[];
-    paths?: Partial<SchemaCommitPaths>;
-    /**
-     * What the database this change is destined for actually has.
-     *
-     * Supplied by the live editor, which read it a moment ago; omitted by the
-     * pure callers, which have no database. It decides two things a plan cannot
-     * know from the collections alone — whether a table holds rows, and which
-     * values an enum type already carries — and both are the difference between
-     * a statement that applies and one that is rejected.
-     */
-    existing?: ExistingSchema;
-}
-
-export interface SchemaCommit {
-    /** Every file the commit writes, source and generated alike. */
-    files: SchemaCommitFile[];
-    /**
-     * The additive statements this change adds, in dependency order.
-     *
-     * Empty when the change needs no DDL. Not written to a migration file —
-     * see the module comment.
-     */
-    statements: string[];
-    classified: ClassifiedChanges;
-    /** A commit message describing the change in the terms a reader wants. */
-    message: string;
-    /**
-     * Constraints this change asks for that the statements do not carry, and
-     * why. Empty for almost every change; when it is not, it is the thing the
-     * person confirming needs to read before they confirm.
-     */
-    withheldConstraints: WithheldConstraint[];
-}
-
-export class SchemaCommitError extends Error {
-    constructor(message: string, readonly classified: ClassifiedChanges) {
-        super(message);
-        this.name = "SchemaCommitError";
-    }
-}
-
-/** An `ExistingSchema` describing a database that has nothing in it. */
-const nothing = () => ({ tables: new Map<string, Set<string>>(), enums: new Set<string>() });
-
-/**
- * The statements that take `before` to `after`.
- *
- * Both sides are planned against the *same* database and the difference is
- * taken by exact statement text. That works because the planner is
- * deterministic: the same collections against the same schema produce the same
- * strings, so anything in the second plan and absent from the first is what
- * this change adds — and nothing else. Planning both sides is what keeps
- * pre-existing drift, which belongs to neither side of the edit, out of the
- * statements this change gets credited with.
- *
- * ## Why `existing` matters more than it looks
- *
- * Planned against `nothing()`, every table reads as one this plan is creating,
- * and the planner is then free to attach constraints that only hold on a table
- * with no rows: a new required property comes out as
- * `ADD COLUMN "x" TEXT NOT NULL`, which is right for a fresh table and fails
- * against a live one holding rows. Those statements would be generated,
- * committed, and then rejected by the very database they were written for.
- *
- * So a caller holding a real database passes it, and gets statements that
- * describe that database. `nothing()` stays the default for the pure uses —
- * generating a commit for inspection, and the tests that compare two plans —
- * where there is no database to describe.
- */
-export function additiveStatements(
-    before: CollectionConfig[],
-    after: CollectionConfig[],
-    existing: ExistingSchema = nothing(),
-    options: EnsureOptions = {}
-): string[] {
-    const previous = new Set(planCollectionSchemaEnsure(before, existing, options).statements);
-    return planCollectionSchemaEnsure(after, existing, options).statements
-        .filter(statement => !previous.has(statement));
-}
-
-/** A commit message that says what changed rather than that something did. */
-export function commitMessage(classified: ClassifiedChanges): string {
-    const { changes } = classified;
-    if (changes.length === 0) return "chore(schema): no change";
-
-    const collections = [...new Set(changes.map(change => change.collection))].sort();
-    const added = changes.filter(c => c.kind === "add-collection").map(c => c.collection);
-    const properties = changes.filter(c => c.kind === "add-property");
-
-    let subject: string;
-    if (added.length === 1 && changes.length === 1) {
-        subject = `add the ${added[0]} collection`;
-    } else if (properties.length === 1 && changes.length === 1) {
-        subject = `add ${properties[0].property} to ${properties[0].collection}`;
-    } else if (collections.length === 1) {
-        subject = `${changes.length} change(s) to ${collections[0]}`;
-    } else {
-        subject = `${changes.length} change(s) across ${collections.length} collections`;
-    }
-
-    const body = changes.map(change => `- ${change.detail}`).join("\n");
-    return `feat(schema): ${subject}\n\n${body}\n`;
-}
-
-/**
- * Build the commit.
- *
- * Refuses when the change is not applicable — a commit describing a schema the
- * ensure path will not produce is a commit that makes the repository lie about
- * the database. The classification travels on the error so a caller can show
- * exactly which change was the problem.
- */
-export async function generateSchemaCommit(input: SchemaCommitInput): Promise<SchemaCommit> {
-    const paths = { ...DEFAULT_COMMIT_PATHS, ...input.paths };
-    const existing = input.existing ?? nothing();
-    // `converge` because every statement this produces is shown to somebody
-    // before it runs. See `ConstraintPolicy` for why the unattended boot does
-    // not get the same latitude.
-    const options: EnsureOptions = { constraints: "converge" };
-    const classified = classifyCollectionChanges(input.before, input.after, input.existing);
-
-    if (!classified.applicable) {
-        const blocking = classified.changes.filter(change => change.verdict !== "safe");
-        throw new SchemaCommitError(
-            `This change cannot be applied to a running database:\n` +
-            blocking.map(change =>
-                `  • ${change.detail}${change.remedy ? `\n    ${change.remedy}` : ""}`
-            ).join("\n"),
-            classified
-        );
-    }
-
-    // The same split `rebase db generate` writes, and it has to be the same:
-    // these files land in the repository, and the next `db push` runs Atlas
-    // against `schema.sql`. Generated whole, it carries the RLS policies (which
-    // Atlas would then own and drop), the search helpers (which its free tier
-    // refuses to parse at all) and `VECTOR(n)` (which its dev database cannot
-    // resolve) — so a live schema edit used to leave behind a desired-state
-    // file that `db push` chokes on.
-    const [schema, ddl, policies, search, vector] = await Promise.all([
-        generateSchema(input.after),
-        generatePostgresDdl(input.after, {
-            includePolicies: false,
-            includeSearch: false,
-            includeVector: false
-        }),
-        Promise.resolve(generatePostgresPoliciesDdl(input.after)),
-        Promise.resolve(generatePostgresSearchDdl(input.after)),
-        // The registry, because this runs inside the booted server, which has
-        // already evaluated the project's `resources.ts`. A commit that wrote a
-        // `vector.sql` disagreeing with the one `rebase db generate` produces
-        // would show up as drift in the repository the moment anyone regenerated.
-        Promise.resolve(generatePostgresVectorDdl(input.after, {
-            extensions: declaredDatabaseExtensions()
-        }))
-    ]);
-
-    const generated: SchemaCommitFile[] = [
-        { path: paths.schemaFile, contents: schema },
-        { path: paths.ddlFile, contents: ddl },
-        { path: paths.policiesFile, contents: policies },
-        { path: paths.searchFile, contents: search },
-        { path: paths.vectorFile, contents: vector }
-    ];
-
-    // Both sides planned once, here, rather than through `additiveStatements` —
-    // which would plan `after` a second time for the withheld constraints. The
-    // planner is pure, so a second call is only wasted work rather than a
-    // correctness problem, but this runs on every `/plan` keystroke in the panel.
-    const previous = planCollectionSchemaEnsure(input.before, existing, options);
-    const next = planCollectionSchemaEnsure(input.after, existing, options);
-    const already = new Set(previous.statements);
-
-    return {
-        files: [...(input.sourceFiles ?? []), ...generated],
-        statements: next.statements.filter(statement => !already.has(statement)),
-        classified,
-        message: commitMessage(classified),
-        // From the `after` plan alone rather than differenced against `before`:
-        // a constraint that was already unenforceable is still something the
-        // person confirming this change should see named.
-        withheldConstraints: next.withheldConstraints
-    };
-}