palgres 0.0.0-stage → 0.1.0

package/types/palgres/src/migrate.d.ts

@@ -0,0 +1,189 @@
+import { type Schema } from './model.js';
+import { type Adoption, type Plan, type Roles } from './plan.js';
+/** A pool that hands out one connection of its own: Bun's SQL and postgres.js both are. */
+export interface Pool {
+    reserve(): Promise<Reserved>;
+}
+export interface Reserved {
+    unsafe(sql: string, params?: unknown[]): PromiseLike<unknown>;
+    release(): void;
+}
+export interface MigratorOptions {
+    /** The database's roles the app connects as (default anon, authenticated, service_role). */
+    roles?: Partial<Roles>;
+    /**
+     * How long a step waits for a table's lock before it gives way, and for all
+     * the others it takes while it holds one (default 500 ms; never past half
+     * of the server's deadlock_timeout).
+     */
+    lockTimeoutMs?: number;
+    /** How long a statement step — a CONCURRENTLY build, a VALIDATE: none blocks a writer — waits for the transactions before it (default 10 minutes). */
+    statementWaitMs?: number;
+    /** How many times a step that gave way is tried (default 10). */
+    attempts?: number;
+    /** Rows a backfill updates per transaction (default 1000). */
+    batchSize?: number;
+    /** How long complete and rollback wait for the version going away to disconnect (default 60 s). */
+    disconnectTimeoutMs?: number;
+    /**
+     * A pool on another database of the same server, as this pool's role: what
+     * taking over a database Palgres has not migrated makes the declared
+     * schema in, to read it as Postgres writes it (adopt.ts). The migrator
+     * creates the database and drops it; the role needs CREATEDB.
+     */
+    shadow?: (database: string) => Pool & {
+        end(): Promise<void>;
+    };
+    log?: (line: string) => void;
+    /**
+     * Who opens a migration this migrator starts, kept with it in the ledger
+     * while it is open: a release (the default, "deploy") or a developer
+     * trying a schema from their own computer ("cli:<who>"). A release that
+     * finds a developer's migration open takes its place; a developer who
+     * finds another's is told whose it is.
+     */
+    openedBy?: string;
+}
+export interface Version {
+    n: number;
+    digest: string;
+    state: 'starting' | 'active' | 'retired' | 'abandoned';
+}
+export interface Status {
+    active: Version | null;
+    /** The open migration, if one is, and who opened it (null for a ledger older than the record). */
+    open: {
+        from: number | null;
+        to: number;
+        phase: string;
+        opened_by: string | null;
+    } | null;
+}
+export type { Adoption };
+export type StartResult = {
+    state: 'in-sync';
+    version: number;
+}
+/** A database Palgres had not migrated, holding the schema as declared: taken over as version 1, nothing to migrate. */
+ | {
+    state: 'adopted';
+    version: number;
+    adoption: Adoption;
+} | {
+    state: 'started' | 'resumed';
+    from: number | null;
+    to: number;
+    changes: string[];
+    completed: boolean;
+    adoption?: Adoption;
+};
+export declare class MigrationRefused extends Error {
+    readonly refusals: string[];
+    constructor(refusals: string[]);
+}
+export declare class MigrationOpen extends Error {
+    readonly from: number | null;
+    readonly to: number;
+    /** Who opened it ("deploy", "cli:<who>"); null when the ledger does not say. */
+    readonly openedBy: string | null;
+    constructor(from: number | null, to: number, openedBy?: string | null);
+}
+/** A step waited for the other version's connections to go, and they have not: nothing is changed, and it goes on when run again. */
+export declare class VersionStillConnected extends Error {
+    readonly version: number;
+    constructor(version: number, left: number, waitedMs: number);
+}
+/** A backfill's rows stayed held by writers pass after pass: nothing is lost, and it goes on when run again. */
+export declare class RowsHeld extends Error {
+    constructor(table: string, passes: number);
+}
+/**
+ * Whether a migration's run ended for something that says nothing of the
+ * migration itself — the database unreachable or restarting, a lock not had
+ * in time, the other version still connected — so that run again it picks up
+ * where it stopped. Anything else is the migration's own: it is refused, or
+ * what the tables hold does not fit it, and running it again changes nothing.
+ */
+export declare function cutOff(e: unknown): boolean;
+export declare const DEFAULT_ROLES: Roles;
+/** application_name of a connection the app holds for version n — how complete knows the old version is gone. */
+export declare const applicationName: (n: number) => string;
+export declare class Migrator {
+    private readonly pool;
+    private readonly roles;
+    private readonly openedBy;
+    private readonly lockTimeoutMs;
+    private readonly statementWaitMs;
+    private lockTimeoutFor;
+    private readonly attempts;
+    private readonly batchSize;
+    private readonly disconnectTimeoutMs;
+    private readonly log;
+    private readonly shadow;
+    constructor(pool: Pool, options?: MigratorOptions);
+    status(): Promise<Status>;
+    /**
+     * What start would do now, without doing it. A database Palgres has not
+     * migrated that holds the schema's tables is taken over first, as start
+     * takes it: held as declared, nothing changes; held otherwise, the plan is
+     * the difference from what it holds. Taking it over is read in a shadow
+     * database (MigratorOptions.shadow), made and dropped; the database itself
+     * is not written.
+     */
+    plan(schema: Schema): Promise<Plan>;
+    /**
+     * Starts the migration to `schema`: when it returns, the new version can
+     * serve beside the one serving now. The same schema again resumes a start
+     * that stopped, or answers that it is in sync.
+     */
+    start(schema: Schema): Promise<StartResult>;
+    /** Ends the open migration once nothing of the old version is connected: what only it used goes. */
+    complete(): Promise<{
+        state: 'completed';
+        version: number;
+    } | {
+        state: 'none';
+    }>;
+    /** Abandons the open migration once nothing of the new version is connected: what start added goes. */
+    rollback(): Promise<{
+        state: 'rolled-back';
+        version: number | null;
+    } | {
+        state: 'none';
+    }>;
+    private runStart;
+    private runComplete;
+    private runSteps;
+    private tx;
+    private settings;
+    private notTakenFirst;
+    private statement;
+    private backfill;
+    private highest;
+    private pagesPerBatch;
+    private pages;
+    private keyedBatch;
+    private pageBatch;
+    private retrying;
+    private waitGone;
+    private adopt;
+    private made;
+    private planFrom;
+    private checkedDomain;
+    private casts;
+    private active;
+    private version;
+    private open;
+    private session;
+    private ownAuth;
+    private authRefusals;
+    private ensure;
+}
+/** The search_path of version n through its views: its views first, then the schema for the types and functions, pg_temp last (connect.ts). */
+export declare function searchPath(n: number, schema?: string): string;
+/**
+ * Whether a version's names are the tables' own: no table or column it
+ * reads is somewhere else. Then it reads and writes the tables directly; its
+ * views are needed only while a migration that renames or retypes is open.
+ */
+export declare function isDirect(layout: Plan['layout']): boolean;

