@intentius/chant-lexicon-sql 0.0.0-stage → 0.112.1

package/dist/postgres/import/live-export.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Live export: `chant import --from <env>` writes a Postgres server's schema as
+ * declarations, each object as the statements the catalog's own printers
+ * give for it (`../live/catalog.ts`), the canonical form.
+ *
+ * - `selector.type` is an entity type (`Postgres::Table`); `selector.name` is
+ *   `name` or `schema.name`.
+ * - `owned` keeps the objects whose comment carries chant's ownership marker.
+ * - Another tool's objects (an ORM's revision table, and its sequence and
+ *   indexes) are left out with a warning naming the tool: they are its, and
+ *   a declaration of them would have chant fight it.
+ * - `verbatim` changes nothing yet: the printers already leave out what the
+ *   server would add by itself.
+ */
+import type { ExportedTemplate, ResourceSelector } from "@intentius/chant/lexicon";
+import { type BindOptions } from "../live/bind.js";
+export interface ExportOptions extends Omit<BindOptions, "environment"> {
+    environment: string;
+    stack?: string;
+    region?: string;
+    selector?: ResourceSelector;
+    owned?: boolean;
+    verbatim?: boolean;
+}
+export declare function exportResources(options: ExportOptions): Promise<ExportedTemplate>;
+//# sourceMappingURL=live-export.d.ts.map

package/dist/postgres/import/live-export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-export.d.ts","sourceRoot":"","sources":["../../../src/postgres/import/live-export.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACnF,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAK9D,MAAM,WAAW,aAAc,SAAQ,IAAI,CAAC,WAAW,EAAE,aAAa,CAAC;IACrE,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,wBAAsB,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAsBvF"}

package/dist/postgres/keywords.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Postgres key words and their categories at the pinned server, as
+ * `pg_get_keywords()` reports them: what decides whether a bare word can be a
+ * name. The parser refuses an unquoted reserved word (`R`) or type/function
+ * name word (`T`) where a column, table or constraint name goes, as Postgres's
+ * `ColId` does, and quoting reads the same table.
+ */
+/** U unreserved, C column name, T type or function name, R reserved. */
+export type KeywordCategory = "U" | "C" | "T" | "R";
+/** A word's key word category, case-insensitively; undefined when it is not a key word. */
+export declare function keywordCategory(word: string): KeywordCategory | undefined;
+/** Whether `word` is a key word of any category. */
+export declare const isKeyword: (word: string) => boolean;
+/**
+ * Whether `name` must be double-quoted to read back as itself: anything but a
+ * lower-case identifier, and every key word that is not unreserved (a
+ * `C` word such as `bigint` is a name only where a column name goes).
+ */
+export declare function needsQuotes(name: string): boolean;
+/** A name as Postgres reads it back: bare when it can be, double-quoted otherwise. */
+export declare function quoteIdent(name: string): string;
+//# sourceMappingURL=keywords.d.ts.map

package/dist/postgres/keywords.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keywords.d.ts","sourceRoot":"","sources":["../../src/postgres/keywords.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,wEAAwE;AACxE,MAAM,MAAM,eAAe,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAKpD,2FAA2F;AAC3F,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAGzE;AAED,oDAAoD;AACpD,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM,KAAG,OAA8C,CAAC;AAExF;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIjD;AAED,sFAAsF;AACtF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C"}

