@ultimabase/postgres 0.0.0-stage → 0.1.0

package/dist/parts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parts.d.ts","sourceRoot":"","sources":["../src/parts.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,YAAY,CAAA;AACrC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,aAAa,CAAA;AAEtC,OAAO,KAAK,EAAE,OAAO,EAAQ,MAAM,YAAY,CAAA;AAC/C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAKxC,gDAAgD;AAChD,wBAAgB,MAAM,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM,CAGzC;AAED,sEAAsE;AACtE,MAAM,MAAM,IAAI,GAAG;IAClB,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,GAAG,GAAG,SAAS,KAAK,GAAG,CAAA;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,yEAAyE;IACzE,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAA;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACpC,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CACrB,CAAA;AAmBD,eAAO,MAAM,QAAQ,QAAS;IAC7B,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;CACjC,KAAG,MAAM,EAAgE,CAAA;AAE1E,yEAAyE;AACzE,wBAAgB,QAAQ,CACvB,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,SAAS,GAAG,EAAE,GAClB,IAAI,CAoCN;AAeD;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,EAAE,CAwBtE"}

package/dist/parts.js

@@ -0,0 +1,99 @@
+// The changes of a write as CTEs, and how they split into statements (D-99).
+import { createQueryId, PostgresQueryCompiler, sql } from 'kysely';
+import { value } from './filter.js';
+import { rows as noted } from './notify.js';
+const compiler = new PostgresQueryCompiler();
+/** How many parameters a piece of SQL binds. */
+export function sizeOf(piece) {
+    return compiler.compileQuery(piece.toOperationNode(), createQueryId())
+        .parameters.length;
+}
+/** A column's type, which a row of VALUES under a SELECT does not infer. */
+const types = {
+    id: 'uuid',
+    string: 'text',
+    enum: 'text',
+    number: 'double precision',
+    decimal: 'numeric',
+    integer: 'integer',
+    boolean: 'boolean',
+    dateTime: 'timestamptz',
+    date: 'date',
+    json: 'jsonb',
+    'text[]': 'text[]',
+    'double precision[]': 'double precision[]',
+    'integer[]': 'integer[]',
+};
+export const fieldsOf = (row) => Object.keys(row).filter((name) => row[name] !== undefined);
+/** Rows inserted into a table, which all set the fields of the first. */
+export function inserted(catalog, model, rows) {
+    const table = catalog.table(model);
+    const name = sql.id(table.name);
+    const fields = fieldsOf(rows[0] ?? {});
+    const columns = sql.join(fields.map((field) => sql.id(catalog.column(table, field))));
+    const tuples = (typed) => sql.join(rows.map((row, at) => {
+        const values = fields.map((field) => {
+            const kind = catalog.kind(table, field);
+            const item = value(kind, row[field]);
+            // The first row's types are the other rows'.
+            return typed && at === 0
+                ? sql `cast(${item} as ${sql.raw(types[kind])})`
+                : item;
+        });
+        return sql `(${sql.join(values)})`;
+    }));
+    const [only] = rows;
+    return {
+        table: table.name,
+        key: ['id'],
+        ...(rows.length === 1 && only !== undefined ? { row: only.id } : {}),
+        build: (gate) => gate === undefined
+            ? sql `insert into ${name} (${columns}) values ${tuples(false)} returning *`
+            : sql `insert into ${name} (${columns}) select * from (values ${tuples(true)}) as "v" where ${gate} returning *`,
+        inserts: true,
+        removes: false,
+        adds: true,
+        reads: new Set(),
+        noted: noted('insert', model),
+    };
+}
+/** Whether `each` may join a statement that already wrote `prior`. */
+function fits(prior, each) {
+    if (prior === undefined)
+        return true;
+    // A join table's changes of distinct pairs never meet.
+    if (each.pairs !== undefined) {
+        return [...each.pairs].every((pair) => !prior.pairs.has(pair));
+    }
+    return prior.inserts && each.inserts;
+}
+/**
+ * The parts of one statement each: a part starts a new one when it writes a
+ * table the statement writes (inserts, and a join table's distinct pairs,
+ * aside) or reads one, since the parts of a statement see the database as it
+ * was, or when its parameters would not fit in the `room` left.
+ */
+export function grouped(parts, room) {
+    const groups = [[]];
+    const written = new Map();
+    let used = 0;
+    for (const each of parts) {
+        const size = sizeOf(each.build(undefined));
+        const clash = !fits(written.get(each.table), each) ||
+            [...each.reads].some((table) => written.has(table)) ||
+            (used > 0 && used + size > room);
+        if (clash) {
+            groups.push([]);
+            written.clear();
+            used = 0;
+        }
+        used += size;
+        groups.at(-1)?.push(each);
+        const prior = written.get(each.table);
+        written.set(each.table, {
+            inserts: (prior?.inserts ?? true) && each.inserts,
+            pairs: new Set([...(prior?.pairs ?? []), ...(each.pairs ?? [])]),
+        });
+    }
+    return groups;
+}

