@ultimabase/postgres 0.0.0-stage → 0.1.0

package/dist/read.js

@@ -0,0 +1,227 @@
+// A read as one statement (D-46): every list, the root's and each included
+// `many`, is a jsonb array the database builds, so relations at any depth
+// cost no extra round trip.
+import { sql } from 'kysely';
+import { all, Filters } from './filter.js';
+const empty = sql `cast('[]' as jsonb)`;
+/** PostgreSQL takes at most 100 arguments: 50 pairs per `jsonb_build_object`. */
+function object(pairs) {
+    const chunks = [];
+    for (let at = 0; at < pairs.length; at += 50) {
+        const items = pairs
+            .slice(at, at + 50)
+            .flatMap(([key, item]) => [sql.lit(key), item]);
+        chunks.push(sql `jsonb_build_object(${sql.join(items)})`);
+    }
+    return sql.join(chunks, sql ` || `);
+}
+const flip = (order) => ({
+    ...order,
+    direction: order.direction === 'asc' ? 'desc' : 'asc',
+    ...(order.nulls && { nulls: order.nulls === 'first' ? 'last' : 'first' }),
+});
+/** Whether `null` sorts after every value (D-149). */
+const nullsLast = ({ direction, nulls }) => (nulls ?? (direction === 'asc' ? 'last' : 'first')) === 'last';
+/** A sort key in `ORDER BY`; PostgreSQL's default `null`s are D-94's. */
+export const sorted = (key, { direction, nulls }) => sql `${key} ${sql.raw(direction)}${nulls ? sql.raw(` nulls ${nulls}`) : sql ``}`;
+export class Compiler {
+    filters;
+    catalog;
+    constructor(catalog) {
+        this.catalog = catalog;
+        this.filters = new Filters(catalog);
+    }
+    /** The rows `nested` selects among those `reach` gives, as a jsonb array. */
+    list(model, nested, reach, alias) {
+        const take = nested.take;
+        if (take === 0)
+            return empty;
+        const table = this.catalog.table(model);
+        const backward = take !== undefined && take < 0;
+        const given = nested.orderBy ?? [{ field: 'id', direction: 'asc' }];
+        const order = backward ? given.map(flip) : given;
+        const by = sql.join(order.map((each) => sorted(this.key(table, alias, each), each)));
+        const conditions = [
+            reach.on,
+            this.filters.where(model, alias, nested.where),
+        ];
+        let from = reach.from;
+        if (nested.cursor !== undefined) {
+            this.filters.tables.add(table.name);
+            const cursor = this.filters.alias();
+            const found = this.filters.alias();
+            const keys = order.map((each, at) => sql `${this.key(table, found, each)} as ${sql.id(`k${at}`)}`);
+            const where = this.filters.where(model, found, nested.cursor);
+            from = sql `${from} cross join (select ${sql.join(keys)} from ${sql.id(table.name)} as ${sql.id(found)} where ${where} limit 1) as ${sql.id(cursor)}`;
+            conditions.push(this.keyset(table, alias, cursor, order));
+        }
+        const limit = take === undefined ? sql `` : sql ` limit ${Math.abs(take)}`;
+        const skip = nested.skip ?? 0;
+        const offset = skip === 0 ? sql `` : sql ` offset ${skip}`;
+        const row = this.row(model, alias, nested);
+        const rows = sql `select ${row} as "r", row_number() over (order by ${by}) as "n" from ${from} where ${all(conditions)} order by ${by}${limit}${offset}`;
+        const sequence = backward ? sql `"n" desc` : sql `"n"`;
+        return sql `(select coalesce(jsonb_agg("q"."r" order by ${sequence}), ${empty}) from (${rows}) as "q")`;
+    }
+    /**
+     * The rows at or after the cursor in `order`, `null` where it sorts, as
+     * `memory()` compares: `a ≥ c` is `a > c`, or `a = c` and the next key
+     * decides.
+     */
+    keyset(table, alias, cursor, order) {
+        let result = sql `true`;
+        for (const [at, each] of [...order.entries()].toReversed()) {
+            const a = this.key(table, alias, each);
+            const c = sql.id(cursor, `k${at}`);
+            const beyond = each.direction === 'asc' ? sql `${a} > ${c}` : sql `${a} < ${c}`;
+            const nulls = nullsLast(each)
+                ? sql `(${a} is null and ${c} is not null)`
+                : sql `(${a} is not null and ${c} is null)`;
+            const after = sql `(${beyond} or ${nulls})`;
+            result = sql `(${after} or (${a} is not distinct from ${c} and ${result}))`;
+        }
+        return result;
+    }
+    /**
+     * A sort key: a column, through `one` relations, or a count; a row the
+     * relations do not reach gives `null` (D-134). A relevance is `ts_rank`'s
+     * (D-148).
+     */
+    key(table, alias, order, steps = order.through ?? []) {
+        const [step, ...rest] = steps;
+        if (order.relevance !== undefined) {
+            return sql `ts_rank(${sql.id(alias, '_search')}, ${this.filters.query(order.relevance)})`;
+        }
+        if (step === undefined) {
+            if (order.count === undefined) {
+                return this.filters.column(table, alias, order.field);
+            }
+            return this.count(table, alias, order.field, order.count);
+        }
+        const field = table.fields.get(step.relation);
+        if (field === undefined || field.kind === 'scalar') {
+            throw new Error(`${table.model.name}.${step.relation} is not a relation.`);
+        }
+        const to = this.filters.alias();
+        const reach = this.filters.reach(table, alias, field, to);
+        const where = this.filters.where(field.target, to, step.where);
+        const key = this.key(this.catalog.table(field.target), to, order, rest);
+        return sql `(select ${key} from ${reach.from} where ${reach.on} and ${where} limit 1)`;
+    }
+    /** The rows of a `many` relation of the row that `where` selects. */
+    count(table, alias, name, where) {
+        const field = table.fields.get(name);
+        if (field === undefined || field.kind === 'scalar') {
+            throw new Error(`${table.model.name}.${name} is not a relation.`);
+        }
+        const to = this.filters.alias();
+        const reach = this.filters.reach(table, alias, field, to);
+        const rows = this.filters.where(field.target, to, where);
+        return sql `(select cast(count(*) as integer) from ${reach.from} where ${reach.on} and ${rows})`;
+    }
+    /**
+     * A scalar column, a date in UTC whatever the session's time zone, a
+     * decimal as text, which jsonb would make a number (D-145).
+     */
+    scalar(table, alias, name) {
+        const column = this.filters.column(table, alias, name);
+        const kind = this.catalog.kind(table, name);
+        if (kind === 'decimal')
+            return sql `cast(${column} as text)`;
+        return kind === 'dateTime' ? sql `(${column} at time zone 'UTC')` : column;
+    }
+    /** A row as jsonb: its fields, each `one` as `{ id }`, then its includes. */
+    row(model, alias, nested) {
+        const table = this.catalog.table(model);
+        const pairs = new Map();
+        const fields = nested.fields && new Set(['id', ...nested.fields]);
+        const reads = (name) => fields?.has(name) ?? true;
+        for (const name of ['id', 'createdAt', 'updatedAt'].filter(reads)) {
+            pairs.set(name, this.scalar(table, alias, name));
+        }
+        for (const field of table.model.fields) {
+            if (!reads(field.name))
+                continue;
+            if (field.kind === 'scalar') {
+                pairs.set(field.name, this.scalar(table, alias, field.name));
+            }
+            else if (field.kind === 'one' && field.stored) {
+                const key = this.filters.column(table, alias, field.name);
+                pairs.set(field.name, sql `case when ${key} is null then null else jsonb_build_object('id', ${key}) end`);
+            }
+            else if (field.kind === 'one') {
+                const to = this.filters.alias();
+                const reach = this.filters.reach(table, alias, field, to);
+                pairs.set(field.name, sql `(select jsonb_build_object('id', ${sql.id(to, 'id')}) from ${reach.from} where ${reach.on} limit 1)`);
+            }
+        }
+        for (const [name, inner] of Object.entries(nested.include ?? {})) {
+            const field = table.fields.get(name);
+            if (field === undefined || field.kind === 'scalar')
+                continue;
+            const to = this.filters.alias();
+            const reach = this.filters.reach(table, alias, field, to);
+            if (field.kind === 'many') {
+                pairs.set(name, this.list(field.target, inner, reach, to));
+                continue;
+            }
+            const where = this.filters.where(field.target, to, inner.where);
+            const row = this.row(field.target, to, inner);
+            pairs.set(name, sql `(select ${row} from ${reach.from} where ${reach.on} and ${where} limit 1)`);
+        }
+        const counts = Object.entries(nested.count ?? {}).map(([name, where]) => [name, this.count(table, alias, name, where)]);
+        if (counts.length > 0)
+            pairs.set('_count', object(counts));
+        return object([...pairs]);
+    }
+}
+/**
+ * The `id` of the first row of each `distinct` key in `read`'s order
+ * (D-147), which the read then sorts and pages.
+ */
+function kept(compiler, read, distinct) {
+    const { filters } = compiler;
+    const table = compiler.catalog.table(read.model);
+    const alias = filters.alias();
+    const numbered = filters.alias();
+    filters.tables.add(table.name);
+    const keys = distinct.map((key) => compiler.key(table, alias, key));
+    const order = (read.orderBy ?? [{ field: 'id', direction: 'asc' }]).map((each) => sorted(compiler.key(table, alias, each), each));
+    const where = filters.where(read.model, alias, read.where);
+    const id = filters.column(table, alias, 'id');
+    const rows = sql `select row_number() over (partition by ${sql.join(keys)} order by ${sql.join(order)}) as "n", ${id} as "i" from ${sql.id(table.name)} as ${sql.id(alias)} where ${where}`;
+    return sql `select ${sql.id(numbered, 'i')} from (${rows}) as ${sql.id(numbered)} where ${sql.id(numbered, 'n')} = 1`;
+}
+/**
+ * `read`'s rows as one jsonb array, its root rows taken from `source`, by
+ * default its table, and the tables it reaches besides; a locked read locks
+ * the root rows its `where` selects, in `id` order (D-99, D-133).
+ */
+export function compileRows(catalog, read, source) {
+    const compiler = new Compiler(catalog);
+    const alias = compiler.filters.alias();
+    const name = source ?? sql.id(catalog.table(read.model).name);
+    const as = sql.id(alias);
+    const table = catalog.table(read.model);
+    const id = compiler.filters.column(table, alias, 'id');
+    // In `id` order, so two reads of the same rows wait instead of deadlocking (D-133).
+    let from = read.lock
+        ? sql `(select * from ${name} as ${as} where ${compiler.filters.where(read.model, alias, read.where)} order by ${id} for update) as ${as}`
+        : sql `${name} as ${as}`;
+    if (read.distinct !== undefined) {
+        from = sql `(select * from ${name} as ${as} where ${id} in (${kept(compiler, read, read.distinct)})) as ${as}`;
+    }
+    const rows = compiler.list(read.model, read, { from, on: sql `true` }, alias);
+    return { rows, tables: compiler.filters.tables };
+}
+/** The statement that returns `read`'s rows as one jsonb array, `rows`. */
+export function compileFind(catalog, read) {
+    return sql `select ${compileRows(catalog, read).rows} as "rows"`;
+}
+export function compileCount(catalog, read) {
+    const filters = new Filters(catalog);
+    const alias = filters.alias();
+    const table = catalog.table(read.model);
+    const where = filters.where(read.model, alias, read.where);
+    return sql `select cast(count(*) as integer) as "count" from ${sql.id(table.name)} as ${sql.id(alias)} where ${where}`;
+}

