@rebasepro/server-postgres 0.17.3-canary.gdd23447 → 0.18.0

package/src/schema/introspect-db-naming.ts

@@ -1,15 +0,0 @@
-/**
- * Naming helpers shared by the introspection modules. These live apart from
- * `introspect-db-logic.ts` because the inference pass needs them too, and
- * importing them from there would close a cycle back through this module.
- */
-
-/**
- * Convert a snake_case name to a human-readable Title Case label.
- * e.g. "created_at" -> "Created At", "customer_id" -> "Customer Id"
- */
-export function humanize(snakeName: string): string {
-    return snakeName
-        .replace(/_/g, " ")
-        .replace(/\b\w/g, (c) => c.toUpperCase());
-}

package/src/schema/introspect-db-project.ts

@@ -1,78 +0,0 @@
-/**
- * What the project being introspected into can actually import.
- *
- * The generator is pure — `introspect-db-logic.ts` reads no files — so the one
- * question it cannot answer for itself lives here: which `defineCollection`, if
- * any, will resolve from the directory the collections are written to.
- */
-import fs from "fs";
-import path from "path";
-
-import { ADMIN_TYPES_PACKAGE, COMMON_PACKAGE, type CollectionBuilder } from "./introspect-db-logic";
-
-/** How far up to look before giving up, if no project root announces itself. */
-const MAX_LEVELS = 8;
-
-/** Every dependency name a manifest declares, in any of the three fields. */
-function declaredDependencies(manifestPath: string): Set<string> {
-    const names = new Set<string>();
-    let parsed: unknown;
-    try {
-        parsed = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
-    } catch {
-        // A malformed or unreadable package.json is not this function's problem
-        // to report — it answers "can this import resolve", and the answer is no.
-        return names;
-    }
-    if (typeof parsed !== "object" || parsed === null) return names;
-    const manifest = parsed as Record<string, unknown>;
-    for (const field of ["dependencies", "devDependencies", "peerDependencies"]) {
-        const block = manifest[field];
-        if (typeof block === "object" && block !== null) {
-            for (const name of Object.keys(block)) names.add(name);
-        }
-    }
-    return names;
-}
-
-/**
- * Which `defineCollection` to generate against, for collections written to `outDir`.
- *
- * **The detection is the package manifests above the output directory**, unioned from
- * `outDir` up to and including the project root — the first ancestor holding a
- * `rebase.json`, or `MAX_LEVELS` up if there is none.
- *
- * That is the rule Node itself applies: a file in `config/collections` resolves a bare
- * specifier through `config/node_modules`, then `<project>/node_modules`, and so on up.
- * Reading the manifests along that same path answers the only question that matters —
- * *will this import resolve in the project I am writing into* — from the state on disk
- * at the moment of generation. The alternatives are all proxies for it: `rebase.json`'s
- * `apps` block says a CMS scaffold declared an admin app, and a `frontend/` directory
- * says one was scaffolded, but neither is what the compiler consults, and either can be
- * true of a project whose `config` package does not depend on `@rebasepro/cms-types`.
- *
- * Ambiguity resolves towards the admin panel: a project that declares both packages has
- * a panel, and `@rebasepro/cms-types` is the flavour that keeps the `admin` block.
- */
-export function detectCollectionBuilder(outDir: string): CollectionBuilder {
-    let dir = path.resolve(outDir);
-    const declared = new Set<string>();
-
-    for (let level = 0; level < MAX_LEVELS; level++) {
-        const manifest = path.join(dir, "package.json");
-        if (fs.existsSync(manifest)) {
-            for (const name of declaredDependencies(manifest)) declared.add(name);
-        }
-        // The project root, and the last level worth reading: anything above it
-        // belongs to whatever the project happens to be checked out inside.
-        if (fs.existsSync(path.join(dir, "rebase.json"))) break;
-
-        const parent = path.dirname(dir);
-        if (parent === dir) break;
-        dir = parent;
-    }
-
-    if (declared.has(ADMIN_TYPES_PACKAGE)) return "admin-types";
-    if (declared.has(COMMON_PACKAGE)) return "common";
-    return "annotation";
-}

package/src/schema/introspect-db-queries.ts

