@kequtech/tenon-orm 0.3.1 → 0.4.2

package/dist/generation/catalog.d.ts

@@ -1,13 +1,12 @@
-import type { PoolClient } from 'pg';
+import { type InputValue, type QueryResult, type Row } from '@kequtech/pgclear';
+export interface CatalogClient {
+    query<T extends object = Row>(text: string, values?: readonly InputValue[]): Promise<QueryResult<T>>;
+}
 export interface ColumnRow {
     name: string;
     oid: string;
-    type: string;
-    typeSchema: string;
     typeKind: string;
     declaredOid: string;
-    declaredType: string;
-    declaredSchema: string;
     nullable: boolean;
     writeNullable: boolean;
     hasDefault: boolean;
@@ -19,4 +18,4 @@ export interface TableRow {
     name: string;
     columns: ColumnRow[];
 }
-export declare function readTables(client: PoolClient, namespace: string): Promise<TableRow[]>;
+export declare function readTables(client: CatalogClient, namespace: string, exclude: readonly string[]): Promise<TableRow[]>;

package/dist/generation/catalog.js

@@ -1,11 +1,11 @@
-import { migrationTable } from '../migrations/history.js';
-export async function readTables(client, namespace) {
+import { builtin, param } from '@kequtech/pgclear';
+export async function readTables(client, namespace, exclude) {
     const tables = await client.query(`
       SELECT c.oid::text AS oid, c.relname AS name
       FROM pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
-      WHERE n.nspname = $1 AND c.relname <> $2 AND c.relkind IN ('r', 'p')
+      WHERE n.nspname = $1 AND NOT (c.relname = ANY($2::text[])) AND c.relkind IN ('r', 'p')
         AND NOT c.relispartition
-      ORDER BY c.relname COLLATE "C"`, [namespace, migrationTable]);
+      ORDER BY c.relname COLLATE "C"`, [namespace, param(exclude, builtin.textArray)]);
     const definitions = [];
     for (const table of tables.rows) {
         // Attached descendants are storage details, not separate generated models.
@@ -18,8 +18,8 @@ export async function readTables(client, namespace) {
           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",
+        SELECT a.attname AS name, t.oid::text AS oid, t.typtype AS "typeKind",
+          declared.oid::text AS "declaredOid",
           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",
@@ -28,11 +28,9 @@ export async function readTables(client, namespace) {
         FROM pg_catalog.pg_attribute a
           JOIN resolved r ON r.attnum = a.attnum AND r.typbasetype = 0
           JOIN pg_catalog.pg_type t ON t.oid = r.oid
-          JOIN pg_catalog.pg_namespace tn ON tn.oid = t.typnamespace
           JOIN pg_catalog.pg_type declared ON declared.oid = a.atttypid
-          JOIN pg_catalog.pg_namespace dn ON dn.oid = declared.typnamespace
         WHERE a.attrelid = $1::oid AND a.attnum > 0 AND NOT a.attisdropped ORDER BY a.attnum`, [table.oid]);
-        definitions.push({ ...table, columns: columns.rows });
+        definitions.push({ ...table, columns: [...columns.rows] });
     }
     return definitions;
 }

package/dist/generation/output.js

