@kequtech/tenon-orm 0.4.2 → 0.4.3

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,8 @@
 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 };
+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 +13,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 +27,52 @@ 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) {
+    let connection;
+    if (typeof options.connection === 'string') {
+        if (!options.connection.trim())
+            throw new Error('Describe requires an explicit nonempty connection string.');
+        connection = { connectionString: options.connection };
+    }
+    else {
+        plainObject(options.connection, 'Inspection connection');
+        if ('acquire' in options.connection || 'close' in options.connection) {
+            throw new Error('Inspection requires connection options, not an open pool.');
+        }
+        connection = { ...options.connection };
+    }
+    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;
     /** 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';
@@ -20,8 +19,6 @@ export interface CloseOptions {
 export type Database = Transaction & {
     /** The underlying pool-level driver client; native calls bypass Tenon's query and transaction 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,7 +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
+Share runtime connection/codecs through `tenon.config.ts`; CLI generation, checking, inspection,
+and migrations read it. Use `--config` for another role/deployment. 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

package/docs/configuration.md

@@ -0,0 +1,146 @@
+# Shared runtime and CLI configuration
+
+Keep connection settings and codec choices in one module used by the application and Tenon's CLI.
+From the project root, create the configuration file:
+
+```sh
+npx tenon init
+```
+
+Initialization opens no database connection, imports no application code, and never overwrites a
+file. Without `--config`, it refuses when a config is already discoverable in this directory or a
+parent. Use `tenon init --config path.mjs` for an explicit additional destination or JavaScript output. The generated TypeScript config looks like this:
+
+```ts
+import type { TenonConfig } from '@kequtech/tenon-orm';
+
+const connectionString = process.env.DATABASE_URL;
+if (!connectionString) throw new Error('DATABASE_URL is required');
+
+export default {
+  connection: {
+    connectionString,
+  },
+  migrations: { directory: 'migrations', namespace: 'public' },
+  generate: { out: 'src/generated-schema.d.ts' },
+  check: { project: 'tsconfig.json' },
+} satisfies TenonConfig;
+```
+
+Add the application's registry as `connection.codecs` when choosing custom representations.
+
+`TenonConfig` and `ConnectionConfig` are exported TypeScript types; configuration is a plain
+default-exported object. Use that connection when constructing the application instance:
+
+```ts
+// src/db.ts
+import { createTenon } from '@kequtech/tenon-orm';
+import config from '../tenon.config.ts';
+
+export const db = createTenon({ connection: config.connection });
+```
+
+The `.ts` imports above run directly with Node.js 24+ TypeScript support. For typechecking with
+`noEmit`, enable `allowImportingTsExtensions`; emitting projects can use
+`rewriteRelativeImportExtensions`. Config and its runtime imports must be runnable by Node without
+bundler aliases or transformations. ESM JavaScript is also supported.
+
+Export configuration values, not an open pool, database instance, or factory. Importing the config
+must not start the server, open listeners, or depend on generated runtime files. Tenon opens and
+closes its own tooling resources. `createTenon` still accepts application-owned pools separately.
+
+## Run commands
+
+```sh
+npx tenon new create_users
+npx tenon migrate
+npx tenon generate
+npx tenon generate --check
+npx tenon check
+npx tenon check src/users.ts:23 --json
+npx tenon describe query.sql
+```
+
+`generate`, `check`, and `describe` require configuration. They use its connection and codec registry
+and never fall back to `DATABASE_URL` merely because a config is missing or invalid. Your config
+chooses which environment variables to read; Tenon does not load `.env` files automatically.
+
+`new`, migration/status/rollback, and baseline commands also discover configuration. Without a
+config, they retain the existing migration-directory defaults and `DATABASE_URL` connection
+workflow. `init`, `new`, and `--help` open no database connection. Config imports may still require environment
+values, according to the module you wrote. Invalid session/timeout settings are rejected when config
+loads, even for commands that do not inspect queries. Migration SQL and history reads use default decoding;
+application codec overrides do not change migration bookkeeping.
+
+## Discovery, paths, and overrides
+
+Tenon searches the working directory and then parents for the nearest directory containing
+`tenon.config.ts`, `.mts`, `.js`, or `.mjs`. Multiple recognized files in that directory are an error.
+Select one explicitly when needed:
+
+```sh
+npx tenon generate --config config/tenon.production.mts --check
+```
+
+`--config` resolves from the working directory. An explicit missing file or an import failure is an
+error; Tenon never switches to another configuration after that failure.
+
+Paths stored in config resolve from the config file's directory. Configured migration directories,
+generation output, and checker projects therefore work when a command runs from a nested directory.
+An omitted migration directory means `migrations` beside the config; an omitted checker project
+means `tsconfig.json` beside it. Relative CLI path arguments and flags resolve from the working
+directory. CLI flags override the corresponding configured values.
+
+## Configuration fields
+
+| Field                  | Purpose                                                                                                                                                     |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `connection`           | Required PostgreSQL URI or pgclear pool-option values, including TLS, password callbacks, startup parameters, and codecs. Open pools are rejected.          |
+| `migrations.directory` | Migration files; defaults to `migrations` relative to config.                                                                                               |
+| `migrations.namespace` | Migration/history schema; defaults to `public`. Also supplies the generation namespace when generation does not specify one.                                |
+| `generate.out`         | Required when a `generate` section is present. Otherwise supply `--out` to the generation command.                                                          |
+| `generate.namespace`   | Schema to generate; overrides the migration namespace for generation only.                                                                                  |
+| `baseline.schemas`     | Optional nonempty list of schemas for native baseline capture. Omission captures the whole database, independently of the migration namespace.              |
+| `baseline.connection`  | Optional native libpq connection for baseline capture; `--connection` overrides it.                                                                         |
+| `check.project`        | TypeScript project; defaults to `tsconfig.json` relative to config.                                                                                         |
+| `check.readTypes`      | Explicit type expressions for custom decoders whose representations are unidentified. See [checking](query-checking.md#programmatic-use-and-custom-codecs). |
+| `session`              | Optional inspection/checking `role`, `searchPath`, and `timeZone` overrides. They do not configure runtime queries or migrations.                           |
+| `timeouts`             | Optional inspection/checking `connectMs`, `statementMs`, and `lockMs` bounds.                                                                               |
+
+Generation and runtime queries use `connection.codecs`. Checking and inspection inherit that registry
+too. Their internal catalog queries keep default decoding. Runtime startup parameters are retained,
+with inspection's statement/lock timeout bounds applied regardless of startup-parameter casing; explicit `session` settings and CLI flags
+then override role, search path, or timezone for inspection. See [connections](connections.md) and
+[inspection limits](query-inspection.md#session-and-timeouts).
+
+Keep credentials and deployment-specific addresses in environment variables or the existing secret
+provider. For a migration role different from the application role, select a separate config that
+imports shared settings and supplies that role's connection. Avoid duplicating codec definitions.
+
+Baseline capture uses native `pg_dump`, which accepts a libpq connection string rather than pgclear
+option objects or password callbacks. Configure its native connection and scope explicitly when
+needed:
+
+```ts
+// Additional fields in the shared config:
+baseline: { connection: connectionString, schemas: ['public'] }
+```
+
+Capture uses `--connection`, then `baseline.connection`, then a string main connection or the
+no-config `DATABASE_URL` fallback. `--schema` flags replace `baseline.schemas`. Adoption ignores
+capture-only settings. Supply the same database and required native TLS/authentication settings;
+Tenon does not translate driver-specific settings into libpq settings.
+
+## Programmatic APIs
+
+The CLI owns generated-file output and freshness checks. `generateDefinitions` returns source text
+without file handling for callers building custom tooling; it accepts explicit connection/options.
+
+`describeQuery` and `checkQueries` accept a URI or connection-option values and inherit
+`connection.codecs`. An explicit `codecs` argument selects the read mappings reported by those
+inspection APIs. They own separate, short-lived sessions and do not join callback transactions.
+Migration APIs continue accepting explicit connection/options. No programmatic API discovers config.
+
+The CLI imports the selected trusted config and its dependencies. Source checking subsequently reads
+query source without importing those query modules or executing application SQL. TypeScript loads
+only for source checking, not for normal queries, migrations, generation, or inspection.

package/docs/connections.md

@@ -18,7 +18,7 @@ export const db = createTenon({
     connectTimeoutMs: 5000,
     acquireTimeoutMs: 5000,
     idleTimeoutMs: 30_000,
-    startupParameters: { search_path: 'app,public', TimeZone: 'UTC' },
+    startupParameters: { search_path: 'app,public' },
   },
 });
 ```
@@ -27,8 +27,9 @@ export const db = createTenon({
 `ConnectionOptions` is Tenon's alias for `PoolOptions`. Object fields override URI settings.
 Reuse an instance for each database configuration.
 
-The driver does not load environment variables, `.env`, pgpass, or service files. Tenon CLI commands
-read `DATABASE_URL`; application code passes its configuration explicitly. An empty options object
+The driver does not load environment variables, `.env`, pgpass, or service files.
+[Shared configuration](configuration.md) supplies connection values to the CLI and application.
+Migration commands retain `DATABASE_URL` fallback when no config exists. An empty options object
 uses localhost:5432, the current OS user and a database with that user's name.
 
 Use `tls: {}` for TLS with certificate and hostname verification using system trust. Supply the
@@ -97,8 +98,9 @@ These choices apply across the database instance, including callback transaction
 options have no per-query codec override. Input encoders remain separate: a `param(value, codec)`
 carries its own encoder, and passing a Date does not select a Date output decoder.
 
-Use `db.generateTypes` with this instance to inherit its read mappings. Pass the same registry
-explicitly to `describeQuery` and `checkQueries`; their CLI forms use default codecs. See
+Place the registry in shared `connection.codecs` for runtime queries and CLI generation, inspection,
+and checking. Programmatic
+`describeQuery` and `checkQueries` inherit codecs from connection-option values too. See
 [schema types and values](schema-types.md#custom-codecs) for custom representations and Temporal.
 
 ## Observe completed queries