@kequtech/tenon-orm 0.0.0-stage → 0.1.1

package/docs/adoption-guide.md

@@ -0,0 +1,91 @@
+# Adopting Tenon from another ORM
+
+This guide covers replacing an existing ORM and, separately, transferring migration ownership. For a
+query tutorial use the [human guide](human-guide.md); for API details use the
+[reference](reference.md). Preserve the existing schema, connection configuration, data, and
+application behavior while replacing the old ORM. Tenon does not need to own migrations to execute
+queries or generate types; keep the existing migration runner if that is the intended scope.
+
+## Replace application queries
+
+1. Locate the old ORM's connection setup, schema, migrations, and call sites. Identify behavior
+   supplied by the ORM: validation, IDs, timestamps, hooks, defaults, relation loading,
+   serialization, and transaction boundaries.
+2. If table row types will help your application, generate them from the existing database:
+
+   ```sh
+   npx tenon generate --out src/generated-schema.ts
+   ```
+
+   Use `--namespace name` for a non-public schema. Generation reads the actual database and requires
+   no Tenon migration history.
+
+3. Replace queries with parameterized SQL in ordinary functions with named object inputs where
+   useful. Preserve each caller's projection, null handling, ordering, and transaction behavior.
+   Generated types describe pg values: check bigint/numeric strings, dates, JSON, and arrays when
+   the old ORM transformed them.
+4. If using optional SQL checking, configure the
+   [SafeQL integration](reference.md#sql-checking-with-safeql) to generate query annotations and
+   check them against the intended schema. Run tests against a dedicated test database. Verify
+   writes and rollback, relationships, validation, and any hooks you moved into application code or
+   SQL. A schema-preserving first release makes application rollback easier.
+5. Remove the old runtime dependency and unused generated code after its callers are gone. Keep the
+   migration tooling until the migration transition below is complete, if that transition is part of
+   the work.
+
+## Move migration ownership to Tenon
+
+Choose one final schema checkpoint for the old runner and bring existing target databases to it.
+Disable its migration/schema synchronization before handing ownership to Tenon. The tools do not
+share locks.
+
+Capture one baseline from the reference database into an empty migration directory:
+
+```sh
+npx tenon baseline capture --directory migrations --namespace public
+```
+
+This uses native `pg_dump --schema-only --no-owner --no-privileges` and writes
+`0001_baseline.up.sql` without a down file. It requires a compatible `pg_dump` on PATH; prefer the
+server's major. Default scope is the whole database schema. Repeat `--schema name` to select schemas
+explicitly, accounting for dependencies, extensions, and required roles. Tenon's selected history
+table is excluded; old ORM metadata is preserved for deliberate cleanup later.
+
+Capture changes no source data, migration history, or sequence positions. Review and commit the SQL.
+Keep the capture header: it identifies native dump SQL that bypasses the authored-migration scanner.
+It is a convention, not proof of provenance; do not use it on handwritten migrations. Normal
+transactional execution and checksums still apply.
+
+On each existing database already at that checkpoint:
+
+```sh
+npx tenon baseline adopt
+```
+
+Adoption records the baseline checksum without executing the SQL or comparing schemas. It requires
+the selected namespace to exist. Repeating matching adoption is harmless, including after later
+migrations; conflicting history fails.
+
+On a fresh database, run migrations instead:
+
+```sh
+npx tenon migrate
+```
+
+That executes the baseline and subsequent migrations. Use the same committed baseline for every
+environment. Do not run adoption unconditionally on fresh databases. Existing databases adopt once
+and then use ordinary `migrate`.
+
+Use the development [`db:migrate` script](human-guide.md#create-a-table) to apply subsequent
+migrations and update table types together. Production continues to run only `npx tenon migrate`.
+Verify both an existing database's upgrade and a fresh replay. Baselines contain schema only; they
+do not back up rows or sequence positions. The missing down file prevents normal rollback through
+the baseline. Keep the application's backup and recovery procedure.
+
+Programmatic equivalents:
+
+- `captureBaseline({ connection, directory?, namespace?, schemas?, onWarning? })` requires a
+  nonempty native libpq connection string and returns `{ id, upPath }`. Omit `schemas` for the whole
+  database schema; an explicitly empty list is rejected.
+- `adoptBaseline({ connection, directory?, namespace? })` accepts the usual Tenon connection options
+  and returns newly recorded migration IDs.

package/docs/agent-guide.md

@@ -0,0 +1,310 @@
+# Tenon agent guide
+
+Tenon executes PostgreSQL SQL through `pg`, with parameter binding, transactions, optional write
+limits, SQL migrations, and generated table row types. Use ordinary functions for reusable queries.
+This guide contains the setup and contracts needed for routine implementation; the
+[reference](reference.md) covers additional options.
+
+## Working conventions
+
+1. Inspect the application's connection setup, migrations, generated types, query modules, and check
+   commands. Reuse them. Do not replace a working migration runner just to use Tenon queries.
+2. Write straightforward SQL with explicit selected columns. Use separate complete queries when
+   variants return different shapes. Introduce fragments only for actual reuse or variable
+   composition.
+3. Put reusable queries in functions. Accept a `QueryClient` and named object inputs when useful;
+   keep SQL and query options together. Call the same function with `db` or `tx`.
+4. After SQL changes, run the configured checker, typechecking, and relevant database tests.
+   Generate/repair annotations deliberately and inspect the diff.
+5. Keep validation, authorization, retries, and parser configuration in the application. A quoted
+   identifier or correct row count does not prove authorization.
+
+## Install and connect
+
+Requires Node.js 24+, PostgreSQL 16+, ESM, TypeScript 6+, and Node development typings. Keep the
+application's strict TypeScript configuration.
+
+```sh
+npm install @kequtech/tenon-orm pg
+npm install --save-dev @types/pg
+```
+
+```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 });
+```
+
+`connection` accepts a URL, `pg.PoolConfig`, or existing `pg.Pool`. An explicit `{}` selects pg's
+environment defaults. Reuse one instance per database connection. `close()` closes owned pools;
+supplied pools remain application-owned and need the application's idle-error handler. Await
+outstanding work before closing. Environment files are not loaded automatically. Qualify SQL names
+or configure `search_path`; CLI `--namespace` does not change runtime query names.
+
+## Query contracts
+
+```ts
+import { sql, type QueryClient } from '@kequtech/tenon-orm';
+import type { User } from './generated-schema.js';
+
+type Summary = Pick<User, 'id' | 'email'>;
+
+function userById(client: QueryClient, { id }: { id: number }) {
+  return client.query(sql<Summary>`SELECT id, email FROM public."User" WHERE id = ${id}`, {
+    returns: 'oneOrNone',
+  });
+}
+
+const user = await userById(db, { id: 42 });
+// In a transaction, call userById(tx, { id: 42 }).
+```
+
+`sql<Row>` describes one selected row. It does not prove SQL/type agreement or validate JSON.
+Unannotated fields stay `unknown`. Generated types describe full table rows; joins, aliases,
+aggregates, and expressions need projection-specific types.
+
+| `returns`          | Result                | Row-count contract |
+| ------------------ | --------------------- | ------------------ |
+| `native` (default) | pg `QueryResult<Row>` | Any                |
+| `many`             | `Row[]`               | Any                |
+| `oneOrNone`        | `Row \| undefined`    | At most one        |
+| `one`              | `Row`                 | Exactly one        |
+
+`query` options are `{ returns?, affectedRows?, label? }`; unknown options fail. Return modes never
+insert `LIMIT` or `RETURNING`. Returned-row checks alone do not undo autocommitted writes. `label`
+is an optional nonempty diagnostic string.
+
+## Parameters and composition
+
+- Ordinary interpolations bind values. Do not quote them or author manual `$n` placeholders inside
+  templates. `undefined` binds SQL null.
+- PostgreSQL infers parameter types from SQL. Cast standalone projections, e.g.
+  `SELECT ${value}::float8 AS value`; without a cast, a standalone parameter returns text.
+- Use `id = ANY(${ids}::integer[])` for an array of IDs. Do not build a comma-separated string of
+  values.
+- `identifier(schema, table)` quotes separate application-approved components. Ordinary strings such
+  as `'DESC'` remain bound values, not SQL syntax.
+- `sql.fragment` carries SQL and bound values without a row type. Use it for shared predicates or
+  partial SQL. Fragments cannot execute alone; full `sql` and `unsafeSql` queries cannot be nested.
+- `sql.join(fragments, separator)` requires a nonempty array of fragments and exactly `'AND'`,
+  `'OR'`, or `','`. No fragment or arbitrary-string separator is accepted. Empty lists and blank
+  fragments throw. Choose empty-filter behavior explicitly.
+- Joins add no parentheses. Group mixed `AND`/`OR` predicates explicitly and preserve authorization
+  conditions when adding optional filters.
+- `unsafeSql<Row>(text, values)` accepts trusted external SQL with an explicit values array. Never
+  concatenate request input into its text. Each query executes one statement.
+
+For example, share a search condition between a page and count query:
+
+```ts
+const search = sql.fragment`active = ${true} AND email ILIKE ${pattern}`;
+const page = sql<Summary>`SELECT id, email FROM public."User"
+  WHERE ${search} ORDER BY id LIMIT ${limit}`;
+const count = sql<{ count: string }>`SELECT count(*) AS count FROM public."User"
+  WHERE ${search}`;
+```
+
+`pattern` and `limit` are validated application inputs. To compose existing predicates, use
+`sql.join([first, second], 'AND')`. The checker supports literal join arrays, constant fragments,
+literal/const-string separators, and [official mutation helpers](reference.md#object-based-mutation-fragments).
+It rejects mutable or runtime-dependent SQL structure. Prefer fixed SQL for simple optional filters, e.g.
+`(${email}::text IS NULL OR email = ${email})`. If runtime composition is required, retain an
+explicit result type, suppress `tenon/check-composition` only on that query with a reason, and test
+each branch. Parameter binding alone does not establish result correctness.
+
+## Object-based writes
+
+Use official `sql.insertValues(rowOrRows, columns?)` and `sql.assignments(patch, columns?)` fragments
+instead of application helpers that enumerate object keys. Keep tables, authorization predicates,
+expressions, conflict behavior and `RETURNING` visible in SQL. Insert missing/undefined fields use
+PostgreSQL defaults; update missing/undefined fields are omitted. Explicit null stays null. Empty
+batches/updates throw; a single default-only insert works. Omit generated columns and batch large
+writes explicitly below the query-wide limit of 65,535 parameters. Expressions and queries are
+rejected as cell values; write arithmetic, `DEFAULT`, and `excluded.column` in the surrounding SQL.
+
+SafeQL reads inline object/array literals directly. Runtime inputs, spreads and data-builder results
+need explicit inline selected columns, e.g. `sql.insertValues(rows, ['name', 'score'])`. Checking
+uses all selected columns conservatively, without interpreting application JavaScript. It verifies
+SQL and result annotations, not input values, constraints, or nonempty runtime input. See the
+[mutation contract](reference.md#object-based-mutation-fragments) and [cookbook](mutations.md).
+
+## Configure and run SQL checking
+
+SafeQL checks SQL against the development/test schema and generates or verifies result annotations.
+Configure it normally and add both exports from `@kequtech/tenon-orm/safeql`:
+
+- `safeqlPlugin` goes in each SafeQL connection's `plugins`. It translates Tenon SQL and constant
+  fragments and supplies pg type mappings. SafeQL performs result inference.
+- `eslintPlugin` goes in ESLint's `plugins`, with `tenon/check-composition` enabled. It reports
+  unsupported forms that the adapter skips. It does not wrap SafeQL's rule.
+
+These tools are optional development tooling; the database runtime does not import them. SafeQL,
+ESLint, and TypeScript are optional peers. The application owns the TypeScript parser configuration
+and imports SafeQL and typescript-eslint itself. Use a TypeScript version supported by the lint
+toolchain. Generated table types are optional and not required by SafeQL.
+
+Reuse existing configuration and scripts. For a new setup:
+
+```sh
+npm install --save-dev eslint typescript-eslint @ts-safeql/eslint-plugin
+```
+
+```js
+// eslint.config.mjs
+import { defineConfig } from 'eslint/config';
+import safeql from '@ts-safeql/eslint-plugin/config';
+import tseslint from 'typescript-eslint';
+import { safeqlPlugin, eslintPlugin } from '@kequtech/tenon-orm/safeql';
+
+const databaseUrl = process.env.DATABASE_URL;
+if (!databaseUrl) throw new Error('DATABASE_URL is required for SQL checking');
+
+export default defineConfig({
+  files: ['src/**/*.ts'],
+  languageOptions: {
+    parser: tseslint.parser,
+    parserOptions: { projectService: true },
+  },
+  plugins: { tenon: eslintPlugin },
+  rules: { 'tenon/check-composition': 'error' },
+  extends: [
+    safeql.configs.connections({
+      databaseUrl,
+      plugins: [safeqlPlugin],
+      targets: [{ tag: 'sql' }],
+    }),
+  ],
+});
+```
+
+Point the URL at the intended development/test database with migrations applied. Supply environment
+variables through the application; no `.env` file is loaded here. `projectService` uses each file's
+nearest TypeScript project. Preserve existing type-aware parser settings if already configured.
+
+`targets` matches the tag spelling. Add aliases to the target list when using them. For a single
+database, `{ tag: { regex: '.*' } }` includes all Tenon aliases and typed object properties; the
+adapter excludes unrelated tags. The composition rule checks every Tenon query in its ESLint file
+scope, independently of SafeQL's targets.
+
+Reuse existing lint scripts or add:
+
+```json
+{
+  "scripts": {
+    "lint": "eslint \"src/**/*.ts\"",
+    "lint:fix": "eslint \"src/**/*.ts\" --fix"
+  }
+}
+```
+
+SQL and annotation errors come from `@ts-safeql/check-sql`; unsupported composition errors come from
+`tenon/check-composition`. Keep both rules enabled.
+
+1. Run the development `db:migrate` script below against the intended development/test database.
+2. Run `npm run lint`. Fix SQL mistakes before accepting generated types.
+3. Run `npm run lint:fix` for missing/stale annotations. It can add
+   `sql<{ id: number; email: string }>` to a query selecting those columns. Review the diff; other
+   enabled ESLint rules may also fix files.
+4. Run the application's typecheck and database tests. CI runs `lint` without `--fix`.
+
+For multiple databases, replace the connection object with an array. Each connection has its own
+URL, `plugins: [safeqlPlugin]`, and distinct `targets`, for example `{ tag: 'usersSql' }` and
+`{ tag: 'billingSql' }`. Import `sql as usersSql` and `sql as billingSql` to select them, even
+within one file. Alternatively, scope separate SafeQL configurations with non-overlapping ESLint
+`files` patterns and keep the `sql` tag. Runtime connections remain independent: execute each query
+with the right database instance. The checker does not trace `db.query` destinations.
+
+Qualify tables with their schema when names repeat across schemas in a database. SafeQL can infer
+the wrong type for an unqualified table despite the connection's `search_path`; explicit schema
+names avoid that ambiguity.
+
+The checker recognizes Tenon imports, aliases, and typed object properties. It resolves constant
+fragments and literal/const identifier names without executing application code. Imported
+fragments need inspectable source initializers. It recognizes the official mutation helpers
+directly; it never inspects function bodies or substitutes helper arguments/defaults. Conditional
+fragments, function-generated fragments, and runtime filter lists require narrow explained
+suppressions and database tests. Ordinary functions containing complete `sql` templates remain
+checkable. Keep reusable authorization policy centralized even when it is test-owned rather than
+statically checked. Use literal newlines and bound string values: outer-template JavaScript escapes
+are rejected because SafeQL reads raw text while Tenon executes decoded text. Bound values and
+constant fragments are decoded consistently.
+
+Checking verifies SQL and result annotations, not JavaScript input compatibility, authorization, or
+JSON contents. PostgreSQL owns parameter inference; the checker adds no casts based on JavaScript
+types. `unsafeSql` is unchecked. Never use `any` to hide an unsupported query.
+
+Default scalar mappings: bigint/numeric are strings; JSON is `unknown`; temporal values are
+`Date | number` because infinities are numbers. Generated `PgArray<T>` supports recursive dimensions
+and null elements. Numeric arrays contain numbers and can lose precision. Custom pg parsers and
+recursive array projections need matching checker overrides and tests, for example
+`overrides: { columns: { 'User.tags': 'PgArray<string>' } }` on the SafeQL connection. Import
+`PgArray` from the generated definitions when using that annotation.
+
+## Transactions and writes
+
+Use `db.transaction(async (tx) => ...)`; use `tx` for every query in scope and await all work. The
+callback commits on success and rolls back on an escaping error. Do not issue direct
+BEGIN/COMMIT/ROLLBACK boundaries or use `tx` after return. Transactions do not span database
+instances. Nested callback transactions and automatic retries are not provided.
+
+Use `affectedRows: { exact: n }` or `{ max: n }` for INSERT/UPDATE/DELETE/MERGE when a write must
+respect a count. Bounds are nonnegative safe integers. A guarded `db.query` uses a transaction; a
+guarded `tx.query` uses a savepoint. Rejected writes are rolled back before throwing. A caught
+guarded failure permits continued work; ordinary SQL failures may abort the transaction. Reserve
+savepoint names beginning with `tenon_affected_rows_`.
+
+Affected counts cover the final command, not extra trigger/cascade/CTE effects. They cannot detect
+the wrong single row. Sequence advances and external effects are not reversible. A lost commit
+acknowledgment may leave the outcome unknown; retry only according to application policy. Native pg
+errors retain their details; `AffectedRowsError` has codes `TENON_AFFECTED_ROWS_MISMATCH` and
+`TENON_AFFECTED_ROWS_UNSUPPORTED`. Cleanup failures can produce `AggregateError`.
+
+Optional `onQuery` observes labels, duration, outcome, and available command/count/ error code,
+without SQL or values. Observers are not awaited. Query success inside a callback does not mean the
+outer transaction committed.
+
+## Schema changes
+
+Reuse the application's migration setup. With Tenon's runner and generated table types, use this
+development script in `package.json`:
+
+```json
+{
+  "scripts": {
+    "db:migrate": "tenon migrate && tenon generate --out src/generated-schema.ts"
+  }
+}
+```
+
+```sh
+npx tenon new create_users
+# Fill the generated up/down SQL before migrating.
+npm run db:migrate
+npx tenon generate --out src/generated-schema.ts --check
+npx tenon status
+npx tenon rollback --steps 1
+```
+
+Commit migrations and generated types together. Production runs only `npx tenon migrate` and deploys
+the already-built application. Omit generation from the development script if table types are
+unused.
+
+Database commands require `DATABASE_URL`. Migration commands accept `--directory` (default
+`migrations`) and `--namespace` (default `public`); generation accepts `--namespace`. Files use
+`<numeric-id>_<name>.up.sql` with optional matching down SQL. Omit a down file for an intentionally
+irreversible migration. Never edit applied files. For a custom namespace, pass it to both commands
+in the development script.
+
+Each migration commits with its history entry; earlier files remain applied if a later one fails.
+Tools use session advisory locks: use a direct connection or session pooling and application
+timeouts. Nontransactional DDL needs a separate procedure. `generate --check` detects representation
+drift, not pending migrations or every possible schema change. Generation covers ordinary tables and
+partitioned roots; views/foreign tables need authored query types.
+
+When replacing another ORM, preserve its schema and behavior. If transferring migration ownership,
+capture one reviewed baseline with `tenon baseline capture`, record it only on matching existing
+databases with `tenon baseline adopt`, and use `tenon migrate` on fresh databases. Adoption does not
+compare schemas or run baseline SQL. See [adoption](adoption-guide.md) for the full transition
+procedure. A down migration or schema-only baseline is not a data backup.

package/docs/human-guide.md

@@ -0,0 +1,271 @@
+# Using Tenon: a human guide
+
+Tenon lets you use PostgreSQL directly from TypeScript. You write SQL; Tenon binds its inputs and
+executes it through `pg`. This guide follows a small application from its first table to reusable
+queries, transactions, and result checking.
+
+Use the [reference](reference.md) when you need exact options or unusual cases. The
+[agent guide](agent-guide.md) is a separate working guide for coding agents;
+[adoption](adoption-guide.md) covers moving an existing application to Tenon.
+
+## Connect to your database
+
+In an existing Node.js 24+ TypeScript project using ESM:
+
+```sh
+npm install @kequtech/tenon-orm pg
+npm install --save-dev @types/pg
+```
+
+Use PostgreSQL 16+ and TypeScript 6+. Keep your existing strict TypeScript configuration and Node
+typings. Supply `DATABASE_URL` through your application's environment setup; Tenon does not load
+`.env` files.
+
+```ts
+// src/db.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 });
+```
+
+Reuse this instance across the application and call `await db.close()` at shutdown. For multiple
+databases, create an instance for each connection. You can also supply an existing `pg.Pool`; your
+application then closes that pool.
+
+## Create a table
+
+If you already have a schema and migration runner, you can keep them. For a new schema, create a
+migration:
+
+```sh
+npx tenon new create_users
+```
+
+Fill the generated files:
+
+```sql
+-- migrations/0001_create_users.up.sql
+CREATE TABLE public."User" (
+  id integer GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  email text NOT NULL UNIQUE,
+  active boolean NOT NULL DEFAULT true
+);
+```
+
+```sql
+-- migrations/0001_create_users.down.sql
+DROP TABLE public."User";
+```
+
+For development, add a script to `package.json` that applies migrations and updates table row types:
+
+```json
+{
+  "scripts": {
+    "db:migrate": "tenon migrate && tenon generate --out src/generated-schema.ts"
+  }
+}
+```
+
+```sh
+npm run db:migrate
+```
+
+Commit migrations and generated types together. In production, run only `npx tenon migrate`; deploy
+the already-built application. If you do not use generated table types, omit generation from the
+development script. For later schema changes, add a new migration instead of editing an applied one.
+If a change cannot be reversed, omit its down file. A down migration is not a backup.
+
+## Write a query
+
+Create a row, then read the fields you need:
+
+```ts
+import { sql } from '@kequtech/tenon-orm';
+import { db } from './db.js';
+
+const email = 'reader@example.test';
+await db.query(sql`INSERT INTO public."User" (email) VALUES (${email})`);
+const user = await db.query(
+  sql<{ id: number; email: string }>`
+    SELECT id, email FROM public."User" WHERE email = ${email}
+  `,
+  { returns: 'oneOrNone' },
+);
+```
+
+`${email}` becomes a bound parameter. Do not put quotes around it: the driver passes the value
+separately from the SQL text, even when the value contains SQL.
+
+The type describes one selected row. `returns: 'oneOrNone'` gives you that row or `undefined`; it
+throws if the query returns more than one row. Use `'one'` when absence should also be an error,
+`'many'` for an array, or omit `returns` for the full driver result with `.rows` and `.rowCount`.
+These options do not change your SQL.
+
+Generated table types can help describe projections without repeating every field:
+
+```ts
+import type { User } from './generated-schema.js';
+type UserSummary = Pick<User, 'id' | 'email'>;
+```
+
+You can then write `sql<UserSummary>`. A table type describes the full table; a join or aggregate
+needs a type for what that particular query selects. An annotation is a declaration, not proof that
+the SQL matches. Without one, result fields are `unknown`. The checking workflow below can generate
+and verify it.
+
+## Reuse a query with a function
+
+Use an ordinary function when several callers need the same query. An object input makes the
+supplied values easy to read:
+
+```ts
+import { sql, type QueryClient } from '@kequtech/tenon-orm';
+import type { User } from './generated-schema.js';
+
+type UserSummary = Pick<User, 'id' | 'email'>;
+
+export function userByEmail(client: QueryClient, { email }: { email: string }) {
+  return client.query(
+    sql<UserSummary>`SELECT id, email FROM public."User" WHERE email = ${email}`,
+    { returns: 'oneOrNone' },
+  );
+}
+
+const user = await userByEmail(db, { email: 'reader@example.test' });
+```
+
+`QueryClient` means the function accepts either your database instance or a transaction client. Keep
+the SQL and execution options together in the function.
+
+## Change data in a transaction
+
+```ts
+await db.transaction(async (tx) => {
+  const user = await userByEmail(tx, { email: 'reader@example.test' });
+  if (!user) throw new Error('User not found');
+
+  await tx.query(sql`UPDATE public."User" SET active = false WHERE id = ${user.id}`, {
+    affectedRows: { exact: 1 },
+  });
+});
+```
+
+Use `tx` for all work in the callback and await it. Tenon commits when the callback succeeds and
+rolls back when an error escapes.
+
+`affectedRows: { exact: 1 }` requires exactly one affected row. `{ max: 1 }` permits zero or one.
+Tenon rolls back a write that violates the bound. You can also use these guards on `db.query`
+outside a callback transaction. The guard checks a count; you still need the correct `WHERE` clause
+and application authorization. Checking returned rows with `returns` alone does not undo an
+autocommitted write.
+
+## Write objects without building column lists by hand
+
+Use `sql.insertValues(rowOrRows)` inside an authored `INSERT` and `sql.assignments(patch)` after
+`SET`. Inserts use database defaults for missing/undefined fields; updates omit those fields.
+Explicit `null` stays null. Empty batches and updates throw. Heterogeneous insert rows remain
+aligned, with `DEFAULT` for missing cells.
+
+```ts
+await db.query(sql`INSERT INTO users ${sql.insertValues({ email, active: true })}`);
+await db.query(sql`UPDATE users SET ${sql.assignments({ email, active })} WHERE id = ${id}`);
+```
+
+These helpers bind values only. Keep expressions, authorization, conflict handling and `RETURNING`
+in SQL. For SafeQL checking of runtime-built objects or batches, supply literal selected columns,
+for example `sql.assignments(patch, ['email', 'active'])`. The checker validates all selected columns
+without inspecting the code that built the patch. See the
+[mutation contract and checking limits](reference.md#object-based-mutation-fragments).
+
+## Check your SQL and result types
+
+There are three different jobs here:
+
+- Tenon executes queries and binds values.
+- TypeScript checks the application code and the result types you declare.
+- SafeQL checks the SQL against your database and verifies or generates those types.
+
+SafeQL is optional development tooling run by ESLint. Configure it normally, with Tenon's
+`safeqlPlugin` adapter to translate queries, constant fragments, and official mutation helpers. A small
+companion ESLint rule, `tenon/check-composition`, flags queries that cannot be checked statically. SafeQL performs the
+database analysis and annotation fixes. Your application's ESLint configuration imports these tools;
+Tenon's database runtime does not need them. Generated table types are a separate convenience and
+are not required by SafeQL. Follow the one-time
+[SQL checking setup](reference.md#sql-checking-with-safeql).
+
+Use the application's existing lint commands. If it has none, the setup shows `lint` and `lint:fix`.
+They run ESLint, including all other enabled rules. Once configured, the normal workflow is:
+
+1. Run `npm run db:migrate` against the development/test database.
+2. Run `npm run lint` to find SQL errors and missing or incorrect annotations.
+3. Use `npm run lint:fix` to generate or repair annotations, then review the diff.
+4. Run TypeScript and database tests. CI runs the check without fixing files.
+
+For example, SafeQL can turn `sql` followed by a query selecting `id, email` into
+`sql<{ id: number; email: string }>` based on your actual schema. It can detect a renamed column or
+an incorrect declared result type before the query runs.
+
+Input validation and database tests still matter. Checking a query does not prove that a request is
+authorized, that its values are valid, or that returned JSON has an application-specific shape.
+
+## Reuse or assemble parts of SQL when needed
+
+For fixed conditions, write them directly:
+
+```ts
+const users = await db.query(
+  sql<UserSummary>`SELECT id, email FROM public."User" WHERE active = ${true}`,
+  { returns: 'many' },
+);
+```
+
+A fragment is a piece of SQL that carries its bound values with it. It is useful when multiple
+queries share a condition. For example, a search can use the same predicate for its result page and
+its count:
+
+```ts
+const search = sql.fragment`active = ${true} AND email ILIKE ${pattern}`;
+const page = sql<UserSummary>`SELECT id, email FROM public."User"
+  WHERE ${search} ORDER BY id LIMIT ${limit}`;
+const count = sql<{ count: string }>`SELECT count(*) AS count FROM public."User"
+  WHERE ${search}`;
+```
+
+Here `pattern` is an application-supplied search pattern and `limit` is a validated page size.
+Execute each query with `db.query`. A fragment cannot execute alone; the complete query supplies the
+result type. The checker can inspect these constant fragments.
+
+For a simple optional filter, a fixed SQL predicate often suffices:
+
+```ts
+// email is string | null; null means no email filter.
+const query = sql<UserSummary>`SELECT id, email FROM public."User"
+  WHERE active = ${true} AND (${email}::text IS NULL OR email = ${email})`;
+```
+
+If you need a variable list of conditions, `sql.join` combines fragments using `'AND'`, `'OR'`, or
+`','`. **SafeQL cannot check runtime-built lists.** Keep an explicit result type and test each
+variant; if you use SafeQL, suppress only this query with an explanation. Parameter binding still
+works, but it does not prove that every variant is valid SQL or returns the declared columns.
+
+```ts
+const filters = [sql.fragment`active = ${true}`];
+if (email !== undefined) filters.push(sql.fragment`email = ${email}`);
+
+// eslint-disable-next-line tenon/check-composition -- Runtime filters are covered by database tests.
+const query = sql<UserSummary>`SELECT id, email FROM public."User"
+  WHERE ${sql.join(filters, 'AND')} ORDER BY id`;
+```
+
+The initial condition keeps this list nonempty. Empty lists throw so that missing filters cannot
+silently remove a condition. `join` adds separators, not parentheses; wrap groups explicitly when
+mixing `AND` and `OR`. Full queries cannot be used as fragments. See the
+[composition reference](reference.md#sql-fragments-and-joins) for static checking rules and other
+details.
+
+For arrays, identifiers, type mappings, CLI options, and error behavior, use the
+[reference](reference.md). You do not need fragments or a query builder to use PostgreSQL joins,
+aggregates, upserts, or other SQL features.