@kequtech/tenon-orm 0.4.3 → 0.4.4

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.4.4
+
+- Pass the shared `TenonConfig` directly to `createTenon`, including its connection, codecs, and
+  `onQuery` observer. `TenonConfig` replaces the `TenonOptions` type.
+- Defer pool creation and connection validation until the first query, transaction, or native-pool
+  access. Importing configuration and closing an unused instance need no credentials. Generated
+  configs use plain environment reads; remove eager credential checks from existing configs.
+- Support named config exports for multiple databases and CLI selection with `--database`. A sole
+  config is selected automatically; ambiguous or unknown names fail without fallback. `tenon init`
+  generates a named `main` export, and existing default exports remain supported.
+- Allow migration-file creation without database credentials while retaining each selected config's
+  migration, generation, and checking settings.
+
 ## 0.4.3
 
 - Add shared runtime/CLI configuration and offline `tenon init`. Restore `tenon generate`, share migration defaults, and require config for generation/checking/inspection.

package/README.md

@@ -15,14 +15,14 @@ typings. The PostgreSQL driver, [pgclear](https://github.com/kequtech/pgclear),
 
 ## Query with SQL
 
-This example assumes a `public.users` table with integer `id` and text `email` columns:
+This example assumes a `public.users` table with integer `id` and text `email` columns and a
+`main` export in your [shared configuration](docs/configuration.md):
 
 ```ts
 import { createTenon, sql } from '@kequtech/tenon-orm';
+import { main } from './tenon.config.ts';
 
-const connection = process.env.DATABASE_URL;
-if (!connection) throw new Error('DATABASE_URL is required');
-const db = createTenon({ connection });
+const db = createTenon(main);
 
 try {
   const email = 'reader@example.test';
@@ -97,10 +97,12 @@ choosing application types.
 
 ## Share configuration with the CLI
 
-Run `tenon init` to create `tenon.config.ts`, put connection settings and codecs there, and use its
-`connection` in `createTenon`.
-Then run `tenon generate`, `tenon generate --check`, `tenon check`, and `tenon describe query.sql`
-without custom scripts. Migration commands also use the shared connection and migration defaults.
+Run `tenon init` to create `tenon.config.ts`. Put connection settings and codecs in its `main` export,
+then reuse that object with `createTenon(main)`. Initialization stays lazy, so builds that only import
+the database instance need no credentials.
+
+The CLI uses the same config for migrations, `tenon generate`, freshness checks, `tenon check`, and
+`tenon describe query.sql`. For multiple databases, add named exports and select one with `--database`.
 See [shared configuration](docs/configuration.md) for the complete setup.
 
 ## Documentation

package/dist/cli.js

@@ -7,6 +7,7 @@ import { adoptBaseline, captureBaseline } from './baseline.js';
 import { describeFlags, inspectionSettings } from './inspection/cli.js';
 import { loadConfig } from './config/load.js';
 import { initConfig } from './config/init.js';
+import { configConnection } from './config/connection.js';
 import { generateDefinitions } from './generate.js';
 import { writeDefinitions } from './generation/output.js';
 import { validatePath } from './validation.js';
@@ -26,7 +27,8 @@ describe: [--connect-timeout-ms 3000] [--statement-timeout-ms 5000] [--lock-time
 describe emits JSON metadata; it does not execute the query or verify result annotations.
 check compares source contracts; mismatches, unchecked sites and no sites fail. Unproven types are notes.
 rollback: --steps 1
-All commands accept --config path. Migration commands fall back to DATABASE_URL only without config.
+All commands accept --config path. Database commands accept --database <export> to select a named config.
+Multiple database exports require --database. Migration commands fall back to DATABASE_URL only without config.
 `;
 function warn(message) {
     process.stderr.write(`Warning: ${message}\n`);
@@ -59,6 +61,7 @@ async function main() {
             connection: { type: 'string' },
             namespace: { type: 'string' },
             config: { type: 'string' },
+            database: { type: 'string' },
             out: { type: 'string' },
             check: { type: 'boolean', default: false },
             schema: { type: 'string', multiple: true },
@@ -94,6 +97,8 @@ async function main() {
         allowed.add('check');
     }
     allowed.add('config');
+    if (command !== 'init')
+        allowed.add('database');
     if (command === 'baseline' && argument === 'capture') {
         allowed.add('schema');
         allowed.add('connection');
@@ -122,7 +127,7 @@ async function main() {
         if (positionals.length !== 2) {
             throw new Error('Use new <name> to create a migration pair.');
         }
-        const config = await loadConfig(values.config, false);
+        const config = await loadConfig(values.config, values.database, false);
         const files = await createMigration({
             name: argument,
             directory: values.directory ?? config?.migrations?.directory ?? 'migrations',
@@ -141,14 +146,14 @@ async function main() {
         throw new Error('Choose init, new, baseline capture|adopt, migrate, generate, describe <query.sql>, check [file.ts[:line]], status, or rollback. Use --help for options.');
     }
     if (command === 'generate' || command === 'check' || command === 'describe') {
-        const config = await loadConfig(values.config);
+        const config = await loadConfig(values.config, values.database);
         if (command === 'generate') {
             const out = values.out === undefined ? config.generate?.out : resolve(values.out);
             if (out === undefined)
                 throw new Error('Configure generate.out or pass --out.');
             const namespace = values.namespace ?? config.generate?.namespace ?? config.migrations?.namespace;
             const source = await generateDefinitions({
-                connection: config.connection,
+                connection: configConnection(config.connection),
                 onWarning: warn,
                 ...(namespace !== undefined && { namespace }),
             });
@@ -158,7 +163,7 @@ async function main() {
         }
         const flags = inspectionSettings(values);
         const settings = {
-            connection: config.connection,
+            connection: configConnection(config.connection),
             session: { ...config.session, ...flags.session },
             timeouts: { ...config.timeouts, ...flags.timeouts },
         };
@@ -185,11 +190,11 @@ async function main() {
             process.exitCode = 1;
         return;
     }
-    const config = await loadConfig(values.config, false);
+    const config = await loadConfig(values.config, values.database, false);
     const capture = command === 'baseline' && argument === 'capture';
     const connection = values.connection ??
         (capture ? config?.baseline?.connection : undefined) ??
-        config?.connection ??
+        (config === undefined ? undefined : configConnection(config.connection)) ??
         process.env.DATABASE_URL;
     if (!connection)
         throw new Error('DATABASE_URL is required.');

package/dist/config/connection.d.ts

@@ -0,0 +1,3 @@
+import type { ConnectionOptions } from '../connection.js';
+/** Resolve only when a command or application actually needs its configured database. */
+export declare function configConnection(value: unknown): string | ConnectionOptions;

package/dist/config/connection.js

@@ -0,0 +1,22 @@
+import { plainObject } from '../validation.js';
+/** Resolve only when a command or application actually needs its configured database. */
+export function configConnection(value) {
+    if (value === undefined) {
+        throw new Error('Tenon config connection is required. Check its database environment variables.');
+    }
+    if (typeof value === 'string') {
+        if (!value.trim())
+            throw new Error('Tenon config connection string must be nonempty.');
+        return value;
+    }
+    if (value !== null && typeof value === 'object' && ('acquire' in value || 'close' in value)) {
+        throw new Error('Tenon config requires connection options, not an open pool.');
+    }
+    const connection = plainObject(value, 'Tenon config connection');
+    // An explicitly configured URI must never silently fall back to the driver's local defaults.
+    if ('connectionString' in connection &&
+        (typeof connection.connectionString !== 'string' || !connection.connectionString.trim())) {
+        throw new Error('Tenon config connectionString must be nonempty. Check its database environment variables.');
+    }
+    return connection;
+}

package/dist/config/init.js

@@ -18,11 +18,8 @@ export async function initConfig(filename) {
         }
     }
     const typed = extension === '.ts' || extension === '.mts';
-    const source = `${typed ? "import type { TenonConfig } from '@kequtech/tenon-orm';\n\n" : ''}const connectionString = process.env.DATABASE_URL;
-if (!connectionString) throw new Error('DATABASE_URL is required');
-
-export default {
-  connection: { connectionString },
+    const source = `${typed ? "import type { TenonConfig } from '@kequtech/tenon-orm';\n\n" : ''}export const main = {
+  connection: { connectionString: process.env.DATABASE_URL },
   migrations: { directory: 'migrations', namespace: 'public' },
   generate: { out: 'src/generated-schema.d.ts' },
   check: { project: 'tsconfig.json' },

package/dist/config/load.d.ts

@@ -3,5 +3,5 @@ export declare const configNames: string[];
 /** Find configuration without importing it, including for offline initialization. */
 export declare function findConfig(directory?: string): Promise<string | undefined>;
 /** Import only the selected trusted configuration module; never discover application entry points. */
-export declare function loadConfig(filename?: string): Promise<TenonConfig>;
-export declare function loadConfig(filename: string | undefined, required: false): Promise<TenonConfig | undefined>;
+export declare function loadConfig(filename?: string, database?: string): Promise<TenonConfig>;
+export declare function loadConfig(filename: string | undefined, database: string | undefined, required: false): Promise<TenonConfig | undefined>;

package/dist/config/load.js

@@ -4,6 +4,7 @@ import { pathToFileURL } from 'node:url';
 import { sessionOptions, timeoutOptions } from '../inspection/options.js';
 import { validateName } from '../sql.js';
 import { plainObject, validatePath } from '../validation.js';
+import { configObject, configSection } from './validate.js';
 export const configNames = [
     'tenon.config.ts',
     'tenon.config.mts',
@@ -20,13 +21,20 @@ async function exists(path) {
         throw error;
     }
 }
-function keys(value, label, allowed) {
-    const config = plainObject(value, label);
-    for (const key of Object.keys(config)) {
-        if (!allowed.includes(key))
-            throw new Error(`Unknown ${label} option: ${key}`);
+function selectDatabase(exports, database) {
+    const names = Object.keys(exports).filter((name) => {
+        const value = exports[name];
+        return (name === 'default' || (value !== null && typeof value === 'object' && 'connection' in value));
+    });
+    if (database !== undefined && !names.includes(database)) {
+        throw new Error(`Unknown database export: ${database}. Available: ${names.join(', ') || 'none'}.`);
     }
-    return config;
+    if (database === undefined && names.length !== 1) {
+        throw new Error(names.length
+            ? `Multiple databases exported: ${names.join(', ')}. Select one with --database.`
+            : 'No database configurations exported. Export a Tenon config with a connection field.');
+    }
+    return exports[database ?? names[0]];
 }
 /** Find configuration without importing it, including for offline initialization. */
 export async function findConfig(directory = process.cwd()) {
@@ -47,50 +55,35 @@ export async function findConfig(directory = process.cwd()) {
         directory = parent;
     }
 }
-export async function loadConfig(filename, required = true) {
+export async function loadConfig(filename, database, required = true) {
     if (filename !== undefined)
         validatePath(filename, 'Config filename');
+    if (database !== undefined && (!database.trim() || database.includes('\0'))) {
+        throw new Error('--database must be a nonempty export name without NUL.');
+    }
     const selected = filename === undefined ? await findConfig() : resolve(filename);
-    if (!selected && !required)
+    if (!selected && !required && database === undefined)
         return undefined;
     if (!selected)
         throw new Error('Tenon configuration is required. Run tenon init or pass --config.');
-    let value;
+    let exports;
     try {
-        value = (await import(pathToFileURL(selected).href)).default;
+        exports = await import(pathToFileURL(selected).href);
     }
     catch {
         // Import errors may contain credentials from environment validation or dependency messages.
         throw new Error(`Could not load Tenon configuration: ${selected}. Check the module and its imports.`);
     }
-    const config = keys(value, 'Tenon config', [
-        'connection',
-        'generate',
-        'migrations',
-        'baseline',
-        'check',
-        'session',
-        'timeouts',
-    ]);
-    if (typeof config.connection === 'string') {
-        if (!config.connection.trim())
-            throw new Error('Tenon config connection must be nonempty.');
-    }
-    else {
-        const connection = plainObject(config.connection, 'Tenon config connection');
-        if ('acquire' in connection || 'close' in connection) {
-            throw new Error('Tenon config requires connection options, not an open pool.');
-        }
-    }
+    const config = configObject(selectDatabase(exports, database));
     const root = dirname(selected);
-    const migrations = keys(config.migrations === undefined ? {} : config.migrations, 'migration config', ['directory', 'namespace']);
+    const migrations = configSection(config.migrations === undefined ? {} : config.migrations, 'migration config', ['directory', 'namespace']);
     if (migrations.directory !== undefined)
         validatePath(migrations.directory, 'Migration directory');
     if (migrations.namespace !== undefined)
         validateName(migrations.namespace);
     let generate;
     if (config.generate !== undefined) {
-        const options = keys(config.generate, 'generation config', ['out', 'namespace']);
+        const options = configSection(config.generate, 'generation config', ['out', 'namespace']);
         validatePath(options.out, 'Generation out');
         if (options.namespace !== undefined)
             validateName(options.namespace);
@@ -99,7 +92,7 @@ export async function loadConfig(filename, required = true) {
             ...(options.namespace !== undefined && { namespace: options.namespace }),
         };
     }
-    const check = keys(config.check === undefined ? {} : config.check, 'checking config', [
+    const check = configSection(config.check === undefined ? {} : config.check, 'checking config', [
         'project',
         'readTypes',
     ]);
@@ -116,10 +109,7 @@ export async function loadConfig(filename, required = true) {
             }
         }
     }
-    const baseline = keys(config.baseline === undefined ? {} : config.baseline, 'baseline config', [
-        'connection',
-        'schemas',
-    ]);
+    const baseline = configSection(config.baseline === undefined ? {} : config.baseline, 'baseline config', ['connection', 'schemas']);
     if (baseline.connection !== undefined &&
         (typeof baseline.connection !== 'string' ||
             !baseline.connection.trim() ||
@@ -136,6 +126,9 @@ export async function loadConfig(filename, required = true) {
     const timeouts = timeoutOptions(config.timeouts === undefined ? {} : config.timeouts);
     return {
         connection: config.connection,
+        ...(config.onQuery !== undefined && {
+            onQuery: config.onQuery,
+        }),
         migrations: {
             directory: resolve(root, migrations.directory ?? 'migrations'),
             ...(migrations.namespace !== undefined && { namespace: migrations.namespace }),

package/dist/config/validate.d.ts

@@ -0,0 +1,3 @@
+export declare function configSection(value: unknown, label: string, allowed: readonly string[]): Record<string, unknown>;
+/** Check the shared shape without resolving credentials or constructing a pool. */
+export declare function configObject(value: unknown): Record<string, unknown>;

package/dist/config/validate.js

@@ -0,0 +1,28 @@
+import { plainObject } from '../validation.js';
+export function configSection(value, label, allowed) {
+    const config = plainObject(value, label);
+    for (const key of Object.keys(config)) {
+        if (!allowed.includes(key))
+            throw new Error(`Unknown ${label} option: ${key}`);
+    }
+    return config;
+}
+/** Check the shared shape without resolving credentials or constructing a pool. */
+export function configObject(value) {
+    const config = configSection(value, 'Tenon config', [
+        'connection',
+        'onQuery',
+        'generate',
+        'migrations',
+        'baseline',
+        'check',
+        'session',
+        'timeouts',
+    ]);
+    if (!('connection' in config))
+        throw new Error('Tenon config must declare connection.');
+    if (config.onQuery !== undefined && typeof config.onQuery !== 'function') {
+        throw new Error('Tenon config onQuery must be a function.');
+    }
+    return config;
+}

package/dist/config.d.ts

@@ -1,8 +1,13 @@
+import type { Pool } from '@kequtech/pgclear';
 import type { ConnectionConfig } from './connection.js';
+import type { QueryEvent } from './types.js';
 import type { InspectionSession, InspectionTimeouts } from './inspection/types.js';
 /** Shared runtime connection values and CLI defaults. Export without opening a database. */
 export interface TenonConfig {
-    readonly connection: ConnectionConfig;
+    /** Environment values may be absent during builds; database use validates them. */
+    readonly connection: ConnectionConfig | Pool | undefined;
+    /** Observe runtime queries; native driver calls and CLI tooling do not invoke this callback. */
+    readonly onQuery?: (event: QueryEvent) => void | Promise<void>;
     readonly generate?: {
         readonly out: string;
         readonly namespace?: string;
@@ -13,7 +18,7 @@ export interface TenonConfig {
     };
     /** Native pg_dump connection/scope; defaults to the main connection only when it is a string. */
     readonly baseline?: {
-        readonly connection?: string;
+        readonly connection?: string | undefined;
         readonly schemas?: readonly string[];
     };
     readonly check?: {

package/dist/connection.d.ts

@@ -2,13 +2,16 @@ import { type Pool, type PoolOptions, type QueryResult as DriverResult, type Exe
 import type { UnknownRow } from './query.js';
 export type ConnectionOptions = PoolOptions;
 /** Connection settings and executable credentials/codecs, without a live pool. */
-export type ConnectionConfig = string | (ConnectionOptions & {
+export type ConnectionConfig = string | (Omit<ConnectionOptions, 'connectionString'> & {
+    /** May be absent during builds; operations reject an explicitly missing URI. */
+    readonly connectionString?: string | undefined;
     readonly acquire?: never;
     readonly close?: never;
 });
 export type Connection = string | ConnectionOptions | Pool;
 export type QueryResult<Row extends object = UnknownRow> = DriverResult<Row>;
 export type QueryExecutor = <T>(text: string, input: readonly unknown[], readResult: (result: QueryResult) => T, guarded: boolean) => Promise<T>;
+export declare function isPool(connection: unknown): connection is Pool;
 /** Constructed pools are owned; supplied public pgclear pools remain application-owned. */
 export declare function createConnection(connection: Connection): {
     pool: Pool;

package/dist/connection.js

@@ -1,6 +1,6 @@
 import { createPool, } from '@kequtech/pgclear';
 import { plainObject } from './validation.js';
-function isPool(connection) {
+export function isPool(connection) {
     return (connection !== null &&
         typeof connection === 'object' &&
         'acquire' in connection &&

package/dist/database.d.ts

@@ -1,7 +1,3 @@
-import type { Connection } from './connection.js';
-import type { Database, QueryEvent } from './types.js';
-export interface TenonOptions {
-    readonly connection: Connection;
-    readonly onQuery?: (event: QueryEvent) => void | Promise<void>;
-}
-export declare function createTenon(options: TenonOptions): Database;
+import type { TenonConfig } from './config.js';
+import type { Database } from './types.js';
+export declare function createTenon(config: TenonConfig): Database;

package/dist/database.js

@@ -1,5 +1,7 @@
 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';
 function closeTimeout(options) {
@@ -17,34 +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,
+        ...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)
@@ -52,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/index.d.ts

@@ -3,7 +3,6 @@ export type { Codec, CodecRegistry, Parameter, PgArray, TemporalConstructors, Te
 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';

package/dist/inspection/options.js

@@ -1,4 +1,5 @@
 import { plainObject } from '../validation.js';
+import { configConnection } from '../config/connection.js';
 const defaults = { connectMs: 3000, statementMs: 5000, lockMs: 1000 };
 export function sessionOptions(value) {
     const input = plainObject(value, 'Inspection session');
@@ -31,19 +32,8 @@ export function timeoutOptions(value) {
 }
 /** 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 };
-    }
+    const selected = configConnection(options.connection);
+    let connection = typeof selected === 'string' ? { connectionString: selected } : { ...selected };
     if (connection.startupParameters !== undefined) {
         plainObject(connection.startupParameters, 'Startup parameters');
     }

package/dist/inspection/types.d.ts

@@ -25,7 +25,7 @@ export interface InspectionContext {
 }
 export interface DescribeOptions {
     /** URI or pool configuration values. Inspection owns a separate, short-lived connection. */
-    readonly connection: ConnectionConfig;
+    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/types.d.ts

@@ -17,7 +17,7 @@ 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;
     /** Await all work inside the callback. Commit on success; rollback on an escaping error. */
     transaction<T>(callback: (tx: Transaction) => Promise<T>): Promise<T>;

package/docs/agent-guide.md

@@ -104,9 +104,8 @@ establishes that contract; do not cast merely to silence a diagnostic. See
 [responding to findings](query-checking.md#responding-to-findings).
 
 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
+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).

package/docs/configuration.md

@@ -1,56 +1,120 @@
 # 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:
+A `TenonConfig` describes one database: its connection, codecs, runtime query observer, and CLI
+defaults. The application and CLI use the same object, so generated types and query checks follow
+the representations returned at runtime.
+
+Create the configuration from the project root:
 
 ```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:
+The command writes `tenon.config.ts` with a named `main` export:
 
 ```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,
-  },
+export const main = {
+  connection: { connectionString: process.env.DATABASE_URL },
   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.
+Add `connection.codecs` when choosing custom representations. Initialization needs no credentials,
+imports no application code, and never overwrites a file. It refuses to create a default config when
+one is already discoverable in the current directory or a parent. Use `--config path.mjs` for an
+explicit destination or JavaScript output.
 
-`TenonConfig` and `ConnectionConfig` are exported TypeScript types; configuration is a plain
-default-exported object. Use that connection when constructing the application instance:
+Import the config into the application and pass it directly to `createTenon`:
 
 ```ts
 // src/db.ts
 import { createTenon } from '@kequtech/tenon-orm';
-import config from '../tenon.config.ts';
+import { main } from '../tenon.config.ts';
 
-export const db = createTenon({ connection: config.connection });
+export const db = createTenon(main);
 ```
 
-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.
+## Initialization and imports
+
+Constructing `db` checks the config's shape without validating credentials or creating a pool. The
+first query or transaction initializes one pool, which subsequent and concurrent calls reuse.
+Accessing `db.native` also initializes the pool and validates its settings; the driver connects when
+an operation needs a session. Closing an unused instance creates no pool and needs no credentials.
+
+Read environment values in the config without a top-level credential check. This lets builds import
+application modules without database access. An undefined or empty `connection`, or an explicitly
+undefined or empty `connectionString`, fails when the database is used and never selects the driver's
+localhost defaults. Environment values are captured when the module is imported, so supply runtime
+variables before starting the application. Queries performed during a build still need credentials.
 
-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.
+The `.ts` imports above run with Node.js 24+ TypeScript support. For typechecking with `noEmit`, enable
+`allowImportingTsExtensions`; emitting projects can use `rewriteRelativeImportExtensions`. Config
+files and their imports must run in Node without bundler aliases or transformations. ESM JavaScript
+is also supported.
+
+Keep config files free of resource initialization: export connection values and codecs, and let Tenon
+open and close its tooling resources. The application reuses its database instance and closes it at
+shutdown. Programmatic configs can also borrow an existing pool; see [pool ownership](connections.md#use-an-application-owned-pool).
+
+## Multiple databases
+
+Export one config per database from the same file. For example, add `analytics` beside `main` in
+`tenon.config.ts`:
+
+```ts
+export const analytics = {
+  connection: { connectionString: process.env.ANALYTICS_DATABASE_URL },
+  migrations: { directory: 'analytics/migrations', namespace: 'public' },
+  generate: { out: 'src/analytics-schema.d.ts' },
+  check: { project: 'tsconfig.json' },
+} satisfies TenonConfig;
+```
+
+Each export has its own connection settings and codecs. Use the same `connection.codecs` value when
+databases share a registry, and give each database its own migrations and generated output.
+Application code selects the export through an ordinary import:
+
+```ts
+import { createTenon } from '@kequtech/tenon-orm';
+import { main, analytics } from '../tenon.config.ts';
+
+export const db = createTenon(main);
+export const analyticsDb = createTenon(analytics);
+```
+
+The CLI selects the corresponding export with `--database`:
+
+```sh
+npx tenon migrate --database main
+npx tenon migrate --database analytics
+npx tenon generate --database analytics
+npx tenon check src/analytics/queries.ts --database analytics
+npx tenon new add_events --database analytics
+```
+
+A file with one config is selected automatically. Multiple database exports require `--database`;
+an unknown name fails without selecting another connection. Named objects with a `connection` field
+are database configs, while other helper exports are ignored. Existing default exports remain
+supported and can be selected explicitly as `--database default`.
+
+Only the selected config's settings are validated, although importing the file evaluates the whole
+module. Keep credentials as plain environment reads so one database does not require another's
+credentials. Runtime selection uses the imported object and does not depend on the working directory.
+Close each instance separately. For databases with different schemas, use separate checker projects
+or select the relevant query file when running `tenon check`.
+
+`--config` selects a file and `--database` selects an export within it. For example,
+`tenon init --config config/tenon.production.ts` creates another file, and
+`tenon migrate --config config/tenon.production.ts --database main` selects its `main` export.
 
 ## Run commands
 
+With the single config generated by `tenon init`:
+
 ```sh
 npx tenon new create_users
 npx tenon migrate
@@ -61,86 +125,87 @@ 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.
+Generation, checking, and inspection require configuration and use its connection and codecs. A
+missing or invalid config fails instead of falling back to `DATABASE_URL`. The config chooses which
+environment variables to read; Tenon does not load `.env` files.
 
-`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.
+Migration creation, migration/status/rollback, and baseline commands also discover configuration.
+Without a config or an explicit `--database`, they retain the migration-directory defaults and
+`DATABASE_URL` workflow. `init`, `new`, and `--help` need no database credentials. `new` reads migration
+settings without validating the connection; `--help` loads no config. Any eager checks in your own
+config module still run when that module is imported.
+
+The CLI validates the selected config's tooling sections when loading it, including session and
+timeout settings for commands that do not inspect queries. Migration SQL and history reads use
+default decoding, independently of application codec overrides.
 
 ## 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:
+Tenon searches the working directory and then its parents for the nearest directory containing
+`tenon.config.ts`, `.mts`, `.js`, or `.mjs`. Multiple recognized files in that directory require an
+explicit selection:
 
 ```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.
+`--config` resolves from the working directory. A missing file, missing database export, or import
+failure is an error; Tenon does not switch to another configuration after a 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.
+Configured paths resolve from the config file's directory. An omitted migration directory means
+`migrations` beside the config, and an omitted checker project means `tsconfig.json` beside it. CLI
+path flags resolve from the working directory and 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:
+| Field                  | Purpose                                                                                                                                         |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `connection`           | PostgreSQL URI or pgclear pool options, including TLS, password callbacks, startup parameters, and codecs. Required when the database is used.  |
+| `onQuery`              | Optional observer for completed runtime queries. CLI tooling and native calls do not invoke it.                                                 |
+| `migrations.directory` | Migration files; defaults to `migrations` beside the config.                                                                                    |
+| `migrations.namespace` | Migration/history schema; defaults to `public`. Also supplies the generation namespace unless overridden.                                       |
+| `generate.out`         | Required when `generate` is present. Otherwise supply `--out`.                                                                                  |
+| `generate.namespace`   | Schema to generate; overrides the migration namespace for generation.                                                                           |
+| `baseline.schemas`     | Optional nonempty schema list for native baseline capture. Omission captures the whole database.                                                |
+| `baseline.connection`  | Optional native libpq connection for baseline capture; `--connection` overrides it.                                                             |
+| `check.project`        | TypeScript project; defaults to `tsconfig.json` beside the config.                                                                              |
+| `check.readTypes`      | Fallback type expressions for unidentified decoder representations. See [query checking](query-checking.md#programmatic-use-and-custom-codecs). |
+| `session`              | Inspection/checking overrides for `role`, `searchPath`, and `timeZone`.                                                                         |
+| `timeouts`             | Inspection/checking bounds for `connectMs`, `statementMs`, and `lockMs`.                                                                        |
+
+Generation, checking, and inspection inherit `connection.codecs`; their internal catalog queries
+keep default decoding. Runtime startup parameters are retained. Inspection applies its statement
+and lock timeout bounds regardless of startup-parameter casing, then applies explicit session and
+CLI overrides. These inspection settings do not change runtime queries or migrations. See
+[connection settings](connections.md) and [inspection limits](query-inspection.md#session-and-timeouts).
+
+Keep credentials and deployment addresses in environment variables or the existing secret provider.
+For a separate migration role, add a config export with that role's connection and the shared codecs.
+
+## Native baseline capture
+
+Baseline capture uses `pg_dump`, which requires a native libpq connection string. If the main
+connection uses a driver-options object, add the native URI to the config:
 
 ```ts
-// Additional fields in the shared config:
-baseline: { connection: connectionString, schemas: ['public'] }
+// Within the database config:
+baseline: { connection: process.env.DATABASE_URL, 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.
+capture-only settings. Supply the same database and its required native TLS/authentication settings;
+Tenon does not translate driver options 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.
+`createTenon(config)` accepts the shared object and initializes its connection lazily. Other
+programmatic APIs take explicit connection and operation options; none discover config files.
 
-`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 owns generated-file output and freshness checks. `generateDefinitions` returns source text
+for custom tooling without writing files. `describeQuery` and `checkQueries` inherit codecs from
+connection-option values; an explicit `codecs` argument selects their reported read mappings. These
+inspection APIs own separate, short-lived sessions and do not join callback transactions.
 
-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.
+The CLI imports the selected trusted config and its dependencies. Source checking then reads query
+modules without importing them or executing their SQL. TypeScript loads only for source checking.

package/docs/connections.md

@@ -5,32 +5,49 @@ needed only when your application imports native pgclear APIs directly.
 
 ## Configure a database instance
 
-```ts
-import { createTenon } from '@kequtech/tenon-orm';
+Define connection settings in the shared config:
 
-const connection = process.env.DATABASE_URL;
-if (!connection) throw new Error('DATABASE_URL is required');
+```ts
+// tenon.config.ts
+import type { TenonConfig } from '@kequtech/tenon-orm';
 
-export const db = createTenon({
+export const main = {
   connection: {
-    connectionString: connection,
+    connectionString: process.env.DATABASE_URL,
     maxConnections: 10,
     connectTimeoutMs: 5000,
     acquireTimeoutMs: 5000,
     idleTimeoutMs: 30_000,
     startupParameters: { search_path: 'app,public' },
   },
-});
+} satisfies TenonConfig;
 ```
 
-`connection` accepts a PostgreSQL URI, pgclear `PoolOptions`, or an existing pgclear `Pool`.
-`ConnectionOptions` is Tenon's alias for `PoolOptions`. Object fields override URI settings.
-Reuse an instance for each database configuration.
+Pass the config to the constructor:
 
-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.
+```ts
+import { createTenon } from '@kequtech/tenon-orm';
+import { main } from '../tenon.config.ts';
+
+export const db = createTenon(main);
+```
+
+`createTenon` takes one `TenonConfig` object. Connection validation and pool creation wait until the
+first query, transaction, or `db.native` access. The pool connects when it needs a session. Closing an
+unused instance does not resolve its connection. Subsequent operations reuse the same pool.
+
+The config's `connection` field accepts a PostgreSQL URI or pgclear pool-option values.
+`ConnectionOptions` is Tenon's alias for `PoolOptions`. Object fields override URI settings. A
+programmatically constructed config may also supply an existing pool, preserving its ownership.
+
+Keep codecs in `connection.codecs` so runtime and tooling use the same representations. See
+[shared configuration](configuration.md) for build-safe environment values and
+[multiple databases](configuration.md#multiple-databases) for named exports and CLI selection.
+
+The config supplies environment values to the driver, which does not load `.env`, pgpass, or service
+files. An explicitly missing URI fails when the instance is used. Deliberately configuring
+`connection: {}` uses the driver's local defaults: 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
 provider's CA or other required TLS settings through pgclear's `tls` options. Preserve the
@@ -68,10 +85,9 @@ without closing the instance.
 When another part of the application already owns a pgclear pool:
 
 ```ts
-import { createPool } from '@kequtech/pgclear';
 import { createTenon } from '@kequtech/tenon-orm';
+import { pool } from './existing-pool.js';
 
-const pool = createPool(connection);
 const db = createTenon({ connection: pool });
 // db.native === pool
 
@@ -84,37 +100,42 @@ outstanding work. Tool APIs that accept `Connection` follow the same ownership r
 
 ## Choose output conversions
 
-Outputs follow the pool's codec registry. For example, to read int8 as JavaScript bigint and
-`timestamptz` as Date:
+Outputs follow the configured codec registry. To read int8 as JavaScript bigint and `timestamptz` as
+Date, set the registry in `tenon.config.ts`:
 
 ```ts
-import { builtin, createTenon, defaultCodecs } from '@kequtech/tenon-orm';
+import { builtin, defaultCodecs, type TenonConfig } from '@kequtech/tenon-orm';
 
 const codecs = defaultCodecs.with(builtin.int8BigInt).with(builtin.timestamptzDate);
-const db = createTenon({ connection: { connectionString: connection, codecs } });
+export const main = {
+  connection: { connectionString: process.env.DATABASE_URL, codecs },
+} satisfies TenonConfig;
 ```
 
 These choices apply across the database instance, including callback transactions. Tenon's query
 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.
 
-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
+The CLI uses that registry for 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
 
+Set `onQuery` on the database config:
+
 ```ts
-const db = createTenon({
-  connection,
+import type { TenonConfig } from '@kequtech/tenon-orm';
+
+export const main = {
+  connection: { connectionString: process.env.DATABASE_URL },
   onQuery(event) {
     console.log(event.label, event.durationMs, event.outcome, event.rowCount);
   },
-});
+} satisfies TenonConfig;
 ```
 
-Set `{ label: 'user-by-email' }` on a query to identify it. `onQuery` receives duration, outcome,
+Set `{ label: 'user-by-email' }` on a query to identify it. The observer receives duration, outcome,
 and available command/count/error-code metadata, with no SQL text or bound values. Validation
 failures before execution are not observed. Native driver calls and tooling are outside this hook.
 
@@ -153,7 +174,8 @@ import the native one as `pgSql`.
 
 ### Listen for notifications
 
-Import `listen` directly from pgclear for a dedicated connection:
+During application startup, pass a validated PostgreSQL URI (`connection` below) to pgclear's
+`listen` for a dedicated notification connection:
 
 ```ts
 import { listen } from '@kequtech/pgclear';

package/docs/human-guide.md

@@ -34,10 +34,8 @@ The command writes `tenon.config.ts` without opening a database or overwriting e
 // tenon.config.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 },
+export const main = {
+  connection: { connectionString: process.env.DATABASE_URL },
   migrations: { directory: 'migrations', namespace: 'public' },
   generate: { out: 'src/generated-schema.d.ts' },
   check: { project: 'tsconfig.json' },
@@ -49,14 +47,20 @@ Use it in the application too:
 ```ts
 // src/db.ts
 import { createTenon } from '@kequtech/tenon-orm';
-import config from '../tenon.config.ts';
+import { main } from '../tenon.config.ts';
 
-export const db = createTenon({ connection: config.connection });
+export const db = createTenon(main);
 ```
 
 These `.ts` imports use Node.js 24+ TypeScript support. See
 [shared configuration](configuration.md) for import conventions, custom codecs, discovery, and overrides.
 
+Importing the config and constructing `db` need no database credentials. The first query or transaction
+validates the connection and initializes its pool; `db.native` access also initializes it. Keep
+database operations out of module imports that run during builds. For another database, add a named
+config export in the same file, pass it to `createTenon`, and select that export in CLI commands with
+`--database`.
+
 Reuse `db` across requests. Call `await db.close()` when a standalone script finishes or a server
 shuts down. See [connections](connections.md) for pool options and application-owned pools.
 

package/docs/query-inspection.md

@@ -9,9 +9,9 @@ compare TypeScript source annotations instead, use [query checking](query-checki
 ```ts
 // scripts/inspect-query.ts
 import { describeQuery, sql } from '@kequtech/tenon-orm';
-import config from '../tenon.config.ts';
+import { main } from '../tenon.config.ts';
 
-const connection = config.connection;
+const connection = main.connection;
 
 const query = sql<{ id: number; total: string }>`
   SELECT ${42}::integer AS id, count(*) AS total FROM pg_catalog.pg_class

package/docs/reference.md

@@ -10,12 +10,19 @@ Requires Node.js 24+, PostgreSQL 16+, and ESM. TypeScript consumers need TypeScr
 development typings. Install `@kequtech/tenon-orm`; pgclear is included as a runtime dependency.
 
 ```text
-createTenon({ connection, onQuery? }): Database
+createTenon(config: TenonConfig): Database
 ```
 
-`connection` is required: a PostgreSQL URI string, pgclear `PoolOptions`, or an existing pgclear
-`Pool`. `Connection` names this union; `ConnectionOptions` aliases `PoolOptions`. A supplied pool
-retains application ownership. Unknown Tenon or driver configuration options reject.
+Pass one database config directly. Its `connection` holds a PostgreSQL URI, pgclear pool-option
+values, or an application-owned pool. Its optional `onQuery` callback observes runtime queries.
+`ConnectionOptions` aliases pgclear `PoolOptions`; a supplied pool retains application ownership.
+Unknown config keys reject. Connection validation and pool creation wait until the first query,
+transaction, or native-pool access. Closing an unused instance needs no credentials.
+
+`tenon init` generates a named `main` config with plain environment reads and no eager credential
+check. Import it and call `createTenon(main)`. Runtime does not discover files. For multiple databases,
+export one config per database and select the matching export in the CLI with `--database`.
+See [shared configuration](configuration.md) for the complete setup.
 
 The returned `Database` provides:
 
@@ -280,21 +287,23 @@ prepared statements, and dedicated notification listeners.
 
 ## Troubleshooting
 
-| Symptom                                      | Response                                                                                                                                                     |
-| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Missing shared configuration                 | Run `tenon init` or select an existing config with `--config`. Generation, checking, and inspection require it.                                              |
-| `DATABASE_URL is required`                   | Supply the variable for migration commands without config, or from your shared config module. No `.env` files are loaded automatically.                      |
-| `PGCLEAR_ENCODE`                             | Check inputs: objects/arrays need `json`/`param`; direct undefined, unsafe integers, nonfinite numbers, and invalid Dates reject. JSON still rejects bigint. |
-| `CardinalityError`                           | Check the expected row count and predicate. To choose one of several rows, author deterministic `ORDER BY ... LIMIT 1`.                                      |
-| `TENON_AFFECTED_ROWS_MISMATCH`               | The guarded operation rolled back. Inspect `actual` and the predicate; retain the intended bound.                                                            |
-| `TENON_AFFECTED_ROWS_UNSUPPORTED`            | The final command lacks a supported write count. Use guards on INSERT/UPDATE/DELETE/MERGE; result modes check returned rows.                                 |
-| Empty assignments                            | All selected fields were missing/undefined. Skip the update or branch to an expression-only statement.                                                       |
-| Duplicate result columns                     | Alias columns uniquely, especially in joins. The driver rejects duplicate object keys.                                                                       |
-| SQLSTATE `42P18` / `42P08` during inspection | Add the intended parameter cast or Describe OID hints. Inspection binds no values.                                                                           |
-| Checker reports `unchecked`                  | Follow the diagnostic. Runtime fragments and optional patches can execute correctly yet remain unsupported by source recovery.                               |
-| Missing/stale generated output               | Check schema, namespace, registry, driver version, and path. Regenerate, review, and commit intended output.                                                 |
-| Migration history conflict                   | Restore original applied files. Add new changes in a forward migration. Checksums include down SQL too.                                                      |
-| Tooling lock wait                            | Check concurrent migration/DDL work, use direct or session pooling, and configure server timeouts.                                                           |
+| Symptom                                       | Response                                                                                                                                                     |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Missing shared configuration                  | Run `tenon init` or select an existing config with `--config`. Generation, checking, and inspection require it.                                              |
+| Multiple databases or unknown database export | Select a named config with `--database name`. Use `--config path` when it belongs to another file.                                                           |
+| Missing or empty config connection            | Set the environment variable read by that database's config before using it. Imports alone need no credentials.                                              |
+| `DATABASE_URL is required`                    | Supply the variable for migration commands without config. Tenon does not load `.env` files.                                                                 |
+| `PGCLEAR_ENCODE`                              | Check inputs: objects/arrays need `json`/`param`; direct undefined, unsafe integers, nonfinite numbers, and invalid Dates reject. JSON still rejects bigint. |
+| `CardinalityError`                            | Check the expected row count and predicate. To choose one of several rows, author deterministic `ORDER BY ... LIMIT 1`.                                      |
+| `TENON_AFFECTED_ROWS_MISMATCH`                | The guarded operation rolled back. Inspect `actual` and the predicate; retain the intended bound.                                                            |
+| `TENON_AFFECTED_ROWS_UNSUPPORTED`             | The final command lacks a supported write count. Use guards on INSERT/UPDATE/DELETE/MERGE; result modes check returned rows.                                 |
+| Empty assignments                             | All selected fields were missing/undefined. Skip the update or branch to an expression-only statement.                                                       |
+| Duplicate result columns                      | Alias columns uniquely, especially in joins. The driver rejects duplicate object keys.                                                                       |
+| SQLSTATE `42P18` / `42P08` during inspection  | Add the intended parameter cast or Describe OID hints. Inspection binds no values.                                                                           |
+| Checker reports `unchecked`                   | Follow the diagnostic. Runtime fragments and optional patches can execute correctly yet remain unsupported by source recovery.                               |
+| Missing/stale generated output                | Check schema, namespace, registry, driver version, and path. Regenerate, review, and commit intended output.                                                 |
+| Migration history conflict                    | Restore original applied files. Add new changes in a forward migration. Checksums include down SQL too.                                                      |
+| Tooling lock wait                             | Check concurrent migration/DDL work, use direct or session pooling, and configure server timeouts.                                                           |
 
 After a guarded query rejects, savepoint cleanup has finished. An unguarded server error normally
 aborts a transaction. A timeout or lost connection does not itself establish whether a commit
@@ -302,12 +311,14 @@ happened; review the transaction contract before adding retries.
 
 ## Command reference
 
-All commands accept `--config path`. `generate`, `check`, and `describe` require
+All commands accept `--config path`. Commands using a database config also accept `--database name`
+to select its export. A file with one config is selected automatically; multiple configs require an
+explicit selection. `generate`, `check`, and `describe` require
 [shared configuration](configuration.md) and use its connection/codecs. Migration and baseline
 commands use config when present and fall back to `DATABASE_URL` only when no config is found.
 `init` creates config without importing application code; `new` uses the configured migration
-directory without opening a database; `--help` loads no config.
-Config modules may read environment variables, but Tenon loads no `.env` files automatically.
+directory without opening a database; `--help` loads no config. Config modules may read environment variables, but Tenon loads no `.env`
+files automatically.
 Configured paths resolve from the config file; CLI path flags resolve from the working directory.
 Unsupported command flags reject.
 

package/docs/schema-types.md

@@ -163,17 +163,22 @@ both become null. For raw JSON text or Date/bigint outputs, configure codecs.
 
 ## Custom codecs
 
-Configure the registry on the application's connection. For example:
+Configure the registry in `tenon.config.ts` so runtime queries and generated declarations use the
+same representations:
 
 ```ts
-import { builtin, createTenon, defaultCodecs } from '@kequtech/tenon-orm';
+import { builtin, defaultCodecs, type TenonConfig } from '@kequtech/tenon-orm';
 
 const codecs = defaultCodecs.with(builtin.int8BigInt).with(builtin.timestamptzDate);
-const db = createTenon({ connection: { connectionString: connection, codecs } });
+export const main = {
+  connection: { connectionString: process.env.DATABASE_URL, codecs },
+  generate: { out: 'src/generated-schema.d.ts' },
+} satisfies TenonConfig;
 ```
 
-Int8 now reads as bigint, and timestamptz reads as a millisecond-precision Date. Regenerate using this
-instance. Scalar overrides affect derived built-in arrays; explicit array overrides win. Date and
+Int8 now reads as bigint, and timestamptz reads as a millisecond-precision Date. Run `tenon generate`
+with this config to update declarations. Scalar overrides affect derived built-in arrays; explicit
+array overrides win. Date and
 Temporal output codecs reject infinity and values outside their supported ranges.
 
 For Temporal, import `createTemporalCodecs` from Tenon and supply a native or compatible polyfill

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kequtech/tenon-orm",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "license": "ISC",
   "type": "module",
   "description": "A PostgreSQL ORM designed for coding agents, with explicit SQL, typed queries, and migrations",