package/dist/postgres/live/bind.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Which Postgres server a chant environment reads: the config lookup and the
+ * binding, shared by observation, live export and the plan, so all of them
+ * read the same server.
+ */
+import type { ChantConfig } from "@intentius/chant/config";
+import type { UnobservedReason } from "@intentius/chant/observation";
+import { type PostgresClient, type PostgresEndpoint } from "./client.js";
+import type { PostgresProvider } from "../providers/types.js";
+export interface PostgresTarget {
+    endpoint: PostgresEndpoint;
+    /** Where the binding came from: `sql.profiles.prod` or `env POSTGRES_URL`. */
+    source: string;
+    /** The schemas in scope; undefined is every schema but the server's own. */
+    schemas?: string[];
+    /** The schema an unqualified declaration lives in. */
+    defaultSchema: string;
+    /** The managed service the server runs on (`sql.profiles.<env>.provider`, else `sql.provider`); its own objects read as foreign. */
+    provider?: PostgresProvider;
+    /** The apply's timeouts the profile sets (`lockTimeoutMs`, `statementTimeoutMs`, `scanTimeoutMs`); the applier's defaults otherwise. */
+    timeouts?: {
+        lockTimeoutMs?: number;
+        statementTimeoutMs?: number;
+        scanTimeoutMs?: number;
+    };
+}
+export interface UnresolvedTarget {
+    reason: "no-binding" | "no-credentials";
+    detail: string;
+}
+export declare const isUnresolvedTarget: (v: PostgresTarget | UnresolvedTarget) => v is UnresolvedTarget;
+/** Whether a URL names a Postgres server. */
+export declare const isPostgresUrl: (url: string) => boolean;
+/** A URL with any password in it taken out, for a message. */
+export declare const redactUrl: (url: string) => string;
+/**
+ * The server an environment reads. Pure: `config` and `env` are passed in.
+ *
+ * 1. `sql.profiles.<environment>` with a `postgres://` URL. A profile naming a
+ *    credential variable that is not set is `no-credentials`.
+ * 2. `POSTGRES_URL`, with `POSTGRES_USER` and `POSTGRES_PASSWORD` when set.
+ * 3. Otherwise `no-binding`.
+ */
+export declare function resolvePostgresTarget(input: {
+    environment?: string;
+    config?: Pick<ChantConfig, "sql">;
+    env?: Record<string, string | undefined>;
+}): PostgresTarget | UnresolvedTarget;
+/** A target that could not be resolved. */
+export declare class PostgresBindingError extends Error {
+    readonly unresolved: UnresolvedTarget;
+    constructor(unresolved: UnresolvedTarget);
+}
+export interface BindOptions {
+    environment?: string;
+    /** The project's config; loaded from `cwd` when omitted. */
+    config?: Pick<ChantConfig, "sql">;
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    /** Connect with this instead of node-postgres (tests). */
+    connect?: (endpoint: PostgresEndpoint) => Promise<PostgresClient>;
+}
+export declare function loadSqlConfig(cwd: string): Promise<Pick<ChantConfig, "sql"> | undefined>;
+/** Resolve the environment's server. Throws {@link PostgresBindingError} when there is none. */
+export declare function resolveBoundTarget(options?: BindOptions): Promise<PostgresTarget>;
+/** Resolve the environment's server and connect to it. The caller ends the client. */
+export declare function bindPostgres(options?: BindOptions): Promise<{
+    target: PostgresTarget;
+    client: PostgresClient;
+}>;
+/** What a failed bind or read means, in the observation vocabulary. */
+export declare function classifyPostgresFailure(err: unknown): {
+    reason: UnobservedReason;
+    detail: string;
+};
+//# sourceMappingURL=bind.d.ts.map

package/dist/postgres/live/bind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bind.d.ts","sourceRoot":"","sources":["../../../src/postgres/live/bind.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAuC,KAAK,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC3G,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,sDAAsD;IACtD,aAAa,EAAE,MAAM,CAAC;IACtB,oIAAoI;IACpI,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,wIAAwI;IACxI,QAAQ,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5F;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,YAAY,GAAG,gBAAgB,CAAC;IACxC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,kBAAkB,GAAI,GAAG,cAAc,GAAG,gBAAgB,KAAG,CAAC,IAAI,gBAAiC,CAAC;AAEjH,6CAA6C;AAC7C,eAAO,MAAM,aAAa,GAAI,KAAK,MAAM,KAAG,OAA2C,CAAC;AAExF,8DAA8D;AAC9D,eAAO,MAAM,SAAS,GAAI,KAAK,MAAM,KAAG,MAA0E,CAAC;AAEnH;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC1C,GAAG,cAAc,GAAG,gBAAgB,CAwCpC;AAED,2CAA2C;AAC3C,qBAAa,oBAAqB,SAAQ,KAAK;IACjC,QAAQ,CAAC,UAAU,EAAE,gBAAgB;gBAA5B,UAAU,EAAE,gBAAgB;CAIlD;AAED,MAAM,WAAW,WAAW;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,0DAA0D;IAC1D,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;CACnE;AAED,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,GAAG,SAAS,CAAC,CAQ9F;AAED,gGAAgG;AAChG,wBAAsB,kBAAkB,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAK3F;AAED,sFAAsF;AACtF,wBAAsB,YAAY,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,CAAC,CAIzH;AAKD,uEAAuE;AACvE,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,MAAM,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAMlG"}