package/types/palgres/src/model.d.ts

@@ -0,0 +1,181 @@
+export interface Schema {
+    tables: Table[];
+    enums: Enum[];
+    /** CREATE EXTENSION IF NOT EXISTS each; never dropped. */
+    extensions: string[];
+    /** Named SQL the typed schema cannot say (an expression unique index, a function): applied once by name. */
+    raw: Raw[];
+}
+export interface Table {
+    /** The Postgres schema; "public" unless given. */
+    schema: string;
+    name: string;
+    /** Its name in the version before this one: renamed, not dropped and created. */
+    renamedFrom?: string;
+    /** Kept, unseen by this version: the step before removing it, which is when its data may go. */
+    ignored?: boolean;
+    columns: Column[];
+    /** Column names; [] for a table without one. */
+    primaryKey: string[];
+    uniques: Unique[];
+    indexes: Index[];
+    checks: Check[];
+    foreignKeys: ForeignKey[];
+    /** Row-level security on: the app's roles see the rows its policies give them. */
+    rls: boolean;
+    policies: Policy[];
+    /** Semantic search over the table's rows: Palgres embeds `from` and keeps the vectors (search.ts). */
+    search?: Search;
+}
+export type SearchMetric = 'cosine' | 'euclidean' | 'inner_product';
+/**
+ * A table's rows found by meaning and by word. `from` are the text columns a
+ * row is read by, in the order their text is joined; `model` and
+ * `dimensions` say how it is embedded. A row whose text changes is embedded
+ * again, and until then its old vector is gone (`null`) or still found (`keep`).
+ */
+export interface Search {
+    from: string[];
+    model: string;
+    dimensions: number;
+    metric: SearchMetric;
+    staleness: 'null' | 'keep';
+}
+export interface Column {
+    name: string;
+    /** A Postgres type, as canonicalType() writes it ("text", "timestamp with time zone", "numeric(10,2)", "public.mood"). */
+    type: string;
+    nullable: boolean;
+    /** An SQL expression. */
+    default?: string;
+    renamedFrom?: string;
+    ignored?: boolean;
+    /**
+     * An SQL expression over the row's columns for what is NULL — the rows
+     * already there and whatever an older version still writes — when the
+     * column becomes NOT NULL.
+     */
+    fill?: string;
+    identity?: 'always' | 'by default';
+    /** GENERATED ALWAYS AS (expr), its value computed when read (virtual) or kept on disk (stored). */
+    generated?: {
+        expr: string;
+        stored: boolean;
+    };
+    /**
+     * The column holds a user's id. Users live in the platform, not here: when
+     * one is deleted, the app's rows of them go (cascade) or forget them (set
+     * null). `owns` marks the one column per table whose user the row belongs to.
+     */
+    user?: {
+        onDelete: 'cascade' | 'set null';
+        owns: boolean;
+    };
+}
+export interface Unique {
+    name: string;
+    columns: string[];
+}
+export interface Index {
+    name: string;
+    keys: IndexKey[];
+    unique: boolean;
+    /** A partial index's predicate, in SQL. */
+    where?: string;
+    method?: 'btree' | 'hash' | 'gin' | 'gist' | 'brin';
+    include?: string[];
+}
+export type IndexKey = {
+    column: string;
+    desc?: boolean;
+    nulls?: 'first' | 'last';
+} | {
+    expr: string;
+    desc?: boolean;
+    nulls?: 'first' | 'last';
+};
+export interface Check {
+    name: string;
+    expr: string;
+}
+export type FkAction = 'no action' | 'restrict' | 'cascade' | 'set null' | 'set default';
+export interface ForeignKey {
+    name: string;
+    columns: string[];
+    refSchema: string;
+    refTable: string;
+    refColumns: string[];
+    onDelete: FkAction;
+    onUpdate: FkAction;
+    match?: 'simple' | 'full';
+}
+export interface Policy {
+    name: string;
+    for: 'all' | 'select' | 'insert' | 'update' | 'delete';
+    /** Role names as the schema writes them; the migrator maps them to the database's roles. */
+    to: string[];
+    using?: string;
+    withCheck?: string;
+    restrictive?: boolean;
+}
+export interface Enum {
+    schema: string;
+    name: string;
+    values: string[];
+}
+export interface Raw {
+    name: string;
+    /** The table it belongs to ("schema.table"), when it does. */
+    table?: string;
+    sql: string;
+    /** What takes it back when it leaves the schema (a schema-level unit's). */
+    drop?: string;
+    /** Made before the schema's tables — a domain, a type, a function a default calls (a schema-level unit's). */
+    before?: boolean;
+    /** The Postgres schema whose file declares it (a schema-level unit's): made if the schema has no table to make it. */
+    schema?: string;
+}
+export declare class SchemaError extends Error {
+    readonly problems: string[];
+    constructor(problems: string[]);
+}
+export declare const emptySchema: () => Schema;
+export declare const tableKey: (t: {
+    schema: string;
+    name: string;
+}) => string;
+export declare function canonicalType(type: string): string;
+/** An enum's type, as a column of it says its type: schema.name, a part quoted when its case is its own (Prisma's "Role"). */
+export declare const enumTypeName: (schema: string, name: string) => string;
+/** The extension a table's search keeps its vectors with. */
+export declare const SEARCH_EXTENSION = "vector";
+export declare const SEARCH_METRICS: readonly SearchMetric[];
+/** What a declaration that names no dimensions embeds in. */
+export declare const SEARCH_DEFAULT_DIMENSIONS = 1536;
+/** pgvector indexes a vector of at most 2000 dimensions, and a half-precision one (halfvec) of at most 4000. */
+export declare const SEARCH_VECTOR_DIMENSIONS = 2000;
+export declare const SEARCH_MAX_DIMENSIONS = 4000;
+/**
+ * What is wrong with a table's search declaration, each with what to write
+ * instead. `what` names the table as its reader knows it: its key in a
+ * schema, defineTable("…") where it is declared.
+ */
+export declare function searchProblems(what: string, t: {
+    columns: readonly Pick<Column, 'name' | 'type' | 'ignored' | 'generated'>[];
+    primaryKey: readonly string[];
+}, s: Search): string[];
+/** Every problem with a schema at once, or none. */
+export declare function validate(schema: Schema): string[];
+/** The schema in one order, every type canonical: what is compared and what the digest is of. */
+export declare function normalize(schema: Schema): Schema;
+/**
+ * The schema normalized, its raw units kept in the order they are declared:
+ * one may need another made first (a materialized view its view), and what
+ * goes, goes last first. What a version records; its digest is of normalize().
+ */
+export declare function normalizeKeepingRawOrder(schema: Schema): Schema;
+/**
+ * What identifies a version: two schemas with one digest are one version.
+ * Column order is part of it — a version's views list columns as declared.
+ */
+export declare function digest(schema: Schema): string;

