@kequtech/tenon-orm 0.1.1 → 0.1.3

package/README.md

@@ -3,7 +3,7 @@
 A PostgreSQL ORM designed for coding agents. Built for Node.js and TypeScript.
 
 Your coding agent already knows SQL. Tenon gives it a small API for parameterized queries,
-transactions, and migrations, with optional tooling to check SQL and generate result types. Queries
+transactions, and migrations, with optional tooling to check SQL and generate database types. Queries
 stay readable, reusable operations are ordinary functions, and humans can review exactly what will
 run against the database.
 
@@ -47,7 +47,7 @@ Tenon also provides:
 
 - Transactions and affected-row limits that roll back rejected writes.
 - SQL migration files and a CLI to apply, inspect, and roll back migrations.
-- TypeScript table row types generated from your database.
+- TypeScript row, insert, and update types generated from your database.
 - SQL fragments for sharing query parts or assembling variable conditions.
 
 Joins, relationships, aggregates, and upserts use ordinary PostgreSQL SQL. Tenon does not introduce
@@ -68,7 +68,9 @@ migrations and table type generation are independent conveniences.
 
 For object-based writes, `sql.insertValues(rows)` preserves database defaults across heterogeneous
 rows and `sql.assignments(patch)` omits undefined fields. Keep the surrounding SQL explicit. Both