@@ -14,12 +14,11 @@ export 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.`);
+            throw new Error(`Generated definitions file is missing: ${output}\nRun db.generateTypes with the same options and check: false, then commit the result.`);
         }
         if (existing !== source) {
-            throw new Error(`Generated definitions differ: ${output}\n${definitionDiff(existing, source)}\nRun tenon generate with the same options, omitting --check, then commit the result.`);
+            throw new Error(`Generated definitions differ: ${output}\n${definitionDiff(existing, source)}\nRun db.generateTypes with the same options and check: false, then commit the result.`);
         }
-        process.stdout.write('Generated definitions are current.\n');
         return;
     }
     await mkdir(dirname(output), { recursive: true });
@@ -31,5 +30,4 @@ export async function writeDefinitions(source, filename, check) {
     finally {
         await rm(temporary, { force: true });
     }
-    process.stdout.write(`Generated ${output}\n`);
 }

package/dist/generation/render.d.ts

@@ -0,0 +1,3 @@
+import { type CodecRegistry } from '@kequtech/pgclear';
+import type { TableRow } from './catalog.js';
+export declare function renderDatabase(tables: readonly TableRow[], namespace: string, codecs: CodecRegistry, warn: (message: string) => void): string;

package/dist/generation/render.js

@@ -0,0 +1,60 @@
+import { defaultCodecs } from '@kequtech/pgclear';
+function columnTypes(column, codecs, path, warn) {
+    const oid = Number(column.oid);
+    let read = codecs.typescript(oid);
+    if (read === undefined) {
+        warn(`Column ${path} uses a custom decoder without a known TypeScript representation; generated as unknown.`);
+        read = 'unknown';
+    }
+    const choices = column.choices?.map((choice) => JSON.stringify(choice)).join(' | ') || 'never';
+    if (column.typeKind === 'e' && codecs === defaultCodecs && read === 'string')
+        read = choices;
+    let write = defaultCodecs.typescript(oid);
+    if (column.typeKind === 'e')
+        write = choices;
+    if (write === 'unknown' || write.startsWith('PgArray<'))
+        write = 'string';
+    if ([20, 1700].includes(oid))
+        write += ' | bigint';
+    if ([1082, 1114, 1184].includes(oid))
+        write += ' | globalThis.Date | TemporalInput';
+    if ([1083, 1186].includes(oid))
+        write += ' | TemporalInput';
+    // Explicit parameters handle arrays, JSON and application-owned codecs without accepting
+    // ambiguous bare JS objects/arrays as ordinary binds.
+    write = write === 'never' ? 'Parameter' : `${write} | Parameter`;
+    return {
+        read: column.nullable && read !== 'unknown' ? `(${read}) | null` : read,
+        write: write + (column.writeNullable ? ' | null' : ''),
+    };
+}
+export function renderDatabase(tables, namespace, codecs, warn) {
+    let arrays = false, parameters = false, temporalInputs = false;
+    const definitions = tables.map((table) => {
+        const columns = table.columns.map((column) => {
+            const name = JSON.stringify(column.name);
+            const types = columnTypes(column, codecs, [namespace, table.name, column.name].map((value) => JSON.stringify(value)).join('.'), warn);
+            arrays ||= /\bPgArray\s*</.test(types.read);
+            parameters ||= column.writable;
+            temporalInputs ||= column.writable && types.write.includes('TemporalInput');
+            const required = column.writable && !column.hasDefault && !column.writeNullable;
+            const optional = column.writable ? `${types.write} | undefined` : 'never';
+            return {
+                row: `      ${name}: ${types.read};`,
+                insert: `      ${name}${required ? '' : '?'}: ${required ? types.write : optional};`,
+                update: `      ${name}?: ${optional};`,
+            };
+        });
+        const shape = (kind) => `    ${kind}: {\n${columns.map((column) => column[kind]).join('\n')}\n    };`;
+        return `  ${JSON.stringify(table.name)}: {\n${shape('row')}\n${shape('insert')}\n${shape('update')}\n  };`;
+    });
+    const imports = [
+        ...(parameters ? ['Parameter'] : []),
+        ...(arrays ? ['PgArray'] : []),
+        ...(temporalInputs ? ['TemporalInput'] : []),
+    ];
+    const header = imports.length
+        ? `import type { ${imports.join(', ')} } from '@kequtech/tenon-orm';\n\n`
+        : '';
+    return `${header}export type Database = {\n${definitions.join('\n')}\n};\n`;
+}

package/dist/generation/schema-summary.d.ts

@@ -1,6 +1,6 @@
-import type { PoolClient } from 'pg';
+import type { CatalogClient } from './catalog.js';
 /** Include only domains reached through selected columns, base domains or arrays. */
-export declare function domainSummaries(client: PoolClient, typeOids: readonly string[]): Promise<string[]>;
+export declare function domainSummaries(client: CatalogClient, typeOids: readonly string[]): Promise<string[]>;
 /** Called inside generation's read-only snapshot, with a fixed local search_path. */
-export declare function tableSummary(client: PoolClient, oid: string, name: string): Promise<string>;
+export declare function tableSummary(client: CatalogClient, oid: string, name: string): Promise<string>;
 export declare function schemaSummary(summaries: readonly string[]): string;

package/dist/generation/schema-summary.js

@@ -3,7 +3,7 @@ import { quote } from '../sql.js';
 export async function domainSummaries(client, typeOids) {
     const domains = await client.query(`
     WITH RECURSIVE referenced(oid) AS (
-      SELECT unnest($1::oid[])
+      SELECT pg_catalog.unnest(pg_catalog.string_to_array($1, ',')::pg_catalog.oid[])
       UNION
       SELECT child.oid FROM referenced r JOIN pg_catalog.pg_type t ON t.oid = r.oid
         CROSS JOIN LATERAL (VALUES (t.typbasetype), (t.typelem)) child(oid)
@@ -16,7 +16,7 @@ export async function domainSummaries(client, typeOids) {
     FROM referenced r JOIN pg_catalog.pg_type t ON t.oid = r.oid
       JOIN pg_catalog.pg_type base ON base.oid = t.typbasetype
     WHERE t.typtype = 'd'
-    ORDER BY pg_catalog.format_type(t.oid, NULL) COLLATE "C"`, [typeOids]);
+    ORDER BY pg_catalog.format_type(t.oid, NULL) COLLATE "C"`, [typeOids.join(',')]);
     const summaries = [];
     for (const domain of domains.rows) {
         const constraints = await client.query(`

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export { builtin, createTemporalCodecs, defaultCodecs, json, param } from '@kequtech/pgclear';
+export type { Codec, CodecRegistry, Parameter, PgArray, TemporalConstructors, TemporalInput, } from '@kequtech/pgclear';
 export type { Connection, ConnectionOptions, QueryResult } from './connection.js';
 export type { AffectedRowsConstraint } from './affected-rows.js';
 export { createTenon } from './database.js';
@@ -12,7 +14,7 @@ export type { DescribeOptions, DescribedColumn, DescribedType, DescriptionIssue,
 export { adoptBaseline, captureBaseline } from './baseline.js';
 export type { CaptureBaselineOptions, CapturedBaseline } from './baseline.js';
 export { generateDefinitions } from './generate.js';
-export type { GenerateOptions } from './generate.js';
+export type { GenerateOptions, GenerateTypesOptions } from './generate.js';
 export { migrate, migrationStatus, rollback } from './migrations.js';
 export type { MigrationStatus } from './migrations.js';
 export type { DatabaseToolOptions } from './migrations/connection.js';

package/dist/index.js

@@ -1,3 +1,5 @@
+// Reuse Pgclear's value conversion helpers without exposing its separate SQL tag.
+export { builtin, createTemporalCodecs, defaultCodecs, json, param } from '@kequtech/pgclear';
 export { createTenon } from './database.js';
 export { AffectedRowsError, CardinalityError } from './errors.js';
 export { identifier, sql, unsafeSql } from './query.js';

package/dist/inspection/catalog.d.ts

@@ -1,12 +1,9 @@
-import type { Client } from 'pg';
-import { type Description } from './protocol.js';
+import type { Session } from '@kequtech/pgclear';
+import type { Description, DescribeStatement } from '@kequtech/pgclear';
 interface CatalogType {
     oid: number;
     schema: string;
     name: string;
-    kind: string;
-    base: number;
-    choices: string[] | null;
 }
 interface ColumnSource {
     oid: number;
@@ -22,5 +19,5 @@ export interface StatementMetadata {
     sources: readonly ColumnSource[];
 }
 /** Describe the statement and read its type and source-column catalog records. */
-export declare function readStatementMetadata(client: Client, text: string): Promise<StatementMetadata>;
+export declare function readStatementMetadata(client: Session, query: DescribeStatement): Promise<StatementMetadata>;
 export {};

package/dist/inspection/catalog.js

@@ -1,26 +1,17 @@
-import { describe } from './protocol.js';
 /** Describe the statement and read its type and source-column catalog records. */
-export async function readStatementMetadata(client, text) {
-    const statement = await describe(client, text);
+export async function readStatementMetadata(client, query) {
+    const statement = await client.describe(query);
     const oids = [
-        ...new Set([...statement.parameters, ...statement.fields.map((c) => c.dataTypeID)]),
+        ...new Set([...statement.parameterTypes, ...statement.fields.map((c) => c.dataTypeOid)]),
     ];
-    const types = (await client.query(`
-    WITH RECURSIVE wanted(oid) AS (
-      SELECT pg_catalog.unnest(pg_catalog.string_to_array($1, ',')::pg_catalog.oid[])
-      UNION
-      SELECT t.typbasetype FROM pg_catalog.pg_type t JOIN wanted w ON w.oid = t.oid
-        WHERE t.typbasetype <> 0
-    )
-    SELECT t.oid, n.nspname AS schema, t.typname AS name,
-      t.typtype AS kind, t.typbasetype AS base,
-      (SELECT pg_catalog.to_json(pg_catalog.array_agg(e.enumlabel::text ORDER BY e.enumsortorder))
-        FROM pg_catalog.pg_enum e WHERE e.enumtypid = t.oid) AS choices
-    FROM wanted w JOIN pg_catalog.pg_type t ON t.oid = w.oid
+    const types = (await client.queryClassic(`
+    SELECT t.oid, n.nspname AS schema, t.typname AS name
+    FROM pg_catalog.pg_type t
       JOIN pg_catalog.pg_namespace n ON n.oid = t.typnamespace
+    WHERE t.oid = ANY(pg_catalog.string_to_array($1, ',')::pg_catalog.oid[])
   `, [oids.join(',')])).rows;
-    const tables = [...new Set(statement.fields.map((c) => c.tableID).filter(Boolean))];
-    const sources = (await client.query(`
+    const tables = [...new Set(statement.fields.map((c) => c.tableOid).filter(Boolean))];
+    const sources = (await client.queryClassic(`
     SELECT c.oid, a.attnum AS number, n.nspname AS schema,
       c.relname AS table, a.attname AS column, a.attnotnull AS "notNull"
     FROM pg_catalog.pg_attribute a JOIN pg_catalog.pg_class c ON c.oid = a.attrelid

package/dist/inspection/cli.d.ts

@@ -19,4 +19,16 @@ export declare const describeFlags: {
     };
 };
 /** Translate CLI flags; validation and defaults belong to the public API. */
+export declare function inspectionSettings(values: Partial<Record<keyof typeof describeFlags, string | undefined>>): {
+    session: {
+        role: string | undefined;
+        searchPath: string | undefined;
+        timeZone: string | undefined;
+    };
+    timeouts: {
+        lockMs?: number;
+        statementMs?: number;
+        connectMs?: number;
+    };
+};
 export declare function runDescribe(filename: string, connection: string, values: Partial<Record<keyof typeof describeFlags, string | undefined>>): Promise<void>;

package/dist/inspection/cli.js

@@ -9,10 +9,8 @@ export const describeFlags = {
     'lock-timeout-ms': { type: 'string' },
 };
 /** Translate CLI flags; validation and defaults belong to the public API. */
-export async function runDescribe(filename, connection, values) {
-    const result = await describeQuery({
-        connection,
-        query: await readFile(filename, 'utf8'),
+export function inspectionSettings(values) {
+    return {
         session: {
             role: values.role,
             searchPath: values['search-path'],
@@ -29,6 +27,13 @@ export async function runDescribe(filename, connection, values) {
                 ? { lockMs: Number(values['lock-timeout-ms']) }
                 : {}),
         },
+    };
+}
+export async function runDescribe(filename, connection, values) {
+    const result = await describeQuery({
+        connection,
+        query: await readFile(filename, 'utf8'),
+        ...inspectionSettings(values),
     });
     process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
 }

package/dist/inspection/connection.d.ts

@@ -1,4 +1,3 @@
-import { Client } from 'pg';
+import { type Session } from '@kequtech/pgclear';
 import type { DescribeOptions, InspectionContext } from './types.js';
-/** Bound every database statement, including bootstrap and metadata queries. */
-export declare function withInspectionConnection<T>(options: Pick<DescribeOptions, 'connection' | 'session' | 'timeouts'>, work: (client: Client, context: InspectionContext) => Promise<T>): Promise<T>;
+export declare function withInspectionConnection<T>(options: Pick<DescribeOptions, 'connection' | 'session' | 'timeouts'>, work: (client: Session, context: InspectionContext) => Promise<T>): Promise<T>;

package/dist/inspection/connection.js

@@ -1,22 +1,17 @@
-import { Client } from 'pg';
+import { connect } from '@kequtech/pgclear';
 import { inspectionOptions } from './options.js';
-/** Bound every database statement, including bootstrap and metadata queries. */
 export async function withInspectionConnection(options, work) {
     const { url, limits, session } = inspectionOptions(options);
-    const client = new Client({
+    const connection = await connect({
         connectionString: url.toString(),
-        connectionTimeoutMillis: limits.connectMs,
-        statement_timeout: limits.statementMs,
-        lock_timeout: limits.lockMs,
-        pipeline: false,
+        connectTimeoutMs: limits.connectMs,
+        startupParameters: {
+            statement_timeout: String(limits.statementMs),
+            lock_timeout: String(limits.lockMs),
+        },
     });
-    // Disconnection errors outside an active query must still have a listener.
-    client.on('error', () => { });
+    const client = connection;
     try {
-        await client.connect();
-        await client.query(`SELECT
-      pg_catalog.set_config('statement_timeout', $1, false),
-      pg_catalog.set_config('lock_timeout', $2, false)`, [String(limits.statementMs), String(limits.lockMs)]);
         for (const [key, name] of [
             ['role', 'role'],
             ['searchPath', 'search_path'],
@@ -24,21 +19,24 @@ export async function withInspectionConnection(options, work) {
         ]) {
             const value = session[key];
             if (value !== undefined)
-                await client.query('SELECT pg_catalog.set_config($1, $2, false)', [name, value]);
+                await client.queryClassic('SELECT pg_catalog.set_config($1, $2, false)', [name, value]);
         }
-        const { rows: [context], } = await client.query(`
-      SELECT pg_catalog.current_database() AS database, session_user AS "sessionUser",
-        current_user AS "currentUser", pg_catalog.current_setting('search_path') AS "searchPath",
+        const { rows: [context], } = await client.queryClassic(`
+      SELECT pg_catalog.current_database() AS database,
+        session_user AS "sessionUser", current_user AS "currentUser",
+        pg_catalog.current_setting('search_path') AS "searchPath",
         pg_catalog.to_json(pg_catalog.current_schemas(true)) AS "resolvedSearchPath",
         pg_catalog.current_setting('TimeZone') AS "timeZone",
-        (SELECT setting::integer FROM pg_catalog.pg_settings WHERE name='statement_timeout') AS "statementTimeoutMs",
-        (SELECT setting::integer FROM pg_catalog.pg_settings WHERE name='lock_timeout') AS "lockTimeoutMs"
-    `);
+        (SELECT setting::integer FROM pg_catalog.pg_settings
+          WHERE name = 'statement_timeout') AS "statementTimeoutMs",
+        (SELECT setting::integer FROM pg_catalog.pg_settings
+          WHERE name = 'lock_timeout') AS "lockTimeoutMs"
+    `, []);
         if (!context)
             throw new Error('Inspection context was not returned.');
-        return await work(client, { mode: 'separate-session', readMappings: 'pg', ...context });
+        return await work(client, { mode: 'separate-session', readMappings: 'pgclear', ...context });
     }
     finally {
-        await client.end();
+        await connection.close();
     }
 }

package/dist/inspection/options.js

@@ -44,12 +44,6 @@ export function inspectionOptions(options) {
     if (!['postgres:', 'postgresql:'].includes(url.protocol)) {
         throw new Error('Describe requires a PostgreSQL connection URI.');
     }
-    for (const [name, value] of [
-        ['statement_timeout', limits.statementMs],
-        ['lock_timeout', limits.lockMs],
-    ]) {
-        url.searchParams.set(name, String(value));
-    }
     if (!url.searchParams.has('application_name')) {
         url.searchParams.set('application_name', 'tenon-describe');
     }

package/dist/inspection/result.d.ts

@@ -1,4 +1,5 @@
+import type { CodecRegistry } from '@kequtech/pgclear';
 import type { StatementMetadata } from './catalog.js';
 import type { InspectionContext, QueryDescription } from './types.js';
-/** Convert database metadata to conservative pg types and diagnostics. */
-export declare function queryDescription({ statement, types, sources }: StatementMetadata, context: InspectionContext): QueryDescription;
+/** Read representations follow the selected registry's wire OIDs, not catalog base types. */
+export declare function queryDescription({ statement, types, sources }: StatementMetadata, context: InspectionContext, codecs: CodecRegistry): QueryDescription;

package/dist/inspection/result.js

@@ -1,32 +1,19 @@
-import { arrayTypes, scalarTypes, valueTypes } from '../driver/types.js';
-/** Convert database metadata to conservative pg types and diagnostics. */
-export function queryDescription({ statement, types, sources }, context) {
+/** Read representations follow the selected registry's wire OIDs, not catalog base types. */
+export function queryDescription({ statement, types, sources }, context, codecs) {
     const catalog = new Map(types.map((t) => [t.oid, t]));
     const issues = new Map();
     function describeType(oid) {
         const type = catalog.get(oid);
         if (!type)
             throw new Error(`PostgreSQL type OID ${oid} was not found.`);
-        let readType;
-        if (type.base) {
-            readType = describeType(type.base).readType;
-        }
-        else if (type.kind === 'e') {
-            readType = type.choices?.map((v) => JSON.stringify(v)).join(' | ') || 'never';
-        }
-        else if (Object.hasOwn(arrayTypes, String(oid))) {
-            readType = `PgArray<${valueTypes(arrayTypes[String(oid)]).read}>`;
-        }
-        else if (type.schema === 'pg_catalog' && Object.hasOwn(scalarTypes, type.name)) {
-            readType = valueTypes(scalarTypes[type.name]).read;
-        }
-        else {
-            readType = 'unknown';
+        const representation = codecs.typescript(oid);
+        const readType = representation ?? 'unknown';
+        if (representation === undefined) {
             issues.set(`type:${oid}`, {
                 code: 'unmapped-type',
                 oid,
                 postgres: `${type.schema}.${type.name}`,
-                message: `No verified pg mapping for ${type.schema}.${type.name} (OID ${oid}).`,
+                message: `The selected pgclear registry cannot identify the decoder representation for ${type.schema}.${type.name} (OID ${oid}). Supply an application type for this custom decoder.`,
             });
         }
         return { oid, postgres: `${type.schema}.${type.name}`, readType };
@@ -38,14 +25,14 @@ export function queryDescription({ statement, types, sources }, context) {
             issues.set(`column:${column.name}`, {
                 code: 'duplicate-column',
                 column: column.name,
-                message: `Duplicate result column ${JSON.stringify(column.name)}; object rows overwrite earlier values.`,
+                message: `Duplicate result column ${JSON.stringify(column.name)}; pgclear rejects duplicate object columns.`,
             });
         }
         names.add(column.name);
-        const source = sourceMap.get(`${column.tableID}:${column.columnID}`);
+        const source = sourceMap.get(`${column.tableOid}:${column.columnAttribute}`);
         return {
             name: column.name,
-            ...describeType(column.dataTypeID),
+            ...describeType(column.dataTypeOid),
             nullability: 'unknown',
             source: source
                 ? {
@@ -57,7 +44,7 @@ export function queryDescription({ statement, types, sources }, context) {
                 : null,
         };
     });
-    const parameters = statement.parameters.map(describeType);
+    const parameters = statement.parameterTypes.map(describeType);
     if (columns.length) {
         issues.set('nullability', {
             code: 'nullability-unknown',
@@ -74,9 +61,9 @@ export function queryDescription({ statement, types, sources }, context) {
             message: 'An unknown read type does not verify JSON structure or an application-specific result type.',
         });
     }
-    const members = columns.map((c) => `  ${JSON.stringify(c.name)}: ${c.readType}${c.readType === 'unknown' ? '' : ' | null'};`);
-    const array = columns.some((c) => c.readType.startsWith('PgArray<'))
-        ? 'type PgArray<T> = (T | null | PgArray<T>)[];\n'
+    const members = columns.map((c) => `  ${JSON.stringify(c.name)}: ${c.readType === 'unknown' ? c.readType : `(${c.readType}) | null`};`);
+    const array = columns.some((c) => /\bPgArray\b/.test(c.readType))
+        ? 'type PgArray<T> = readonly (T | null | PgArray<T>)[];\n'
         : '';
     return {
         context,

package/dist/inspection/types.d.ts

@@ -1,4 +1,4 @@
-import type { SqlQuery } from '../query.js';
+import type { CodecRegistry, DescribeStatement } from '@kequtech/pgclear';
 export interface InspectionSession {
     readonly role?: string | undefined;
     /** PostgreSQL's search_path setting, as used in the application's connection options. */
@@ -20,13 +20,15 @@ export interface InspectionContext {
     readonly timeZone: string;
     readonly statementTimeoutMs: number;
     readonly lockTimeoutMs: number;
-    readonly readMappings: 'pg';
+    readonly readMappings: 'pgclear';
 }
 export interface DescribeOptions {
     /** PostgreSQL connection URI. Inspection owns a separate, short-lived connection. */
     readonly connection: string;
     /** Finished SQL; query values are neither bound nor executed. */
-    readonly query: string | Pick<SqlQuery, 'text'>;
+    readonly query: string | DescribeStatement;
+    /** Use the same registry as execution; custom decoder types can remain unresolved. */
+    readonly codecs?: CodecRegistry | undefined;
     readonly session?: InspectionSession | undefined;
     readonly timeouts?: InspectionTimeouts | undefined;
 }
@@ -50,7 +52,7 @@ export type DescriptionIssue = {
 export interface DescribedType {
     readonly oid: number;
     readonly postgres: string;
-    /** pg read representation, before considering result nullability. */
+    /** pgclear read representation, before considering result nullability. */
     readonly readType: string;
 }
 export interface DescribedColumn extends DescribedType {

package/dist/migrations/connection.d.ts

@@ -1,9 +1,9 @@
-import type { PoolClient } from 'pg';
+import { type Session } from '@kequtech/pgclear';
 import type { Connection } from '../connection.js';
 export interface DatabaseToolOptions {
     readonly connection: Connection;
     readonly namespace?: string;
     readonly directory?: string;
 }
-/** Coordinate tools independently of application sessions; PostgreSQL owns the wait. */
-export declare function withMigrationLock<T>(options: DatabaseToolOptions, mode: 'shared' | 'exclusive', work: (client: PoolClient, namespace: string) => Promise<T>): Promise<T>;
+/** Hold one session advisory lock while tooling runs, restoring transactions before release. */
+export declare function withMigrationLock<T>(options: DatabaseToolOptions, mode: 'shared' | 'exclusive', work: (client: Session, namespace: string) => Promise<T>): Promise<T>;

package/dist/migrations/connection.js

@@ -1,6 +1,7 @@
-import { createConnection, watchClient } from '../connection.js';
+import { defaultCodecs } from '@kequtech/pgclear';
+import { createConnection } from '../connection.js';
 import { validateName } from '../sql.js';
-/** Coordinate tools independently of application sessions; PostgreSQL owns the wait. */
+/** Hold one session advisory lock while tooling runs, restoring transactions before release. */
 export async function withMigrationLock(options, mode, work) {
     const namespace = options.namespace ?? 'public';
     validateName(namespace);
@@ -8,41 +9,34 @@ export async function withMigrationLock(options, mode, work) {
     const suffix = mode === 'shared' ? '_shared' : '';
     const lockKey = `tenon:migrations:${namespace}`;
     const errors = [];
-    let client;
-    let connection;
+    let lease;
     let locked = false;
     let result;
     try {
-        client = await pool.connect();
-        connection = watchClient(client);
-        await client.query(`SELECT pg_advisory_lock${suffix}(hashtextextended($1, 0))`, [lockKey]);
+        lease = await pool.acquire();
+        const client = lease;
+        await client.queryClassic(`SELECT pg_advisory_lock${suffix}(hashtextextended($1, 0))`, [lockKey], { codecs: defaultCodecs });
         locked = true;
         result = await work(client, namespace);
-        connection.check();
     }
     catch (error) {
         errors.push(error);
     }
     finally {
-        if (client) {
-            let releaseError;
+        if (lease) {
+            const client = lease;
             try {
-                connection.check();
-                if (errors.length)
-                    await client.query('ROLLBACK');
+                if (lease.transactionStatus !== 'idle')
+                    await client.queryClassic('ROLLBACK', []);
                 if (locked) {
-                    await client.query(`SELECT pg_advisory_unlock${suffix}(hashtextextended($1, 0))`, [
-                        lockKey,
-                    ]);
+                    await client.queryClassic(`SELECT pg_advisory_unlock${suffix}(hashtextextended($1, 0))`, [lockKey], { codecs: defaultCodecs });
                 }
             }
             catch (error) {
                 errors.push(error);
-                releaseError =
-                    error instanceof Error ? error : new Error('Tool connection cleanup failed.');
             }
             try {
-                connection.release(releaseError);
+                await lease.release({ discard: errors.length > 0 });
             }
             catch (error) {
                 errors.push(error);
@@ -55,9 +49,8 @@ export async function withMigrationLock(options, mode, work) {
             errors.push(error);
         }
     }
-    if (errors.length === 1) {
+    if (errors.length === 1)
         throw errors[0];
-    }
     if (errors.length > 1) {
         throw new AggregateError(errors, 'Database operation and cleanup failed.');
     }

package/dist/migrations/history.d.ts

@@ -1,4 +1,4 @@
-import type { PoolClient } from 'pg';
+import type { Session } from '@kequtech/pgclear';
 import type { SqlMigration } from './files.js';
 export declare const migrationTable = "__tenon_migrations";
 interface AppliedMigration {
@@ -6,7 +6,7 @@ interface AppliedMigration {
     name: string;
     checksum: string;
 }
-export declare function migrationState(client: PoolClient, namespace: string, migrations: readonly SqlMigration[]): Promise<readonly AppliedMigration[]>;
-export declare function createHistoryTable(client: PoolClient, namespace: string): Promise<void>;
-export declare function recordMigration(client: PoolClient, namespace: string, migration: SqlMigration): Promise<void>;
+export declare function migrationState(client: Session, namespace: string, migrations: readonly SqlMigration[]): Promise<readonly AppliedMigration[]>;
+export declare function createHistoryTable(client: Session, namespace: string): Promise<void>;
+export declare function recordMigration(client: Session, namespace: string, migration: SqlMigration): Promise<void>;
 export {};