package/types/palgres/src/plan.d.ts

@@ -0,0 +1,107 @@
+import { type Raw, type Schema } from './model.js';
+import { type SearchGeneration } from './search.js';
+/** A version's names: each visible table and column of the schema, and where it is in the database. */
+export interface Layout {
+    tables: {
+        schema: string;
+        name: string;
+        physical: string;
+        columns: {
+            name: string;
+            physical: string;
+        }[];
+    }[];
+}
+export type Step = 
+/** One transaction, under the migrator's lock timeout; tried again as a whole. */
+{
+    kind: 'tx';
+    sql: string[];
+    why: string;
+}
+/** One statement outside a transaction: CONCURRENTLY, VALIDATE, ALTER TYPE … ADD VALUE. */
+ | {
+    kind: 'statement';
+    sql: string;
+    why: string;
+}
+/** UPDATE in batches until no row matches `where`, each its own short transaction. */
+ | {
+    kind: 'backfill';
+    table: string;
+    key: string[];
+    set: string;
+    where: string;
+    why: string;
+};
+export interface Plan {
+    from: number | null;
+    to: number;
+    /** What changes, a line each, for people. */
+    changes: string[];
+    /** What cannot be done this way, and what to do instead; a plan with any is not run. */
+    refusals: string[];
+    start: Step[];
+    complete: Step[];
+    rollback: Step[];
+    layout: Layout;
+    /** A database Palgres had not migrated, taken over first (Migrator.plan): what that changes itself, and what it leaves as it is. */
+    adoption?: Adoption;
+}
+/** A database taken over: what adoption changed itself, and what it left as it is. */
+export interface Adoption {
+    /** Tables whose row-level security was FORCEd on their owner, as v2 made them: no longer. */
+    unforced: string[];
+    unmanaged: string[];
+}
+/** The database's roles a policy's names stand for. */
+export interface Roles {
+    anon: string;
+    authenticated: string;
+    service: string;
+}
+export interface PlanInput {
+    /** The version serving now, or null for a database Palgres has not migrated yet. */
+    from: {
+        n: number;
+        schema: Schema;
+    } | null;
+    /** The new version's number: past every version the database has recorded, an abandoned one too. */
+    next: number;
+    to: Schema;
+    /** Tables of `from` that hold at least one row. */
+    hasRows: (tableKey: string) => boolean;
+    /**
+     * Whether Postgres casts a value of one type to the other (the types as the
+     * plan writes them in SQL), or undefined where it cannot tell — a type this
+     * deploy makes. A column whose type changes is kept in both by casts.
+     */
+    castable: (from: string, to: string) => boolean | undefined;
+    /**
+     * Whether a type is a domain with a CHECK or NOT NULL (the type as the plan
+     * writes it), or undefined where it cannot tell: Postgres rewrites a table
+     * under a lock to add a column of one.
+     */
+    checkedDomain: (type: string) => boolean | undefined;
+    roles: Roles;
+    /**
+     * The generations of search vectors the database holds for a table
+     * ("schema.table"), as palgres_search.generations says them; none where
+     * not given. A filling one becomes the one that serves only while no
+     * migrator runs and no migration is open (search.ts' promote), so what a
+     * start reads here is what its steps find.
+     */
+    generations?: (tableKey: string) => SearchGeneration[];
+    /** The schema pgvector's types are in (default public, where the migration makes the extension). */
+    vectorSchema?: string;
+}
+export declare const versionSchema: (n: number, schema: string) => string;
+export declare function plan(input: PlanInput): Plan;
+/**
+ * The sequences a default takes its values from — `nextval('public.items_id_seq'::regclass)`,
+ * a serial column's. Palgres makes such a sequence before the column and
+ * hands it to the column (OWNED BY), as `serial` does.
+ */
+export declare function sequencesOf(expr: string | undefined): string[];
+/** The index a raw unit makes, if its SQL is one CREATE INDEX: adoption compares it by this name. */
+export declare function rawIndexName(r: Raw): string | undefined;