package/dist/scratch.d.ts

@@ -0,0 +1,22 @@
+import type { Kysely } from 'kysely';
+import type { PoolConfig } from 'pg';
+/** A new test schema's name. */
+export declare const scratchName: () => string;
+/**
+ * The connections to `url`, in `schema` when one is given, then in the
+ * schemas of the extensions its tables use (D-141).
+ */
+export declare function connecting(url: string, schema: string | undefined, extensions?: readonly string[]): PoolConfig;
+/**
+ * Creates `schema`, or empties the tables in it, once the connections are
+ * known to use it and nothing else.
+ */
+export declare function emptied(db: Kysely<object>, schema: string): Promise<void>;
+/**
+ * Installs pg_trgm where a migration would, in the first schema of the
+ * url's own `search_path`, and answers that schema (D-141).
+ */
+export declare function trigrams(url: string): Promise<string>;
+/** Drops `schema` and its tables. */
+export declare function dropped(url: string, schema: string): Promise<void>;
+//# sourceMappingURL=scratch.d.ts.map

package/dist/scratch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scratch.d.ts","sourceRoot":"","sources":["../src/scratch.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEpC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,IAAI,CAAA;AAMpC,gCAAgC;AAChC,eAAO,MAAM,WAAW,QAAO,MACqB,CAAA;AAEpD;;;GAGG;AACH,wBAAgB,UAAU,CACzB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,UAAU,GAAE,SAAS,MAAM,EAAO,GAChC,UAAU,CASZ;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAC5B,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,EAClB,MAAM,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAaf;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAoB3D;AAED,qCAAqC;AACrC,wBAAsB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQxE"}