package/dist/postgres/live/catalog.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Reading a live Postgres server's schema from its catalog, and printing each
+ * object as the statement that creates it.
+ *
+ * Postgres has no `SHOW CREATE TABLE`, so the statement is assembled from the
+ * server's own printers, the way `pg_dump` assembles it: `format_type()` for
+ * every type, `pg_get_expr()` for defaults, generated columns and partition
+ * bounds, `pg_get_constraintdef()` for every constraint, `pg_get_indexdef()`,
+ * `pg_get_viewdef()` and `pg_get_partkeydef()`. The session reads with an
+ * empty `search_path` (`./client.ts`), so every name outside `pg_catalog` is
+ * schema-qualified in what they print. That printed form is the canonical
+ * one: import writes it, and normalization compares against it.
+ *
+ * Left out, each for its reason:
+ *
+ * - the server's own schemas (`pg_catalog`, `information_schema`, `pg_toast`,
+ *   the temp schemas) and `public`, which every database has;
+ * - objects an extension owns (`pg_depend.deptype = 'e'`): the extension
+ *   declares them, so the extension is what is imported;
+ * - `plpgsql`, installed in every database;
+ * - a sequence an identity column owns (it is the column's), and a `serial`
+ *   column's sequence, since the column prints as `serial`;
+ * - an index that backs a constraint (the constraint creates it), and an
+ *   index partition (the partitioned index creates it);
+ * - chant's own receipts tables (`../../core/ownership.ts`), and the working
+ *   columns, constraints and indexes of an expand-and-contract migration in
+ *   progress (`../migrate/names.ts`, `../migrate/carry.ts`), so a table reads
+ *   as it was before the migration until its switch, and as declared after it.
+ *
+ * Objects another tool owns, an ORM's or a migration runner's revision table
+ * ({@link FOREIGN_TABLES}), are read and marked with the tool, so import
+ * leaves them out with a warning and observation reports them foreign, never
+ * as orphans (#3047 question 10).
+ */
+import type { PostgresClient } from "./client.js";
+import { type PostgresEntityType } from "../entity-types.js";
+import type { PostgresProvider } from "../providers/types.js";
+/** The server's own schemas, never part of a declared schema. */
+export declare const SYSTEM_SCHEMAS: string[];
+/** Tables another tool keeps its migration history in, by name, with the tool. */
+export declare const FOREIGN_TABLES: Readonly<Record<string, string>>;
+export interface LivePgObject {
+    type: PostgresEntityType;
+    /** The schema it is in; absent for a schema and an extension. */
+    schema?: string;
+    name: string;
+    /** The catalog oid, the object's physical id. */
+    oid: string;
+    /** The object's comment as the server holds it, chant's ownership trailer included. */
+    comment?: string;
+    /**
+     * The statements that create it as the server prints them, chant's trailer
+     * taken out of every comment: the CREATE, then a `COMMENT ON` per comment.
+     */
+    statement: string;
+    /** The tool whose bookkeeping this is, when it is another tool's (an ORM's revision table). */
+    foreign?: string;
+}
+/** What {@link readLiveSchema} reads. */
+export interface SchemaScope {
+    /** The schemas in scope; undefined is every schema but the server's own and `public`'s own objects included. */
+    schemas?: readonly string[];
+}
+interface SequenceParams {
+    type: string;
+    start: string;
+    increment: string;
+    min: string;
+    max: string;
+    cache: string;
+    cycle: boolean;
+}
+/** The defaults `CREATE SEQUENCE` gives a sequence of `type` counting by `increment`. */
+export declare function sequenceDefaults(type: string, increment: bigint): Omit<SequenceParams, "type" | "increment" | "cycle">;
+/**
+ * The sequence options that differ from what `CREATE SEQUENCE` would choose,
+ * in the order the reference page lists them. `withType` writes `AS type`
+ * when it is not `bigint`; an identity sequence takes its column's type.
+ */
+export declare function sequenceOptions(p: SequenceParams, withType: boolean): string[];
+/**
+ * Every object in scope, in a stable order: schemas, extensions, enums,
+ * domains, sequences, tables, views and materialized views, indexes; each
+ * kind by schema then name, in byte order.
+ */
+export declare function readLiveSchema(client: PostgresClient, scope?: SchemaScope): Promise<LivePgObject[]>;
+/** The key an object is found by: its type and schema-qualified name. */
+export declare const liveKey: (type: string, schema: string | undefined, name: string) => string;
+/**
+ * Mark what the managed service owns (#3282) as foreign: its reserved
+ * schemas and everything in them, and the extensions it installs itself
+ * (`rdsadmin`, Supabase's `auth` and `storage`, ...). They are the
+ * provider's, so import leaves them out and observation never reports them
+ * as chant's.
+ */
+export declare function markProviderOwned(objects: readonly LivePgObject[], provider: PostgresProvider | undefined): LivePgObject[];
+export {};
+//# sourceMappingURL=catalog.d.ts.map

package/dist/postgres/live/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../src/postgres/live/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAyB,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAKjF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,iEAAiE;AACjE,eAAO,MAAM,cAAc,UAAmD,CAAC;AAE/E,kFAAkF;AAClF,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAa3D,CAAC;AAEF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,kBAAkB,CAAC;IACzB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,uFAAuF;IACvF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,+FAA+F;IAC/F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,yCAAyC;AACzC,MAAM,WAAW,WAAW;IAC1B,gHAAgH;IAChH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAyCD,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB;AAQD,yFAAyF;AACzF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,WAAW,GAAG,OAAO,CAAC,CAKtH;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,EAAE,CAa9E;AAcD;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE,KAAK,GAAE,WAAgB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAmX7G;AAED,yEAAyE;AACzE,eAAO,MAAM,OAAO,GAAI,MAAM,MAAM,EAAE,QAAQ,MAAM,GAAG,SAAS,EAAE,MAAM,MAAM,KAAG,MAA2C,CAAC;AAE7H;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,EAAE,QAAQ,EAAE,gBAAgB,GAAG,SAAS,GAAG,YAAY,EAAE,CAW1H"}

package/dist/postgres/live/client.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The Postgres wire client: node-postgres (`pg`), loaded the first time a
+ * Postgres server is read, so a ClickHouse-only project never loads it.
+ *
+ * Every session reads the catalog with an empty `search_path`, as `pg_dump`
+ * does: `pg_get_*def()` and `format_type()` then qualify every name outside
+ * `pg_catalog`, so what a server prints does not depend on the role's own
+ * search path.
+ */
+export interface PostgresEndpoint {
+    /** A `postgres://` connection URL, without a password. */
+    url: string;
+    user?: string;
+    password?: string;
+}
+/** What chant reads and writes through: one connection. */
+export interface PostgresClient {
+    query<T = Record<string, unknown>>(sql: string, params?: readonly unknown[]): Promise<T[]>;
+    /** Close the connection. Safe to call twice. */
+    end(): Promise<void>;
+}
+/** A failed statement, with the server's SQLSTATE when it sent one. */
+export declare class PostgresQueryError extends Error {
+    readonly code?: string | undefined;
+    readonly position?: number | undefined;
+    constructor(message: string, code?: string | undefined, position?: number | undefined);
+}
+/** Connect to `endpoint` and set the catalog-reading session up. */
+export declare function connectPostgres(endpoint: PostgresEndpoint, options?: {
+    applicationName?: string;
+}): Promise<PostgresClient>;
+//# sourceMappingURL=client.d.ts.map

package/dist/postgres/live/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/postgres/live/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,2DAA2D;AAC3D,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAC3F,gDAAgD;IAChD,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACtB;AAED,uEAAuE;AACvE,qBAAa,kBAAmB,SAAQ,KAAK;IAGzC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM;gBAF1B,OAAO,EAAE,MAAM,EACN,IAAI,CAAC,EAAE,MAAM,YAAA,EACb,QAAQ,CAAC,EAAE,MAAM,YAAA;CAK7B;AAgBD,oEAAoE;AACpE,wBAAsB,eAAe,CAAC,QAAQ,EAAE,gBAAgB,EAAE,OAAO,GAAE;IAAE,eAAe,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,cAAc,CAAC,CAgCrI"}

package/dist/postgres/live/describe-resources.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `describeResources()` for the Postgres dialect: which declared objects exist
+ * on the environment's server.
+ *
+ * One catalog read per run (`./catalog.ts`), then a lookup per declared
+ * entity, so N entities are a fixed handful of queries. An object the catalog
+ * does not list is absent, and the `queried` address names the server and the
+ * object asked for. A server that cannot be reached, or refuses the
+ * credentials, leaves every entity unobserved with that reason: never absent.
+ *
+ * Ownership is chant's marker, the trailer on the object's comment
+ * (`../../core/ownership.ts`): `owned` when the comment carries it, `foreign`
+ * when it does not. With `owned: true` a foreign object is withheld as
+ * `filtered`. An object another tool keeps (an ORM's revision table) is
+ * foreign whatever its comment says.
+ */
+import { type DescribeResourcesResult } from "@intentius/chant/observation";
+import { type BindOptions, type PostgresTarget } from "./bind.js";
+/** The schema and name a declared entity is created as; a bare name is in the default schema. */
+export declare function declaredAddress(entity: {
+    type: string;
+    props: Record<string, unknown>;
+}, defaultSchema: string): {
+    schema?: string;
+    name: string;
+};
+/** A schema scope for the catalog read: the profile's schemas, else every schema the declarations name and the default one. */
+export declare function scopeFor(target: PostgresTarget, entities: ReadonlyArray<{
+    type: string;
+    props: Record<string, unknown>;
+}>): string[] | undefined;
+export declare function describeResources(options: {
+    environment: string;
+    entityNames: string[];
+    entities: Map<string, {
+        entityType: string;
+        props: Record<string, unknown>;
+    }>;
+    owned?: boolean;
+} & Omit<BindOptions, "environment">): Promise<DescribeResourcesResult>;
+//# sourceMappingURL=describe-resources.d.ts.map

package/dist/postgres/live/describe-resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-resources.d.ts","sourceRoot":"","sources":["../../../src/postgres/live/describe-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAGL,KAAK,uBAAuB,EAG7B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAoD,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,MAAM,QAAQ,CAAC;AAWjH,iGAAiG;AACjG,wBAAgB,eAAe,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EAAE,aAAa,EAAE,MAAM,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAIlJ;AAED,+HAA+H;AAC/H,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,GAAG,MAAM,EAAE,GAAG,SAAS,CAUhJ;AA4CD,wBAAsB,iBAAiB,CACrC,OAAO,EAAE;IACP,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,IAAI,CAAC,WAAW,EAAE,aAAa,CAAC,GACnC,OAAO,CAAC,uBAAuB,CAAC,CAMlC"}

package/dist/postgres/migrate/backfill.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The backfill and the verification of the expand-and-contract migration
+ * (#3281).
+ *
+ * ## Backfill
+ *
+ * The rows that were in the table before the dual write started are filled
+ * in batches: one range of the primary key per batch (`./batches.ts`:
+ * `[b * size, (b + 1) * size)` of an integer key, else between boundaries
+ * recorded in the receipt store), so a batch is the same rows on every run
+ * however many rows were written since. Each batch is one transaction:
+ *
+ *     UPDATE t SET new = <expression> WHERE key >= lo AND key < hi AND new IS DISTINCT FROM <expression>;
+ *     INSERT INTO __chant_receipts ... -- the batch's receipt, last
+ *     COMMIT;
+ *
+ * under `lock_timeout` (a row an application transaction holds makes the
+ * batch give up and try again rather than queue behind it) and the
+ * statement timeout for a catalog change, which bounds how long one batch
+ * may hold its row locks.
+ *
+ * Per batch, the cycle core's `effect()` step runs
+ * (concepts/effect-receipts.mdx): read the receipt, skip the batch when it
+ * matches, otherwise update and write the receipt last, on success only.
+ * The batches are only known when the run reads the table, so the cycle runs
+ * here over the shared core's `ReceiptStore` seam (`./receipts.ts`), as the
+ * ClickHouse rebuild's does per partition. Unlike ClickHouse, the receipt
+ * commits in the batch's own transaction: a run killed anywhere leaves a
+ * batch with its receipt or neither, and a resumed backfill starts at the
+ * first batch with no receipt and updates no batch twice.
+ *
+ * Before each batch the backfill waits while a replica is further behind
+ * than the bound (`./replication.ts`).
+ *
+ * ## Verification
+ *
+ * One statement over the whole table, one snapshot: the rows, the rows whose
+ * new column differs from the expression over the old one, the new column's
+ * NULLs, and a checksum (the sum of a 64-bit hash of each value) of the new
+ * column and of the expression. Any difference, or a NULL where the column
+ * is declared NOT NULL, fails the run, whose onFailure then drops what the
+ * expand added. The dual-write trigger keeps writes going during the
+ * verification consistent; the statement reads the table under ACCESS SHARE
+ * only.
+ */
+import { type MigrationObservation } from "./observe.js";
+import { type PostgresReceiptStore } from "./receipts.js";
+import { waitForReplicas } from "./replication.js";
+import { type MigrationRun } from "./steps.js";
+import { type Batch } from "./batches.js";
+export interface BackfillResult {
+    state: MigrationObservation["state"];
+    /** Batches of the table's key ranges that hold rows. */
+    batches: number;
+    /** Batches filled in this run. */
+    filled: number;
+    /** Batches skipped: their receipt matched. */
+    skipped: number;
+    /** Rows this run updated. */
+    rows: number;
+    /** How long the backfill paused for replicas, in ms. */
+    pausedMs: number;
+}
+/** The effect a batch is, and its receipt's address suffix. */
+export declare const batchEffect: (key: string, batch: string) => string;
+/** The receipt's expected value for one batch: bound to the table, the new column's attribute number, the batch's rows and the expression. */
+export declare function batchExpectation(o: MigrationObservation, batch: Pick<Batch, "id" | "inputs">): string;
+/** The address suffix of the recorded batch boundaries of a key that is not one integer column. */
+export declare const BATCHES_RECORD = "batches";
+export interface BackfillDeps {
+    /** The receipt store. Default: `<schema>.__chant_receipts` over the run's connection. */
+    receipts?: PostgresReceiptStore;
+    /** Called after a batch's receipt is written and before its transaction commits; a test kills the run here. */
+    beforeCommit?: (batch: string) => void | Promise<void>;
+    /** Called after each batch commits; a test interrupts the backfill here. */
+    afterBatch?: (batch: string) => void | Promise<void>;
+    /** Wait for replicas with this (tests). */
+    waitForReplicas?: typeof waitForReplicas;
+}
+export declare function backfill(run: MigrationRun, deps?: BackfillDeps): Promise<BackfillResult>;
+export interface VerifyResult {
+    state: MigrationObservation["state"];
+    /** The digest the switch gate binds: the plan and the verified new column. Absent once the switch has run. */
+    planDigest?: string;
+    rows: number;
+    /** Rows whose new column differs from the expression over the old one. */
+    mismatched: number;
+    /** Rows whose new column is NULL. */
+    nulls: number;
+    /** The sum of a 64-bit hash of every new value, and of every value the expression gives. */
+    checksum: string;
+    expected: string;
+    /** One line for the run record and the gate. */
+    summary: string;
+}
+/** A verification that found the columns different. */
+export declare class MigrationVerificationError extends Error {
+    readonly key: string;
+    readonly result: Omit<VerifyResult, "summary" | "planDigest">;
+    constructor(key: string, result: Omit<VerifyResult, "summary" | "planDigest">, reason: string);
+}
+export declare function verifyMigration(run: MigrationRun): Promise<VerifyResult>;
+//# sourceMappingURL=backfill.d.ts.map

package/dist/postgres/migrate/backfill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backfill.d.ts","sourceRoot":"","sources":["../../../src/postgres/migrate/backfill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAKH,OAAO,EAA0C,KAAK,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAC9F,OAAO,EAAwC,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC7F,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAmD,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAE7F,OAAO,EAAiD,KAAK,KAAK,EAAE,MAAM,WAAW,CAAC;AAEtF,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,oBAAoB,CAAC,OAAO,CAAC,CAAC;IACrC,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,+DAA+D;AAC/D,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,EAAE,OAAO,MAAM,KAAG,MAAmC,CAAC;AAE7F,8IAA8I;AAC9I,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,oBAAoB,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,GAAG,QAAQ,CAAC,GAAG,MAAM,CASrG;AAED,mGAAmG;AACnG,eAAO,MAAM,cAAc,YAAY,CAAC;AAExC,MAAM,WAAW,YAAY;IAC3B,yFAAyF;IACzF,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,+GAA+G;IAC/G,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,4EAA4E;IAC5E,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,2CAA2C;IAC3C,eAAe,CAAC,EAAE,OAAO,eAAe,CAAC;CAC1C;AAED,wBAAsB,QAAQ,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CA2DlG;AAID,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,oBAAoB,CAAC,OAAO,CAAC,CAAC;IACrC,8GAA8G;IAC9G,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,4FAA4F;IAC5F,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,uDAAuD;AACvD,qBAAa,0BAA2B,SAAQ,KAAK;IAEjD,QAAQ,CAAC,GAAG,EAAE,MAAM;IACpB,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,YAAY,CAAC;gBADpD,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,YAAY,CAAC,EAC7D,MAAM,EAAE,MAAM;CAKjB;AAED,wBAAsB,eAAe,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CA0C9E"}

package/dist/postgres/migrate/batches.d.ts

@@ -0,0 +1,90 @@
+/**
+ * How the backfill cuts a table into batches (#3281, #3322). A batch must be
+ * the same rows on every run, or a receipt written for it by one run would
+ * vouch for different rows in the next.
+ *
+ * - A primary key of one smallint, integer or bigint column: ranges of its
+ *   value, `[b * size, (b + 1) * size)`. Arithmetic, so nothing needs to be
+ *   remembered, and a batch is the same range however many rows were
+ *   written since.
+ * - Any other primary key (uuid, text, a timestamp, several columns):
+ *   ranges between recorded boundaries in the key's order. The first run
+ *   walks the key's index once, taking every `size`-th key as a boundary
+ *   (`WHERE key >= boundary ORDER BY key OFFSET size LIMIT 1`, so the walk
+ *   reads each key once and sorts nothing), and records the boundaries in
+ *   the receipt store, beside the batches' receipts, before any batch runs.
+ *   Every later run reads them back instead of walking again, so batch `i`
+ *   is `boundary[i] <= key < boundary[i + 1]` in every run. The first batch
+ *   has no lower bound and the last no upper one, so a row written since,
+ *   anywhere in the key's order, falls in exactly one batch (and the dual
+ *   write has already filled it). Each batch is a range scan of the primary
+ *   key's index, with a row comparison (`(a, b) >= ($1, $2)`) in the index's
+ *   own column order.
+ *
+ * Hash buckets (`hash(key) % n`) were the other option: they need nothing
+ * recorded but the bucket count, but no index can serve them, so every batch
+ * would read the whole table. Ranges recorded once read each row once.
+ *
+ * The record is bound to the table's oid and the new column's attribute
+ * number, like the batches' receipts: a migration started again after
+ * onFailure (which drops the new column and the receipts) walks the key
+ * again. A record left from another batch size is kept, since its batches'
+ * receipts are what the run resumes from.
+ */
+import type { PostgresClient } from "../live/client.js";
+import type { PostgresReceiptStore } from "./receipts.js";
+/** One primary-key column, in the key's order. */
+export interface KeyColumn {
+    name: string;
+    /** As `format_type` prints it: what a boundary's text is cast back to. */
+    type: string;
+}
+/** One batch: its id (the receipt's address suffix), its rows as a condition with parameters from `$1`, and what its receipt binds. */
+export interface Batch {
+    id: string;
+    where: string;
+    params: string[];
+    inputs: Record<string, unknown>;
+}
+export declare const INTEGER_KEY_TYPES: ReadonlySet<string>;
+/** Whether the key is batched by arithmetic ranges of its one integer column. */
+export declare const isIntegerKey: (keys: readonly KeyColumn[]) => boolean;
+/** `id`, or `(tenant_id, id)`. */
+export declare const keyText: (keys: readonly KeyColumn[]) => string;
+/** The batches of an integer key: one per range that holds rows. */
+export declare function integerBatches(client: PostgresClient, table: string, key: KeyColumn, size: number): Promise<Batch[]>;
+/** The batches between recorded boundaries: `[undefined, b1)`, `[b1, b2)`, ..., `[bn, undefined)`, where `b0` is only where the walk started. */
+export declare function boundaryBatches(keys: readonly KeyColumn[], bounds: readonly string[][]): Batch[];
+/** Walk the key's order and take every `size`-th key: the boundaries the batches lie between. */
+export declare function walkBoundaries(client: PostgresClient, table: string, keys: readonly KeyColumn[], size: number, signal?: AbortSignal): Promise<string[][]>;
+/** The batching a run recorded, as kept in the receipt store. */
+export interface BatchRecord {
+    v: 1;
+    /** The table's oid and the new column's attribute number, which the record is for. */
+    table: string;
+    column: number;
+    keys: string[];
+    size: number;
+    bounds: string[][];
+}
+/**
+ * The boundary batches of a key that is not one integer column: read from
+ * the record in the receipt store, or walked and recorded when there is
+ * none for this table and new column.
+ */
+export declare function recordedBatches(client: PostgresClient, input: {
+    table: string;
+    oid: string;
+    attnum: number;
+    keys: readonly KeyColumn[];
+    size: number;
+    effect: string;
+    receipts: PostgresReceiptStore;
+    log: (line: string) => void;
+    signal?: AbortSignal;
+}): Promise<{
+    batches: Batch[];
+    record: BatchRecord;
+    walked: boolean;
+}>;
+//# sourceMappingURL=batches.d.ts.map

package/dist/postgres/migrate/batches.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batches.d.ts","sourceRoot":"","sources":["../../../src/postgres/migrate/batches.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,kDAAkD;AAClD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;CACd;AAED,uIAAuI;AACvI,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAA8C,CAAC;AAEjG,iFAAiF;AACjF,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,SAAS,EAAE,KAAG,OAAoE,CAAC;AAE/H,kCAAkC;AAClC,eAAO,MAAM,OAAO,GAAI,MAAM,SAAS,SAAS,EAAE,KAAG,MAAyF,CAAC;AAQ/I,oEAAoE;AACpE,wBAAsB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAQ1H;AAED,iJAAiJ;AACjJ,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,KAAK,EAAE,CAqBhG;AAED,iGAAiG;AACjG,wBAAsB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAY/J;AAED,iEAAiE;AACjE,MAAM,WAAW,WAAW;IAC1B,CAAC,EAAE,CAAC,CAAC;IACL,sFAAsF;IACtF,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,SAAS,SAAS,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,oBAAoB,CAAC;IAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GACjM,OAAO,CAAC;IAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC,CAsBrE"}