@kequtech/tenon-orm 0.2.2 → 0.3.0

package/docs/reference.md

@@ -1,14 +1,14 @@
 # Tenon reference
 
-Exact API contracts and limitations. The [human guide](human-guide.md) introduces the workflow;
-the [agent guide](agent-guide.md) covers routine implementation. Examples below use the
-`public.users` table from the human guide and an existing `db` instance, unless stated otherwise.
+Exact API contracts and limitations. The [human guide](human-guide.md) introduces the workflow; the
+[agent guide](agent-guide.md) covers routine implementation. Examples below use the `public.users`
+table from the human guide and an existing `db` instance, unless stated otherwise.
 
 ## Installation and connection
 
 Requires Node.js 24+, PostgreSQL 16+, and ESM. TypeScript consumers need TypeScript 6+ and Node
-development typings. Tenon includes `postgres@3.4.9`; no driver peer or special compiler plugin is
-required. A usual Node TypeScript setup uses `module: "NodeNext"`.
+development typings. Tenon includes `pg@8.23.1` and its TypeScript declarations; no driver peer or
+special compiler plugin is required. A usual Node TypeScript setup uses `module: "NodeNext"`.
 
 ```sh
 npm install @kequtech/tenon-orm
@@ -18,71 +18,66 @@ npm install @kequtech/tenon-orm
 and `close`. The required `connection` accepts:
 
 - A PostgreSQL URI string.
-- `{ url: string, options?: ConnectionOptions }` to combine a URI with driver settings.
-- A Postgres.js options object; an explicit `{}` uses the driver's environment defaults.
-- An existing Postgres.js client, borrowed by identity.
+- A pg `PoolConfig` object; an explicit `{}` uses the driver's environment defaults.
+- An existing `pg.Pool`, borrowed by identity.
 
 ```ts
 const db = createTenon({
   connection: {
-    url: connection,
-    options: { connect_timeout: 5, idle_timeout: 10, connection: { search_path: 'app,public' } },
+    connectionString: connection,
+    connectionTimeoutMillis: 5000,
+    options: '-c search_path=app,public',
   },
 });
 ```
 
-Tenon forwards `{ url, options }` to `postgres(url, options)`. Explicit driver options override
-corresponding URI pool/transport options. URI startup parameters such as `search_path` and
-`application_name` override `options.connection`. Timeouts above are seconds; preserve the
-deployment's credentials and TLS requirements. `ConnectionUri` and `ConnectionOptions` are
-exported. The latter includes `onnotify(channel, payload)` for native notification handling;
-configure callbacks at construction.
-
-Reuse an instance for each database configuration. `db.close({ timeoutMs? })` rejects new Tenon
-work immediately and gives owned connections a 5,000 ms grace period by default before requesting
-driver termination. Use `0` for immediate termination. The timeout must be an integer from 0 to
-2,147,483,647 milliseconds; `CloseOptions` is exported. Finish outstanding work before closing
-when possible. The timeout bounds the shutdown wait and rejects pending client queries; it is not
-a PostgreSQL cancellation request. Server work can complete afterward, including an autocommitted
-write, and JavaScript inside a transaction callback is not canceled.
-
-The first valid close call chooses the timeout. Concurrent and later calls return the same promise,
-including the same shutdown failure; later options do not change it. Invalid initial options reject
-without closing the instance. For a borrowed client, close only disables the Tenon wrapper and
-leaves the driver pool and its work to the caller. Tenon does not load environment files.
-
-Qualify SQL names or configure runtime `search_path`. CLI `--namespace` selects tooling scope;
-it does not configure application queries. Baseline capture and Describe accept connection
-strings rather than the runtime connection union.
+Strings become pg's `connectionString`; configuration objects pass to `new Pool(config)`.
+`ConnectionOptions` is an alias for pg's `PoolConfig`. Driver options and defaults are unchanged,
+including no acquisition timeout unless `connectionTimeoutMillis` is configured. Pool timeouts use
+milliseconds. pg parses the URI for connection fields; matching URI values override client
+configuration, including an `options` URI parameter overriding the configuration's `options` string.
+Preserve deployment credentials and TLS requirements; see
+[pg connection configuration](https://node-postgres.com/features/connecting).
+
+Reuse an instance for each database configuration. `db.close({ timeoutMs? })` immediately rejects
+new Tenon work. For owned pools, accepted Tenon operations can drain for up to 5,000 ms by default;
+at the deadline, remaining operations reject and Tenon requests driver termination. `0` skips the
+grace period. The timeout must be an integer from 0 to 2,147,483,647 milliseconds; `CloseOptions` is
+exported. This bounds Tenon's wait, not every native transport's teardown or server execution. It
+sends no PostgreSQL cancellation request and does not cancel JavaScript callbacks. An unbounded
+authentication attempt can keep a connection open after close resolves. Configure pg's
+`connectionTimeoutMillis` when connection establishment also needs a deadline.
+
+The first valid close call chooses the timeout. Concurrent and later calls share the same promise
+and outcome. Invalid initial options reject without closing the instance. For borrowed pools, close
+only disables the Tenon wrapper; the application retains the pool and outstanding work. Tenon does
+not load environment files.
+
+Qualify SQL names or configure runtime `search_path`. CLI `--namespace` selects tooling scope; it
+does not configure application queries. Baseline capture and Describe accept connection strings
+rather than the runtime connection union.
 
 ## Native driver access
 
-`db.native` is the actual pool-level Postgres.js client, readonly in TypeScript. Use it for LISTEN,
-cursors, COPY, and other [native APIs](https://github.com/porsager/postgres/tree/v3.4.9#usage).
-Native calls bypass Tenon's result modes, affected-row guards, SQL checks, and `onQuery`. They use
-native preparation defaults and do not join a Tenon transaction; callback clients expose only
-`tx.query`.
+`db.native` is the actual `pg.Pool`, readonly in TypeScript. Native calls bypass Tenon's result
+modes, affected-row guards, SQL checks, and `onQuery`. They follow pg's query configuration and do
+not join a Tenon transaction; callback clients expose only `tx.query`.
 
-Native access alone does not install Tenon's array correction. The first Tenon query or transaction
-installs it on the shared client; native statements prepared earlier may retain their old parsers.
+Use pg's [native APIs](https://node-postgres.com/apis/pool) and compatible cursor/COPY packages when
+needed. For LISTEN, check out a client with `await db.native.connect()`, attach `notification` and
+`error` listeners, and issue `LISTEN` on that client. Keep it checked out while listening; release
+it after `UNLISTEN`. Native queued acquisitions follow pg's shutdown behavior and must be settled by
+their caller before closing. A disconnected client does not reconnect. The application owns
+resubscription and catch-up; notifications are not replayed.
 
-Native `.listen(channel, onPayload, onReady?)` uses a dedicated physical connection. `onReady`
-runs after subscription and resubscription. Missed notifications are not replayed; the application
-owns catch-up and callback errors. That dedicated client installs its own close handler, so a
-constructor `onclose` does not report its outages. Explicit LISTEN on a dedicated reserved native
-connection can use constructor callbacks when disconnect detection is required. Subscription
-cancellation follows the pinned driver; known reconnect limitations are recorded in
-[maintainer considerations](https://github.com/kequtech/tenon-orm/blob/main/CONSIDERATIONS.md#native-driver-access-and-listen-lifecycle).
-
-Close owned clients through `db.close()` to prevent queued LISTEN reconnects from reopening them.
-Direct `db.native.end()` bypasses that protection. Borrowed clients and their listeners remain
-usable after wrapper close until their owner ends them.
+Close owned pools through `db.close()` for bounded shutdown, including checked-out native clients.
+Borrowed pools and their listeners remain usable after wrapper close until their owner ends them.
 
 ## Queries and result modes
 
 `sql<Row>` creates a detached `SqlQuery<Row>` with SQL `text` and ordered `values`; it does not
-execute. `Row` declares one selected row. Without an annotation, fields are `unknown`. An
-annotation does not verify the SQL or validate returned data.
+execute. `Row` declares one selected row. Without an annotation, fields are `unknown`. An annotation
+does not verify the SQL or validate returned data.
 
 ```ts
 const user = await db.query(
@@ -94,17 +89,17 @@ const user = await db.query(
 `query` options are `{ returns?, affectedRows?, label? }`; unknown keys fail. A supplied `label`
 must be a nonempty string.
 
-| `returns`          | Output                          | Allowed returned rows |
-| ------------------ | ------------------------------- | --------------------- |
-| `native` (default) | `QueryResult<Row>` driver array | Any                   |
-| `many`             | Plain `Row[]`                   | Any                   |
-| `oneOrNone`        | `Row \| undefined`              | Zero or one           |
-| `one`              | `Row`                           | Exactly one           |
+| `returns`          | Output                           | Allowed returned rows |
+| ------------------ | -------------------------------- | --------------------- |
+| `native` (default) | `QueryResult<Row>` driver object | Any                   |
+| `many`             | Plain `Row[]`                    | Any                   |
+| `oneOrNone`        | `Row \| undefined`               | Zero or one           |
+| `one`              | `Row`                            | Exactly one           |
 
-Native arrays carry `command`, `count`, `columns`, `statement`, and `state` metadata. `count` is
-the command's affected-row count, independent of `RETURNING`; it can be null for commands without
-a count. Result modes never add `LIMIT` or `RETURNING`. A returned-row mismatch alone does not
-undo an autocommitted write; use `affectedRows` for write bounds that roll back on failure.
+Native results expose `rows`, `rowCount`, `command`, and `fields`, following pg's `QueryResult`.
+`rowCount` is the command's affected-row count, independent of `RETURNING`; it can be null for
+commands without a count. Result modes never add `LIMIT` or `RETURNING`. A returned-row mismatch
+alone does not undo an autocommitted write; use `affectedRows` for write bounds that roll back.
 
 Functions accepting `QueryClient` can use either `Database` or `Transaction`. Public types also
 include `QueryOptions`, `QueryReturnMode`, and `QueryOutput<Row, Mode>`.
@@ -112,9 +107,10 @@ include `QueryOptions`, `QueryReturnMode`, and `QueryOutput<Row, Mode>`.
 ## SQL parameters and identifiers
 
 Ordinary `sql` interpolations bind values. Do not quote them or write manual `$n` placeholders
-inside templates. `undefined` bound parameters fail; `null` means SQL null. Pass JSON objects and
-arrays directly. SQL context distinguishes PostgreSQL arrays from JSON; cast standalone parameters
-when that context is absent.
+inside templates. Values follow pg serialization: `null` and `undefined` bind as SQL null, arrays
+bind as PostgreSQL arrays, and objects use pg's JSON serialization. For JSON input, use
+`JSON.stringify(value)`, including for JSON arrays, strings, and JSON null. Generated JSON write
+types accept encoded strings. Cast standalone parameters when SQL must establish their type.
 
 ```ts
 const ids = [1, 2, 3];
@@ -122,26 +118,27 @@ const query = sql<{ id: number }>`SELECT id FROM public.users
   WHERE id = ANY(${ids}::integer[])`;
 ```
 
-`identifier(schema, table)` quotes components separately. Names must contain 1–63 UTF-8 bytes and
-no NUL. Choose application-approved names; quoting does not authorize access. SQL syntax such as
-`DESC` belongs in fixed query alternatives or fragments, not a string parameter.
+`identifier(schema, table)` quotes components separately. Names must contain 1–63 UTF-8 bytes and no
+NUL. Choose application-approved names; quoting does not authorize access. SQL syntax such as `DESC`
+belongs in fixed query alternatives or fragments, not a string parameter.
 
 `unsafeSql<Row>(text, values)` accepts trusted external SQL and an explicit values array, including
 `[]`. Never concatenate request input into its text. Full `sql` and `unsafeSql` queries cannot be
 nested; use fragments for partial SQL.
 
-Each Tenon query executes one statement through the extended protocol. Application execution
-explicitly disables prepared-statement caching, including on supplied clients with `prepare: true`.
-Values remain bound separately. Migrations deliberately support multi-statement scripts.
+Each Tenon query executes one statement through the extended protocol. Application execution uses
+unnamed queries without a `name` or prepared-statement cache. Values remain bound separately.
+Migrations deliberately support multi-statement scripts.
 
 ## SQL fragments and joins
 
 `sql.fragment` creates immutable partial SQL with bound values. It has no row type, cannot execute
 alone, and rejects blank SQL. Insert it into a complete `sql<Row>` query.
 
-`sql.join(fragments, separator)` requires a nonempty list. Separators are `'AND'`, `'OR'`, and `','`.
-It does not add parentheses or change SQL precedence. Each fragment use receives correctly ordered
-parameters, including repeated and nested uses; literal `$1` text in strings/comments is unchanged.
+`sql.join(fragments, separator)` requires a nonempty list. Separators are `'AND'`, `'OR'`, and
+`','`. It does not add parentheses or change SQL precedence. Each fragment use receives correctly
+ordered parameters, including repeated and nested uses; literal `$1` text in strings/comments is
+unchanged.
 
 ```ts
 const email: string | undefined = 'reader@example.test';
@@ -178,10 +175,10 @@ fragment construction; nested objects retain ordinary driver serialization behav
 | SQL fragment, identifier, or query as a cell | Rejected               | Rejected        |
 
 Inserts accept one object or an array. Without `columns`, they infer the union of enumerable keys
-with defined values in first-seen order. Heterogeneous rows stay aligned. A single default-only
-row emits `DEFAULT VALUES`. Empty batches fail; multiple default-only rows need explicit columns.
-Assignments omit undefined values and fail when no assignments remain, even if surrounding SQL
-has other assignments.
+with defined values in first-seen order. Heterogeneous rows stay aligned. A single default-only row
+emits `DEFAULT VALUES`. Empty batches fail; multiple default-only rows need explicit columns.
+Assignments omit undefined values and fail when no assignments remain, even if surrounding SQL has
+other assignments.
 
 A supplied column list must be nonempty, unique, and valid. It selects and orders fields, ignoring
 unlisted keys. Missing insert cells use defaults; missing update fields are omitted. TypeScript
@@ -190,7 +187,7 @@ Helpers have no schema metadata; PostgreSQL enforces identity, generated-column,
 rules. Use [generated inputs](#insert-and-update-inputs) and application validation.
 
 Write arithmetic, `column = DEFAULT`, and `excluded.column` in the surrounding SQL. There is no
-expression/default sentinel. A complete query accepts at most 65,533 bound parameters, including
+expression/default sentinel. A complete query accepts at most 65,535 bound parameters, including
 surrounding interpolations; Tenon does not split batches. See the [mutation cookbook](mutations.md).
 
 ## Transactions, guarded writes, and errors
@@ -221,8 +218,8 @@ Sequence advances and external effects are not reversible. A lost commit acknowl
 the outcome unknown; applications own retry and idempotency policy.
 
 Set isolation before data queries with `SET TRANSACTION ISOLATION LEVEL SERIALIZABLE`, and use
-`SET LOCAL statement_timeout = '5s'` to bound statements in that transaction. Manual savepoints are supported;
-reserve names beginning with `tenon_affected_rows_` for Tenon.
+`SET LOCAL statement_timeout = '5s'` to bound statements in that transaction. Manual savepoints are
+supported; reserve names beginning with `tenon_affected_rows_` for Tenon.
 
 SQL errors retain native driver details. Invalid inputs throw ordinary `Error` objects.
 `CardinalityError` has code `TENON_CARDINALITY_MISMATCH`, `expected` (`one` or `oneOrNone`),
@@ -233,59 +230,59 @@ produce `AggregateError`.
 
 Optional `onQuery` observes completed calls with `label`, `durationMs`, `outcome`, and available
 `command`, `rowCount`, and `errorCode`. It receives no SQL or values. Validation failures before
-execution are not observed. Observers are not awaited; failures emit warnings without changing
-the query outcome. Query success inside a callback does not establish outer commit.
+execution are not observed. Observers are not awaited; failures emit warnings without changing the
+query outcome. Query success inside a callback does not establish outer commit.
 
 ## Generated types and checking
 
-`generateDefinitions({ connection, namespace?, onWarning? })` returns TypeScript declarations
-from a consistent read-only snapshot; it does not need migration files or history. The CLI writes
-them atomically. Default namespace is `public`; default output is `src/generated-schema.ts`.
-Both `.ts` and `.d.ts` outputs are supported. Commit exact output and exclude it from formatting.
+`generateDefinitions({ connection, namespace?, onWarning? })` returns TypeScript declarations from a
+consistent read-only snapshot; it does not need migration files or history. The CLI writes them
+atomically. Default namespace is `public`; default output is `src/generated-schema.ts`. Both `.ts`
+and `.d.ts` outputs are supported. Commit exact output and exclude it from formatting.
 
 ```sh
 npx tenon generate --out src/generated-schema.d.ts
 npx tenon generate --out src/generated-schema.d.ts --check
 ```
 
-`--check` never rewrites the file. Missing/stale output fails with a diagnostic and a short diff
-for changes. It compares the generated representation, not pending migrations or every database
-object. Output includes relation/constraint/index summaries and referenced domains, not function
-bodies, grants, or a complete schema fingerprint.
+`--check` never rewrites the file. Missing/stale output fails with a diagnostic and a short diff for
+changes. It compares the generated representation, not pending migrations or every database object.
+Output includes relation/constraint/index summaries and referenced domains, not function bodies,
+grants, or a complete schema fingerprint.
 
 Generation covers ordinary tables and partitioned roots. Views, foreign tables, and attached
 partitions need query-specific types. A missing namespace fails; an existing empty schema is valid.
 Exact table names are available through `Rows['users']`; valid nonreserved identifiers also receive
 named aliases. Use `Pick` for projections; a join or aggregate needs its actual selected shape.
 
-| PostgreSQL type                                | Read representation  | Generated write input                                        |
-| ---------------------------------------------- | -------------------- | ------------------------------------------------------------ |
-| smallint, integer, oid, real, double precision | `number`             | `number`                                                     |
-| bigint                                         | `string`             | `string \| bigint`                                           |
-| numeric                                        | `string`             | `string \| number`                                           |
-| boolean                                        | `boolean`            | `boolean`                                                    |
-| text, name, varchar, char, uuid, time, timetz  | `string`             | `string`                                                     |
-| date, timestamp, timestamptz                   | `Date`               | `Date \| string`                                             |
-| enum                                           | String literal union | Same union; `never` for an empty enum                        |
-| json, jsonb                                    | `unknown`            | `Exclude<JSONValue, null>`; `JSONValue` is exported by Tenon |
-| bytea                                          | `Buffer`             | `Buffer`                                                     |
-
-Nullable columns add null; `unknown` already includes it. Domains retain verified base mappings
-and the column's read nullability. Verified arrays use `PgArray<T> = (T | null | PgArray<T>)[]` for
-null elements and multiple dimensions. Numeric arrays contain strings; enum arrays and arrays of
-domains are unverified. Unmapped types warn and use `unknown` reads / `never` non-null writes.
+| PostgreSQL type                                | Read representation  | Generated write input                 |
+| ---------------------------------------------- | -------------------- | ------------------------------------- |
+| smallint, integer, oid, real, double precision | `number`             | `number`                              |
+| bigint                                         | `string`             | `string \| bigint`                    |
+| numeric                                        | `string`             | `string \| number`                    |
+| boolean                                        | `boolean`            | `boolean`                             |
+| text, name, varchar, char, uuid, time, timetz  | `string`             | `string`                              |
+| date, timestamp, timestamptz                   | `Date \| number`     | `Date \| string`                      |
+| enum                                           | String literal union | Same union; `never` for an empty enum |
+| json, jsonb                                    | `unknown`            | `string` containing encoded JSON      |
+| bytea                                          | `Buffer`             | `Buffer`                              |
+
+Nullable columns add null; `unknown` already includes it. Domains retain verified base mappings and
+the column's read nullability. Verified arrays use `PgArray<T> = (T | null | PgArray<T>)[]` for null
+elements and multiple dimensions. Numeric arrays contain numbers and can lose precision; select/cast
+them as text when exact values are required. Bigint arrays contain strings; enum arrays and arrays
+of domains are unverified. Unmapped types warn and use `unknown` reads / `never` non-null writes.
 Custom parsers need matching application types.
 
-Date-only parsing uses UTC; timestamps without time zone use Node's local timezone. Infinite
-temporal reads become invalid dates: check `Number.isFinite(value.getTime())` before date methods.
-Bound temporal values require finite dates; use SQL literals for PostgreSQL infinity.
+Date-only values and timestamps without time zone use Node's local timezone. Infinite temporal reads
+are numbers (`Infinity` or `-Infinity`); narrow with `value instanceof Date` before date methods.
+Temporal write inputs accept `Date | string`; use PostgreSQL's text `infinity` or `-infinity` when
+needed.
 
 ### Persistence and domain values
 
-Generated types describe storage representations. Text `CHECK` constraints do not become unions,
-and JSON reads remain unknown; validate before narrowing to domain types. Convert third-party
-payloads into validated native JSON-compatible objects rather than asserting compatibility or
-pre-serializing them. A bound null means SQL null; use `'null'::jsonb` for JSON null.
+Generated types describe storage representations. Text `CHECK` constraints do not become unions, and
+JSON reads remain unknown. Validate values before narrowing to application domain types.
 
 Bigint and `count(*)` reads are decimal strings. Use SQL or BigInt for exact arithmetic and decimal
 strings at JSON boundaries; convert to number only when bounded or approximate values are intended.
@@ -303,14 +300,14 @@ sql.assignments(patch);
 
 Insert fields are required when nonnullable, writable, and without a default. Other writable insert
 fields and all writable update fields are optional and accept explicit undefined, including with
-`exactOptionalPropertyTypes`. Explicit null requires both column and domain-chain permission.
-Domain defaults count; column defaults take precedence.
+`exactOptionalPropertyTypes`. Explicit null requires both column and domain-chain permission. Domain
+defaults count; column defaults take precedence.
 
 Computed and `GENERATED ALWAYS` identity columns use optional `never` fields. Serial and
-`GENERATED BY DEFAULT` identities are optional on insert and writable on update; other primary
-keys remain writable. Use `Pick`/`Omit` for application restrictions. Apply the generated types
-through annotations, `satisfies`, or helper generic arguments; they do not validate constraints,
-JSON structure, authorization, or nonempty input.
+`GENERATED BY DEFAULT` identities are optional on insert and writable on update; other primary keys
+remain writable. Use `Pick`/`Omit` for application restrictions. Apply the generated types through
+annotations, `satisfies`, or helper generic arguments; they do not validate constraints, JSON
+structure, authorization, or nonempty input.
 
 For unverified write mappings, provide a reviewed application-owned replacement, for example
 `Omit<Rows.Insert['events'], 'delay'> & { delay: string }` for interval text input. Selected columns
@@ -319,19 +316,20 @@ can discard required fields; see [the cookbook](mutations.md#input-types-and-run
 ## Query inspection
 
 `describeQuery({ connection, query, session?, timeouts? })` accepts a PostgreSQL URI and a finished
-SQL string or `{ text }` object. It returns PostgreSQL metadata, conservative read mappings and
-row declaration, session context, and coded findings. It does not bind values, execute the
-statement, or verify `sql<Row>`.
+SQL string or `{ text }` object. It returns PostgreSQL metadata, conservative read mappings and row
+declaration, session context, and coded findings. It does not bind values, execute the statement, or
+verify `sql<Row>`.
 
 Inspection owns a separate session with bounded timeouts. Match runtime settings; temporary tables,
-uncommitted changes, and custom parsers are not inherited. Nullability stays unknown. See
+and uncommitted changes are not inherited. Reported mappings assume pg's default parsers; parser
+overrides need matching application types. Nullability stays unknown. See
 [query inspection](query-inspection.md) for settings, result fields, issue codes, and testing.
 
 ## Command reference
 
-Database commands require `DATABASE_URL`. `new` and `--help` work offline. No environment files
-are loaded. Paths are relative to the working directory. Explicit flags unsupported by a command
-are rejected; `--check` is only a generation check, not a migration dry run.
+Database commands require `DATABASE_URL`. `new` and `--help` work offline. No environment files are
+loaded. Paths are relative to the working directory. Explicit flags unsupported by a command are
+rejected; `--check` is only a generation check, not a migration dry run.
 
 ```text
 tenon new <name> [--directory migrations]
@@ -356,10 +354,10 @@ file has down SQL before executing any; `steps` is a positive safe integer. Use
 function bodies and explicit `E'...'` backslash escapes. Nontransactional DDL such as
 `CREATE INDEX CONCURRENTLY` requires a separate procedure.
 
-Migration/status/rollback/adoption use session advisory locks per database and namespace;
-generation uses the same lock in shared mode. Use direct or session-pooled connections and server
-timeouts to bound waits. Baseline capture uses a local creation lock and native `pg_dump`;
-it does not acquire the runner's database advisory lock. See [adoption](adoption-guide.md).
+Migration/status/rollback/adoption use session advisory locks per database and namespace; generation
+uses the same lock in shared mode. Use direct or session-pooled connections and server timeouts to
+bound waits. Baseline capture uses a local creation lock and native `pg_dump`; it does not acquire
+the runner's database advisory lock. See [adoption](adoption-guide.md).
 
 Programmatic `migrate`, `migrationStatus`, and `rollback` accept
 `{ connection, directory?, namespace? }`; rollback also accepts `steps`. Migration/rollback return

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kequtech/tenon-orm",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "license": "ISC",
   "type": "module",
   "description": "A PostgreSQL ORM designed for coding agents, with explicit SQL, typed queries, and migrations",
@@ -54,7 +54,8 @@
     "benchmark": "npm run build && node scripts/benchmark.mjs"
   },
   "dependencies": {
-    "postgres": "3.4.9"
+    "pg": "8.23.1",
+    "@types/pg": "8.23.1"
   },
   "devDependencies": {
     "@types/node": "^24.19.2",

package/dist/driver/array.d.ts

@@ -1,5 +0,0 @@
-import type postgres from 'postgres';
-/** Preserve driver scalar parsers and serializers; replace only lossy array parsing. */
-export declare function prepareArrays(sql: postgres.Sql): Promise<void>;
-/** PostgreSQL text arrays: only unquoted NULL is null; quoted values use the scalar parser. */
-export declare function parseArray(text: string, parse: (value: string) => unknown, delimiter?: string): unknown[];

package/dist/driver/array.js

@@ -1,70 +0,0 @@
-const initialization = new WeakMap();
-/** Preserve driver scalar parsers and serializers; replace only lossy array parsing. */
-export function prepareArrays(sql) {
-    const existing = initialization.get(sql);
-    if (existing)
-        return existing;
-    const ready = (async () => {
-        const customArrays = new Set(Object.values(sql.options.types).flatMap((type) => type.from));
-        const arrays = await sql `
-      SELECT t.typarray AS oid, t.oid AS element, t.typdelim AS delimiter
-      FROM pg_catalog.pg_type t WHERE t.typarray <> 0`;
-        for (const type of arrays) {
-            if (customArrays.has(type.oid))
-                continue;
-            const scalar = sql.options.parsers[type.element] ?? ((value) => value);
-            sql.options.parsers[type.oid] = (value) => parseArray(value, scalar, type.delimiter);
-        }
-    })();
-    initialization.set(sql, ready);
-    void ready.catch(() => initialization.delete(sql));
-    return ready;
-}
-/** PostgreSQL text arrays: only unquoted NULL is null; quoted values use the scalar parser. */
-export function parseArray(text, parse, delimiter = ',') {
-    let position = text.startsWith('[') ? text.indexOf('=') + 1 : 0;
-    function array() {
-        if (text[position++] !== '{')
-            throw new Error('Invalid PostgreSQL array.');
-        const values = [];
-        while (position < text.length && text[position] !== '}') {
-            if (text[position] === '{')
-                values.push(array());
-            else {
-                let value = '';
-                const quoted = text[position] === '"';
-                if (quoted)
-                    position++;
-                while (position < text.length) {
-                    const char = text[position];
-                    if (char === '\\') {
-                        position++;
-                        value += text[position++] ?? '';
-                    }
-                    else if (quoted && char === '"') {
-                        position++;
-                        break;
-                    }
-                    else if (!quoted && (char === delimiter || char === '}'))
-                        break;
-                    else {
-                        value += char;
-                        position++;
-                    }
-                }
-                values.push(!quoted && value === 'NULL' ? null : parse(value));
-            }
-            if (text[position] === delimiter)
-                position++;
-            else if (text[position] !== '}')
-                throw new Error('Invalid PostgreSQL array separator.');
-        }
-        if (text[position++] !== '}')
-            throw new Error('Unterminated PostgreSQL array.');
-        return values;
-    }
-    const result = array();
-    if (position !== text.length)
-        throw new Error('Unexpected PostgreSQL array suffix.');
-    return result;
-}

package/dist/driver/lifecycle.d.ts

@@ -1,15 +0,0 @@
-import type postgres from 'postgres';
-export interface Watch {
-    failure?: Error;
-    check(): void;
-    closed: Promise<never>;
-    reject(error: Error): void;
-}
-interface State {
-    acquiring: Set<(error: Error) => void>;
-    active: Map<number, Watch>;
-    capture(marker: string, watch: Watch): () => void;
-}
-/** Observe the driver's public connection callbacks; never reuse a reconnected transaction. */
-export declare function observeConnections(sql: postgres.Sql): State;
-export {};

package/dist/driver/lifecycle.js

@@ -1,57 +0,0 @@
-const states = new WeakMap();
-function disconnected() {
-    return Object.assign(new Error('The reserved PostgreSQL connection closed.'), {
-        code: 'CONNECTION_CLOSED',
-    });
-}
-/** Observe the driver's public connection callbacks; never reuse a reconnected transaction. */
-export function observeConnections(sql) {
-    const previous = states.get(sql);
-    if (previous)
-        return previous;
-    const markers = new Map();
-    let debug = sql.options.debug;
-    // Capture the bootstrap connection ID, then restore debug before application work.
-    // Leaving it enabled would make the driver include SQL and values in enumerable errors.
-    const captureDebug = (id, text, values, types) => {
-        const watch = markers.get(text);
-        if (watch) {
-            state.active.set(id, watch);
-            markers.delete(text);
-        }
-        if (!markers.size)
-            sql.options.debug = debug;
-        if (typeof debug === 'function')
-            debug(id, text, values, types);
-    };
-    const state = {
-        acquiring: new Set(),
-        active: new Map(),
-        capture(marker, watch) {
-            if (!markers.size) {
-                debug = sql.options.debug;
-                sql.options.debug = captureDebug;
-            }
-            markers.set(marker, watch);
-            return () => {
-                markers.delete(marker);
-                if (!markers.size)
-                    sql.options.debug = debug;
-            };
-        },
-    };
-    const onclose = sql.options.onclose;
-    sql.options.onclose = (id) => {
-        const error = disconnected();
-        const watch = state.active.get(id);
-        if (watch) {
-            watch.failure ??= error;
-            watch.reject(watch.failure);
-        }
-        for (const reject of state.acquiring)
-            reject(error);
-        onclose?.(id);
-    };
-    states.set(sql, state);
-    return state;
-}

package/dist/driver/listener.d.ts

@@ -1,3 +0,0 @@
-import type postgres from 'postgres';
-/** Prevent an owned LISTEN client's queued reconnect from reopening it after shutdown. */
-export declare function guardListenerShutdown(sql: postgres.Sql): () => void;