package/dist/plan-indexes.d.ts

@@ -0,0 +1,12 @@
+import type { Emit } from './plan-parts.ts';
+import type { TableSnapshot } from './snapshot.ts';
+/** Drops the indexes of `from` that `to` changes. */
+export declare function dropIndexes(name: string, from: TableSnapshot, to: TableSnapshot, emit: Emit): void;
+/** Whether `to` adds a trigram index `from` lacks. */
+export declare const addsTrigrams: (from: TableSnapshot | undefined, to: TableSnapshot) => boolean;
+/**
+ * Creates the indexes `table` adds to `was`. A trigram index reads the
+ * column under the database's collation, as `contains` does (D-141).
+ */
+export declare function addIndexes(name: string, was: TableSnapshot | undefined, table: TableSnapshot, emit: Emit): void;
+//# sourceMappingURL=plan-indexes.d.ts.map

package/dist/plan-indexes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-indexes.d.ts","sourceRoot":"","sources":["../src/plan-indexes.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,IAAI,EAAS,MAAM,iBAAiB,CAAA;AAElD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAkBlD,qDAAqD;AACrD,wBAAgB,WAAW,CAC1B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,aAAa,EACnB,EAAE,EAAE,aAAa,EACjB,IAAI,EAAE,IAAI,GACR,IAAI,CAoBN;AAED,sDAAsD;AACtD,eAAO,MAAM,YAAY,SAClB,aAAa,GAAG,SAAS,MAC3B,aAAa,KACf,OAA8D,CAAA;AAEjE;;;GAGG;AACH,wBAAgB,UAAU,CACzB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,aAAa,GAAG,SAAS,EAC9B,KAAK,EAAE,aAAa,EACpB,IAAI,EAAE,IAAI,GACR,IAAI,CAgCN"}

package/dist/plan-indexes.js

@@ -0,0 +1,49 @@
+// The indexes a plan drops and creates: B-tree, GIN on a list (D-120),
+// trigram for `contains` (D-141), and the `_search` column with its GIN
+// index (D-148).
+import { literal } from './fills.js';
+import { added, changed, fields, id, list, same } from './plan-parts.js';
+const indexesOf = (table) => Object.fromEntries(Object.entries(table?.indexes ?? {}).map(([key, columns]) => [
+    key,
+    {
+        columns,
+        gin: columns.some((name) => table?.columns[name]?.type.endsWith('[]') === true),
+    },
+]));
+/** Drops the indexes of `from` that `to` changes. */
+export function dropIndexes(name, from, to, emit) {
+    for (const [key, { columns }] of changed(indexesOf(from), indexesOf(to))) {
+        emit(`drop index ${id(key)}`, `dropped the index on ${fields(from, columns)}`);
+    }
+    for (const [key, column] of changed(from.trigrams, to.trigrams)) {
+        emit(`drop index ${id(key)}`, `dropped the contains index on ${fields(from, [column])}`);
+    }
+    // A generated column holds nothing of its own: a change makes it again.
+    if (from.search !== null && !same(from.search, to.search)) {
+        emit(`alter table ${id(name)} drop column "_search"`, `dropped the search on ${fields(from, from.search.columns)}`);
+    }
+}
+/** Whether `to` adds a trigram index `from` lacks. */
+export const addsTrigrams = (from, to) => added(from?.trigrams ?? {}, to.trigrams).length > 0;
+/**
+ * Creates the indexes `table` adds to `was`. A trigram index reads the
+ * column under the database's collation, as `contains` does (D-141).
+ */
+export function addIndexes(name, was, table, emit) {
+    for (const [key, { columns, gin }] of added(indexesOf(was), indexesOf(table))) {
+        emit(`create index ${id(key)} on ${id(name)}${gin ? ' using gin' : ''} (${list(columns)})`, `indexed ${fields(table, columns)}`);
+    }
+    for (const [key, column] of added(was?.trigrams ?? {}, table.trigrams)) {
+        emit(`create index ${id(key)} on ${id(name)} using gin ((${id(column)} collate "default") gin_trgm_ops)`, `indexed ${fields(table, [column])} for contains`);
+    }
+    const { search } = table;
+    if (search === null || (was !== undefined && same(was.search, search))) {
+        return;
+    }
+    const text = search.columns
+        .map((column) => `coalesce(${id(column)}, '')`)
+        .join(` || ' ' || `);
+    const searched = fields(table, search.columns);
+    emit(`alter table ${id(name)} add column "_search" tsvector generated always as (to_tsvector(${literal(search.language)}::regconfig, ${text})) stored`, `added the search on ${searched}`);
+    emit(`create index ${id(search.index)} on ${id(name)} using gin ("_search")`, `indexed the search on ${searched}`);
+}

