@kequtech/tenon-orm 0.4.2 → 0.4.4

package/docs/configuration.md

@@ -0,0 +1,211 @@
+# Shared runtime and CLI configuration
+
+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
+```
+
+The command writes `tenon.config.ts` with a named `main` export:
+
+```ts
+import type { TenonConfig } from '@kequtech/tenon-orm';
+
+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 `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.
+
+Import the config into the application and pass it directly to `createTenon`:
+
+```ts
+// src/db.ts
+import { createTenon } from '@kequtech/tenon-orm';
+import { main } from '../tenon.config.ts';
+
+export const db = createTenon(main);
+```
+
+## 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.
+
+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
+npx tenon generate
+npx tenon generate --check
+npx tenon check
+npx tenon check src/users.ts:23 --json
+npx tenon describe query.sql
+```
+
+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.
+
+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 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. A missing file, missing database export, or import
+failure is an error; Tenon does not switch to another configuration after a failure.
+
+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`           | 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
+// 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 its required native TLS/authentication settings;
+Tenon does not translate driver options into libpq settings.
+
+## Programmatic APIs
+
+`createTenon(config)` accepts the shared object and initializes its connection lazily. Other
+programmatic APIs take explicit connection and operation options; none discover config files.
+
+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 then reads query
+modules without importing them or executing their SQL. TypeScript loads only for source checking.

package/docs/connections.md

@@ -5,31 +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', TimeZone: 'UTC' },
+    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. Tenon CLI commands
-read `DATABASE_URL`; application code passes its configuration explicitly. 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
@@ -67,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
 
@@ -83,36 +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.
 
-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
+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.
 
@@ -151,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

@@ -22,17 +22,45 @@ Supply `DATABASE_URL` through your environment setup. For a local example databa
 export DATABASE_URL=postgresql://postgres:postgres@localhost:5432/your_database
 ```
 
-Tenon does not create the database or load `.env` files. Create one shared database module:
+Tenon does not create the database or load `.env` files. Create shared configuration:
+
+```sh
+npx tenon init
+```
+
+The command writes `tenon.config.ts` without opening a database or overwriting existing config:
+
+```ts
+// tenon.config.ts
+import type { TenonConfig } from '@kequtech/tenon-orm';
+
+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;
+```
+
+Use it in the application too:
 
 ```ts
 // src/db.ts
 import { createTenon } 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');
-export const db = createTenon({ 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.
 
@@ -166,35 +194,26 @@ savepoints, and retry limits. For object-based inserts and patches, see [writing
 ## Generate types
 
 Generation is optional. It reads the migrated database and writes table read/insert/update types.
-Run it through the configured instance so the types use the same value conversions as your queries:
-
-```ts
-// scripts/generate-types.ts
-import { parseArgs } from 'node:util';
-import { db } from '../src/db.ts';
+The CLI uses the shared connection and codecs from `tenon.config.ts`:
 
-const { values } = parseArgs({ options: { check: { type: 'boolean', default: false } } });
-try {
-  await db.generateTypes({ out: 'src/generated-schema.d.ts', check: values.check });
-} finally {
-  await db.close();
-}
+```sh
+npx tenon generate
+npx tenon generate --check
 ```
 
-This script runs directly on Node.js 24+ using its TypeScript support. For this execution path,
-`src/db.ts` must be runnable without build-time transformations or extension rewriting. If your
-project compiles scripts, use its normal runner and import conventions instead. To typecheck `.ts`
-imports with `noEmit`, enable `allowImportingTsExtensions`; emitting projects can use
-`rewriteRelativeImportExtensions`.
+The second command checks committed output without rewriting it. The namespace comes from
+`generate.namespace`, then `migrations.namespace`, then `public`, independently of runtime
+`search_path`. Generate after migrations have committed.
 
-Add these scripts to your existing `package.json`:
+Add these commands to your existing `package.json`:
 
 ```json
 {
   "scripts": {
-    "db:generate": "node scripts/generate-types.ts",
-    "db:check-types": "npm run db:generate -- --check",
-    "db:migrate": "tenon migrate && npm run db:generate"
+    "db:generate": "tenon generate",
+    "db:check-types": "tenon generate --check",
+    "db:check": "tenon check",
+    "db:migrate": "tenon migrate && tenon generate"
   }
 }
 ```