package/types/palgres/src/pull.d.ts

@@ -0,0 +1,13 @@
+import type { SchemaUnit } from './units.js';
+import { type Schema } from './model.js';
+export interface Pulled {
+    /** File name (db/public.ts) → its source. */
+    files: Map<string, string>;
+    /** What a person should look at, one line each. */
+    notes: string[];
+}
+export declare function pullSchema(schema: Schema, options?: {
+    from?: string;
+    unmanaged?: readonly string[];
+    units?: readonly SchemaUnit[];
+}): Pulled;

package/types/palgres/src/query/admission.d.ts

@@ -0,0 +1,80 @@
+export interface AdmissionLease {
+    queueMs: number;
+    release(): void;
+}
+/** Deployment settings, never something a query declares. */
+export interface DatabaseAdmissionOptions {
+    /** Requests' transactions at once. */
+    concurrency: number;
+    /**
+     * Further transactions of requests already admitted, at once, beside
+     * `concurrency` (default: twice as many — a request holds at most two at
+     * once, its $asService transaction, open to its end, and an $atomic beside
+     * it — so no admitted request waits for this share on another's account).
+     * The pool holds concurrency + nestedConcurrency.
+     */
+    nestedConcurrency?: number;
+    queueLimit?: number;
+    queueTimeoutMs?: number;
+    /** A signed top-level claim to take turns by instead of `sub`. */
+    tenantClaim?: string;
+    onReject?: (event: {
+        reason: 'full' | 'timeout' | 'cancelled';
+        active: number;
+        queued: number;
+    }) => void;
+}
+export declare class DatabaseAdmission {
+    readonly options: DatabaseAdmissionOptions;
+    private active;
+    private queued;
+    private tenants;
+    private pending;
+    private lastTenant?;
+    private accepted;
+    private rejected;
+    private readonly limit;
+    private readonly timeout;
+    private readonly nestedLimit;
+    private nestedActive;
+    private readonly nestedPending;
+    constructor(options: DatabaseAdmissionOptions);
+    /** How long a wait for a turn lasts before it is a 429: a request's own wait for its further transactions keeps the same deadline. */
+    get queueTimeoutMs(): number;
+    get snapshot(): {
+        active: number;
+        queued: number;
+        nested: {
+            active: number;
+            queued: number;
+        };
+        tenants: number;
+        accepted: number;
+        rejected: {
+            full: number;
+            timeout: number;
+            cancelled: number;
+        };
+    };
+    private nestedLease;
+    private acquireNested;
+    private rejection;
+    private take;
+    private drain;
+    /**
+     * A transaction's turn; `nested` for a further transaction of a request
+     * already admitted, `returning` for the next one of a request that gave its
+     * connection back meanwhile — at the head of its user's line, not refused
+     * as full.
+     */
+    acquire(claims: Record<string, unknown>, signal?: AbortSignal, options?: {
+        nested?: boolean;
+        returning?: boolean;
+    }): Promise<AdmissionLease>;
+}
+/**
+ * The one queue of a pool. Keyed by the driver object, so every database
+ * built on one pool — two versions of an app while a migration is open — waits
+ * in the same line; a second set of settings for it is refused.
+ */
+export declare function databaseAdmission(pool: object, options?: DatabaseAdmissionOptions): DatabaseAdmission;