package/dist/plan-parts.d.ts

@@ -0,0 +1,16 @@
+import type { Statement } from 'ultimabase';
+import type { TableSnapshot } from './snapshot.ts';
+export declare const id: (name: string) => string;
+export declare const list: (names: readonly string[]) => string;
+export declare const same: (a: unknown, b: unknown) => boolean;
+export type Named<T> = {
+    readonly [name: string]: T;
+};
+export type Emit = (sql: string, does: string, more?: Pick<Statement, 'loses' | 'tries' | 'rename'>) => void;
+/** The entries of `from` that `to` lacks or defines otherwise. */
+export declare const changed: <T>(from: Named<T>, to: Named<T>) => [string, T][];
+/** The entries of `to` that `from` lacks or defines otherwise. */
+export declare const added: <T>(from: Named<T>, to: Named<T>) => [string, T][];
+/** The model's names for columns, which messages use. */
+export declare const fields: (table: TableSnapshot, columns: readonly string[]) => string;
+//# sourceMappingURL=plan-parts.d.ts.map

package/dist/plan-parts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-parts.d.ts","sourceRoot":"","sources":["../src/plan-parts.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAElD,eAAO,MAAM,EAAE,SAAU,MAAM,KAAG,MAA2C,CAAA;AAE7E,eAAO,MAAM,IAAI,UAAW,SAAS,MAAM,EAAE,KAAG,MACvB,CAAA;AAEzB,eAAO,MAAM,IAAI,MAAO,OAAO,KAAK,OAAO,KAAG,OACN,CAAA;AAExC,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI;IAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAAA;CAAE,CAAA;AAErD,MAAM,MAAM,IAAI,GAAG,CAClB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC,KAChD,IAAI,CAAA;AAET,kEAAkE;AAClE,eAAO,MAAM,OAAO,GAAI,CAAC,QAAQ,KAAK,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,KAAG,CAAC,MAAM,EAAE,CAAC,CAAC,EACE,CAAA;AAEvE,kEAAkE;AAClE,eAAO,MAAM,KAAK,GAAI,CAAC,QAAQ,KAAK,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,KAAG,CAAC,MAAM,EAAE,CAAC,CAAC,EACjD,CAAA;AAElB,yDAAyD;AACzD,eAAO,MAAM,MAAM,UACX,aAAa,WACX,SAAS,MAAM,EAAE,KACxB,MACwE,CAAA"}

package/dist/plan-parts.js