package/dist/scratch.js

@@ -0,0 +1,77 @@
+// A test file's own schema (D-137): the connections' `search_path`, its
+// tables emptied at each start, and dropped after the file's last test.
+import { randomBytes } from 'node:crypto';
+import { sql } from 'kysely';
+import { Client } from 'pg';
+import { parseIntoClientConfig } from 'pg-connection-string';
+import { tables, tablesOf } from './migrations.js';
+import { id } from './plan-parts.js';
+/** A new test schema's name. */
+export const scratchName = () => `ultimabase_test_${randomBytes(4).toString('hex')}`;
+/**
+ * The connections to `url`, in `schema` when one is given, then in the
+ * schemas of the extensions its tables use (D-141).
+ */
+export function connecting(url, schema, extensions = []) {
+    if (schema === undefined)
+        return { connectionString: url };
+    const config = parseIntoClientConfig(url);
+    // After the url's own options: a `search_path` it sets loses.
+    const path = [schema, ...extensions].join(',');
+    const options = [config.options, `-c search_path=${path}`]
+        .filter(Boolean)
+        .join(' ');
+    return { ...config, options };
+}
+/**
+ * Creates `schema`, or empties the tables in it, once the connections are
+ * known to use it and nothing else.
+ */
+export async function emptied(db, schema) {
+    await sql `create schema if not exists ${sql.id(schema)}`.execute(db);
+    const { rows } = await sql `select current_schema() as current`.execute(db);
+    if (rows[0]?.current !== schema) {
+        throw new Error(`The connections did not take ${schema} as their search_path: does a pooler drop their startup options?`);
+    }
+    const names = (await tablesOf(db)).filter((name) => !tables.includes(name));
+    if (names.length === 0)
+        return;
+    await sql.raw(`truncate ${names.map(id).join(', ')} cascade`).execute(db);
+}
+/**
+ * Installs pg_trgm where a migration would, in the first schema of the
+ * url's own `search_path`, and answers that schema (D-141).
+ */
+export async function trigrams(url) {
+    const client = new Client({ connectionString: url });
+    await client.connect();
+    try {
+        await client
+            .query('create extension if not exists pg_trgm')
+            .catch((error) => {
+            // Another test file created it at the same time.
+            const code = Reflect.get(Object(error), 'code');
+            if (code !== '23505' && code !== '42710')
+                throw error;
+        });
+        const { rows } = await client.query(`select n.nspname as schema from pg_extension e join pg_namespace n on n.oid = e.extnamespace where e.extname = 'pg_trgm'`);
+        const [row] = rows;
+        if (row === undefined)
+            throw new Error('pg_trgm is not installed.');
+        return row.schema;
+    }
+    finally {
+        await client.end();
+    }
+}
+/** Drops `schema` and its tables. */
+export async function dropped(url, schema) {
+    const client = new Client({ connectionString: url });
+    await client.connect();
+    try {
+        await client.query(`drop schema if exists ${id(schema)} cascade`);
+    }
+    finally {
+        await client.end();
+    }
+}