package/types/palgres/src/query/catalog.d.ts

@@ -0,0 +1,50 @@
+import type { Binding } from '../connect.js';
+import { type ColumnDef } from '../dsl/columns.js';
+import { type SchemaDef } from '../dsl/schema.js';
+import { type Relation } from './relations.js';
+export interface Transform {
+    fromDb?: (v: unknown) => unknown;
+    toDb?: (v: unknown) => unknown;
+}
+export interface TableInfo {
+    /** Bare in public, "schema.table" otherwise. */
+    key: string;
+    schema: string;
+    name: string;
+    /** The relation as the engine's SQL names it. */
+    sql: string;
+    /** The columns this version sees, in declared order. */
+    columns: Map<string, ColumnDef>;
+    /** Declared, but not this version's to name. */
+    ignored: Set<string>;
+    primaryKey: string[];
+    /** The primary key when it is one column — what lock ordering and `has`/`with` correlate on. */
+    singleKey: string | null;
+    uniqueKeys: string[][];
+    transforms: Map<string, Transform>;
+    /** Columns only the database writes (an ALWAYS identity). */
+    databaseOnly: Set<string>;
+    relations: Relation[];
+    /** Projection lists by alias, made once. */
+    projections: Map<string, string>;
+    /** The table's search, when it declares one: its key in Palgres' search schema ("schema.table") and the columns its text is read from. */
+    search?: {
+        key: string;
+        from: readonly string[];
+    };
+}
+export declare const quoteIdent: (name: string) => string;
+/** A column's type as the engine reads it: the DSL's, an sqlType() as "sql:<type>". */
+export declare function engineType(def: ColumnDef): string;
+export declare class Catalog {
+    readonly version: number;
+    private readonly tables;
+    private readonly ignoredTables;
+    constructor(schemas: readonly SchemaDef[], binding: Binding);
+    /** A table of this version, or a refusal that names why it is not one. */
+    table(key: string, caller: string): TableInfo;
+}
+/** The expression that reads a column as its row type promises, or null when the driver's value already is that. */
+export declare function typedResult(type: string | null, expr: string): string | null;
+/** Whether a JSON-typed column: its value is written as JSON whatever JS value it is. */
+export declare function isJsonType(type: string): boolean;