@@ -0,0 +1,9 @@
+export const id = (name) => `"${name.replaceAll('"', '""')}"`;
+export const list = (names) => names.map(id).join(', ');
+export const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+/** The entries of `from` that `to` lacks or defines otherwise. */
+export const changed = (from, to) => Object.entries(from).filter(([name, value]) => !same(value, to[name]));
+/** The entries of `to` that `from` lacks or defines otherwise. */
+export const added = (from, to) => changed(to, from);
+/** The model's names for columns, which messages use. */
+export const fields = (table, columns) => columns.map((column) => table.columns[column]?.field ?? column).join(', ');

package/dist/plan.d.ts

@@ -0,0 +1,6 @@
+import type { Statement } from 'ultimabase';
+import type { Fills } from './fills.ts';
+import type { Snapshot } from './snapshot.ts';
+/** Every statement from `from`, or an empty database, to `to`. */
+export declare function plan(from: Snapshot | undefined, to: Snapshot, fills: Fills): Statement[];
+//# sourceMappingURL=plan.d.ts.map

package/dist/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../src/plan.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAC3C,OAAO,KAAK,EAAQ,KAAK,EAAE,MAAM,YAAY,CAAA;AAK7C,OAAO,KAAK,EAAqB,QAAQ,EAAiB,MAAM,eAAe,CAAA;AA4S/E,kEAAkE;AAClE,wBAAgB,IAAI,CACnB,IAAI,EAAE,QAAQ,GAAG,SAAS,EAC1B,EAAE,EAAE,QAAQ,EACZ,KAAK,EAAE,KAAK,GACV,SAAS,EAAE,CAyEb"}

package/dist/plan.js