@@ -1,326 +0,0 @@
-/**
- * The catalog queries introspection runs, and the shape they produce.
- *
- * These live apart from {@link ./introspect-db.ts} (the CLI entry point) on
- * purpose: the fixture-capture script and the live e2e read a database through
- * this module too, so what the tests see is what the CLI sees. A query that
- * only exists inside the CLI's `main()` can only be tested by running the CLI.
- *
- * No side effects beyond `SELECT`. Introspection reads a database it does not
- * own — it must never `ANALYZE`, create a temp table, or otherwise write.
- */
-import type {
-    TableRow,
-    TableColumn,
-    EnumValue,
-    PrimaryKeyRow,
-    ForeignKeyRow,
-    UniqueConstraintRow,
-    CheckConstraintRow,
-    CommentRow,
-    SchemaMetadata
-} from "./introspect-db-logic";
-
-/** The subset of `pg.Client` this module needs, so tests can pass a fake. */
-export interface QueryableClient {
-    query<R = Record<string, unknown>>(text: string, values?: unknown[]): Promise<{ rows: R[] }>;
-}
-
-/**
- * Base tables, excluding partitions.
- *
- * `relispartition` is the reason this reads `pg_class` rather than
- * `information_schema.tables`, which reports every partition as a base table of
- * its own. Pagila partitions `payment` by month; introspected through
- * information_schema it yields `payment` plus 26 near-identical
- * `payment_p2022_*` collections, each with its own nav entry.
- *
- * `relkind = 'p'` (the partitioned parent) is included and `'r'` partitions are
- * dropped, which is the right way round: the parent is the queryable table.
- */
-export const TABLES_QUERY = `
-    SELECT c.relname AS table_name,
-           c.relkind = 'p' AS is_partitioned
-    FROM pg_class c
-    JOIN pg_namespace n ON n.oid = c.relnamespace
-    WHERE n.nspname = $1
-      AND c.relkind IN ('r', 'p')
-      AND NOT c.relispartition
-      AND c.relname NOT LIKE 'drizzle_%'
-      AND c.relname NOT LIKE 'rebase_%'
-    ORDER BY c.relname
-`;
-
-/**
- * Columns, with the catalog facts that say a column is not the user's to edit.
- *
- * `is_generated`/`is_identity` are read for that reason: a generated column
- * rejects any write, so a form that offers it is offering a field that always
- * errors. `character_maximum_length` is the declared `varchar(n)` bound —
- * already enforced by the database, and free to surface as validation.
- */
-export const COLUMNS_QUERY = `
-    SELECT
-        c.table_name,
-        c.column_name,
-        c.data_type,
-        c.udt_name,
-        c.is_nullable,
-        c.column_default,
-        c.ordinal_position,
-        c.is_generated,
-        c.is_identity,
-        c.identity_generation,
-        c.character_maximum_length,
-        c.numeric_precision,
-        c.numeric_scale,
-        (SELECT a.atttypmod FROM pg_attribute a
-         JOIN pg_class pc ON a.attrelid = pc.oid
-         WHERE pc.relname = c.table_name
-           AND a.attname = c.column_name
-           AND pc.relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = c.table_schema)) as atttypmod
-    FROM information_schema.columns c
-    WHERE c.table_schema = $1
-    ORDER BY c.table_name, c.ordinal_position
-`;
-
-export const ENUMS_QUERY = `
-    SELECT t.typname AS enum_name,
-           e.enumlabel AS enum_value,
-           e.enumsortorder AS sort_order
-    FROM pg_type t
-    JOIN pg_enum e ON t.oid = e.enumtypid
-    JOIN pg_namespace n ON t.typnamespace = n.oid
-    WHERE n.nspname = $1
-    ORDER BY t.typname, e.enumsortorder
-`;
-
-/**
- * Primary key columns, in key order.
- *
- * `ORDER BY k.ord` matters for composite keys: the position of a column inside
- * the key is what tells a two-column PK made of two foreign keys apart from an
- * ordinary composite key, and `= ANY(i.indkey)` (the shape this replaced)
- * returns catalog order instead.
- */
-export const PRIMARY_KEYS_QUERY = `
-    SELECT t.relname AS table_name,
-           a.attname AS column_name
-    FROM pg_index i
-    JOIN pg_class t ON t.oid = i.indrelid
-    JOIN pg_namespace n ON n.oid = t.relnamespace
-    CROSS JOIN LATERAL unnest(i.indkey) WITH ORDINALITY AS k(attnum, ord)
-    JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum
-    WHERE i.indisprimary AND n.nspname = $1
-    ORDER BY t.relname, k.ord
-`;
-
-/**
- * Foreign keys, one row per referencing column, with the delete rule.
- *
- * Read from `pg_constraint` rather than through
- * `information_schema.constraint_column_usage`, which does not preserve the
- * pairing on a composite foreign key: it reports the cross product of the
- * constraint's columns, so a two-column FK comes back as four rows, two of them
- * pairing the wrong columns. `unnest(...) WITH ORDINALITY` on both sides joined
- * on the ordinal keeps each referencing column with the column it references.
- *
- * `confdeltype` is carried because `ON DELETE CASCADE` is the schema author
- * saying, in the database, that the child cannot outlive the parent — the one
- * unambiguous declaration of ownership a schema contains.
- *
- * Constraints declared on a *partition* are attributed to the partition root,
- * because that is the table this run generates a collection for. Pagila declares
- * `payment`'s three foreign keys on each monthly partition and none on the
- * parent, so reading `pg_constraint` at face value gives the `payment`
- * collection no relations at all. `pick = 1` then keeps one row per logical key,
- * preferring the root's own constraint when it has one, so a schema that
- * declares the key on the parent *and* inherits it onto 26 partitions does not
- * yield 27 copies of the same relation.
- */
-export const FOREIGN_KEYS_QUERY = `
-    WITH fk AS (
-        SELECT con.oid,
-               con.conname,
-               con.conrelid,
-               con.confrelid,
-               con.conkey,
-               con.confkey,
-               con.confdeltype,
-               COALESCE(pg_partition_root(con.conrelid), con.conrelid) AS root_oid,
-               row_number() OVER (
-                   PARTITION BY COALESCE(pg_partition_root(con.conrelid), con.conrelid),
-                                con.confrelid, con.conkey, con.confkey
-                   ORDER BY (con.conrelid = COALESCE(pg_partition_root(con.conrelid), con.conrelid)) DESC,
-                            con.oid
-               ) AS pick
-        FROM pg_constraint con
-        JOIN pg_namespace n ON n.oid = con.connamespace
-        WHERE con.contype = 'f' AND n.nspname = $1
-    )
-    SELECT root.relname AS table_name,
-           sa.attname AS column_name,
-           tgt.relname AS foreign_table_name,
-           ta.attname AS foreign_column_name,
-           fk.conname AS constraint_name,
-           s.ord::int AS ordinal,
-           CASE fk.confdeltype
-               WHEN 'a' THEN 'NO ACTION'
-               WHEN 'r' THEN 'RESTRICT'
-               WHEN 'c' THEN 'CASCADE'
-               WHEN 'n' THEN 'SET NULL'
-               WHEN 'd' THEN 'SET DEFAULT'
-           END AS delete_rule
-    FROM fk
-    JOIN pg_class root ON root.oid = fk.root_oid
-    JOIN pg_class tgt ON tgt.oid = fk.confrelid
-    CROSS JOIN LATERAL unnest(fk.conkey) WITH ORDINALITY AS s(attnum, ord)
-    JOIN pg_attribute sa ON sa.attrelid = fk.conrelid AND sa.attnum = s.attnum
-    CROSS JOIN LATERAL unnest(fk.confkey) WITH ORDINALITY AS f(attnum, ord)
-    JOIN pg_attribute ta ON ta.attrelid = fk.confrelid AND ta.attnum = f.attnum
-    WHERE fk.pick = 1 AND s.ord = f.ord
-    ORDER BY root.relname, fk.conname, s.ord
-`;
-
-/**
- * Unique constraints and unique indexes, as ordered column lists.
- *
- * Indexes rather than constraints alone, because `CREATE UNIQUE INDEX` and
- * `ADD CONSTRAINT ... UNIQUE` produce the same guarantee and schemas use both.
- * Partial indexes (`indpred IS NOT NULL`) are excluded: they promise uniqueness
- * only over the rows matching their predicate, which is not the promise a
- * `validation: { unique: true }` field makes.
- */
-export const UNIQUE_CONSTRAINTS_QUERY = `
-    SELECT t.relname AS table_name,
-           ic.relname AS constraint_name,
-           -- ::text, because the driver has no parser for an array of \`name\`
-           -- and hands back the raw \`{a,b}\` literal as a string. Every consumer
-           -- here indexes and compares it as an array, and a string of that
-           -- shape fails those silently rather than loudly.
-           array_agg(a.attname::text ORDER BY k.ord) AS column_names
-    FROM pg_index i
-    JOIN pg_class t ON t.oid = i.indrelid
-    JOIN pg_class ic ON ic.oid = i.indexrelid
-    JOIN pg_namespace n ON n.oid = t.relnamespace
-    CROSS JOIN LATERAL unnest(i.indkey) WITH ORDINALITY AS k(attnum, ord)
-    JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum
-    WHERE i.indisunique
-      AND NOT i.indisprimary
-      AND i.indpred IS NULL
-      AND n.nspname = $1
-      AND NOT t.relispartition
-    GROUP BY t.relname, ic.relname
-    ORDER BY t.relname, ic.relname
-`;
-
-/**
- * CHECK constraints, as the source text Postgres reproduces them from.
- *
- * `pg_get_constraintdef` output is normalized by the server — the parser in
- * {@link ./introspect-db-constraints.ts} reads that normalized form, not
- * whatever the author typed.
- */
-export const CHECK_CONSTRAINTS_QUERY = `
-    SELECT DISTINCT
-           root.relname AS table_name,
-           con.conname AS constraint_name,
-           pg_get_constraintdef(con.oid) AS definition
-    FROM pg_constraint con
-    JOIN pg_namespace n ON n.oid = con.connamespace
-    JOIN pg_class root ON root.oid = COALESCE(pg_partition_root(con.conrelid), con.conrelid)
-    WHERE con.contype = 'c'
-      AND n.nspname = $1
-    ORDER BY root.relname, con.conname
-`;
-
-/**
- * `COMMENT ON TABLE` / `COMMENT ON COLUMN`, which is documentation the author
- * already wrote and which nothing downstream has ever read.
- */
-export const COMMENTS_QUERY = `
-    SELECT t.relname AS table_name,
-           a.attname AS column_name,
-           d.description AS comment
-    FROM pg_description d
-    JOIN pg_class t ON t.oid = d.objoid
-    JOIN pg_namespace n ON n.oid = t.relnamespace
-    LEFT JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = d.objsubid
-    WHERE n.nspname = $1
-      AND t.relkind IN ('r', 'p')
-      AND (d.objsubid = 0 OR a.attname IS NOT NULL)
-    ORDER BY t.relname, d.objsubid
-`;
-
-/**
- * Counts a table's rows, stopping once the answer can only be "more than
- * `limit`".
- *
- * Introspection asks this to tell a small reference table from a table that
- * merely looks like one (see `classifyTables`). `reltuples` would answer for
- * free but lies on a table that has never been analyzed — which is every table
- * in a database restored from a dump, i.e. exactly the case introspection meets
- * — and reports -1 there rather than an error, so the lie is silent.
- *
- * The subquery's LIMIT caps the work at `limit + 1` rows however large the
- * table is, so this stays cheap on a table with a billion rows.
- */
-export async function countRowsUpTo(
-    client: QueryableClient,
-    schema: string,
-    table: string,
-    limit: number
-): Promise<number> {
-    const { rows } = await client.query<{ count: string }>(
-        `SELECT count(*)::text AS count FROM (SELECT 1 FROM "${schema}"."${table}" LIMIT ${limit + 1}) probe`
-    );
-    return Number(rows[0]?.count ?? 0);
-}
-
-/**
- * Reads everything the generator needs, in one pass.
- *
- * `rowCounts` is deliberately absent here: it costs a query per table and only
- * a handful of tables can possibly need it. The caller fills it in for the
- * candidates `lookupCandidates()` names.
- */
-export async function readSchemaMetadata(
-    client: QueryableClient,
-    schema: string
-): Promise<SchemaMetadata> {
-    // Sequential, not `Promise.all`. A `pg.Client` is a single connection with
-    // one protocol stream: concurrent `query()` calls on one are queued and
-    // deprecated (removed in pg@9), so the parallel version buys nothing and
-    // warns while doing it.
-    const tables = await client.query<TableRow>(TABLES_QUERY, [schema]);
-    const columns = await client.query<TableColumn>(COLUMNS_QUERY, [schema]);
-    const enumValues = await client.query<EnumValue>(ENUMS_QUERY, [schema]);
-    const pks = await client.query<PrimaryKeyRow>(PRIMARY_KEYS_QUERY, [schema]);
-    const fks = await client.query<ForeignKeyRow>(FOREIGN_KEYS_QUERY, [schema]);
-    const uniques = await client.query<UniqueConstraintRow>(UNIQUE_CONSTRAINTS_QUERY, [schema]);
-    const checks = await client.query<CheckConstraintRow>(CHECK_CONSTRAINTS_QUERY, [schema]);
-    const comments = await client.query<CommentRow>(COMMENTS_QUERY, [schema]);
-
-    // A column list scoped to the schema still names tables this run excludes —
-    // views, partitions, the drizzle bookkeeping tables. Narrow every row set to
-    // the tables actually being introspected so downstream code never has to
-    // ask whether a table it found in `columns` really exists.
-    const known = new Set(tables.rows.map((t) => t.table_name));
-    const scoped = <T extends { table_name: string }>(rows: T[]) => rows.filter((r) => known.has(r.table_name));
-
-    return {
-        schema,
-        tables: tables.rows,
-        columns: scoped(columns.rows),
-        enumValues: enumValues.rows,
-        pks: scoped(pks.rows),
-        // A foreign key pointing *out* of the introspected set (into another
-        // schema, or at a view) cannot be turned into a relation: there is no
-        // collection on the other end to link to.
-        fks: scoped(fks.rows).filter((fk) => known.has(fk.foreign_table_name)),
-        uniques: scoped(uniques.rows),
-        checks: scoped(checks.rows),
-        comments: scoped(comments.rows),
-        rowCounts: {}
-    };
-}