package/docs/migrations.md

@@ -10,8 +10,10 @@ you intend to [transfer migration ownership](adoption-guide.md#transfer-migratio
 npx tenon new add_user_display_name
 ```
 
-`new` works offline. It creates the next numeric pair in `migrations/`, starting at `0001` in an empty
-directory. For a directory whose latest migration is `0001`:
+`new` opens no database connection. It creates the next numeric pair in the configured migration
+directory, defaulting to `migrations/`, and starts at `0001` in an empty directory. As with other
+commands, importing your config may require its environment values. For a directory whose latest
+migration is `0001`:
 
 ```sql
 -- migrations/0002_add_user_display_name.up.sql
@@ -23,7 +25,8 @@ ALTER TABLE public.users ADD COLUMN display_name text;
 ALTER TABLE public.users DROP COLUMN display_name;
 ```
 
-Set `DATABASE_URL` through your environment, then run:
+Configure `connection` and migration directory/namespace in [shared configuration](configuration.md).
+Without config, migration commands retain the `DATABASE_URL` workflow. Then run:
 
 ```sh
 npx tenon status
@@ -82,8 +85,12 @@ may not be recoverable. Use the application's backup and recovery procedure when
 
 ## Directory, schema, and locking
 
-Defaults are `--directory migrations` and `--namespace public`. For a custom schema, use the same
-options consistently:
+Set `migrations: { directory: 'db/migrations', namespace: 'app' }` in shared configuration to use
+the same defaults for creation, status, migration, and rollback. Generation inherits that namespace
+unless `generate.namespace` is set. Without configured values, defaults are directory `migrations`
+and namespace `public`.
+
+CLI flags override the config for an individual command:
 
 ```sh
 npx tenon new add_setting --directory db/migrations
@@ -95,7 +102,7 @@ npx tenon rollback --directory db/migrations --namespace app --steps 1
 The namespace selects history location, migration search path, and lock scope. During a file,
 `search_path` is `<namespace>, pg_catalog`; qualify cross-schema names explicitly. The runner creates
 the namespace when applying pending migrations. It does not configure runtime application queries.
-Pass the matching namespace to type generation when generating that schema.
+Keep generation on the same namespace, through the shared default or an explicit override.
 
 Migration and adoption operations use an exclusive session advisory lock for this database and
 namespace. Status and generation use a shared lock. Different namespaces have independent lock

package/docs/query-checking.md

@@ -4,13 +4,13 @@
 metadata. It can catch a missing result property, an int8 result declared as number, or an unsupported
 bound input. It is optional; normal execution still trusts `sql<Row>` annotations.
 
-The checker reads source without importing the application, evaluating input expressions, binding
-values, or executing application SQL. PostgreSQL still parses/analyzes each recovered statement,
+The CLI imports the selected configuration module; the checker then reads query source without
+importing those modules, evaluating input expressions, binding values, or executing application SQL. PostgreSQL still parses/analyzes each recovered statement,
 which can take locks. Use a representative migrated development/test database.
 
 ## Run a check
 
-Set `DATABASE_URL`, then select a project, file, or one query:
+Create [shared configuration](configuration.md), then select a project, file, or one query:
 
 ```sh
 npx tenon check
@@ -23,15 +23,16 @@ A one-based line selects the complete query containing it, including multiline t
 variable declaration line. A line with no query or multiple queries fails. A fragment alone is not
 a complete query target.
 
-The checker discovers `tsconfig.json` from the target's directory or current working directory.
-Use `--project` for another config or project directory; targets must belong to that project.
+The CLI uses `check.project`, defaulting to `tsconfig.json` beside the shared config. Use `--project`
+for another TypeScript config or project directory; targets must belong to that project. Configured
+paths resolve from the shared config; CLI targets and path flags resolve from the working directory.
 It uses the bundled TypeScript 6 compiler and the project's imports, aliases, indexed access,
 `Pick`, unions, and path mappings. `strictNullChecks` is required. Invalid configuration and compiler
 errors in selected files fail the report.
 
 Match runtime role, search path, timezone, and codecs. Session/timeout flags are the same as
-[Describe](query-inspection.md#cli). CLI checks use default codecs; use the programmatic API for
-a custom registry.
+[Describe](query-inspection.md#cli). CLI checks inherit the shared connection
+and codec registry. Inspection-only session settings and flags override runtime startup settings.
 
 ## What gets checked
 
@@ -166,7 +167,9 @@ if (!report.ok) process.exitCode = 1;
 ```
 
 The report has `ok`, `project`, `queries`, `diagnostics`, and available inspection `context`. Options
-also accept `session`, `timeouts`, `codecs`, and `readTypes`. `connection` is a URI.
+also accept `session`, `timeouts`, `codecs`, and `readTypes`. `connection` is a URI or pool-option
+values; its `codecs` are inherited unless the explicit inspection `codecs` argument is supplied.
+The programmatic API does not discover shared configuration.
 
 For a custom codec, pass the same registry as runtime queries. A text codec may declare its output:
 
@@ -193,7 +196,7 @@ registry representation. It cannot replace known metadata or claim JSON members
 decoding. Expressions resolve from the tsconfig directory. A codec declaration is trusted output
 metadata, not data validation.
 
-Custom configuration belongs in an application-owned checking script; the checker does not load
-application configuration automatically. Generated-file freshness remains a separate
-`db.generateTypes({ out, check: true })` operation. For behavior tests, see
+The CLI loads the shared configuration for custom codecs; no checking script is required. An
+application-owned script may still call the programmatic API with explicit options. Generated-file
+freshness remains a separate `tenon generate --check` operation. For behavior tests, see
 [query inspection and testing](query-inspection.md).

package/docs/query-inspection.md

@@ -7,10 +7,11 @@ compare TypeScript source annotations instead, use [query checking](query-checki
 ## Inspect completed SQL
 
 ```ts
+// scripts/inspect-query.ts
 import { describeQuery, 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 connection = main.connection;
 
 const query = sql<{ id: number; total: string }>`
   SELECT ${42}::integer AS id, count(*) AS total FROM pg_catalog.pg_class
@@ -28,8 +29,8 @@ and analyzes the statement, which can take locks.
 
 ## Session and timeouts
 
-Inspection opens and closes its own short-lived session. `connection` must be a PostgreSQL URI;
-it does not inherit a runtime pool or transaction:
+Inspection opens and closes its own short-lived session. `connection` accepts a PostgreSQL URI or pgclear pool-option values;
+it does not reuse a runtime pool or transaction:
 
 ```ts
 const description = await describeQuery({
@@ -83,7 +84,8 @@ members remain unknown.
 
 ## Custom codecs
 
-Pass the runtime registry as `codecs` to report its read representations; omission uses defaults:
+Programmatic inspection inherits `connection.codecs` when connection-option values are supplied.
+With a URI, pass the runtime registry as `codecs`; omission uses defaults:
 
 ```ts
 import { builtin, defaultCodecs } from '@kequtech/tenon-orm';
@@ -157,11 +159,12 @@ npx tenon describe query.sql
 npx tenon describe query.sql --search-path app,public --time-zone UTC
 ```
 
-The CLI reads `DATABASE_URL` and prints JSON using default codecs. Session flags are `--role`,
+The CLI requires [shared configuration](configuration.md) and prints JSON using its connection
+and codec registry. Pass `--config path` to select a specific module. Session flags are `--role`,
 `--search-path`, and `--time-zone`; timeout flags are `--connect-timeout-ms`,
 `--statement-timeout-ms`, and `--lock-timeout-ms`. Unsupported flags, including `--namespace` and
 `--check`, reject.
 
 Exit 0 means inspection succeeded, even with unresolved findings. Input, connection, timeout, or
 PostgreSQL analysis failures exit 1. The inspected statement is never executed. Generated-file
-freshness uses `db.generateTypes({ out, check: true })`, a separate operation.
+freshness uses `tenon generate --check`, a separate operation.