@@ -0,0 +1,278 @@
+import { literal } from './fills.js';
+import { addIndexes, addsTrigrams, dropIndexes } from './plan-indexes.js';
+import { added, changed, fields, id, list, same } from './plan-parts.js';
+/** A key's columns as a tried change names them: `Locker (label, size)`. */
+const keyOf = (table, columns) => `${table.model} (${fields(table, columns)})`;
+/** An enum's values; a list's elements are among them, with `<@` (D-127). */
+function checked(name, { column, values, list: all }) {
+    const items = values.map(literal).join(', ');
+    const test = all ? `<@ array[${items}]::text[]` : `in (${items})`;
+    return `constraint ${id(name)} check (${id(column)} ${test})`;
+}
+/** A type as messages show it, without its collation. */
+const shown = (type) => type.replace(' collate "C"', '');
+const column = (name, type, nullable) => `${id(name)} ${type}${nullable ? '' : ' not null'}`;
+/**
+ * Columns as a rename compares them: names, types and nullability, sorted,
+ * because a stored snapshot's columns come back in jsonb's order.
+ */
+const shape = (table) => Object.entries(table.columns)
+    .map(([name, { type, nullable }]) => [name, type, nullable])
+    .toSorted(([a], [b]) => String(a).localeCompare(String(b)));
+function create(name, table) {
+    const parts = [
+        ...Object.entries(table.columns).map(([key, { type, nullable }]) => column(key, type, nullable)),
+        `constraint ${id(table.primaryKey.name)} primary key (${list(table.primaryKey.columns)})`,
+        ...Object.entries(table.uniques).map(([key, columns]) => `constraint ${id(key)} unique (${list(columns)})`),
+        ...Object.entries(table.checks).map(([key, given]) => checked(key, given)),
+    ];
+    return `create table ${id(name)} (\n\t${parts.join(',\n\t')}\n)`;
+}
+/** Drops the keys, checks and indexes of `from` that `to` changes. */
+function dropKeys(name, from, to, emit) {
+    const drop = (key) => `alter table ${id(name)} drop constraint ${id(key)}`;
+    if (!same(from.primaryKey, to.primaryKey)) {
+        emit(drop(from.primaryKey.name), 'dropped the primary key');
+    }
+    for (const [key, columns] of changed(from.uniques, to.uniques)) {
+        emit(drop(key), `dropped the unique key on ${fields(from, columns)}`);
+    }
+    for (const [key, { column: on }] of changed(from.checks, to.checks)) {
+        emit(drop(key), `dropped the values of ${fields(from, [on])}`);
+    }
+    dropIndexes(name, from, to, emit);
+}
+/** Adds a column; a required one takes its fixed default in the rows. */
+function addColumn(table, key, now, model, fill, emit) {
+    const add = `${table} add column ${column(key, now.type, now.nullable)}`;
+    if (now.nullable)
+        return emit(add, `added ${now.field}`);
+    if (fill === undefined) {
+        return emit(add, `added ${now.field}`, {
+            tries: `adding the required "${model}.${now.field}" fails when ${model} holds rows: make it optional, or give it a value as its default, not a function`,
+        });
+    }
+    // The rows take the default; the column keeps none, as the models say.
+    emit(`${add} default ${fill.sql}`, `added ${now.field}`);
+    emit(`${table} alter column ${id(key)} drop default`, `${fill.shown} in the rows it held`);
+}
+/** The types PostgreSQL converts no value of a type to, on PG 15 to 18. */
+const arrays = ['text[]', 'double precision[]', 'integer[]'];
+const scalars = ['boolean', 'timestamptz', 'date', 'jsonb'];
+const numbers = ['double precision', 'numeric', 'integer'];
+const unconvertible = {
+    'double precision': ['boolean', 'timestamptz', 'date', 'jsonb', ...arrays],
+    numeric: ['boolean', 'timestamptz', 'date', 'jsonb', ...arrays],
+    integer: ['timestamptz', 'date', 'jsonb', ...arrays],
+    boolean: [
+        'double precision',
+        'numeric',
+        'timestamptz',
+        'date',
+        'jsonb',
+        ...arrays,
+    ],
+    date: [...numbers, 'boolean', 'jsonb', ...arrays],
+    timestamptz: [
+        'double precision',
+        'numeric',
+        'integer',
+        'boolean',
+        'jsonb',
+        ...arrays,
+    ],
+    jsonb: ['timestamptz', 'date', ...arrays],
+    'text[]': [...numbers, ...scalars],
+    'double precision[]': [...numbers, ...scalars],
+    'integer[]': [...numbers, ...scalars],
+};
+/** A type without its precision and scale: `numeric(10,2)` is `numeric`. */
+const family = (type) => type.startsWith('numeric(') ? 'numeric' : type;
+/**
+ * Whether converting reads each value: text or json to another type,
+ * anything but a boolean to whole numbers, which refuse a fraction (D-132),
+ * anything to a decimal, which refuses more integer digits (D-145).
+ */
+const reads = (from, to) => to.startsWith('integer')
+    ? from !== 'boolean'
+    : to.startsWith('numeric') ||
+        ((from === 'jsonb' || from.startsWith('text')) &&
+            !to.startsWith('text collate'));
+/**
+ * A date as text is `toISOString()`'s, whatever the session's time zone; a
+ * day is `YYYY-MM-DD` whatever its `DateStyle`, and an instant's day is UTC's.
+ * Whole numbers come from text, which refuses `1.5` that a cast rounds; a
+ * decimal's text through float8, as `12.00` is `12`.
+ */
+function converted(named, from, to) {
+    if (from === 'timestamptz' && to.startsWith('text')) {
+        return `to_char(${named} at time zone 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')`;
+    }
+    if (from === 'date' && to.startsWith('text')) {
+        return `to_char(${named}, 'YYYY-MM-DD')`;
+    }
+    if (from === 'timestamptz' && to === 'date') {
+        return `(${named} at time zone 'UTC')::date`;
+    }
+    if (from === 'date' && to === 'timestamptz') {
+        return `(${named}::timestamp at time zone 'UTC')`;
+    }
+    const whole = to.startsWith('integer') && reads(from, to);
+    const via = from.startsWith('numeric') ? 'float8::' : '';
+    return `${named}::${whole ? `${via}text::` : ''}${to}`;
+}
+/**
+ * Changes a column's type. One PostgreSQL cannot convert loses its values,
+ * as an added column has none: null, or its fixed default when required.
+ */
+function retype(table, key, [was, now], model, fill, emit) {
+    const change = `changing "${model}.${now.field}" from ${shown(was)} to ${shown(now.type)}`;
+    const alter = `${table} alter column ${id(key)} type ${now.type}`;
+    const does = `changed ${now.field} to ${shown(now.type)}`;
+    if (!unconvertible[family(was)]?.includes(family(now.type))) {
+        return emit(`${alter} using ${converted(id(key), was, now.type)}`, does, {
+            loses: `${change} rewrites its data`,
+            ...(reads(was, now.type)
+                ? {
+                    tries: `${change} fails when a row holds a value it cannot convert`,
+                }
+                : {}),
+        });
+    }
+    const loses = `${change} deletes its data: PostgreSQL converts no ${shown(was)} to ${shown(now.type)}`;
+    if (!now.nullable && fill !== undefined) {
+        return emit(`${alter} using ${fill.sql}`, `${does}, ${fill.shown} in the rows it held`, { loses });
+    }
+    emit(`${alter} using null`, `${does} without its values`, {
+        loses,
+        ...(now.nullable
+            ? {}
+            : {
+                tries: `${change} empties it, which fails when ${model} holds rows: make it optional, or give it a value as its default, not a function`,
+            }),
+    });
+}
+/** Changes the columns of a table both snapshots hold. */
+function alterColumns(name, from, to, fills, emit) {
+    const table = `alter table ${id(name)}`;
+    const fresh = Object.entries(to.columns).filter(([key]) => from.columns[key] === undefined);
+    for (const [key, was] of Object.entries(from.columns)) {
+        if (to.columns[key] !== undefined)
+            continue;
+        const twin = fresh.find(([, now]) => now.type === was.type);
+        emit(`${table} drop column ${id(key)}`, `removed ${was.field}`, {
+            loses: `removing "${from.model}.${was.field}" deletes data`,
+            ...(twin === undefined
+                ? {}
+                : {
+                    rename: {
+                        to: `${to.model}.${twin[1].field}`,
+                        dbName: key,
+                        sql: `${table} rename column ${id(key)} to ${id(twin[0])}`,
+                    },
+                }),
+        });
+    }
+    for (const [key, now] of Object.entries(to.columns)) {
+        const was = from.columns[key];
+        if (was === undefined) {
+            addColumn(table, key, now, to.model, fills[key], emit);
+            continue;
+        }
+        // Optional first, so a type that loses its values can hold none.
+        if (!was.nullable && now.nullable) {
+            emit(`${table} alter column ${id(key)} drop not null`, `made ${now.field} optional`);
+        }
+        if (was.type !== now.type) {
+            retype(table, key, [was.type, now], to.model, fills[key], emit);
+        }
+        if (was.nullable && !now.nullable) {
+            emit(`${table} alter column ${id(key)} set not null`, `made ${now.field} required`, {
+                tries: `making "${to.model}.${now.field}" required fails when a row holds no value`,
+            });
+        }
+    }
+}
+/** Adds the keys and checks of `to` that `from` lacks or changed. */
+function addKeys(name, from, to, emit) {
+    const add = (part) => `alter table ${id(name)} add ${part}`;
+    if (!same(from.primaryKey, to.primaryKey)) {
+        const { name: key, columns } = to.primaryKey;
+        emit(add(`constraint ${id(key)} primary key (${list(columns)})`), `keyed on ${fields(to, columns)}`, {
+            tries: `keying ${keyOf(to, columns)} fails when two rows share a value`,
+        });
+    }
+    for (const [key, columns] of added(from.uniques, to.uniques)) {
+        emit(add(`constraint ${id(key)} unique (${list(columns)})`), `added a unique key on ${fields(to, columns)}`, {
+            tries: `a unique key on ${keyOf(to, columns)} fails when two rows share a value`,
+        });
+    }
+    for (const [key, given] of added(from.checks, to.checks)) {
+        const field = fields(to, [given.column]);
+        const values = given.values.join(', ');
+        emit(add(checked(key, given)), `limited ${field} to ${values}`, {
+            tries: `limiting "${to.model}.${field}" to ${values} fails when a row holds another value`,
+        });
+    }
+}
+const foreignKey = (table, key, { column: name, table: target, cascade }) => `alter table ${id(table)} add constraint ${id(key)} foreign key (${id(name)}) references ${id(target)} ("id")${cascade ? ' on delete cascade' : ''} deferrable initially deferred`;
+/** Every statement from `from`, or an empty database, to `to`. */
+export function plan(from, to, fills) {
+    const before = from?.tables ?? {};
+    const after = to.tables;
+    const phases = [[], [], [], [], [], [], []];
+    const emit = (phase, model) => (sql, does, more = {}) => {
+        phases[phase]?.push({ sql, model, does, ...more });
+    };
+    const fresh = Object.entries(after).filter(([name]) => before[name] === undefined);
+    for (const [name, table] of Object.entries(before)) {
+        const now = after[name];
+        const keys = changed(table.foreignKeys, now?.foreignKeys ?? {});
+        for (const [key, { column: on }] of keys) {
+            emit(0, table.model)(`alter table ${id(name)} drop constraint ${id(key)}`, `dropped the foreign key on ${fields(table, [on])}`);
+        }
+        if (now !== undefined) {
+            dropKeys(name, table, now, emit(1, now.model));
+            alterColumns(name, table, now, fills[name] ?? {}, emit(3, now.model));
+            addKeys(name, table, now, emit(5, now.model));
+            continue;
+        }
+        const twin = fresh.find(([, created]) => same(shape(created), shape(table)));
+        emit(2, table.model)(`drop table ${id(name)}`, 'removed', {
+            loses: `removing ${table.model} deletes its rows`,
+            ...(twin === undefined
+                ? {}
+                : {
+                    rename: {
+                        to: twin[1].model,
+                        dbName: name,
+                        sql: `alter table ${id(name)} rename to ${id(twin[0])}`,
+                    },
+                }),
+        });
+    }
+    for (const [name, table] of fresh) {
+        emit(4, table.model)(create(name, table), 'created');
+    }
+    // The extension is database-wide; no plan drops it (D-141).
+    const trigram = Object.entries(after).find(([name, table]) => addsTrigrams(before[name], table));
+    if (trigram !== undefined) {
+        emit(5, trigram[1].model)('create extension if not exists pg_trgm', 'installed pg_trgm');
+    }
+    for (const [name, table] of Object.entries(after)) {
+        const was = before[name];
+        addIndexes(name, was, table, emit(5, table.model));
+        const keys = added(was?.foreignKeys ?? {}, table.foreignKeys);
+        for (const [key, given] of keys) {
+            const field = fields(table, [given.column]);
+            emit(6, table.model)(foreignKey(name, key, given), `added the foreign key on ${field}`, 
+            // A column added with its key holds no value yet.
+            was?.columns[given.column] === undefined
+                ? {}
+                : {
+                    tries: `linking "${table.model}.${field}" fails when a row points to no row`,
+                });
+        }
+    }
+    return phases.flat();
+}