-support selected columns and [SafeQL checking](docs/reference.md#object-based-mutation-fragments).
+support selected columns and [SafeQL checking](docs/reference.md#checking-mutation-fragments).
+Use [generated input types](docs/reference.md#insert-and-update-inputs) to check those objects
+against your schema.
 
 ## Checking query results
 
@@ -79,12 +81,10 @@ For that, Tenon provides an optional integration with [SafeQL](https://safeql.de
 SQL against your development database and can write or repair the result annotation. ESLint runs the
 check during development and CI; it is not part of query execution.
 
-Configure SafeQL in your application's ESLint setup. Tenon supplies a `safeqlPlugin` adapter for its
-queries, constant fragments, and official mutation helpers, plus an `eslintPlugin` rule that flags
-queries the adapter cannot check. SafeQL handles database analysis and result annotations; Tenon keeps the SQL and pg type
-mappings consistent with execution. Both integrations are optional development tooling. See
-[SQL checking setup](docs/reference.md#sql-checking-with-safeql) for installation and a complete
-configuration, including multiple databases.
+Configure SafeQL in your application's ESLint setup with Tenon's `safeqlPlugin` adapter and
+`eslintPlugin` companion rule. The adapter supports queries, constant fragments, and mutation
+helpers; the rule reports queries it cannot inspect. See the
+[SQL checking setup](docs/reference.md#sql-checking-with-safeql).
 
 Checking complements typed inputs and database tests. It does not validate request values or
 arbitrary JSON, and runtime-built query variants need their own tests.
@@ -97,7 +97,9 @@ arbitrary JSON, and runtime-built query variants need their own tests.
 - **[Reference](docs/reference.md)** — complete options, SQL checking setup, type mappings, and
   limitations.
 - **[Adoption guide](docs/adoption-guide.md)** — replace an existing ORM and, if needed, transfer
-  migration ownership.
+  migration ownership; upgrade local write helpers and adopt SQL checking incrementally.
+- **[Mutation cookbook](docs/mutations.md)** — defaults, patches, upserts, arrays, batching, and
+  the boundaries between input typing and SQL checking.
 
 The complete `docs/` folder ships with the npm package. Maintainer instructions are in
 [CONTRIBUTING.md](https://github.com/kequtech/tenon-orm/blob/main/CONTRIBUTING.md), which is not

package/dist/cli.js

@@ -5,6 +5,7 @@ import { dirname, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 import { adoptBaseline, captureBaseline } from './baseline.js';
 import { generateDefinitions } from './generate.js';
+import { definitionDiff } from './generation/diff.js';
 import { migrate, migrationStatus, rollback } from './migrations.js';
 import { createMigration } from './migrations/files.js';
 const help = `tenon migrate|status|rollback [--directory migrations] [--namespace public]
@@ -30,9 +31,10 @@ async function writeDefinitions(source, filename, check) {
             if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) {
                 throw error;
             }
+            throw new Error(`Generated definitions file is missing: ${output}\nRun tenon generate with the same options, omitting --check, then commit the result.`);
         }
         if (existing !== source) {
-            throw new Error('Generated definitions are stale or missing; run tenon generate and commit the result.');
+            throw new Error(`Generated definitions differ: ${output}\n${definitionDiff(existing, source)}\nRun tenon generate with the same options, omitting --check, then commit the result.`);
         }
         process.stdout.write('Generated definitions are current.\n');
         return;
@@ -152,7 +154,7 @@ async function main() {
     }
 }
 main().catch((error) => {
-    // Do not print connection configuration or raw SQL/parameter payloads.
+    // Report diagnostics without connection configuration or query parameter payloads.
     process.stderr.write(`${error instanceof Error ? error.message : 'Database command failed.'}\n`);
     process.exitCode = 1;
 });

package/dist/generate.js

@@ -1,5 +1,5 @@
 import { readTables } from './generation/catalog.js';
-import { renderRowTypes } from './generation/row-types.js';
+import { renderTableTypes } from './generation/table-types.js';
 import { domainSummaries, schemaSummary, tableSummary } from './generation/schema-summary.js';
 import { withMigrationLock } from './migrations/connection.js';
 import { quote } from './sql.js';
@@ -24,7 +24,7 @@ export async function generateDefinitions(options) {
             summaries.push(await tableSummary(client, table.oid, table.name));
         }
         const domains = await domainSummaries(client, definitions.flatMap((table) => table.columns.map((column) => column.declaredOid)));
-        const types = renderRowTypes(definitions, namespace, onWarning);
+        const types = renderTableTypes(definitions, namespace, onWarning);
         await client.query('COMMIT');
         return `// Generated by Tenon from the PostgreSQL schema. Do not edit.
 // Commit this file and regenerate it after changing the schema.

package/dist/generation/catalog.d.ts

@@ -9,6 +9,9 @@ export interface ColumnRow {
     declaredType: string;
     declaredSchema: string;
     nullable: boolean;
+    writeNullable: boolean;
+    hasDefault: boolean;
+    writable: boolean;
     choices: string[] | null;
 }
 export interface TableRow {

package/dist/generation/catalog.js

@@ -11,16 +11,19 @@ export async function readTables(client, namespace) {
         // Attached descendants are storage details, not separate generated models.
         const columns = await client.query(`
         WITH RECURSIVE resolved AS (
-          SELECT a.attnum, t.oid, t.typbasetype
+          SELECT a.attnum, t.oid, t.typbasetype, t.typnotnull AS domain_not_null
           FROM pg_catalog.pg_attribute a JOIN pg_catalog.pg_type t ON t.oid = a.atttypid
           WHERE a.attrelid = $1::oid AND a.attnum > 0 AND NOT a.attisdropped
           UNION ALL
-          SELECT r.attnum, t.oid, t.typbasetype
+          SELECT r.attnum, t.oid, t.typbasetype, r.domain_not_null OR t.typnotnull
           FROM resolved r JOIN pg_catalog.pg_type t ON t.oid = r.typbasetype
         )
         SELECT a.attname AS name, t.oid::text AS oid, t.typname AS type, tn.nspname AS "typeSchema", t.typtype AS "typeKind",
           declared.oid::text AS "declaredOid", declared.typname AS "declaredType", dn.nspname AS "declaredSchema",
           NOT a.attnotnull AS nullable,
+          NOT (a.attnotnull OR r.domain_not_null) AS "writeNullable",
+          (a.atthasdef OR declared.typdefaultbin IS NOT NULL OR a.attidentity <> '') AS "hasDefault",
+          (a.attgenerated = '' AND a.attidentity <> 'a') AS writable,
           (SELECT array_agg(e.enumlabel::text ORDER BY e.enumsortorder) FROM pg_catalog.pg_enum e WHERE e.enumtypid = t.oid) AS choices
         FROM pg_catalog.pg_attribute a
           JOIN resolved r ON r.attnum = a.attnum AND r.typbasetype = 0

package/dist/generation/diff.d.ts

@@ -0,0 +1,2 @@
+/** A bounded text excerpt, not a schema comparison or an applicable patch. */
+export declare function definitionDiff(saved: string, generated: string): string;

package/dist/generation/diff.js

@@ -0,0 +1,30 @@
+/** A bounded text excerpt, not a schema comparison or an applicable patch. */
+export function definitionDiff(saved, generated) {
+    const before = saved.split('\n');
+    const after = generated.split('\n');
+    let start = 0;
+    while (start < before.length && start < after.length && before[start] === after[start]) {
+        start++;
+    }
+    if (start === before.length && start === after.length)
+        return '';
+    let beforeEnd = before.length;
+    let afterEnd = after.length;
+    while (beforeEnd > start && afterEnd > start && before[beforeEnd - 1] === after[afterEnd - 1]) {
+        beforeEnd--;
+        afterEnd--;
+    }
+    function excerpt(lines, end, marker) {
+        const shown = lines.slice(start, Math.min(end, start + 8));
+        const output = shown.map((line) => `${marker} ${line.length > 200 ? line.slice(0, 200) + '…' : line}`);
+        if (end - start > shown.length) {
+            output.push(`  … ${end - start - shown.length} more ${marker} lines omitted`);
+        }
+        return output;
+    }
+    return [
+        `Diff excerpt from line ${start + 1} (- saved, + generated):`,
+        ...excerpt(before, beforeEnd, '-'),
+        ...excerpt(after, afterEnd, '+'),
+    ].join('\n');
+}

package/dist/generation/table-types.d.ts

@@ -0,0 +1,2 @@
+import type { TableRow } from './catalog.js';
+export declare function renderTableTypes(tables: readonly TableRow[], namespace: string, onWarning: (message: string) => void): string;

package/dist/generation/table-types.js

@@ -0,0 +1,146 @@
+// Every generated table remains accessible through Rows["exact SQL name"].
+const reservedTypeNames = new Set(`
+  as await break case catch class const continue debugger default delete do else enum
+  export extends false finally for function if implements import in instanceof
+  interface let new null package private protected public return static super
+  switch this throw true try typeof var void while with yield any bigint boolean
+  intrinsic never number object string symbol undefined unknown
+  Rows globalThis PgArray
+`
+    .trim()
+    .split(/\s+/));
+function canExportRowName(name) {
+    return (/^[$_\p{ID_Start}][$_\u200c\u200d\p{ID_Continue}]*$/u.test(name) && !reservedTypeNames.has(name));
+}
+// A string means the read and write representations match. Arrays use verified
+// built-in OIDs because their parsers can differ from scalar parsers (numeric[]).
+const arrayTypes = {
+    '1000': 'boolean',
+    '1001': 'import("node:buffer").Buffer',
+    '1005': 'number',
+    '1007': 'number',
+    '1021': 'number',
+    '1022': 'number',
+    '1028': 'number',
+    '1016': { read: 'string', write: 'string | bigint' },
+    '1231': { read: 'number', write: 'string | number' },
+    '1009': 'string',
+    '1014': 'string',
+    '1015': 'string',
+    '1183': 'string',
+    '1270': 'string',
+    '2951': 'string',
+    '1182': { read: 'globalThis.Date | number', write: 'globalThis.Date | string' },
+    '1115': { read: 'globalThis.Date | number', write: 'globalThis.Date | string' },
+    '1185': { read: 'globalThis.Date | number', write: 'globalThis.Date | string' },
+    '199': { read: 'unknown', write: 'string' },
+    '3807': { read: 'unknown', write: 'string' },
+};
+const scalarTypes = {
+    int2: 'number',
+    int4: 'number',
+    oid: 'number',
+    float4: 'number',
+    float8: 'number',
+    bool: 'boolean',
+    text: 'string',
+    name: 'string',
+    varchar: 'string',
+    bpchar: 'string',
+    time: 'string',
+    timetz: 'string',
+    uuid: 'string',
+    // pg returns +/-Infinity as numbers. TypeScript has no infinity literal type.
+    date: { read: 'globalThis.Date | number', write: 'globalThis.Date | string' },
+    timestamp: { read: 'globalThis.Date | number', write: 'globalThis.Date | string' },
+    timestamptz: { read: 'globalThis.Date | number', write: 'globalThis.Date | string' },
+    int8: { read: 'string', write: 'string | bigint' },
+    numeric: { read: 'string', write: 'string | number' },
+    json: { read: 'unknown', write: 'string' },
+    jsonb: { read: 'unknown', write: 'string' },
+    bytea: 'import("node:buffer").Buffer',
+};
+function valueTypes(mapping) {
+    return typeof mapping === 'string' ? { read: mapping, write: mapping } : mapping;
+}
+function isSupportedArray(value) {
+    return Object.hasOwn(arrayTypes, value.oid);
+}
+function columnTypes(value, column, onWarning) {
+    let types;
+    if (isSupportedArray(value)) {
+        const element = valueTypes(arrayTypes[value.oid]);
+        types = { read: `PgArray<${element.read}>`, write: `PgArray<${element.write}>` };
+    }
+    else if (value.typeKind === 'e') {
+        const choice = value.choices?.map((choice) => JSON.stringify(choice)).join(' | ') || 'never';
+        types = { read: choice, write: choice };
+    }
+    else {
+        const type = value.typeSchema === 'pg_catalog' && Object.hasOwn(scalarTypes, value.type)
+            ? scalarTypes[value.type]
+            : undefined;
+        if (type) {
+            types = valueTypes(type);
+        }
+        else {
+            const underlying = value.declaredOid === value.oid
+                ? ''
+                : ` with underlying type ${JSON.stringify(value.typeSchema)}.${JSON.stringify(value.type)} (OID ${value.oid})`;
+            onWarning(`Column ${column} uses PostgreSQL type ${JSON.stringify(value.declaredSchema)}.${JSON.stringify(value.declaredType)} (OID ${value.declaredOid})${underlying} without a verified pg mapping; generated as unknown for reads and never for non-null writes.`);
+            types = { read: 'unknown', write: 'never' };
+        }
+    }
+    // unknown already includes null, including for nullable JSON and unmapped types.
+    return {
+        read: `${types.read}${value.nullable && types.read !== 'unknown' ? ' | null' : ''}`,
+        write: `${types.write}${value.writeNullable ? ' | null' : ''}`,
+    };
+}
+export function renderTableTypes(tables, namespace, onWarning) {
+    const definitions = tables.map((table) => {
+        const tableName = JSON.stringify(table.name);
+        const columns = table.columns.map((column) => {
+            const columnName = JSON.stringify(column.name);
+            const path = `${JSON.stringify(namespace)}.${tableName}.${columnName}`;
+            const types = columnTypes(column, path, onWarning);
+            const requiredOnInsert = column.writable && !column.hasDefault && !column.writeNullable;
+            const optionalInputType = column.writable ? `${types.write} | undefined` : 'never';
+            return {
+                row: `    ${columnName}: ${types.read};`,
+                insert: `    ${columnName}${requiredOnInsert ? '' : '?'}: ${requiredOnInsert ? types.write : optionalInputType};`,
+                update: `    ${columnName}?: ${optionalInputType};`,
+            };
+        });
+        return { tableName, columns };
+    });
+    const render = (kind, indent = '') => definitions
+        .map(({ tableName, columns }) => `${indent}  ${tableName}: {
+${columns.map((column) => indent + column[kind]).join('\n')}
+${indent}  };`)
+        .join('\n');
+    const aliases = tables
+        .filter((table) => canExportRowName(table.name))
+        .map((table) => `export type ${table.name} = Rows[${JSON.stringify(table.name)}];`);
+    const arrays = tables.some((table) => table.columns.some(isSupportedArray))
+        ? 'export type PgArray<T> = (T | null | PgArray<T>)[];\n\n'
+        : '';
+    return `${arrays}// Full database rows. Compose query types with Pick, indexed access, and intersections.
+export type Rows = {
+${render('row')}
+};
+
+export declare namespace Rows {
+  // Bound inputs for sql.insertValues. Missing/undefined fields use database defaults.
+  type Insert = {
+${render('insert', '  ')}
+  };
+
+  // Bound inputs for sql.assignments. Missing/undefined fields are omitted.
+  type Update = {
+${render('update', '  ')}
+  };
+}
+${aliases.join('\n')}
+`;
+}

package/dist/mutations.d.ts

@@ -1,7 +1,7 @@
 export type MutationPart = string | Readonly<{
     value: unknown;
 }>;
-export type MutationColumns<Row> = Row extends object ? Extract<keyof Row, string> : never;
+export type MutationColumns<Input> = Input extends object ? Extract<keyof Input, string> : never;
 /** Validate and quote one explicit column list, shared by runtime and SQL checking. */
 export declare function mutationColumns(columns: readonly string[]): string[];
 /** SQL structure depends only on these columns and cells, never on JavaScript source. */

package/dist/query.d.ts

@@ -21,9 +21,9 @@ export interface SqlFragment {
 declare function fragment(strings: TemplateStringsArray, ...values: readonly unknown[]): SqlFragment;
 declare function join(fragments: readonly SqlFragment[], separator: 'AND' | 'OR' | ','): SqlFragment;
 /** Object fields become bound values; absent insert cells use PostgreSQL defaults. */
-declare function insertValues<Row extends object>(input: Row | readonly Row[], columns?: readonly NoInfer<MutationColumns<Row>>[]): SqlFragment;
+declare function insertValues<Input extends object>(input: Input | readonly Input[], columns?: readonly NoInfer<MutationColumns<Input>>[]): SqlFragment;
 /** Omit undefined fields; null remains a value. Empty assignments reject. */
-declare function assignments<Row extends object>(input: Row, columns?: readonly NoInfer<MutationColumns<Row>>[]): SqlFragment;
+declare function assignments<Input extends object>(input: Input, columns?: readonly NoInfer<MutationColumns<Input>>[]): SqlFragment;
 declare function createQuery<Row extends QueryResultRow = UnknownRow>(strings: TemplateStringsArray, ...values: readonly unknown[]): NoInfer<SqlQuery<Row>>;
 /** Values bind parameters; identifiers quote names; fragments compose authored SQL. */
 export declare const sql: typeof createQuery & {

package/dist/query.js

@@ -111,7 +111,7 @@ export function unsafeSql(text, values) {
     if (!Array.isArray(values))
         throw new Error('SQL input must be an explicit array.');
     if (values.length > 65535)
-        throw new Error('A PostgreSQL query supports at most 65535 bound parameters; split large batches explicitly.');
+        throw new Error(`A PostgreSQL query supports at most 65535 bound parameters; received ${values.length}. Split large batches explicitly.`);
     return Object.freeze({ [queryTag]: true, text, values: Object.freeze([...values]) });
 }
 export function assertQuery(value) {

package/dist/safeql/composition.js

@@ -106,6 +106,15 @@ export function renderFragment(node, checker, seen = new Set()) {
         }
         return list.elements.map((item) => renderFragment(item, checker, visited)).join(between);
     }
+    if (ts.isCallExpression(node)) {
+        throw new CompositionError(`Function-generated fragments from ${node.expression.getText()}() are not analyzed; the checker does not inspect function bodies.`);
+    }
+    if (ts.isConditionalExpression(node)) {
+        throw new CompositionError('Conditional fragments are not analyzed; the checker does not choose JavaScript branches, even for literal conditions.');
+    }
+    if (ts.isIdentifier(node)) {
+        throw new CompositionError(`Fragment "${node.text}" has no inspectable const initializer; mutable and runtime-supplied fragments are not analyzed.`);
+    }
     throw new CompositionError('Only constant sql.fragment templates, literal sql.join arrays, and official mutation helpers are supported. Function-generated fragments and conditional SQL structure are not analyzed.');
 }
 export function renderIdentifier(node, checker, seen = new Set()) {

package/dist/safeql/eslint.js

@@ -22,21 +22,26 @@ export const eslintPlugin = {
                             !ts.isTaggedTemplateExpression(template) ||
                             !isExport(template.tag, checker, 'sql'))
                             return;
-                        try {
-                            if (node.quasi.quasis.some(({ value }) => value.raw !== value.cooked)) {
-                                throw new CompositionError('JavaScript escapes in an outer sql template would be checked as different SQL. Use literal newlines and bound string values instead.');
-                            }
-                            if (ts.isTemplateExpression(template.template)) {
-                                for (const span of template.template.templateSpans) {
+                        if (node.quasi.quasis.some(({ value }) => value.raw !== value.cooked)) {
+                            context.report({
+                                node,
+                                message: new CompositionError('JavaScript escapes in an outer sql template would be checked as different SQL. Use literal newlines and bound string values instead.').message,
+                            });
+                            return;
+                        }
+                        if (ts.isTemplateExpression(template.template)) {
+                            for (const [index, span] of template.template.templateSpans.entries()) {
+                                try {
                                     renderValue(span.expression, checker);
                                 }
+                                catch (error) {
+                                    if (!(error instanceof CompositionError))
+                                        throw error;
+                                    context.report({ node: node.quasi.expressions[index], message: error.message });
+                                    return;
+                                }
                             }
                         }
-                        catch (error) {
-                            if (!(error instanceof CompositionError))
-                                throw error;
-                            context.report({ node, message: error.message });
-                        }
                     },
                 };
             },

package/docs/adoption-guide.md

@@ -11,10 +11,10 @@ queries or generate types; keep the existing migration runner if that is the int
 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:
+2. If row and mutation input types will help your application, generate them from the existing database:
 
    ```sh
-   npx tenon generate --out src/generated-schema.ts
+   npx tenon generate --out src/generated-schema.d.ts
    ```
 
    Use `--namespace name` for a non-public schema. Generation reads the actual database and requires
@@ -25,14 +25,107 @@ queries or generate types; keep the existing migration runner if that is the int
    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
+   [SafeQL integration](reference.md#sql-checking-with-safeql) and follow the
+   [incremental audit workflow](#adopt-sql-checking-incrementally) below before accepting generated
+   annotations. 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.
 
+## Replace local write helpers
+
+Use `sql.insertValues(rows)` and `sql.assignments(patch)` in place of local object-to-SQL utilities:
+
+```ts
+import { sql } from '@kequtech/tenon-orm';
+
+const insert = sql`INSERT INTO profiles ${sql.insertValues(rows)} RETURNING id`;
+const update = sql`UPDATE profiles SET ${sql.assignments(patch)} WHERE id = ${id}`;
+```
+
+Compare omission, defaults, nulls, and empty-input behavior with the old helpers. Keep expressions
+in SQL and remove the local utilities after their callers move. Generated `Rows.Insert` and
+`Rows.Update` types can replace handwritten table inputs; retain application-specific refinements
+and validation. Run the existing write and rollback workflows. See the [mutation cookbook](mutations.md).
+
+## Adopt SQL checking incrementally
+
+For an existing application, including Next.js, SQL checking can run as a separate audit while the
+normal lint/build commands keep their existing database requirements. Extend the existing flat
+ESLint configuration rather than replacing it. After installing the
+[checking dependencies](reference.md#install-and-configure), a single-database setup can use:
+
+```js
+// eslint.sql.config.mjs
+import { defineConfig } from 'eslint/config';
+import baseConfig from './eslint.config.mjs';
+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(baseConfig, {
+  files: ['src/**/*.ts', 'src/**/*.tsx'],
+  languageOptions: {
+    parser: tseslint.parser,
+    parserOptions: { projectService: true },
+  },
+  plugins: { tenon: eslintPlugin },
+  rules: { 'tenon/check-composition': 'error' },
+  extends: [
+    safeql.configs.connections({
+      databaseUrl,
+      plugins: [safeqlPlugin],
+      targets: [{ tag: { regex: '.*' } }],
+    }),
+  ],
+});
+```
+
+Preserve existing type-aware parser settings where configured. The broad target above lets Tenon
+recognize aliases; use distinct targets for [multiple databases](reference.md#configuration-choices-and-multiple-databases).
+The example does not load environment files. Use the application's existing environment loader
+and URL selection to supply its migrated development/test database through `DATABASE_URL`.
+
+```json
+{
+  "scripts": {
+    "lint:sql": "eslint --config eslint.sql.config.mjs \"src/**/*.{ts,tsx}\""
+  }
+}
+```
+
+Start with `npm run lint:sql`. Keep both checking rules enabled and distinguish the findings:
+
+- SQL errors identify problems in reconstructed SQL; review them before accepting inferred types.
+- Missing/mismatched annotations may reflect an outdated type, a deliberate application refinement,
+  or a checker limitation. They are not all demonstrated application bugs.
+- `tenon/check-composition` means SQL analysis was skipped. Add inline selected columns for opaque
+  mutation inputs where useful. Keep reusable authorization policy centralized when its fragments
+  remain unsupported, with database tests for runtime variants.
+
+Preview fixes on a small module first, without writing source. Invoke ESLint directly to select
+one file, since the script above already supplies a source glob:
+
+```sh
+npx eslint --config eslint.sql.config.mjs src/database/profiles.ts --fix-dry-run --format json
+```
+
+Review the proposed annotations, apply selected changes deliberately, and run TypeScript and
+database tests. Broader inferred types may require validation where raw database values enter the
+application. For example, require a finite `Date` before calling `.getTime()`, validate structured
+JSON from `unknown`, and justify CHECK-constrained string refinements with matching schema checks
+or a reviewed column override. Do not globally map timestamps to `Date`: pg can return numeric
+infinities. See [checker mappings](reference.md#supported-sql-and-limitations).
+
+Unsupported queries have not had their SQL verified. Keep database tests for their runtime variants
+and use explained suppressions only where appropriate. Once the intended scope passes, make SQL
+checking a required CI step. Fix commands can also apply other enabled ESLint rules.
+
 ## Move migration ownership to Tenon
 
 Choose one final schema checkpoint for the old runner and bring existing target databases to it.