package/dist/snapshot.d.ts

@@ -0,0 +1,66 @@
+import type { Catalog } from './names.ts';
+/** `field` is the model's name for it, which messages use. */
+export type Column = {
+    readonly field: string;
+    readonly type: string;
+    readonly nullable: boolean;
+};
+export type ForeignKey = {
+    readonly column: string;
+    readonly table: string;
+    readonly cascade: boolean;
+};
+/** A column among `values`; each element of a list's (D-127). */
+export type Check = {
+    readonly column: string;
+    readonly values: string[];
+    readonly list?: true;
+};
+/**
+ * `model` is the model's name, or `Book.tags` for a join table. Constraints
+ * and indexes are keyed by name, columns in table order.
+ */
+export type TableSnapshot = {
+    readonly model: string;
+    readonly columns: {
+        readonly [name: string]: Column;
+    };
+    readonly primaryKey: {
+        readonly name: string;
+        readonly columns: string[];
+    };
+    readonly uniques: {
+        readonly [name: string]: string[];
+    };
+    readonly checks: {
+        readonly [name: string]: Check;
+    };
+    readonly indexes: {
+        readonly [name: string]: string[];
+    };
+    /** A `contains` index's name → its column (D-141). */
+    readonly trigrams: {
+        readonly [name: string]: string;
+    };
+    readonly foreignKeys: {
+        readonly [name: string]: ForeignKey;
+    };
+    /** The `_search` column, from these columns, and its GIN index (D-148). */
+    readonly search: Search | null;
+};
+export type Search = {
+    readonly index: string;
+    readonly language: string;
+    readonly columns: string[];
+};
+export type Snapshot = {
+    readonly postgres: 1;
+    readonly tables: {
+        readonly [name: string]: TableSnapshot;
+    };
+};
+/** The snapshot of the catalog's tables, join tables last. */
+export declare function snapshotOf(catalog: Catalog): Snapshot;
+/** A snapshot read back from a database or a file, checked. */
+export declare function parseSnapshot(value: unknown): Snapshot;
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAS,MAAM,YAAY,CAAA;AAIhD,8DAA8D;AAC9D,MAAM,MAAM,MAAM,GAAG;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC1B,CAAA;AAED,MAAM,MAAM,UAAU,GAAG;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CACzB,CAAA;AAED,iEAAiE;AACjE,MAAM,MAAM,KAAK,GAAG;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAA;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAA;CACpB,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAA;IACrD,QAAQ,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAA;IAC1E,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;KAAE,CAAA;IACvD,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,CAAA;KAAE,CAAA;IACnD,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;KAAE,CAAA;IACvD,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAA;IACtD,QAAQ,CAAC,WAAW,EAAE;QAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,CAAA;KAAE,CAAA;IAC7D,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B,CAAA;AAED,MAAM,MAAM,MAAM,GAAG;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAC1B,CAAA;AAED,MAAM,MAAM,QAAQ,GAAG;IACtB,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CAAA;KAAE,CAAA;CAC3D,CAAA;AA8HD,8DAA8D;AAC9D,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ,CAkFrD;AAsHD,+DAA+D;AAC/D,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAMtD"}