package/dist/pool.d.ts

@@ -0,0 +1,5 @@
+import type { PostgresPool } from 'kysely';
+import type { Pool } from 'pg';
+/** `pool`, whose failures to give a connection say why. */
+export declare function pooled(url: string, pool: Pool, connections: number, wait: number): PostgresPool;
+//# sourceMappingURL=pool.d.ts.map

package/dist/pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../src/pool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AAC1C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAA;AA0C9B,2DAA2D;AAC3D,wBAAgB,MAAM,CACrB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,IAAI,EACV,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,GACV,YAAY,CAYd"}

package/dist/pool.js

@@ -0,0 +1,41 @@
+import { parse } from 'pg-connection-string';
+/** The codes of a server the network does not reach, or does not know. */
+const unreachable = /^(ECONNREFUSED|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|EHOSTUNREACH|ENETUNREACH)$/;
+/** What pg-pool throws when no connection frees, or opens, in time. */
+const busy = 'timeout exceeded when trying to connect';
+const silent = 'Connection terminated due to connection timeout';
+/**
+ * `error`, or one naming the server `url` cannot reach, not its password
+ * (D-105), or the connections that stayed busy.
+ */
+function failed(url, error, connections, wait) {
+    const message = error instanceof Error ? error.message : '';
+    const seconds = `${wait / 1000}s`;
+    if (message === busy) {
+        return new Error(`Every one of the ${connections} PostgreSQL connections stayed busy for ${seconds}: a transaction may wait on something slow or never end.`, { cause: error });
+    }
+    const code = Reflect.get(Object(error), 'code');
+    const reachable = typeof code !== 'string' || !unreachable.test(code);
+    if (reachable && message !== silent)
+        return error;
+    const { host, port } = parse(url);
+    const address = `${host || process.env['PGHOST'] || 'localhost'}:${port || 5432}`;
+    const why = reachable ? `no answer in ${seconds}` : code;
+    const reached = new Error(`Cannot reach PostgreSQL at ${address} (${why}): is it running, and is its url right?`, { cause: error });
+    return reachable ? reached : Object.assign(reached, { code });
+}
+/** `pool`, whose failures to give a connection say why. */
+export function pooled(url, pool, connections, wait) {
+    return {
+        options: pool.options,
+        connect: async () => {
+            try {
+                return await pool.connect();
+            }
+            catch (error) {
+                throw failed(url, error, connections, wait);
+            }
+        },
+        end: async () => pool.end(),
+    };
+}

