@kequtech/tenon-orm 0.2.1 → 0.3.0

package/dist/migrations/history.d.ts

@@ -1,4 +1,4 @@
-import type { SqlConnection } from '../connection.js';
+import type { PoolClient } from 'pg';
 import type { SqlMigration } from './files.js';
 export declare const migrationTable = "__tenon_migrations";
 interface AppliedMigration {
@@ -6,7 +6,7 @@ interface AppliedMigration {
     name: string;
     checksum: string;
 }
-export declare function migrationState(client: SqlConnection, namespace: string, migrations: readonly SqlMigration[]): Promise<readonly AppliedMigration[]>;
-export declare function createHistoryTable(client: SqlConnection, namespace: string): Promise<void>;
-export declare function recordMigration(client: SqlConnection, namespace: string, migration: SqlMigration): Promise<void>;
+export declare function migrationState(client: PoolClient, namespace: string, migrations: readonly SqlMigration[]): Promise<readonly AppliedMigration[]>;
+export declare function createHistoryTable(client: PoolClient, namespace: string): Promise<void>;
+export declare function recordMigration(client: PoolClient, namespace: string, migration: SqlMigration): Promise<void>;
 export {};

package/dist/migrations/history.js

@@ -1,11 +1,11 @@
 import { qualified } from '../sql.js';
 export const migrationTable = '__tenon_migrations';
 export async function migrationState(client, namespace, migrations) {
-    const exists = await client.unsafe('SELECT to_regclass($1)::text AS name', [qualified(namespace, migrationTable)]);
-    if (exists[0].name === null) {
+    const exists = await client.query('SELECT to_regclass($1)::text AS name', [qualified(namespace, migrationTable)]);
+    if (exists.rows[0].name === null) {
         return [];
     }
-    const applied = await client.unsafe(`SELECT id, name, checksum FROM ${qualified(namespace, migrationTable)} ORDER BY id::numeric`);
+    const { rows: applied } = await client.query(`SELECT id, name, checksum FROM ${qualified(namespace, migrationTable)} ORDER BY id::numeric`);
     for (const [i, record] of applied.entries()) {
         const file = migrations[i];
         if (!file ||
@@ -18,7 +18,7 @@ export async function migrationState(client, namespace, migrations) {
     return applied;
 }
 export async function createHistoryTable(client, namespace) {
-    await client.unsafe(`CREATE TABLE IF NOT EXISTS ${qualified(namespace, migrationTable)} (
+    await client.query(`CREATE TABLE IF NOT EXISTS ${qualified(namespace, migrationTable)} (
       id TEXT PRIMARY KEY CHECK (id ~ '^[0-9]+$'),
       name TEXT NOT NULL,
       checksum TEXT NOT NULL,
@@ -26,5 +26,5 @@ export async function createHistoryTable(client, namespace) {
     )`);
 }
 export async function recordMigration(client, namespace, migration) {
-    await client.unsafe(`INSERT INTO ${qualified(namespace, migrationTable)} (id, name, checksum) VALUES ($1, $2, $3)`, [migration.id, migration.name, migration.checksum]);
+    await client.query(`INSERT INTO ${qualified(namespace, migrationTable)} (id, name, checksum) VALUES ($1, $2, $3)`, [migration.id, migration.name, migration.checksum]);
 }

package/dist/migrations.js

@@ -28,25 +28,25 @@ async function execute(options, direction, steps) {
         if (!selected.length) {
             return [];
         }
-        await client.unsafe(`CREATE SCHEMA IF NOT EXISTS ${quote(namespace)}`);
+        await client.query(`CREATE SCHEMA IF NOT EXISTS ${quote(namespace)}`);
         await createHistoryTable(client, namespace);
         const completed = [];
         for (const file of selected) {
             try {
-                await client.unsafe('BEGIN');
+                await client.query('BEGIN');
                 // Match the string-literal rules used by the authored migration scanner.
-                await client.unsafe('SET LOCAL standard_conforming_strings TO on');
-                await client.unsafe(`SET LOCAL search_path TO ${quote(namespace)}, pg_catalog`);
-                await client.unsafe(direction === 'up' ? file.up : file.down);
+                await client.query('SET LOCAL standard_conforming_strings TO on');
+                await client.query(`SET LOCAL search_path TO ${quote(namespace)}, pg_catalog`);
+                await client.query(direction === 'up' ? file.up : file.down);
                 if (direction === 'up') {
                     await recordMigration(client, namespace, file);
                 }
                 else {
-                    await client.unsafe(`DELETE FROM ${qualified(namespace, migrationTable)} WHERE id = $1`, [
+                    await client.query(`DELETE FROM ${qualified(namespace, migrationTable)} WHERE id = $1`, [
                         file.id,
                     ]);
                 }
-                const result = await client.unsafe('COMMIT');
+                const result = await client.query('COMMIT');
                 if (result.command !== 'COMMIT') {
                     throw new Error('The migration transaction was rolled back.');
                 }

package/dist/query-options.js

@@ -1,5 +1,6 @@
 import { validateAffectedRows } from './affected-rows.js';
 import { plainObject } from './validation.js';
+import { CardinalityError } from './errors.js';
 export function validateOptions(options) {
     const config = options === undefined ? {} : plainObject(options, 'Query options');
     for (const key of Object.keys(config)) {
@@ -26,10 +27,9 @@ export function queryOutput(options, result) {
     if (options.returns === 'native')
         return result;
     if (options.returns === 'many')
-        return [...result];
-    const expected = options.returns === 'oneOrNone' ? 'at most one row' : 'exactly one row';
-    if (result.length > 1 || (options.returns === 'one' && result.length === 0)) {
-        throw new Error(`${options.label ?? 'Query'} expected ${expected}, but returned ${result.length} rows.`);
+        return result.rows;
+    if (result.rows.length > 1 || (options.returns === 'one' && result.rows.length === 0)) {
+        throw new CardinalityError(options.returns === 'oneOrNone' ? 'oneOrNone' : 'one', result.rows.length, options.label);
     }
-    return result[0];
+    return result.rows[0];
 }

package/dist/query.js

@@ -110,8 +110,8 @@ export function unsafeSql(text, values) {
         throw new Error('SQL must be a nonempty string.');
     if (!Array.isArray(values))
         throw new Error('SQL input must be an explicit array.');
-    if (values.length > 65533)
-        throw new Error(`Postgres.js 3.4.9 supports at most 65533 bound parameters; received ${values.length}. Split large batches explicitly.`);
+    if (values.length > 65535)
+        throw new Error(`PostgreSQL supports at most 65535 bound parameters; received ${values.length}. Split large batches explicitly.`);
     return Object.freeze({ [queryTag]: true, text, values: Object.freeze([...values]) });
 }
 export function assertQuery(value) {

package/dist/transaction.d.ts

@@ -1,4 +1,4 @@
-import type postgres from 'postgres';
+import type { Pool } from 'pg';
 import type { QueryExecutor } from './connection.js';
 /** The callback owns one connection and expires before commit or rollback begins. */
-export declare function withTransaction<T>(pool: postgres.Sql, work: (query: QueryExecutor) => Promise<T>): Promise<T>;
+export declare function withTransaction<T>(pool: Pool, work: (query: QueryExecutor) => Promise<T>): Promise<T>;

package/dist/transaction.js

@@ -1,11 +1,11 @@
-import { reserveConnection } from './driver/session.js';
-import { executeSql } from './connection.js';
+import { executeSql, watchClient } from './connection.js';
 /** The callback owns one connection and expires before commit or rollback begins. */
 export async function withTransaction(pool, work) {
-    const connection = await reserveConnection(pool, 'BEGIN');
-    const client = connection.sql;
+    const client = await pool.connect();
+    const connection = watchClient(client);
     let active = true;
-    let discard = false;
+    let began = false;
+    let releaseError;
     let savepointId = 0;
     let pending = Promise.resolve();
     let recoveryFailure;
@@ -21,16 +21,16 @@ export async function withTransaction(pool, work) {
             if (!guarded)
                 return readResult(await executeSql(client, text, input));
             const savepoint = `tenon_affected_rows_${++savepointId}`;
-            await client.unsafe(`SAVEPOINT ${savepoint}`);
+            await client.query(`SAVEPOINT ${savepoint}`);
             try {
                 const result = readResult(await executeSql(client, text, input));
-                await client.unsafe(`RELEASE SAVEPOINT ${savepoint}`);
+                await client.query(`RELEASE SAVEPOINT ${savepoint}`);
                 return result;
             }
             catch (error) {
                 try {
-                    await client.unsafe(`ROLLBACK TO SAVEPOINT ${savepoint}`);
-                    await client.unsafe(`RELEASE SAVEPOINT ${savepoint}`);
+                    await client.query(`ROLLBACK TO SAVEPOINT ${savepoint}`);
+                    await client.query(`RELEASE SAVEPOINT ${savepoint}`);
                 }
                 catch (rollbackError) {
                     // Even if application code catches this error, the outer transaction
@@ -45,13 +45,15 @@ export async function withTransaction(pool, work) {
         return operation;
     };
     try {
+        await client.query('BEGIN');
+        began = true;
         const result = await work(query);
         active = false;
         await pending;
         connection.check();
         if (recoveryFailure)
             throw recoveryFailure;
-        const committed = await client.unsafe('COMMIT');
+        const committed = await client.query('COMMIT');
         if (committed.command !== 'COMMIT') {
             throw new Error('PostgreSQL rolled back the aborted transaction.');
         }
@@ -60,17 +62,20 @@ export async function withTransaction(pool, work) {
     catch (error) {
         active = false;
         await pending;
+        if (!began) {
+            releaseError = error instanceof Error ? error : new Error('BEGIN failed.');
+            throw error;
+        }
         try {
-            connection.check();
-            await client.unsafe('ROLLBACK');
+            await client.query('ROLLBACK');
         }
         catch (rollbackError) {
-            discard = true;
+            releaseError = rollbackError instanceof Error ? rollbackError : new Error('Rollback failed.');
             throw new AggregateError([error, rollbackError], 'Transaction and rollback failed.');
         }
         throw error;
     }
     finally {
-        await connection.release(discard);
+        connection.release(releaseError);
     }
 }

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type postgres from 'postgres';
+import type { Pool } from 'pg';
 import type { QueryResult } from './connection.js';
 import type { QueryOptions, QueryOutput, QueryReturnMode } from './query-options.js';
 import type { SqlQuery } from './query.js';
@@ -12,12 +12,16 @@ export interface QueryClient {
     query<Row extends object>(query: SqlQuery<Row>, options: QueryOptions | undefined): NoInfer<Promise<QueryOutput<Row, QueryReturnMode>>>;
 }
 export type Transaction = QueryClient;
+export interface CloseOptions {
+    /** Grace period before requesting owned driver termination; milliseconds, default 5000. */
+    readonly timeoutMs?: number | undefined;
+}
 export type Database = Transaction & {
     /** The underlying pool-level driver client; native calls bypass Tenon's query and transaction guards. */
-    readonly native: postgres.Sql;
+    readonly native: Pool;
     /** Await all work inside the callback. Commit on success; rollback on an escaping error. */
     transaction<T>(callback: (tx: Transaction) => Promise<T>): Promise<T>;
-    close(): Promise<void>;
+    close(options?: CloseOptions): Promise<void>;
 };
 /** One completed public query call, including rollback/commit time for guarded calls. */
 export interface QueryEvent {

package/docs/adoption-guide.md

@@ -1,151 +1,138 @@
-# Adopting Tenon from another ORM
+# Adopting Tenon
 
-This guide covers replacing an existing ORM and, separately, transferring migration ownership. For a
-query tutorial use the [human guide](human-guide.md); for API details use the
-[reference](reference.md). Preserve the existing schema, connection configuration, data, and
-application behavior while replacing the old ORM. Tenon does not need to own migrations to execute
-queries or generate types; keep the existing migration runner if that is the intended scope.
+Replace application queries independently of migration ownership. Tenon can query an existing schema
+and generate types while the current migration runner stays in place. For a Tenon version upgrade,
+read the [Changelog](../CHANGELOG.md).
 
-## Replace application queries
+## Preserve connections and behavior
 
-1. Locate the old ORM's connection setup, schema, migrations, and call sites. Identify behavior
-   supplied by the ORM: validation, IDs, timestamps, hooks, defaults, relation loading,
-   serialization, and transaction boundaries.
-2. If row and mutation input types will help your application, generate them from the existing database:
+Keep the existing database URI, credentials, TLS requirements, schema, and data. Tenon can add
+driver settings through pg configuration:
 
-   ```sh
-   npx tenon generate --out src/generated-schema.d.ts
-   ```
-
-   Use `--namespace name` for a non-public schema. Generation reads the actual database and requires
-   no Tenon migration history.
-
-3. Replace queries with parameterized SQL in ordinary functions with named object inputs where
-   useful. Preserve each caller's projection, null handling, ordering, and transaction behavior.
-   Generated types describe Postgres.js values: check bigint/numeric strings, dates, JSON, and arrays when
-   the old ORM transformed them.
-4. Inspect completed queries and test their behavior using the
-   [inspection workflow](#inspect-queries-during-adoption) below. Declare result types explicitly
-   and run tests against a dedicated test database. Verify
-   writes and rollback, relationships, validation, and any hooks you moved into application code or
-   SQL. A schema-preserving first release makes application rollback easier.
-5. Remove the old runtime dependency and unused generated code after its callers are gone. Keep the
-   migration tooling until the migration transition below is complete, if that transition is part of
-   the work.
+```ts
+import { createTenon } from '@kequtech/tenon-orm';
+
+const db = createTenon({
+  connection: {
+    connectionString: existingUri,
+    connectionTimeoutMillis: 5000,
+  },
+});
+```
 
-For driver features such as LISTEN or COPY, use [`db.native`](reference.md#native-driver-access).
-Preserve the application's notification recovery and resource ownership. Native pool queries do
-not join Tenon transactions; use `tx.query` for operations that must commit together.
+Translate old driver configuration into pg `PoolConfig` rather than passing it through. Pool
+timeouts use milliseconds. Preserve runtime `search_path` through the pg startup options string, for
+example `options: '-c search_path=app,public'`. URI startup options take precedence when both are
+supplied. CLI `--namespace` does not change runtime queries. See
+[connection options](reference.md#installation-and-connection).
 
-## Replace local write helpers
+Before conversion, identify behavior supplied by the old ORM: IDs/defaults, timestamps, validation,
+hooks, serialization, relationships, and transaction boundaries. Preserve it explicitly in
+application code or SQL where required.
 
-Use `sql.insertValues(rows)` and `sql.assignments(patch)` in place of local object-to-SQL utilities:
+## Replace queries
 
-```ts
-import { sql } from '@kequtech/tenon-orm';
+1. Optionally generate persistence types from the existing schema:
 
-const insert = sql`INSERT INTO profiles ${sql.insertValues(rows)} RETURNING id`;
-const update = sql`UPDATE profiles SET ${sql.assignments(patch)} WHERE id = ${id}`;
-```
+   ```sh
+   npx tenon generate --namespace public --out src/generated-schema.d.ts
+   ```
 
-Compare omission, defaults, nulls, and empty-input behavior with the old helpers. Keep expressions
-in SQL and remove the local utilities after their callers move. Generated `Rows.Insert` and
-`Rows.Update` types can replace handwritten table inputs; retain application-specific refinements
-and validation. Run the existing write and rollback workflows. See the [mutation cookbook](mutations.md).
+   This needs no Tenon migration history. Use the application's namespace and commit exact output.
 
-## Inspect queries during adoption
+2. Replace queries with parameterized SQL in ordinary functions accepting `QueryClient` where
+   callers may supply `db` or `tx`. Retain projections, ordering, null handling, and authorization.
+3. Review value conversions against [Tenon's mappings](reference.md#generated-types-and-checking):
+   numeric values, dates, arrays, and JSON serialization may differ from the previous driver.
+   Generated declarations do not replace domain validation.
+4. Inspect meaningful completed query variants and run database assertions for actual rows,
+   permissions, write effects, and rollback. See [query inspection](query-inspection.md).
+5. Remove unused runtime dependencies and generated code after their callers are gone. Dependencies
+   retained by other application code or installed transitively may still be needed.
 
-Use `describeQuery` from `@kequtech/tenon-orm` on the completed query object, or
-`npx tenon describe query.sql` on a SQL file. Inspection is available with the normal Tenon
-installation and uses no TypeScript compiler API. It works with helpers and runtime-built
-fragments because it receives the final SQL. See [query inspection](query-inspection.md).
+Check cardinality when replacing a first-row accessor. `oneOrNone` rejects multiple rows and `one`
+also rejects zero rows. Use deterministic `ORDER BY` plus `LIMIT 1` when choosing one of several
+matches is intended; modes do not add a limit.
 
-Reuse the application's connection URI and session configuration; compare the reported role,
-search path, and timezone with execution. Inspection uses a separate connection and Postgres.js
-read mappings. Custom parsers and transaction-local state remain application responsibilities.
+Use `sql.insertValues` and `sql.assignments` to replace object-to-SQL utilities, checking omission,
+default, null, and empty-input semantics. Generated `Rows.Insert`/`Rows.Update` types can replace
+handwritten persistence inputs. See the [mutation cookbook](mutations.md).
 
-Pair descriptions with durable database tests of actual rows and effects. For each converted
-query, cover the meaningful filter/ownership branches, null relationships, JSON structure, empty
-results, ordering/cursors, and transaction failure/replay behavior as applicable. Describe's success
-does not verify a TypeScript annotation or prove that execution is permitted or succeeds. Preserve
-existing authorization policy and transaction boundaries while making queries available to tests.
+Use `tx.query` for work that must commit together. Native pool calls do not join Tenon transactions.
+For driver features, preserve resource ownership and recovery policy under the
+[native access contract](reference.md#native-driver-access).
 
-Keep these tests in routine validation. A described query instance does not cover untested source
-queries or detect stale annotations elsewhere.
+## Transfer migration ownership
 
-## Move migration ownership to Tenon
+Choose one final checkpoint for the old runner. Bring existing databases to it and disable that
+runner before handover; the runners do not share locks. Capture from a trusted reference database,
+preferably a disposable replay of the legacy migrations.
 
-Choose one final schema checkpoint for the old runner and bring existing target databases to it.
-Disable its migration/schema synchronization before handing ownership to Tenon. The tools do not
-share locks.
+### Capture a baseline
 
-Capture one baseline from the reference database into an empty migration directory:
+For an application owning `app` in a shared database:
 
 ```sh
-npx tenon baseline capture --directory migrations --namespace public
+npx tenon baseline capture --directory migrations --namespace app --schema app
 ```
 
-This uses native `pg_dump --schema-only --no-owner --no-privileges` and writes
-`0001_baseline.up.sql` without a down file. It requires a compatible `pg_dump` on PATH; prefer the
-server's major. Default scope is the whole database schema. Repeat `--schema name` to select schemas
-explicitly, accounting for dependencies, extensions, and required roles. Tenon's selected history
-table is excluded; old ORM metadata is preserved for deliberate cleanup later.
-
-The baseline recreates application schema, not a complete deployment environment. It omits
-ownership, grants/revokes, and default privileges. PostgreSQL creates replayed objects under the
-migration role. Role definitions and memberships also remain outside the dump. Functions,
-policies, or other object definitions can still refer to roles; provision any referenced roles
-before replay. See the [PostgreSQL pg_dump reference](https://www.postgresql.org/docs/16/app-pgdump.html).
-
-For `SECURITY DEFINER` functions, the owner determines execution authority, and newly created
-functions ordinarily permit `PUBLIC` execution. A captured function body alone does not preserve
-its original security boundary. Keep fixed application policy, such as revoking `PUBLIC` execution,
-in reviewed SQL in the baseline before its first adoption or in a subsequent application migration.
-Deployment provisioning assigns the intended owners, schema access, and grants to runtime roles.
-Keeping all security setup in provisioning is also supported, provided it runs before application access.
-
-On fresh environments, provision required roles, apply migrations, then apply the deployment's
-ownership/grant policy before starting the application. Verify both allowed and denied operations,
-including execution of sensitive functions and access to their underlying tables. For a shared
-database, apply only the selected application's policy. On existing environments, confirm the same
-provisioning procedure is repeatable. After adoption, use subsequent migrations rather than editing
-checksummed history.
-
-Capture changes no source data, migration history, or sequence positions. Review and commit the SQL.
-Keep the capture header: it identifies native dump SQL that bypasses the authored-migration scanner.
-It is a convention, not proof of provenance; do not use it on handwritten migrations. Normal
-transactional execution and checksums still apply.
-
-On each existing database already at that checkpoint:
-
-```sh
-npx tenon baseline adopt
-```
+The directory must contain no SQL files. Capture uses native
+`pg_dump --schema-only --no-owner --no-privileges` and writes `0001_baseline.up.sql` with no down
+file. Install compatible PostgreSQL client tools on PATH; prefer the server's major version.
 
-Adoption records the baseline checksum without executing the SQL or comparing schemas. It requires
-the selected namespace to exist. Repeating matching adoption is harmless, including after later
-migrations; conflicting history fails.
+| Option                | Scope                                                                                |
+| --------------------- | ------------------------------------------------------------------------------------ |
+| `--namespace app`     | Tenon history table to exclude from capture; history/runner scope for later commands |
+| `--schema app`        | Objects selected by native `pg_dump`; repeat to select additional schemas            |
+| Runtime `search_path` | Configured independently on the application connection                               |
 
-On a fresh database, run migrations instead:
+Omitting `--schema` captures the whole database schema, even with a custom namespace. Capture does
+not modify source data/history or preserve sequence positions. It excludes Tenon's selected history
+table but can retain the old runner's metadata tables. Review and commit the SQL. Preserve the
+capture header, which opts this reviewed dump into native baseline parsing; do not add it to
+handwritten migrations.
 
-```sh
-npx tenon migrate
-```
+A scoped dump can refer to objects it does not include. Provision external schemas, functions,
+extensions, and referenced roles before they are needed. A fresh replay must execute representative
+operations, not just reproduce generated relation types. Tenon requires no particular extension.
 
-That executes the baseline and subsequent migrations. Use the same committed baseline for every
-environment. Do not run adoption unconditionally on fresh databases. Existing databases adopt once
-and then use ordinary `migrate`.
+### Check and adopt an existing database
 
-Use the development [`db:migrate` script](human-guide.md#create-a-table) to apply subsequent
-migrations and update table types together. Production continues to run only `npx tenon migrate`.
-Verify both an existing database's upgrade and a fresh replay. Baselines contain schema only; they
-do not back up rows or sequence positions. The missing down file prevents normal rollback through
-the baseline. Keep the application's backup and recovery procedure.
+Verify the final legacy checkpoint before adoption. If using schema comparisons, freeze separate
+reference definitions rather than comparing against types regenerated after later migrations.
+`generateDefinitions` covers relation metadata, not functions or privileges; include reviewed
+catalog checks for other objects the application needs. Tenon does not perform these comparisons.
 
-Programmatic equivalents:
+```sh
+npx tenon baseline adopt --directory migrations --namespace app
+npx tenon migrate --directory migrations --namespace app
+```
 
-- `captureBaseline({ connection, directory?, namespace?, schemas?, onWarning? })` requires a
-  nonempty native libpq connection string and returns `{ id, upPath }`. Omit `schemas` for the whole
-  database schema; an explicitly empty list is rejected.
-- `adoptBaseline({ connection, directory?, namespace? })` accepts the usual Tenon connection options
-  and returns newly recorded migration IDs.
+Adoption records the baseline checksum without executing its SQL. The namespace must already exist.
+Repeating matching adoption is harmless, including after later migrations; history conflicts fail.
+Once Tenon owns history, add forward migrations rather than editing the baseline.
+
+### Replay a fresh database
+
+Run `tenon migrate --directory migrations --namespace app`, without adoption. It executes the same
+committed baseline and subsequent migrations. Apply the deployment's required roles, ownership, and
+grants before application access.
+
+The portable baseline omits ownership, grants/revokes, and default privileges. Objects are recreated
+under the migration role. For `SECURITY DEFINER` functions, that owner controls execution authority,
+and new functions ordinarily permit `PUBLIC` execution. Keep fixed policy such as revoking public
+execution in reviewed baseline SQL before first adoption or in a forward migration. Deployment
+provisioning supplies named roles, owners, and grants. Verify permitted and denied operations on
+both adopted and fresh environments. See the
+[pg_dump contract](https://www.postgresql.org/docs/16/app-pgdump.html).
+
+For development, generate types after migrating; production runs migrations and consumes committed
+types. Test existing-row preservation, repeatable adoption, subsequent migrations, and fresh replay.
+A schema-only baseline and down migration are not backups. The missing down file prevents rollback
+across the baseline; use the application's backup/recovery procedure for that boundary.
+
+Programmatic capture is
+`captureBaseline({ connection, directory?, namespace?, schemas?, onWarning? })` and returns
+`{ id, upPath }`. It requires a native libpq connection string; an explicitly empty `schemas` list
+fails. `adoptBaseline({ connection, directory?, namespace? })` accepts Tenon's runtime connection
+forms and returns newly recorded IDs.