package/dist/snapshot.js

@@ -0,0 +1,272 @@
+import { constraint } from './names.js';
+import { Refused } from 'ultimabase';
+const types = {
+    string: 'text collate "C"',
+    number: 'double precision',
+    decimal: 'numeric',
+    boolean: 'boolean',
+    dateTime: 'timestamptz',
+    date: 'date',
+    json: 'jsonb',
+    enum: 'text collate "C"',
+};
+/** A list's column: an enum's is text, as its single values (D-98, D-127). */
+const lists = {
+    string: 'text[]',
+    number: 'double precision[]',
+    enum: 'text[]',
+};
+/** Refuses two things stored under one name (D-98). */
+function claimer() {
+    const owners = new Map();
+    return (name, what) => {
+        const prior = owners.get(name);
+        if (prior !== undefined) {
+            throw new Refused(`${prior} and ${what} are both stored as "${name}".`);
+        }
+        owners.set(name, what);
+        return name;
+    };
+}
+function empty(claims, model, table, keys) {
+    const name = claims.schema(constraint(`${table}_pkey`), `the key of ${model}`);
+    return {
+        model,
+        columns: {},
+        primaryKey: { name, columns: keys },
+        uniques: {},
+        checks: {},
+        indexes: {},
+        trigrams: {},
+        foreignKeys: {},
+        search: null,
+    };
+}
+function index(claims, building, table, columns, what) {
+    const name = constraint(`${table}_${columns.join('_')}_idx`);
+    building.indexes[claims.schema(name, `the index on ${what}`)] = columns;
+}
+function field(catalog, claims, table, building, given) {
+    if (given.kind === 'many' || (given.kind === 'one' && !given.stored))
+        return;
+    const what = `${table.model.name}.${given.name}`;
+    const column = claims.columns(catalog.column(table, given.name), what);
+    const type = given.kind === 'one'
+        ? 'uuid'
+        : given.integer === true
+            ? `integer${given.list ? '[]' : ''}`
+            : given.type === 'decimal'
+                ? `numeric(${given.precision},${given.scale})`
+                : ((given.list ? lists[given.type] : undefined) ?? types[given.type]);
+    building.columns[column] = {
+        field: given.name,
+        type,
+        nullable: given.optional,
+    };
+    if (given.kind === 'scalar' && given.type === 'enum') {
+        const name = constraint(`${table.name}_${column}_check`);
+        building.checks[claims.schema(name, `the check on ${what}`)] = {
+            column,
+            values: [...(given.values ?? [])],
+            ...(given.list ? { list: true } : {}),
+        };
+    }
+    if (given.kind !== 'one')
+        return;
+    const key = constraint(`${table.name}_${column}_fkey`);
+    building.foreignKeys[claims.schema(key, `the foreign key of ${what}`)] = {
+        column,
+        table: catalog.table(given.target).name,
+        cascade: false,
+    };
+    if (!given.unique)
+        index(claims, building, table.name, [column], what);
+}
+/** The fields of a key or an index, as `Thing(a, b)`. */
+const on = (model, fields) => `${model}(${fields.join(', ')})`;
+/** The snapshot of the catalog's tables, join tables last. */
+export function snapshotOf(catalog) {
+    const tables = {};
+    const schema = claimer();
+    for (const table of catalog.tables.values()) {
+        const model = table.model.name;
+        const claims = { schema, columns: claimer() };
+        schema(table.name, `the table of ${model}`);
+        const building = empty(claims, model, table.name, ['id']);
+        for (const [column, name, type] of [
+            ['id', 'id', 'uuid'],
+            ['created_at', 'createdAt', 'timestamptz'],
+            ['updated_at', 'updatedAt', 'timestamptz'],
+        ]) {
+            claims.columns(column, `${model}.${name}`);
+            building.columns[column] = { field: name, type, nullable: false };
+        }
+        for (const given of table.model.fields) {
+            field(catalog, claims, table, building, given);
+        }
+        const [, ...uniques] = table.uniques;
+        for (const { name, fields } of uniques) {
+            const what = `the unique key on ${on(model, fields)}`;
+            building.uniques[schema(name, what)] = fields.map((given) => catalog.column(table, given));
+        }
+        for (const { fields, unique, contains } of table.model.indexes) {
+            if (unique)
+                continue;
+            if (contains) {
+                const [column = ''] = fields.map((name) => catalog.column(table, name));
+                const name = constraint(`${table.name}_${column}_trgm`);
+                const what = `the contains index on ${on(model, fields)}`;
+                building.trigrams[schema(name, what)] = column;
+                continue;
+            }
+            const columns = fields.map((name) => catalog.column(table, name));
+            index(claims, building, table.name, columns, on(model, fields));
+        }
+        const searched = table.model.fields.flatMap((given) => given.kind === 'scalar' && given.search === true
+            ? [catalog.column(table, given.name)]
+            : []);
+        if (searched.length > 0) {
+            claims.columns('_search', `the search of ${model}`);
+            const name = constraint(`${table.name}__search_idx`);
+            building.search = {
+                index: schema(name, `the search index of ${model}`),
+                language: catalog.language,
+                columns: searched,
+            };
+        }
+        tables[table.name] = building;
+    }
+    for (const [side, join] of catalog.joins) {
+        // Both sides of a relation share its table.
+        if (side !== join.relation)
+            continue;
+        const claims = { schema, columns: claimer() };
+        schema(join.table, `the join table of ${side}`);
+        const building = empty(claims, side, join.table, [join.self, join.other]);
+        for (const column of [join.self, join.other]) {
+            building.columns[column] = {
+                field: column,
+                type: 'uuid',
+                nullable: false,
+            };
+        }
+        for (const [column, table] of [
+            [join.self, join.owner],
+            [join.other, join.target],
+        ]) {
+            const key = constraint(`${join.table}_${column}_fkey`);
+            building.foreignKeys[schema(key, `the foreign key of ${side}`)] = {
+                column,
+                table,
+                cascade: true,
+            };
+        }
+        index(claims, building, join.table, [join.other], side);
+        tables[join.table] = building;
+    }
+    return { postgres: 1, tables };
+}
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isStrings = (value) => Array.isArray(value) && value.every((item) => typeof item === 'string');
+/** Each entry of a record, checked by `read`, or `undefined`. */
+function entries(value, read) {
+    if (!isRecord(value))
+        return undefined;
+    const result = {};
+    for (const [key, item] of Object.entries(value)) {
+        const checked = read(item);
+        if (checked === undefined)
+            return undefined;
+        result[key] = checked;
+    }
+    return result;
+}
+const columnOf = (value) => isRecord(value) &&
+    typeof value['field'] === 'string' &&
+    typeof value['type'] === 'string' &&
+    typeof value['nullable'] === 'boolean'
+    ? {
+        field: value['field'],
+        type: value['type'],
+        nullable: value['nullable'],
+    }
+    : undefined;
+const checkOf = (value) => isRecord(value) &&
+    typeof value['column'] === 'string' &&
+    isStrings(value['values'])
+    ? {
+        column: value['column'],
+        values: value['values'],
+        ...(value['list'] === true ? { list: true } : {}),
+    }
+    : undefined;
+const foreignKeyOf = (value) => isRecord(value) &&
+    typeof value['column'] === 'string' &&
+    typeof value['table'] === 'string' &&
+    typeof value['cascade'] === 'boolean'
+    ? {
+        column: value['column'],
+        table: value['table'],
+        cascade: value['cascade'],
+    }
+    : undefined;
+const stringsOf = (value) => isStrings(value) ? value : undefined;
+/** A search, `null` for none, or `undefined` when it is neither. */
+const searchOf = (value) => value === null
+    ? null
+    : isRecord(value) &&
+        typeof value['index'] === 'string' &&
+        typeof value['language'] === 'string' &&
+        isStrings(value['columns'])
+        ? {
+            index: value['index'],
+            language: value['language'],
+            columns: value['columns'],
+        }
+        : undefined;
+function tableOf(value) {
+    if (!isRecord(value))
+        return undefined;
+    const key = value['primaryKey'];
+    const columns = entries(value['columns'], columnOf);
+    const uniques = entries(value['uniques'], stringsOf);
+    const checks = entries(value['checks'], checkOf);
+    const indexes = entries(value['indexes'], stringsOf);
+    const trigrams = entries(value['trigrams'], (item) => typeof item === 'string' ? item : undefined);
+    const foreignKeys = entries(value['foreignKeys'], foreignKeyOf);
+    const search = searchOf(value['search']);
+    const model = value['model'];
+    if (typeof model !== 'string' ||
+        !isRecord(key) ||
+        typeof key['name'] !== 'string' ||
+        !isStrings(key['columns']) ||
+        columns === undefined ||
+        uniques === undefined ||
+        checks === undefined ||
+        indexes === undefined ||
+        trigrams === undefined ||
+        foreignKeys === undefined ||
+        search === undefined) {
+        return undefined;
+    }
+    const primaryKey = { name: key['name'], columns: key['columns'] };
+    return {
+        model,
+        columns,
+        primaryKey,
+        uniques,
+        checks,
+        indexes,
+        trigrams,
+        foreignKeys,
+        search,
+    };
+}
+/** A snapshot read back from a database or a file, checked. */
+export function parseSnapshot(value) {
+    const tables = isRecord(value) ? entries(value['tables'], tableOf) : undefined;
+    if (!isRecord(value) || value['postgres'] !== 1 || tables === undefined) {
+        throw new Error('The schema snapshot is not one postgres() wrote.');
+    }
+    return { postgres: 1, tables };
+}