package/dist/read.d.ts

@@ -0,0 +1,47 @@
+import type { CountRead, Nested, Order, Read, Sort } from 'ultimabase';
+import type { Reach, Sql } from './filter.ts';
+import { Filters } from './filter.ts';
+import type { Catalog, Table } from './names.ts';
+/** A sort key in `ORDER BY`; PostgreSQL's default `null`s are D-94's. */
+export declare const sorted: (key: Sql, { direction, nulls }: Sort) => Sql;
+export declare class Compiler {
+    readonly filters: Filters;
+    readonly catalog: Catalog;
+    constructor(catalog: Catalog);
+    /** The rows `nested` selects among those `reach` gives, as a jsonb array. */
+    list(model: string, nested: Nested, reach: Reach, alias: string): Sql;
+    /**
+     * 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.
+     */
+    private keyset;
+    /**
+     * 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: Table, alias: string, order: Pick<Order, 'field' | 'through' | 'count' | 'relevance'>, steps?: NonNullable<Order['through']>): Sql;
+    /** The rows of a `many` relation of the row that `where` selects. */
+    private count;
+    /**
+     * 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).
+     */
+    private scalar;
+    /** A row as jsonb: its fields, each `one` as `{ id }`, then its includes. */
+    row(model: string, alias: string, nested: Nested): Sql;
+}
+/**
+ * `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 declare function compileRows(catalog: Catalog, read: Read, source?: Sql): {
+    readonly rows: Sql;
+    readonly tables: ReadonlySet<string>;
+};
+/** The statement that returns `read`'s rows as one jsonb array, `rows`. */
+export declare function compileFind(catalog: Catalog, read: Read): Sql;
+export declare function compileCount(catalog: Catalog, read: CountRead): Sql;
+//# sourceMappingURL=read.d.ts.map

