@kequtech/tenon-orm 0.4.0 → 0.4.3

package/docs/configuration.md

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

package/docs/connections.md

@@ -0,0 +1,187 @@
+# Connections and driver access
+
+`createTenon` uses a pgclear connection pool. Tenon includes the driver; a separate installation is
+needed only when your application imports native pgclear APIs directly.
+
+## Configure a database instance
+
+```ts
+import { createTenon } from '@kequtech/tenon-orm';
+
+const connection = process.env.DATABASE_URL;
+if (!connection) throw new Error('DATABASE_URL is required');
+
+export const db = createTenon({
+  connection: {
+    connectionString: connection,
+    maxConnections: 10,
+    connectTimeoutMs: 5000,
+    acquireTimeoutMs: 5000,
+    idleTimeoutMs: 30_000,
+    startupParameters: { search_path: 'app,public' },
+  },
+});
+```
+
+`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.
+
+The driver does not load environment variables, `.env`, pgpass, or service files.
+[Shared configuration](configuration.md) supplies connection values to the CLI and application.
+Migration commands retain `DATABASE_URL` fallback when no config exists. An empty options object
+uses localhost:5432, the current OS user and a database with that user's name.
+
+Use `tls: {}` for TLS with certificate and hostname verification using system trust. Supply the
+provider's CA or other required TLS settings through pgclear's `tls` options. Preserve the
+connection requirements of your deployment. The complete option list is in the installed driver's
+`docs/public-api.md`; unknown options reject.
+
+Qualify table names in SQL or set runtime `search_path`. Tooling `namespace` options select the
+schema to migrate or generate; they do not configure your application's queries. The example above
+assumes an `app` schema already exists.
+
+## Close resources
+
+For a short-lived script, use `try/finally`:
+
+```ts
+try {
+  // Await database work here.
+} finally {
+  await db.close();
+}
+```
+
+For a server, stop accepting work and finish requests before closing the database. A close call
+immediately rejects new Tenon work and gives an owned pool a default 5,000 ms grace period. Set
+`db.close({ timeoutMs: 1000 })` to change it; `0` requests immediate shutdown. Remaining driver work
+and checkouts expire at the deadline. This bounds database resources, not arbitrary JavaScript
+callbacks or proof that a remote rollback completed.
+
+The first valid close call fixes the timeout. Concurrent and later calls share its promise and
+outcome. Timeout must be an integer from 0 to 2,147,483,647 ms; invalid initial options reject
+without closing the instance.
+
+### Use an application-owned pool
+
+When another part of the application already owns a pgclear pool:
+
+```ts
+import { createPool } from '@kequtech/pgclear';
+import { createTenon } from '@kequtech/tenon-orm';
+
+const pool = createPool(connection);
+const db = createTenon({ connection: pool });
+// db.native === pool
+
+await db.close(); // Disables this wrapper; pool remains open.
+await pool.close(); // The application owns the pool's shutdown.
+```
+
+Tenon borrows the supplied pool by identity. Closing the wrapper does not cancel that pool's
+outstanding work. Tool APIs that accept `Connection` follow the same ownership rule.
+
+## Choose output conversions
+
+Outputs follow the pool's codec registry. For example, to read int8 as JavaScript bigint and
+`timestamptz` as Date:
+
+```ts
+import { builtin, createTenon, defaultCodecs } from '@kequtech/tenon-orm';
+
+const codecs = defaultCodecs.with(builtin.int8BigInt).with(builtin.timestamptzDate);
+const db = createTenon({ connection: { connectionString: connection, codecs } });
+```
+
+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
+[schema types and values](schema-types.md#custom-codecs) for custom representations and Temporal.
+
+## Observe completed queries
+
+```ts
+const db = createTenon({
+  connection,
+  onQuery(event) {
+    console.log(event.label, event.durationMs, event.outcome, event.rowCount);
+  },
+});
+```
+
+Set `{ label: 'user-by-email' }` on a query to identify it. `onQuery` 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.
+
+Observers are not awaited. A thrown error or rejected observer promise emits a warning and leaves
+the query outcome unchanged. A successful query event inside a transaction does not mean the outer
+transaction committed. Guarded-call duration includes its commit or rollback work.
+
+## Use native driver features
+
+`db.native` is the actual pgclear pool. Use it for prepared statements, streams, COPY, or held
+sessions. For a finished SQL string:
+
+```ts
+const result = await db.native.queryClassic('SELECT $1::integer AS value', [42]);
+```
+
+Native calls bypass Tenon's result modes, affected-row guards, SQL boundary checks, and `onQuery`.
+They do not join a Tenon callback transaction. A callback's `tx` exposes only `query`.
+
+Use the public driver session APIs and release held leases. For example:
+
+```ts
+await db.native.withSession(async (session) => {
+  const prepared = await session.prepare('SELECT $1::integer AS value');
+  try {
+    await prepared.query<{ value: number }>([42]);
+  } finally {
+    await prepared.close();
+  }
+});
+```
+
+Native `query` accepts pgclear's own SQL tag. Tenon's `sql` and `unsafeSql` results belong in
+`db.query`; use `queryClassic` for text to avoid needing a second tag. When both tags are used,
+import the native one as `pgSql`.
+
+### Listen for notifications
+
+Import `listen` directly from pgclear for a dedicated connection:
+
+```ts
+import { listen } from '@kequtech/pgclear';
+
+const listener = await listen(connection, {
+  channels: ['users_changed'],
+  onNotification: ({ payload }) => console.log(payload),
+  reconnect: true,
+});
+// At shutdown:
+await listener.close();
+```
+
+A listener has a separate lifetime and is not closed by `db.close()`. Notifications are not replayed
+after a disconnection; the application owns its recovery policy.
+
+## Update the driver
+
+Tenon depends on `@kequtech/pgclear: ^0.3.0`, which permits compatible 0.3.x patch updates. With npm:
+
+```sh
+npm update @kequtech/pgclear
+npm ls @kequtech/pgclear
+```
+
+Review the resolved version and lockfile, regenerate affected declarations, and run application
+checks before committing. A lockfile keeps its chosen version until updated. Pgclear 0.4 is outside
+this range and requires an explicit Tenon compatibility update.
+
+If the application imports pgclear directly, declare it as a dependency with a compatible version
+so the package manager can share a copy. See the [changelog](../CHANGELOG.md) when updating Tenon.