@kequtech/tenon-orm 0.4.2 → 0.4.4

package/dist/database.js

@@ -1,8 +1,9 @@
 import { createClient } from './client.js';
-import { createConnection, executeSql } from './connection.js';
+import { createConnection, executeSql, isPool } from './connection.js';
+import { configConnection } from './config/connection.js';
+import { configObject } from './config/validate.js';
 import { withTransaction } from './transaction.js';
 import { plainObject } from './validation.js';
-import { generateTypes } from './generate.js';
 function closeTimeout(options) {
     const settings = plainObject(options === undefined ? {} : options, 'Close options');
     for (const key of Object.keys(settings)) {
@@ -18,38 +19,40 @@ function closeTimeout(options) {
     }
     return timeoutMs;
 }
-export function createTenon(options) {
-    for (const key of Object.keys(plainObject(options, 'Tenon options'))) {
-        if (key !== 'connection' && key !== 'onQuery') {
-            throw new Error(`Unknown Tenon option: ${key}`);
-        }
-    }
-    if (options.onQuery !== undefined && typeof options.onQuery !== 'function') {
-        throw new Error('onQuery must be a function.');
-    }
-    const { pool, close } = createConnection(options.connection);
+export function createTenon(config) {
+    configObject(config);
+    const onQuery = config.onQuery;
+    let connection;
     let closing;
     function checkOpen() {
         if (closing) {
             throw new Error('This database instance is closed.');
         }
     }
+    function currentConnection() {
+        if (!connection) {
+            checkOpen();
+            const value = config.connection;
+            connection = createConnection(isPool(value) ? value : configConnection(value));
+        }
+        return connection;
+    }
     const query = (text, input, readResult, guarded) => {
         checkOpen();
+        const { pool } = currentConnection();
         if (guarded)
             return withTransaction(pool, (query) => query(text, input, readResult, false));
         return executeSql(pool, text, input).then(readResult);
     };
     return {
-        ...createClient(query, options.onQuery),
-        native: pool,
-        async generateTypes(options) {
-            checkOpen();
-            await generateTypes(pool, options);
+        ...createClient(query, onQuery),
+        get native() {
+            return currentConnection().pool;
         },
         async transaction(callback) {
             checkOpen();
-            return withTransaction(pool, (query) => callback(createClient(query, options.onQuery)));
+            const { pool } = currentConnection();
+            return withTransaction(pool, (query) => callback(createClient(query, onQuery)));
         },
         close(options) {
             if (closing)
@@ -57,7 +60,7 @@ export function createTenon(options) {
             try {
                 const timeoutMs = closeTimeout(options);
                 // Cache before invoking driver callbacks, so reentrant/concurrent callers share shutdown.
-                closing = Promise.resolve().then(() => close(timeoutMs));
+                closing = Promise.resolve().then(() => connection?.close(timeoutMs));
                 return closing;
             }
             catch (error) {

package/dist/describe.js

@@ -23,6 +23,8 @@ export async function describeQuery(options) {
             ? { parameterTypes: [...options.query.parameterTypes] }
             : {}),
     };
-    const codecs = options.codecs ?? defaultCodecs;
+    const codecs = options.codecs ??
+        (typeof options.connection === 'object' ? options.connection?.codecs : undefined) ??
+        defaultCodecs;
     return withInspectionConnection(options, async (client, context) => queryDescription(await readStatementMetadata(client, query), context, codecs));
 }

package/dist/generate.d.ts

@@ -4,16 +4,5 @@ export interface GenerateOptions {
     readonly namespace?: string;
     readonly onWarning?: (message: string) => void | Promise<void>;
 }
-export interface GenerateTypesOptions {
-    /** Output path, resolved from the working directory. */
-    readonly out: string;
-    /** Schema to inspect; defaults to public. */
-    readonly namespace?: string;
-    /** Reject missing or stale output without writing. Defaults to false. */
-    readonly check?: boolean;
-    readonly onWarning?: (message: string) => void | Promise<void>;
-}
-/** Generate with the owning database's connection and preserve exact file freshness checks. */
-export declare function generateTypes(connection: Connection, options: GenerateTypesOptions): Promise<void>;
 /** Read one schema snapshot with default catalog codecs and the selected application read mappings. */
 export declare function generateDefinitions(options: GenerateOptions): Promise<string>;

package/dist/generate.js

@@ -4,32 +4,7 @@ import { renderDatabase } from './generation/render.js';
 import { domainSummaries, schemaSummary, tableSummary } from './generation/schema-summary.js';
 import { withMigrationLock } from './migrations/connection.js';
 import { migrationTable } from './migrations/history.js';
-import { quote, validateName } from './sql.js';
-import { plainObject } from './validation.js';
-import { writeDefinitions } from './generation/output.js';
-/** Generate with the owning database's connection and preserve exact file freshness checks. */
-export async function generateTypes(connection, options) {
-    const config = plainObject(options, 'Generation options');
-    for (const key of Object.keys(config)) {
-        if (!['out', 'namespace', 'check', 'onWarning'].includes(key)) {
-            throw new Error(`Unknown generation option: ${key}`);
-        }
-    }
-    if (typeof config.out !== 'string' || !config.out.trim() || config.out.includes('\0')) {
-        throw new Error('Generation out must be a nonempty file path.');
-    }
-    if (config.check !== undefined && typeof config.check !== 'boolean') {
-        throw new Error('Generation check must be a boolean.');
-    }
-    if (options.namespace !== undefined)
-        validateName(options.namespace);
-    const source = await generateDefinitions({
-        connection,
-        ...(options.namespace !== undefined && { namespace: options.namespace }),
-        ...(options.onWarning !== undefined && { onWarning: options.onWarning }),
-    });
-    await writeDefinitions(source, config.out, config.check === true);
-}
+import { quote } from './sql.js';
 /** Read one schema snapshot with default catalog codecs and the selected application read mappings. */
 export async function generateDefinitions(options) {
     if (options.onWarning !== undefined && typeof options.onWarning !== 'function') {

package/dist/generation/output.js

@@ -14,10 +14,10 @@ export async function writeDefinitions(source, filename, check) {
             if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) {
                 throw error;
             }
-            throw new Error(`Generated definitions file is missing: ${output}\nRun db.generateTypes with the same options and check: false, then commit the result.`);
+            throw new Error(`Generated definitions file is missing: ${output}\nRun tenon generate with the same options, omitting --check, then commit the result.`);
         }
         if (existing !== source) {
-            throw new Error(`Generated definitions differ: ${output}\n${definitionDiff(existing, source)}\nRun db.generateTypes with the same options and check: false, then commit the result.`);
+            throw new Error(`Generated definitions differ: ${output}\n${definitionDiff(existing, source)}\nRun tenon generate with the same options, omitting --check, then commit the result.`);
         }
         return;
     }

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 export { builtin, createTemporalCodecs, defaultCodecs, json, param } from '@kequtech/pgclear';
 export type { Codec, CodecRegistry, Parameter, PgArray, TemporalConstructors, TemporalInput, } from '@kequtech/pgclear';
-export type { Connection, ConnectionOptions, QueryResult } from './connection.js';
+export type { Connection, ConnectionConfig, ConnectionOptions, QueryResult } from './connection.js';
 export type { AffectedRowsConstraint } from './affected-rows.js';
 export { createTenon } from './database.js';
-export type { TenonOptions } from './database.js';
+export type { TenonConfig } from './config.js';
 export { AffectedRowsError, CardinalityError } from './errors.js';
 export type { QueryOptions, QueryOutput, QueryReturnMode } from './query-options.js';
 export { identifier, sql, unsafeSql } from './query.js';
@@ -14,7 +14,7 @@ export type { DescribeOptions, DescribedColumn, DescribedType, DescriptionIssue,
 export { adoptBaseline, captureBaseline } from './baseline.js';
 export type { CaptureBaselineOptions, CapturedBaseline } from './baseline.js';
 export { generateDefinitions } from './generate.js';
-export type { GenerateOptions, GenerateTypesOptions } from './generate.js';
+export type { GenerateOptions } from './generate.js';
 export { migrate, migrationStatus, rollback } from './migrations.js';
 export type { MigrationStatus } from './migrations.js';
 export type { DatabaseToolOptions } from './migrations/connection.js';

package/dist/inspection/cli.d.ts

@@ -21,9 +21,9 @@ export declare const describeFlags: {
 /** Translate CLI flags; validation and defaults belong to the public API. */
 export declare function inspectionSettings(values: Partial<Record<keyof typeof describeFlags, string | undefined>>): {
     session: {
-        role: string | undefined;
-        searchPath: string | undefined;
-        timeZone: string | undefined;
+        timeZone?: string;
+        searchPath?: string;
+        role?: string;
     };
     timeouts: {
         lockMs?: number;
@@ -31,4 +31,3 @@ export declare function inspectionSettings(values: Partial<Record<keyof typeof d
         connectMs?: number;
     };
 };
-export declare function runDescribe(filename: string, connection: string, values: Partial<Record<keyof typeof describeFlags, string | undefined>>): Promise<void>;

package/dist/inspection/cli.js

@@ -1,5 +1,3 @@
-import { readFile } from 'node:fs/promises';
-import { describeQuery } from '../describe.js';
 export const describeFlags = {
     role: { type: 'string' },
     'search-path': { type: 'string' },
@@ -12,9 +10,9 @@ export const describeFlags = {
 export function inspectionSettings(values) {
     return {
         session: {
-            role: values.role,
-            searchPath: values['search-path'],
-            timeZone: values['time-zone'],
+            ...(values.role !== undefined && { role: values.role }),
+            ...(values['search-path'] !== undefined && { searchPath: values['search-path'] }),
+            ...(values['time-zone'] !== undefined && { timeZone: values['time-zone'] }),
         },
         timeouts: {
             ...(values['connect-timeout-ms'] !== undefined
@@ -29,11 +27,3 @@ export function inspectionSettings(values) {
         },
     };
 }
-export async function runDescribe(filename, connection, values) {
-    const result = await describeQuery({
-        connection,
-        query: await readFile(filename, 'utf8'),
-        ...inspectionSettings(values),
-    });
-    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-}

package/dist/inspection/connection.js

@@ -1,27 +1,30 @@
-import { connect } from '@kequtech/pgclear';
+import { createPool, defaultCodecs } from '@kequtech/pgclear';
 import { inspectionOptions } from './options.js';
 export async function withInspectionConnection(options, work) {
-    const { url, limits, session } = inspectionOptions(options);
-    const connection = await connect({
-        connectionString: url.toString(),
+    const { connection, limits, session } = inspectionOptions(options);
+    const pool = createPool({
+        ...connection,
+        codecs: defaultCodecs,
+        maxConnections: 1,
         connectTimeoutMs: limits.connectMs,
         startupParameters: {
+            ...Object.fromEntries(Object.entries(connection.startupParameters ?? {}).filter(([name]) => !['statement_timeout', 'lock_timeout'].includes(name.toLowerCase()))),
             statement_timeout: String(limits.statementMs),
             lock_timeout: String(limits.lockMs),
         },
     });
-    const client = connection;
     try {
-        for (const [key, name] of [
-            ['role', 'role'],
-            ['searchPath', 'search_path'],
-            ['timeZone', 'TimeZone'],
-        ]) {
-            const value = session[key];
-            if (value !== undefined)
-                await client.queryClassic('SELECT pg_catalog.set_config($1, $2, false)', [name, value]);
-        }
-        const { rows: [context], } = await client.queryClassic(`
+        return await pool.withSession(async (client) => {
+            for (const [key, name] of [
+                ['role', 'role'],
+                ['searchPath', 'search_path'],
+                ['timeZone', 'TimeZone'],
+            ]) {
+                const value = session[key];
+                if (value !== undefined)
+                    await client.queryClassic('SELECT pg_catalog.set_config($1, $2, false)', [name, value]);
+            }
+            const { rows: [context], } = await client.queryClassic(`
       SELECT pg_catalog.current_database() AS database,
         session_user AS "sessionUser", current_user AS "currentUser",
         pg_catalog.current_setting('search_path') AS "searchPath",
@@ -32,11 +35,12 @@ export async function withInspectionConnection(options, work) {
         (SELECT setting::integer FROM pg_catalog.pg_settings
           WHERE name = 'lock_timeout') AS "lockTimeoutMs"
     `, []);
-        if (!context)
-            throw new Error('Inspection context was not returned.');
-        return await work(client, { mode: 'separate-session', readMappings: 'pgclear', ...context });
+            if (!context)
+                throw new Error('Inspection context was not returned.');
+            return await work(client, { mode: 'separate-session', readMappings: 'pgclear', ...context });
+        });
     }
     finally {
-        await connection.close();
+        await pool.close({ timeoutMs: limits.connectMs });
     }
 }

package/dist/inspection/options.d.ts

@@ -1,15 +1,13 @@
-import type { DescribeOptions } from './types.js';
+import type { DescribeOptions, InspectionSession, InspectionTimeouts } from './types.js';
+export declare function sessionOptions(value: unknown): InspectionSession;
+export declare function timeoutOptions(value: unknown): InspectionTimeouts;
 /** Validate and capture caller-owned settings before opening a connection. */
 export declare function inspectionOptions(options: Pick<DescribeOptions, 'connection' | 'session' | 'timeouts'>): {
-    url: URL;
+    connection: import("@kequtech/pgclear").PoolOptions;
     limits: {
         connectMs: number;
         statementMs: number;
         lockMs: number;
     };
-    session: {
-        role?: string | undefined;
-        searchPath?: string | undefined;
-        timeZone?: string | undefined;
-    };
+    session: InspectionSession;
 };

package/dist/inspection/options.js

@@ -1,11 +1,9 @@
 import { plainObject } from '../validation.js';
-/** Validate and capture caller-owned settings before opening a connection. */
-export function inspectionOptions(options) {
-    if (typeof options.connection !== 'string' || !options.connection.trim()) {
-        throw new Error('Describe requires an explicit nonempty connection string.');
-    }
-    plainObject(options.session ?? {}, 'Inspection session');
-    const session = { ...options.session };
+import { configConnection } from '../config/connection.js';
+const defaults = { connectMs: 3000, statementMs: 5000, lockMs: 1000 };
+export function sessionOptions(value) {
+    const input = plainObject(value, 'Inspection session');
+    const session = { ...input };
     for (const [key, value] of Object.entries(session)) {
         if (!['role', 'searchPath', 'timeZone'].includes(key)) {
             throw new Error(`Unknown inspection session option: ${key}`);
@@ -16,9 +14,11 @@ export function inspectionOptions(options) {
             throw new Error(`Inspection session ${key} requires a nonempty string without NUL.`);
         }
     }
-    plainObject(options.timeouts ?? {}, 'Inspection timeouts');
-    const timeouts = { ...options.timeouts };
-    const defaults = { connectMs: 3000, statementMs: 5000, lockMs: 1000 };
+    return session;
+}
+export function timeoutOptions(value) {
+    const input = plainObject(value, 'Inspection timeouts');
+    const timeouts = { ...input };
     for (const [key, value] of Object.entries(timeouts)) {
         if (!Object.hasOwn(defaults, key))
             throw new Error(`Unknown inspection timeout: ${key}`);
@@ -28,24 +28,41 @@ export function inspectionOptions(options) {
             throw new Error(`Inspection timeout ${key} must be a positive integer in milliseconds.`);
         }
     }
+    return timeouts;
+}
+/** Validate and capture caller-owned settings before opening a connection. */
+export function inspectionOptions(options) {
+    const selected = configConnection(options.connection);
+    let connection = typeof selected === 'string' ? { connectionString: selected } : { ...selected };
+    if (connection.startupParameters !== undefined) {
+        plainObject(connection.startupParameters, 'Startup parameters');
+    }
+    const session = sessionOptions(options.session ?? {});
+    const timeouts = timeoutOptions(options.timeouts ?? {});
     const limits = {
         connectMs: timeouts.connectMs ?? defaults.connectMs,
         statementMs: timeouts.statementMs ?? defaults.statementMs,
         lockMs: timeouts.lockMs ?? defaults.lockMs,
     };
     // URL startup options must not disable the inspection's server-side bounds.
-    let url;
-    try {
-        url = new URL(options.connection);
-    }
-    catch {
-        throw new Error('Describe requires a PostgreSQL connection URI.');
-    }
-    if (!['postgres:', 'postgresql:'].includes(url.protocol)) {
-        throw new Error('Describe requires a PostgreSQL connection URI.');
+    if (connection.connectionString !== undefined) {
+        let url;
+        try {
+            url = new URL(connection.connectionString);
+        }
+        catch {
+            throw new Error('Describe requires a PostgreSQL connection URI.');
+        }
+        if (!['postgres:', 'postgresql:'].includes(url.protocol)) {
+            throw new Error('Describe requires a PostgreSQL connection URI.');
+        }
+        if (!url.searchParams.has('application_name') && connection.applicationName === undefined) {
+            url.searchParams.set('application_name', 'tenon-describe');
+        }
+        connection = { ...connection, connectionString: url.toString() };
     }
-    if (!url.searchParams.has('application_name')) {
-        url.searchParams.set('application_name', 'tenon-describe');
+    else if (connection.applicationName === undefined) {
+        connection = { ...connection, applicationName: 'tenon-describe' };
     }
-    return { url, limits, session };
+    return { connection, limits, session };
 }

package/dist/inspection/types.d.ts

@@ -1,4 +1,5 @@
 import type { CodecRegistry, DescribeStatement } from '@kequtech/pgclear';
+import type { ConnectionConfig } from '../connection.js';
 export interface InspectionSession {
     readonly role?: string | undefined;
     /** PostgreSQL's search_path setting, as used in the application's connection options. */
@@ -23,8 +24,8 @@ export interface InspectionContext {
     readonly readMappings: 'pgclear';
 }
 export interface DescribeOptions {
-    /** PostgreSQL connection URI. Inspection owns a separate, short-lived connection. */
-    readonly connection: string;
+    /** URI or pool configuration values. Inspection owns a separate, short-lived connection. */
+    readonly connection: ConnectionConfig | undefined;
     /** Finished SQL; query values are neither bound nor executed. */
     readonly query: string | DescribeStatement;
     /** Use the same registry as execution; custom decoder types can remain unresolved. */

package/dist/migrations/history.d.ts

@@ -1,4 +1,4 @@
-import type { Session } from '@kequtech/pgclear';
+import { type Session } from '@kequtech/pgclear';
 import type { SqlMigration } from './files.js';
 export declare const migrationTable = "__tenon_migrations";
 interface AppliedMigration {

package/dist/migrations/history.js

@@ -1,11 +1,12 @@
+import { defaultCodecs } from '@kequtech/pgclear';
 import { qualified } from '../sql.js';
 export const migrationTable = '__tenon_migrations';
 export async function migrationState(client, namespace, migrations) {
-    const exists = await client.queryClassic('SELECT to_regclass($1)::text AS name', [qualified(namespace, migrationTable)]);
+    const exists = await client.queryClassic('SELECT pg_catalog.to_regclass($1)::text AS name', [qualified(namespace, migrationTable)], { codecs: defaultCodecs });
     if (exists.rows[0].name === null) {
         return [];
     }
-    const { rows: applied } = await client.queryClassic(`SELECT id, name, checksum FROM ${qualified(namespace, migrationTable)} ORDER BY id::numeric`, []);
+    const { rows: applied } = await client.queryClassic(`SELECT id, name, checksum FROM ${qualified(namespace, migrationTable)} ORDER BY id::numeric`, [], { codecs: defaultCodecs });
     for (const [i, record] of applied.entries()) {
         const file = migrations[i];
         if (!file ||

package/dist/types.d.ts

@@ -2,7 +2,6 @@ import type { Pool } from '@kequtech/pgclear';
 import type { QueryResult } from './connection.js';
 import type { QueryOptions, QueryOutput, QueryReturnMode } from './query-options.js';
 import type { SqlQuery } from './query.js';
-import type { GenerateTypesOptions } from './generate.js';
 export interface QueryClient {
     query<Row extends object>(query: SqlQuery<Row>, options?: QueryOptions & {
         readonly returns?: 'native';
@@ -18,10 +17,8 @@ export interface CloseOptions {
     readonly timeoutMs?: number | undefined;
 }
 export type Database = Transaction & {
-    /** The underlying pool-level driver client; native calls bypass Tenon's query and transaction guards. */
+    /** The underlying pool; access initializes shared config. Native calls bypass Tenon's guards. */
     readonly native: Pool;
-    /** Write or check schema declarations using this instance's configured codecs. */
-    generateTypes(options: GenerateTypesOptions): Promise<void>;
     /** Await all work inside the callback. Commit on success; rollback on an escaping error. */
     transaction<T>(callback: (tx: Transaction) => Promise<T>): Promise<T>;
     close(options?: CloseOptions): Promise<void>;

package/dist/validation.d.ts

@@ -1 +1,3 @@
 export declare function plainObject(value: unknown, name: string): Record<string, unknown>;
+/** Validate before resolving paths so an empty override cannot become the working directory. */
+export declare function validatePath(value: unknown, label: string): asserts value is string;

package/dist/validation.js

@@ -8,3 +8,9 @@ export function plainObject(value, name) {
     }
     return value;
 }
+/** Validate before resolving paths so an empty override cannot become the working directory. */
+export function validatePath(value, label) {
+    if (typeof value !== 'string' || !value.trim() || value.includes('\0')) {
+        throw new Error(`${label} must be a nonempty path without NUL.`);
+    }
+}

package/docs/adoption-guide.md

@@ -15,10 +15,12 @@ Before replacing an ORM, identify behavior it currently supplies: IDs/defaults,
 validation, hooks, serialization, relationship loading, and transaction boundaries. Preserve needed
 behavior in application code, constraints, or SQL. Tenon has no model lifecycle or implicit loading.
 
+Use [shared configuration](configuration.md) to reuse connection settings and codecs across runtime,
+generation, checking, inspection, and migrations. Keep credentials supplied by the deployment.
+
 ## Replace queries
 
-1. Optionally generate persistence types with
-   `await db.generateTypes({ out: 'src/generated-schema.d.ts', namespace: 'public' })`.
+1. Optionally run `tenon generate` with the application's shared configuration.
    Use the application's schema and codec registry; no Tenon migration history is required.
 2. Replace one workflow at a time with parameterized SQL in ordinary functions. Accept
    `QueryClient` when callers may use either `db` or `tx`. Preserve selected columns, ordering,
@@ -48,9 +50,13 @@ reference database, preferably a disposable replay of the old migrations.
 For an application owning `app` in a shared database:
 
 ```sh
-npx tenon baseline capture --directory migrations --namespace app --schema app
+npx tenon baseline capture --directory migrations --namespace app --schema app --connection "$DATABASE_URL"
 ```
 
+This example supplies the native libpq URI for the same database through `DATABASE_URL`.
+The native connection can instead be stored in `baseline.connection`, and the captured schemas in
+`baseline.schemas`. A string main connection can be used directly. Preserve required native authentication and TLS settings.
+
 The directory must contain no SQL files. Capture uses native
 `pg_dump --schema-only --no-owner --no-privileges` and writes `0001_baseline.up.sql` without a down
 file. Install compatible PostgreSQL client tools on PATH, preferably matching the server's major

package/docs/agent-guide.md

@@ -5,8 +5,8 @@ Use this as a short workflow for changing an existing Tenon application. For fir
 
 ## Read the project first
 
-Inspect the database module, nearby query functions, migration runner, generated types, and check
-commands. Reuse the application's package manager, connection configuration, namespace, and
+Inspect `tenon.config.ts` (or its JavaScript equivalent), the database module, nearby query
+functions, migration runner, generated types, and check commands. Reuse the application's package manager, connection configuration, namespace, and
 conventions. Read the docs shipped with the installed Tenon version.
 
 For an upgrade, find the previous resolved version in the lockfile and read the
@@ -52,8 +52,9 @@ Plain bigint, valid Date, and supported Temporal inputs are accepted; inputs do
 decoders. Plain arrays/objects require `json`, `param`, or encoded text. Direct undefined rejects.
 JSON encoding still rejects bigint. Import parameter/codec helpers from Tenon.
 
-Use the application's registry for queries and generation, and pass it explicitly to programmatic
-inspection/checking. Retain application validation, authorization, domain conversion, and retry
+Keep the registry in shared `connection.codecs` so queries and CLI tools agree. Programmatic
+inspection/checking inherit codecs from connection-option values; pass the registry explicitly
+when using a URI. Retain application validation, authorization, domain conversion, and retry
 policy. See [schema types and values](schema-types.md).
 
 ## Change data deliberately
@@ -83,16 +84,11 @@ files or omit an irreversible down file, and apply it. Never change applied SQL;
 both directions. Each file commits separately. Use direct or session pooling for tooling advisory
 locks. See [migrations](migrations.md).
 
-Generate with the configured database instance, after migrations commit:
-
-```ts
-await db.generateTypes({ out: 'src/generated-schema.d.ts', namespace: 'public' });
-```
-
-Use the project's [generation script](human-guide.md#generate-types), review the diff, and commit
-migrations with exact generated output. Keep handwritten aliases separate and generated files out
-of formatting. In CI, migrate the test database and use `check: true` without first regenerating.
-Production consumes committed declarations.
+After migrations commit, run `tenon generate` with the project's
+[shared configuration](configuration.md). Review the diff and commit migrations with exact
+generated output. Keep handwritten aliases separate and generated files out of formatting. In CI,
+migrate the test database and run `tenon generate --check` without first regenerating. Production
+consumes committed declarations.
 
 ## Verify the changed workflow
 
@@ -107,8 +103,9 @@ intentional omission behavior and test it. Narrow to required fields only when a
 establishes that contract; do not cast merely to silence a diagnostic. See
 [responding to findings](query-checking.md#responding-to-findings).
 
-Match the runtime role, search path, timezone, and codecs. Describe uses a separate session and
-cannot establish result nullability, JSON members, cardinality, or execution permissions. Native
+Share runtime connection/codecs through `tenon.config.ts`; CLI generation, checking, inspection,
+and migrations read it. Select a named export with `--database`, or another file with `--config`.
+Match runtime role, search path, timezone, and codecs. Describe uses a separate session and cannot establish result nullability, JSON members, cardinality, or execution permissions. Native
 calls bypass Tenon's guards/observations and need explicit resource ownership; see
 [connections and driver access](connections.md). For common failures, use
 [troubleshooting](reference.md#troubleshooting).