package/dist/read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../src/read.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACX,SAAS,EAGT,MAAM,EACN,KAAK,EACL,IAAI,EACJ,IAAI,EACJ,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAO,OAAO,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AA0BhD,yEAAyE;AACzE,eAAO,MAAM,MAAM,QAAS,GAAG,wBAAwB,IAAI,KAAG,GACiB,CAAA;AAE/E,qBAAa,QAAQ;IACpB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IAEzB,YAAY,OAAO,EAAE,OAAO,EAG3B;IAED,6EAA6E;IAC7E,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,GAAG,GAAG,CAkCpE;IAED;;;;OAIG;IACH,OAAO,CAAC,MAAM;IAqBd;;;;OAIG;IACH,GAAG,CACF,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,WAAW,CAAC,EAC/D,KAAK,GAAE,WAAW,CAAC,KAAK,CAAC,SAAS,CAAC,CAAuB,GACxD,GAAG,CAoBL;IAED,qEAAqE;IACrE,OAAO,CAAC,KAAK;IAWb;;;OAGG;IACH,OAAO,CAAC,MAAM;IAOd,6EAA6E;IAC7E,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,CAgDrD;CACD;AA0BD;;;;GAIG;AACH,wBAAgB,WAAW,CAC1B,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,IAAI,EACV,MAAM,CAAC,EAAE,GAAG,GACV;IAAE,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CAAE,CAgB9D;AAED,2EAA2E;AAC3E,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,GAAG,GAAG,CAE7D;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,GAAG,GAAG,CAMnE"}