@dbsp/adapter-pgsql 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,2154 @@
+import { ExpressionRef, IndexInfo, TruncateOptions, VacuumOptions, AlterColumnOptions, CreateIndexOptions, DropIndexOptions, ModelIR as ModelIR$1 } from '@dbsp/core';
+export { normalizeSQL } from '@dbsp/core';
+import * as _dbsp_types from '@dbsp/types';
+import { DialectCapabilities, ModelIR, DbCasing, ColumnIR, HierarchyIR, Adapter, AdapterLogger, AdapterCapabilities, PlanReport, CompileOptions, CompiledQuery, CompileResultWithIncludes, SubqueryIncludeInfo, ExpressionIntent, InsertIntent, InsertFromIntent, UpdateIntent, BatchUpdateIntent, DeleteIntent, UpsertIntent, UpsertFromIntent, RecursivePlanReport, CteQueryIntent, SetOperationIntent, DumpMeta, Dump, AdapterStreamOptions, CompileOnlyAdapter, QueryIntent } from '@dbsp/types';
+import * as _pgsql_types from '@pgsql/types';
+import { Node, OnConflictClause, ParamRef } from '@pgsql/types';
+import { Pool, PoolClient } from 'pg';
+
+/**
+ * Default primary key column name used as convention fallback
+ * when schema metadata doesn't provide an explicit PK.
+ *
+ * Consumers (handlers, compiler) must NOT use this directly —
+ * they use `requiredColumn()` to throw on missing data.
+ * Only convention mappers (extractors, introspection) should reference this.
+ */
+declare const DEFAULT_PK_COLUMN = "id";
+/**
+ * Derive a foreign key column name from a table name and the PK column it references.
+ *
+ * Convention: `${singularTableName}_${pkColumnName}`
+ * e.g. (authors, id) → author_id, (categories, id) → category_id
+ *
+ * Consumers should use `deriveFkColumnName` from CompilerContext or options
+ * for configurable behavior.
+ */
+type FkColumnDerivation = (tableName: string, pkColumnName: string) => string;
+declare const defaultFkDerivation: FkColumnDerivation;
+
+/**
+ * NamingPlugin - Identifier transformation between model and database naming conventions
+ *
+ * Inspired by Kysely's CamelCasePlugin architecture.
+ * The plugin transforms identifiers bidirectionally:
+ * - toDatabase: model name (camelCase) → database name (snake_case)
+ * - toModel: database name (snake_case) → model name (camelCase)
+ */
+/**
+ * Interface for naming convention transformation plugins
+ */
+interface NamingPlugin {
+    /**
+     * Transform a model identifier to database format
+     * Example: "createdAt" → "created_at"
+     */
+    toDatabase(identifier: string): string;
+    /**
+     * Transform a database identifier to model format
+     * Example: "created_at" → "createdAt"
+     */
+    toModel(identifier: string): string;
+}
+/**
+ * Identity plugin - no transformation
+ * Use this when model and database naming conventions match
+ */
+declare class IdentityNamingPlugin implements NamingPlugin {
+    toDatabase(identifier: string): string;
+    toModel(identifier: string): string;
+}
+/**
+ * CamelCase ↔ snake_case transformation plugin
+ *
+ * Follows the same logic as Kysely's CamelCasePlugin:
+ * - Handles consecutive uppercase letters (e.g., "parseJSON" → "parse_json")
+ * - Handles numbers (e.g., "field1Name" → "field1_name")
+ * - Preserves leading underscores
+ */
+declare class CamelCaseNamingPlugin implements NamingPlugin {
+    /**
+     * camelCase → snake_case
+     */
+    toDatabase(identifier: string): string;
+    /**
+     * snake_case → camelCase
+     */
+    toModel(identifier: string): string;
+}
+/**
+ * Singleton instances for convenience
+ */
+declare const identityNaming: IdentityNamingPlugin;
+declare const camelCaseNaming: CamelCaseNamingPlugin;
+/**
+ * Get a naming plugin by DbCasing (intuitive semantics).
+ * - `'snake_case'`: DB uses snake_case → CamelCaseNamingPlugin (transforms to camelCase)
+ * - `'camelCase'`: DB uses camelCase → IdentityNamingPlugin (no transform)
+ * - `'preserve'`: No transformation → IdentityNamingPlugin
+ */
+declare function getNamingPluginForDbCasing(casing: 'snake_case' | 'camelCase' | 'preserve'): NamingPlugin;
+
+/**
+ * Simplified PlanDecision for the spike
+ * (In production, import from @dbsp/core)
+ */
+interface PlanDecision {
+    readonly type: string;
+    readonly table?: string;
+    readonly column?: string;
+    readonly alias?: string;
+    readonly field?: string;
+    readonly operator?: string;
+    readonly value?: unknown;
+    readonly paramIndex?: number;
+    readonly direction?: 'ASC' | 'DESC';
+    readonly nulls?: 'FIRST' | 'LAST';
+    readonly joinType?: 'inner' | 'left';
+    readonly sourceColumn?: string;
+    readonly targetColumn?: string;
+    readonly targetTable?: string;
+    readonly function?: string;
+    readonly args?: readonly unknown[];
+    readonly conditions?: readonly PlanDecision[];
+    readonly columns?: readonly string[];
+    readonly values?: readonly unknown[];
+    readonly set?: readonly {
+        column: string;
+        value: unknown;
+    }[];
+    readonly limit?: number | {
+        paramIndex: number;
+    };
+    readonly offset?: number | {
+        paramIndex: number;
+    };
+    readonly partitionBy?: readonly string[];
+    readonly orderBy?: readonly {
+        field: string;
+        direction?: 'asc' | 'desc';
+    }[];
+    readonly dataType?: string;
+    readonly sourceTable?: string;
+    readonly relationName?: string;
+    readonly relationType?: 'belongsTo' | 'hasMany' | 'hasOne';
+    readonly foreignKey?: string;
+    readonly parentKey?: string;
+    readonly children?: readonly PlanDecision[];
+    readonly intentPath?: string;
+    readonly choice?: string;
+    readonly subquery?: {
+        readonly from: string;
+        readonly select: string;
+        readonly where?: PlanDecision;
+        readonly limit?: number;
+        readonly orderBy?: readonly {
+            field: string;
+            direction?: string;
+        }[];
+    };
+    readonly expressionType?: string;
+    readonly relation?: string;
+    readonly columnAliases?: Readonly<Record<string, string>>;
+    readonly traversal?: string;
+    readonly pkColumn?: string;
+    readonly fkColumn?: string;
+    readonly maxDepth?: number;
+    readonly role?: string;
+    readonly jsonPath?: readonly string[];
+    readonly jsonMode?: 'json' | 'text';
+    readonly selectColumn?: string;
+    readonly aggregate?: string;
+    readonly subqueryOperator?: string;
+    readonly filterCondition?: PlanDecision;
+    readonly expressionIntent?: unknown;
+    readonly escape?: string;
+    readonly include?: readonly PlanDecision[];
+    readonly joinRarg?: Node;
+    readonly joinOnNode?: Node;
+    readonly batchValuesParams?: readonly unknown[];
+}
+/**
+ * Any decision of type 'join'.
+ * Narrows `type` to the literal 'join' for safe switch exhaustion.
+ */
+interface JoinDecision extends PlanDecision {
+    readonly type: 'join';
+}
+/**
+ * A 'join' decision that carries pre-compiled PostgreSQL AST nodes.
+ * Used by both table-mode and BatchValues-mode joins when the ON condition
+ * has been compiled ahead of time in adapter-compiler-select.ts.
+ *
+ * The `joinRarg` is the right-hand RangeVar/RangeFunction; `joinOnNode` is
+ * the A_Expr tree for the ON clause.
+ */
+interface PrecompiledJoinDecision extends JoinDecision {
+    readonly joinRarg: Node;
+    readonly joinOnNode: Node;
+}
+/**
+ * A pre-compiled 'join' decision backed by a BatchValues unnest() source.
+ * `batchValuesParams` must be spliced into compiler state BEFORE other query
+ * parameters so that $1/$2/… ParamRefs in the RangeFunction align correctly.
+ */
+interface BatchValuesJoinDecision extends PrecompiledJoinDecision {
+    readonly batchValuesParams: readonly unknown[];
+}
+/** Narrows a PlanDecision to JoinDecision (type === 'join'). */
+declare function isJoinDecision(d: PlanDecision): d is JoinDecision;
+/**
+ * Narrows a PlanDecision to PrecompiledJoinDecision.
+ * True when the join carries pre-compiled `joinRarg` + `joinOnNode` AST nodes
+ * (table mode or BatchValues mode).
+ */
+declare function isPrecompiledJoinDecision(d: PlanDecision): d is PrecompiledJoinDecision;
+/**
+ * Narrows a PlanDecision to BatchValuesJoinDecision.
+ * True when the join is a BatchValues unnest() join and carries pre-spliced
+ * parameter arrays in `batchValuesParams`.
+ */
+declare function isBatchValuesJoinDecision(d: PlanDecision): d is BatchValuesJoinDecision;
+/**
+ * Simplified PlanReport for the spike
+ */
+interface SimplifiedPlanReport {
+    readonly rootTable: string;
+    readonly decisions: readonly PlanDecision[];
+    readonly schema?: string;
+    /** If true, wrap result in SELECT EXISTS(SELECT 1 ...) AS "exists" */
+    readonly existsWrap?: boolean;
+    /** Row-level lock (FOR UPDATE/SHARE/etc.) */
+    readonly lock?: _dbsp_types.LockIntent;
+    /**
+     * When present, the FROM clause is replaced by a pre-compiled RangeFunction node
+     * (e.g. unnest() AS alias) instead of the root table rangeVar.
+     * `batchValuesFromParams` holds the parameter arrays to splice into state first.
+     */
+    readonly batchValuesFromNode?: unknown;
+    readonly batchValuesFromParams?: readonly unknown[];
+}
+/**
+ * Compiled query result
+ */
+interface CompiledResult {
+    readonly sql: string;
+    readonly parameters: readonly unknown[];
+    readonly ast: Node;
+}
+interface CompilerOptions {
+    readonly naming?: NamingPlugin;
+    readonly schema?: string;
+    /** Default primary key column name convention (default: 'id') */
+    readonly defaultPkColumnName?: string;
+    /** Convention for deriving FK column names: (tableName, pkName) => fkColumnName */
+    readonly deriveFkColumnName?: FkColumnDerivation;
+    /** ModelIR for type-aware parameter casting in WHERE clauses */
+    readonly model?: _dbsp_types.ModelIR;
+}
+declare class PlanCompiler {
+    private readonly naming;
+    private readonly schema;
+    private readonly defaultPk;
+    private readonly deriveFk;
+    private readonly model;
+    /** Mutable state shared with extracted condition/value compilation functions */
+    private state;
+    /** Track root table for EXISTS FK correlation */
+    private currentRootTable;
+    /** Pending JOINs registered by filter/include strategies (flushed in compileSelect) */
+    private pendingJoins;
+    /** Raw JOIN AST nodes from include handlers (e.g., LATERAL) */
+    private rawJoins;
+    /** CTE nodes from include handlers (e.g., CTE strategy) */
+    private pendingCtes;
+    /**
+     * Maps joined targetTable → alias for multi-hop FK resolution.
+     * Populated as join decisions are compiled so later hops can find
+     * the correct source alias (e.g., 'symbols' → 'callee').
+     */
+    private joinAliasMap;
+    /**
+     * Tracks all join aliases in use for the current query.
+     * Ensures no two JOINs share the same alias (DOUBLE-ALIAS prevention).
+     */
+    private usedJoinAliases;
+    constructor(options?: CompilerOptions);
+    /** Build immutable context for handler-based WHERE compilation */
+    private handlerCtx;
+    /**
+     * Dispatch a PlanDecision through the unified WHERE handler system.
+     * Bridges PlanCompiler's state to handler types, calls dispatcher, syncs back.
+     */
+    private dispatchWhere;
+    /**
+     * Recursively convert a PlanDecision (potentially with nested in+subquery)
+     * into a HandlerDecision suitable for the WHERE dispatcher.
+     *
+     * When a PlanDecision has operator='in'/'notIn' with a subquery object,
+     * mapToHandlerDecision loses the subquery because HandlerDecision has no
+     * `subquery` field. This method detects that pattern and converts it to the
+     * inSubquery/notInSubquery form that buildScalarSubquery expects.
+     *
+     * Called recursively so 2+ levels of nested IN subqueries all work.
+     */
+    private mapInSubqueryCondition;
+    /**
+     * Bridge PlanDecision to handler Decision and dispatch to include handler.
+     * Returns targets and optional pending joins to apply.
+     */
+    private compileIncludeViaHandler;
+    /**
+     * Compile a simplified plan report to SQL
+     */
+    compile(plan: SimplifiedPlanReport): CompiledResult;
+    private detectQueryType;
+    /** Build a HandlerCompilerContext for the given plan and optional alias override. */
+    private createHandlerContext;
+    /** Build a fresh HandlerCompilerState sharing the current parameter array. */
+    private createHandlerState;
+    /**
+     * Compile a SELECT-list target via expression handler.
+     * Wraps the node in a ResTarget and pushes it onto targetList.
+     */
+    private compileSelectTarget;
+    /**
+     * Compile an includeStrategy decision and register its results.
+     * Pushes targets onto targetList, raw joins / CTEs onto instance collections.
+     */
+    private compileIncludeDecision;
+    /**
+     * Fold a WHERE-family decision into an existing where expression.
+     * Returns the updated (or new) where node.
+     */
+    private compileWhereDecision;
+    /**
+     * Flush pendingJoins and rawJoins into the FROM clause.
+     * Mutates the from array in-place.
+     */
+    private flushPendingJoins;
+    /**
+     * Build the initial FROM clause array and register batch-values parameters.
+     * For batch-values queries, the unnest RangeFunction replaces the root rangeVar.
+     */
+    private compileFromClause;
+    /**
+     * Fold WHERE conditions from a join-strategy include decision into the
+     * accumulated WHERE expression. The join alias is used as currentAlias so
+     * column refs like `project_id` resolve against the joined table, not root.
+     */
+    private compileIncludeWhereConditions;
+    /**
+     * Apply a single join decision to the FROM clause in-place.
+     * Chains multiple joins by wrapping from[0] as the left-arg each time.
+     */
+    private compileJoinDecision;
+    /**
+     * Compile a single orderBy decision into a SortBy AST node.
+     * Supports both expression-intent and plain column references.
+     */
+    /**
+     * Compile a single orderBy decision into a SortBy AST node.
+     * Supports both expression-intent and plain column references.
+     * Returns undefined when neither expressionIntent nor column is present.
+     */
+    private compileOrderByDecision;
+    /**
+     * Compile a single groupBy decision into a ColumnRef AST node.
+     * Supports dotted 'relation.column' notation for joined tables.
+     */
+    private compileGroupByDecision;
+    /**
+     * Assemble the final SelectStmt from all accumulated clause nodes.
+     * Also handles the default SELECT *, CTEs, and row-level locking.
+     */
+    private buildSelectStmt;
+    private compileSelect;
+    /**
+     * Wrap a SELECT statement in SELECT EXISTS(SELECT 1 ...) AS "exists"
+     *
+     * This transforms the inner SELECT by:
+     * 1. Replacing targetList with just `1` (constant)
+     * 2. Wrapping in SubLink with EXISTS_SUBLINK
+     * 3. Creating outer SELECT with EXISTS result aliased as "exists"
+     */
+    private wrapSelectInExists;
+    private compileCaseExpression;
+    /**
+     * Compile a CASE THEN/ELSE value based on its ExpressionIntent kind.
+     * Delegates to shared resolveCaseValue with nested CASE support.
+     */
+    private compileCaseValue;
+    private compileInsert;
+    private compileUpdate;
+    private compileDelete;
+    /**
+     * Register an INNER JOIN for a belongsTo filter-strategy decision.
+     * The JOIN replaces the EXISTS subquery when the planner chooses 'join'.
+     * The ON condition correlates FK → PK (belongsTo: source.FK = target.PK).
+     */
+    private registerJoinFilter;
+    private compileJoin;
+}
+/**
+ * Convenience function to compile a plan
+ */
+declare function compilePlan(plan: SimplifiedPlanReport, options?: CompilerOptions): CompiledResult;
+
+/**
+ * DDL Generator - Generates PostgreSQL DDL statements from ModelIR
+ *
+ * Generates SQL strings directly for better compatibility and control.
+ * Two-pass strategy handles circular FK dependencies.
+ *
+ * @module ddl/ddl-generator
+ */
+
+interface GenerateDDLOptions {
+    /** Include DROP TABLE IF EXISTS statements before CREATE TABLE */
+    readonly includeDropStatements?: boolean;
+    /** Database schema name (e.g., 'public', 'tenant_123') */
+    readonly schemaName?: string;
+    /**
+     * Automatically create indexes on foreign key columns.
+     * FK columns are frequently used in JOINs, so indexing is a best practice.
+     * @default true
+     */
+    readonly fkAutoIndex?: boolean;
+    /** Naming plugin for identifier transformation */
+    readonly naming?: NamingPlugin;
+    /** Dialect capabilities — DDL passes for unsupported features will be skipped */
+    readonly dialectCapabilities?: DialectCapabilities;
+}
+/**
+ * Generate DDL statements from a ModelIR schema.
+ *
+ * Uses a two-pass approach to handle circular FK dependencies:
+ * 1. CREATE TABLE (without FK constraints)
+ * 2. ALTER TABLE ADD CONSTRAINT for foreign keys
+ * 3. CREATE INDEX (explicit + auto-generated for FKs)
+ *
+ * @param schema - The ModelIR schema to generate DDL from
+ * @param options - Optional configuration
+ * @returns Array of DDL statements in dependency order
+ */
+declare function generateDDL(schema: ModelIR, options?: GenerateDDLOptions): string[];
+
+/**
+ * Schema Comparison Engine (DDL-PROV Block 1)
+ *
+ * Compares two ModelIRs (schema definition vs database state)
+ * and produces a structured diff of changes needed.
+ *
+ * @module schema-diff
+ */
+
+type ChangeKind = 'create_table' | 'drop_table' | 'add_column' | 'drop_column' | 'alter_column_type' | 'alter_column_nullable' | 'alter_column_default' | 'add_primary_key' | 'drop_primary_key' | 'add_foreign_key' | 'drop_foreign_key' | 'alter_foreign_key' | 'validate_constraint' | 'create_index' | 'drop_index' | 'add_check_constraint' | 'drop_check_constraint' | 'create_enum' | 'alter_enum_add_value' | 'drop_enum' | 'alter_column_collation' | 'alter_column_identity' | 'add_comment' | 'drop_comment' | 'create_extension' | 'drop_extension' | 'create_sequence' | 'alter_sequence' | 'drop_sequence' | 'enable_rls' | 'disable_rls' | 'create_policy' | 'drop_policy';
+interface SchemaChange {
+    readonly kind: ChangeKind;
+    readonly table: string;
+    readonly column?: string;
+    readonly destructive: boolean;
+    readonly details: string;
+    /** Additional metadata for SQL generation */
+    readonly meta?: Readonly<Record<string, unknown>>;
+}
+interface DiffSummary {
+    readonly tables: {
+        readonly added: number;
+        readonly dropped: number;
+    };
+    readonly columns: {
+        readonly added: number;
+        readonly dropped: number;
+        readonly altered: number;
+    };
+    readonly indexes: {
+        readonly added: number;
+        readonly dropped: number;
+    };
+    readonly constraints: {
+        readonly added: number;
+        readonly dropped: number;
+        readonly altered: number;
+    };
+}
+interface SchemaDiff {
+    readonly changes: readonly SchemaChange[];
+    readonly hasDestructive: boolean;
+    readonly summary: DiffSummary;
+}
+interface CompareSchemataOptions {
+    /**
+     * Database naming convention.
+     * When set, schema model names (camelCase) are converted to DB format
+     * (e.g. snake_case) before comparison with the introspected model.
+     */
+    dbCasing?: DbCasing;
+    /** Dialect capabilities — comparisons for unsupported features will be skipped */
+    readonly dialectCapabilities?: DialectCapabilities;
+}
+/**
+ * Compare two ModelIRs and produce a structured diff.
+ *
+ * @param schema - The desired schema (from definition)
+ * @param db - The current database state (from introspection)
+ * @param options - Optional comparison settings (e.g. dbCasing)
+ * @returns SchemaDiff with all changes needed to bring DB in sync with schema
+ */
+declare function compareSchemata(schema: ModelIR, db: ModelIR, options?: CompareSchemataOptions): SchemaDiff;
+
+/**
+ * Migration SQL Generator (DDL-PROV Block 1)
+ *
+ * Generates ordered SQL statements from a SchemaDiff.
+ * Statements are topologically sorted: DROP constraints → DROP objects → CREATE objects → ADD constraints.
+ *
+ * @module migration-sql
+ */
+
+interface MigrationSQLOptions {
+    /** Schema namespace (default: none — unqualified) */
+    readonly schemaName?: string;
+    /** Whether to include destructive changes (drops) */
+    readonly includeDestructive?: boolean;
+    /** Automatically create indexes on FK columns for new tables (default: true) */
+    readonly fkAutoIndex?: boolean;
+    /** Dialect capabilities — migration SQL for unsupported features will be filtered */
+    readonly dialectCapabilities?: DialectCapabilities;
+}
+/**
+ * Generate ordered SQL statements from a SchemaDiff.
+ *
+ * Topological order:
+ * 0.  DROP FK/CHECK constraints (must drop before referenced tables)
+ * 1.  DROP indexes
+ * 2.  DROP columns
+ * 3.  DROP primary keys
+ * 4.  DROP tables, DROP ENUMs
+ * 5.  CREATE ENUMs (must exist before tables that use them)
+ * 6.  CREATE tables
+ * 7.  ADD columns
+ * 8.  ALTER columns (type, nullable, default)
+ * 9.  ADD primary keys
+ * 10. ADD FK constraints (must add after referenced tables exist)
+ * 11. ALTER FK (drop + re-add)
+ * 12. CREATE indexes
+ * 13. ADD CHECK constraints
+ * 14. ALTER ENUM ADD VALUE (must be last — has transaction visibility caveats in PG)
+ * 15. COMMENT ON TABLE / COLUMN (very last)
+ */
+declare function generateMigrationSQL(diff: SchemaDiff, options?: MigrationSQLOptions): readonly string[];
+/**
+ * Generate ordered DOWN SQL statements from a SchemaDiff.
+ *
+ * Reverses the topological order used in UP migrations:
+ * phases run in descending order (11, 10, 9, ..., 0).
+ *
+ * Irreversible changes (drops that lose data) produce SQL WARNING comments.
+ */
+declare function generateDownSQL(diff: SchemaDiff, options?: MigrationSQLOptions): readonly string[];
+
+/**
+ * Migration File Format v2 — UP + DOWN sections.
+ *
+ * File format:
+ *   <UP statements>;
+ *   -- DOWN
+ *   <DOWN statements>;
+ *
+ * The separator `-- DOWN` must be on its own line (SC-25).
+ *
+ * @module ddl/migration-file
+ */
+
+/**
+ * Result of parsing a migration file's UP/DOWN sections.
+ */
+interface ParsedMigrationFile {
+    readonly upStatements: readonly string[];
+    readonly downStatements: readonly string[];
+    readonly hasDown: boolean;
+}
+/**
+ * Generate a migration file content with UP and DOWN sections.
+ */
+declare function generateMigrationFile(diff: SchemaDiff, options?: MigrationSQLOptions & {
+    name?: string;
+}): string;
+/**
+ * Parse a migration file into UP and DOWN sections.
+ * Separator: `^\s*-- DOWN\s*$` (strict regex, own line only — SC-25)
+ */
+declare function parseMigrationFile(content: string): ParsedMigrationFile;
+/**
+ * Check if SQL statements contain destructive operations.
+ * Destructive: DROP TABLE, DROP COLUMN, lossy ALTER COLUMN TYPE
+ */
+declare function isDestructiveDown(downStatements: readonly string[]): boolean;
+
+/**
+ * Migration Tracker — `_dbsp_migrations` table CRUD.
+ *
+ * Manages the tracking table that records which migrations
+ * have been applied to a database.
+ */
+
+interface MigrationRecord {
+    /** Migration filename (e.g., "0001_create_users.sql") */
+    readonly name: string;
+    /** SHA-256 checksum of the migration file content */
+    readonly checksum: string;
+    /** When the migration was applied */
+    readonly appliedAt: Date;
+    /** Schema version at time of this migration */
+    readonly schemaVersion: number;
+    /** Whether this migration contains destructive changes */
+    readonly destructive: boolean;
+}
+/**
+ * Acquire a session-level advisory lock for migration operations.
+ *
+ * @deprecated Use {@link withMigrationLock} instead — pool.query may release
+ * the connection (and the lock) before the migration completes.
+ */
+declare function acquireMigrationLock(pool: Pool): Promise<void>;
+/**
+ * Release the session-level advisory lock for migration operations.
+ *
+ * @deprecated Use {@link withMigrationLock} instead.
+ */
+declare function releaseMigrationLock(pool: Pool): Promise<void>;
+/**
+ * Execute a callback under an advisory lock using a dedicated client.
+ * The lock is held for the duration of the callback.
+ * The client is released (and lock freed) after the callback completes.
+ */
+declare function withMigrationLock<T>(pool: Pool, fn: (client: PoolClient) => Promise<T>): Promise<T>;
+/**
+ * Ensure the migrations tracking table exists.
+ * Auto-migrates existing tables that lack `schema_version`/`destructive` columns,
+ * and backfills `schema_version` by `applied_at` order for rows still at 0.
+ */
+declare function ensureMigrationsTable(pool: Pool): Promise<void>;
+/**
+ * Get all applied migrations, ordered by name.
+ */
+declare function getAppliedMigrations(pool: Pool): Promise<readonly MigrationRecord[]>;
+/**
+ * Record a migration as applied.
+ */
+declare function recordMigration(pool: Pool, name: string, checksum: string, schemaVersion: number, destructive: boolean): Promise<void>;
+/**
+ * Check if a specific migration has been applied.
+ */
+declare function isMigrationApplied(pool: Pool, name: string): Promise<boolean>;
+/**
+ * Get the next schema version number (max + 1, or 1 if no migrations).
+ */
+declare function getNextSchemaVersion(pool: Pool): Promise<number>;
+/**
+ * Remove a migration record (for rollback).
+ */
+declare function removeMigrationRecord(pool: Pool, name: string): Promise<void>;
+
+/**
+ * Type Mapping - Maps ModelIR ColumnType to PostgreSQL data types
+ *
+ * Supports both manual schemas and introspected schemas (preserving originalDbType).
+ * Handles auto-increment via SERIAL/BIGSERIAL types.
+ *
+ * @module ddl/type-mapping
+ */
+
+/**
+ * Map ColumnType to PostgreSQL data type string.
+ *
+ * Uses originalDbType if available (from introspection), otherwise
+ * falls back to reasonable PostgreSQL defaults.
+ *
+ * @param col - Column definition from ModelIR
+ * @returns PostgreSQL type string (e.g., 'VARCHAR(255)', 'SERIAL', 'JSONB')
+ */
+declare function mapColumnType(col: ColumnIR): string;
+/**
+ * Map OnDeleteAction to PostgreSQL syntax.
+ */
+declare function mapOnDeleteAction(action?: string): string;
+
+/**
+ * EXPLAIN Statement Compiler
+ *
+ * Generates PostgreSQL EXPLAIN statements with various options.
+ * Supports:
+ * - ANALYZE (execute and show actual run times)
+ * - FORMAT (text, json, xml, yaml)
+ * - VERBOSE, COSTS, BUFFERS, TIMING, SETTINGS
+ */
+
+/**
+ * Output format for EXPLAIN results.
+ */
+type ExplainFormat = 'text' | 'json' | 'xml' | 'yaml';
+/**
+ * Options for EXPLAIN statement.
+ */
+interface ExplainOptions {
+    /** Execute the query and show actual run times */
+    analyze?: boolean;
+    /** Show more detailed output */
+    verbose?: boolean;
+    /** Show cost estimates (default: true) */
+    costs?: boolean;
+    /** Show buffer usage (requires analyze) */
+    buffers?: boolean;
+    /** Show actual timing (requires analyze) */
+    timing?: boolean;
+    /** Show non-default settings */
+    settings?: boolean;
+    /** Output format */
+    format?: ExplainFormat;
+}
+/**
+ * Build an EXPLAIN statement wrapping a query.
+ *
+ * @param query - The query to explain (SelectStmt, InsertStmt, etc.)
+ * @param options - EXPLAIN options
+ * @returns ExplainStmt AST node
+ *
+ * @example
+ * ```typescript
+ * const selectAst = { SelectStmt: { ... } };
+ * const explainAst = buildExplain(selectAst, { analyze: true, format: 'json' });
+ * // Produces: EXPLAIN (ANALYZE, FORMAT JSON) SELECT ...
+ * ```
+ */
+declare function buildExplain(query: Node, options?: ExplainOptions): Node;
+/**
+ * Build EXPLAIN ANALYZE with JSON format (common pattern).
+ *
+ * @param query - The query to explain
+ * @returns ExplainStmt with ANALYZE and JSON format
+ */
+declare function buildExplainAnalyzeJson(query: Node): Node;
+/**
+ * Build simple EXPLAIN (plan only, no execution).
+ *
+ * @param query - The query to explain
+ * @returns ExplainStmt with default options
+ */
+declare function buildExplainPlan(query: Node): Node;
+/**
+ * Build verbose EXPLAIN with costs and buffers.
+ *
+ * @param query - The query to explain
+ * @returns ExplainStmt with verbose options
+ */
+declare function buildExplainVerbose(query: Node): Node;
+/**
+ * Parse EXPLAIN JSON output to get execution statistics.
+ *
+ * @param jsonOutput - The JSON string from EXPLAIN (ANALYZE, FORMAT JSON)
+ * @returns Parsed plan with execution statistics
+ */
+declare function parseExplainJson(jsonOutput: string): ExplainPlan[];
+/**
+ * Parsed EXPLAIN plan structure (simplified).
+ */
+interface ExplainPlan {
+    Plan: {
+        'Node Type': string;
+        'Relation Name'?: string;
+        Alias?: string;
+        'Startup Cost'?: number;
+        'Total Cost'?: number;
+        'Plan Rows'?: number;
+        'Plan Width'?: number;
+        'Actual Startup Time'?: number;
+        'Actual Total Time'?: number;
+        'Actual Rows'?: number;
+        'Actual Loops'?: number;
+        Plans?: ExplainPlan['Plan'][];
+    };
+    'Planning Time'?: number;
+    'Execution Time'?: number;
+    Triggers?: unknown[];
+}
+/**
+ * Extract total execution time from EXPLAIN ANALYZE JSON output.
+ *
+ * @param plans - Parsed EXPLAIN plans
+ * @returns Total execution time in milliseconds
+ */
+declare function getTotalExecutionTime(plans: ExplainPlan[]): number;
+/**
+ * Extract row counts from EXPLAIN ANALYZE JSON output.
+ *
+ * @param plans - Parsed EXPLAIN plans
+ * @returns Object with estimated and actual row counts
+ */
+declare function getRowEstimates(plans: ExplainPlan[]): {
+    estimated: number;
+    actual: number;
+};
+
+/**
+ * ParadeDB Extension Wrappers
+ *
+ * Type-safe query builders for ParadeDB BM25 full-text search.
+ * All functions return ExpressionRef instances that can be used in:
+ * - SELECT: .column(score('id').as('score'))
+ * - WHERE:  .where(bm25Search('symbols', query, { name: 3.0, doc: 1.0 }))
+ * - ORDER BY: .orderBy(score('id'), 'desc')
+ *
+ * @remarks
+ * ParadeDB functions accept both named and positional arguments.
+ * This module uses named args via namedArg() for parse(), which produces:
+ *   paradedb.parse(field => 'field_name', query_string => $1)
+ * Named parameter syntax is supported via the NamedArgExpressionIntent (EXT-NAMED-PARAMS).
+ */
+
+/**
+ * BM25 relevance score for a row.
+ *
+ * Use in SELECT and ORDER BY to retrieve and sort by full-text relevance.
+ * Requires a BM25 index on the table.
+ *
+ * @param keyField - The key field of the BM25 index (typically the primary key, e.g. 'id')
+ * @returns ExpressionRef that compiles to: paradedb.score("keyField")
+ *
+ * @example
+ * orm.select('symbols').column(score('id').as('score')).orderBy(score('id'), 'desc')
+ * // → paradedb.score("id") AS "score"
+ */
+declare function score(keyField: string): ExpressionRef;
+/**
+ * Parse a single-field BM25 query expression.
+ *
+ * Compiles to: paradedb.parse(field => 'field_name', query_string => $N)
+ *
+ * @param field - Column name to search in (must be indexed in the BM25 index)
+ * @param query - Query string value (will be bound as a parameter)
+ * @returns ExpressionRef for use with boost() or booleanSearch()
+ *
+ * @example
+ * parse('name', 'hello world')
+ * // → paradedb.parse(field => 'name', query_string => $1)
+ */
+declare function parse(field: string, query: ExpressionRef | unknown): ExpressionRef;
+/**
+ * Apply a boost multiplier to a BM25 sub-expression.
+ *
+ * Compiles to: paradedb.boost(factor, expr)
+ *
+ * @param factor - Boost multiplier (e.g. 3.0 for 3x weight)
+ * @param expr - Expression to boost (typically a parse() call)
+ * @returns ExpressionRef for use with booleanSearch()
+ *
+ * @example
+ * boost(3.0, parse('name', 'hello'))
+ * // → paradedb.boost(3.0, paradedb.parse('name', $1))
+ */
+declare function boost(factor: number, expr: ExpressionRef): ExpressionRef;
+/**
+ * Combine multiple BM25 sub-expressions with boolean OR logic.
+ *
+ * Compiles to: paradedb.boolean(expr1, expr2, ...)
+ *
+ * @param exprs - One or more sub-expressions (typically boost() calls)
+ * @returns ExpressionRef for use on the right side of the @@@ operator
+ *
+ * @example
+ * booleanSearch([boost(3.0, parse('name', q)), boost(1.0, parse('doc', q))])
+ * // → paradedb.boolean(paradedb.boost(3.0, ...), paradedb.boost(1.0, ...))
+ */
+/**
+ * Combine multiple BM25 sub-expressions with boolean OR logic.
+ *
+ * Compiles to: paradedb.boolean(should => ARRAY[expr1, expr2, ...])
+ *
+ * @param exprs - One or more sub-expressions (typically boost() calls)
+ * @returns ExpressionRef for use on the right side of the @@@ operator
+ *
+ * @example
+ * booleanSearch([boost(3.0, parse('name', q)), boost(1.0, parse('doc', q))])
+ * // → paradedb.boolean(should => ARRAY[paradedb.boost(3.0, ...), paradedb.boost(1.0, ...)])
+ */
+declare function booleanSearch(exprs: ExpressionRef[]): ExpressionRef;
+/**
+ * Full BM25 multi-field search with per-field boost weights.
+ *
+ * Produces: table @@@ paradedb.boolean(boost1, boost2, ...)
+ *
+ * Each field in `fieldBoosts` generates a `paradedb.boost(weight, paradedb.parse(field, $N))`
+ * sub-expression. The same query string is used for all fields (single parameter binding).
+ *
+ * @param table - Table alias for the left side of the @@@ operator
+ * @param query - Query string (bound as a single $N parameter, shared across all fields)
+ * @param fieldBoosts - Map of column name → boost weight
+ * @returns ExpressionRef for use in .where()
+ *
+ * @example
+ * bm25Search('s', searchTerm, {
+ *   name_searchable: 3.0,
+ *   name: 1.0,
+ *   signature: 1.5,
+ *   doc_searchable: 1.0,
+ * })
+ * // → s @@@ paradedb.boolean(
+ * //     paradedb.boost(3.0, paradedb.parse('name_searchable', $1)),
+ * //     paradedb.boost(1.0, paradedb.parse('name', $1)),
+ * //     paradedb.boost(1.5, paradedb.parse('signature', $1)),
+ * //     paradedb.boost(1.0, paradedb.parse('doc_searchable', $1))
+ * //   )
+ *
+ * @remarks
+ * The query parameter is shared: all parse() calls reference the same $N slot.
+ * If you need different query strings per field, compose parse()/boost()/booleanSearch() manually.
+ *
+ * @remarks
+ * ParadeDB's boolean() function accepts both positional args and the named
+ * `should => ARRAY[...]` syntax. This wrapper uses positional args.
+ * Named parameter syntax is deferred to EXT-NAMED-PARAMS.
+ */
+declare function bm25Search(table: string, query: unknown, fieldBoosts: Record<string, number>): ExpressionRef;
+
+/**
+ * PostgreSQL built-in function helpers.
+ *
+ * Thin wrappers around core expression primitives for common PostgreSQL functions.
+ * Same pattern as pgvector.ts and paradedb.ts.
+ */
+
+/**
+ * Generate a series of values: generate_series(start, stop[, step])
+ *
+ * Returns a set of values from start to stop (inclusive), with an optional step.
+ * Commonly used with CTE for batch operations.
+ *
+ * @example generateSeries(1, 100) → generate_series(1, 100)
+ * @example generateSeries(0, 50, 5) → generate_series(0, 50, 5)
+ */
+declare function generateSeries(start: number, stop: number, step?: number): ExpressionRef;
+/**
+ * Get next value from a sequence: nextval('sequence_name')
+ *
+ * @example nextval('order_id_seq') → nextval('order_id_seq')
+ */
+declare function nextval(sequenceName: string): ExpressionRef;
+
+/**
+ * pgvector Extension Wrappers
+ *
+ * Type-safe query builders for pgvector distance operators.
+ * All functions return ExpressionRef instances that can be used in:
+ * - SELECT: .column(cosineDistance('vector', qv).as('score'))
+ * - WHERE:  .where(cosineDistance('vector', qv).gte(0.5))
+ * - ORDER BY: .orderBy(rawDistance('vector', qv), 'asc')
+ */
+
+/**
+ * Cosine similarity: 1 - (col <=> vector)
+ *
+ * Score in [0, 1], higher = more similar.
+ * Use in SELECT to get a similarity score.
+ *
+ * @example
+ * orm.select('embeddings').column(cosineDistance('vector', qv).as('score'))
+ */
+declare function cosineDistance(column: string, vector: number[]): ExpressionRef;
+/**
+ * Raw cosine distance: col <=> vector
+ *
+ * Lower = closer. Index-friendly — use in ORDER BY for ANN search.
+ * Do NOT use in SELECT as a similarity score (lower = closer is counterintuitive).
+ *
+ * @example
+ * orm.select('embeddings').orderBy(rawDistance('vector', qv), 'asc')
+ */
+declare function rawDistance(column: string, vector: number[]): ExpressionRef;
+/**
+ * L2 (Euclidean) distance: col <-> vector
+ *
+ * @example
+ * orm.select('embeddings').orderBy(l2Distance('vector', qv), 'asc')
+ */
+declare function l2Distance(column: string, vector: number[]): ExpressionRef;
+/**
+ * Inner product distance: col <#> vector (negative inner product)
+ *
+ * For maximum inner product search: ORDER BY innerProduct('vector', qv) ASC.
+ *
+ * @example
+ * orm.select('embeddings').orderBy(innerProduct('vector', qv), 'asc')
+ */
+declare function innerProduct(column: string, vector: number[]): ExpressionRef;
+/**
+ * Get the number of dimensions of a vector column: vector_dims(col)
+ *
+ * Returns an integer — the dimension count of the stored vector.
+ * Useful for sanity-checking that embeddings match the expected model dimension.
+ *
+ * @example
+ * orm.from(embeddings).columns([vectorDims('vector').as('dim')]).first()
+ * // → SELECT vector_dims("t0"."vector") AS "dim" FROM "embeddings" AS "t0"
+ */
+declare function vectorDims(column: string): ExpressionRef;
+
+/**
+ * Immutable context passed to all handlers during compilation.
+ */
+interface CompilerContext {
+    /** Naming convention transformer */
+    readonly naming: NamingPlugin;
+    /** Schema name for table qualification (optional) */
+    readonly schema?: string;
+    /** Root table name for the query */
+    readonly rootTable: string;
+    /** Current table alias (for JOINs) */
+    readonly currentAlias?: string;
+    /** Maximum recursive depth (default: 100) */
+    readonly maxRecursiveDepth: number;
+    /** Optional callback for raw SQL audit trail */
+    readonly onRawSQL?: (sql: string) => void;
+    /** Default primary key column name for convention fallbacks (default: 'id') */
+    readonly defaultPkColumnName?: string;
+    /** Convention for deriving FK column names: (tableName, pkName) => fkColumnName */
+    readonly deriveFkColumnName?: FkColumnDerivation;
+    /** Alias of the outer (parent) query — used for FieldRef scope:'outer' resolution in EXISTS subqueries */
+    readonly outerAlias?: string;
+    /**
+     * Optional callback to compile a QueryIntent into an AST Node (SubLink subselect).
+     * Set by PlanCompiler when compiling selectCustomExpression — enables SubqueryExpressionIntent
+     * to embed a fully compiled sub-SELECT into the parent SELECT column list.
+     *
+     * @param query - The inner QueryIntent to compile
+     * @param paramOffset - Current outer paramIndex; inner $N are renumbered by this offset
+     * @returns The compiled SelectStmt AST node and the inner parameters
+     */
+    readonly compileSubquery?: (query: _dbsp_types.QueryIntent, paramOffset: number) => {
+        ast: Node;
+        parameters: readonly unknown[];
+    };
+    /**
+     * Optional ModelIR for type-aware parameter casting.
+     * When provided, WHERE comparisons emit `$N::type` to eliminate
+     * PostgreSQL type inference ambiguity for nullable columns.
+     */
+    readonly model?: ModelIR;
+}
+/**
+ * Mutable state maintained during compilation.
+ */
+interface CompilerState {
+    /** Collected parameters in order */
+    parameters: unknown[];
+    /** Current parameter index (1-based for PostgreSQL) */
+    paramIndex: number;
+    /** Registered CTEs for the query */
+    ctes: Map<string, Node>;
+    /** Table aliases in use */
+    aliases: Map<string, string>;
+    /** JOIN clauses accumulated */
+    joins: Node[];
+}
+/**
+ * Base decision interface matching core's PlanDecision structure.
+ */
+interface Decision {
+    readonly type: string;
+    readonly table?: string;
+    readonly column?: string;
+    readonly alias?: string;
+    readonly operator?: string;
+    readonly value?: unknown;
+    readonly paramIndex?: number;
+    readonly dataType?: string;
+    readonly direction?: 'ASC' | 'DESC';
+    readonly nulls?: 'FIRST' | 'LAST';
+    readonly joinType?: 'inner' | 'left';
+    readonly sourceColumn?: string;
+    readonly targetColumn?: string;
+    readonly targetTable?: string;
+    readonly function?: string;
+    readonly args?: readonly unknown[];
+    readonly conditions?: readonly Decision[];
+    readonly columns?: readonly string[];
+    readonly values?: readonly unknown[];
+    readonly set?: readonly {
+        column: string;
+        value: unknown;
+    }[];
+    readonly limit?: number | {
+        paramIndex: number;
+    };
+    readonly offset?: number | {
+        paramIndex: number;
+    };
+    readonly strategy?: 'join' | 'lateral' | 'json_agg' | 'cte';
+    readonly relation?: string;
+    readonly relationName?: string;
+    readonly include?: readonly Decision[];
+    readonly relationType?: 'belongsTo' | 'hasMany' | 'hasOne';
+    readonly foreignKey?: string;
+    readonly parentKey?: string;
+    readonly children?: readonly Decision[];
+    readonly partition?: readonly string[];
+    readonly orderBy?: readonly {
+        column: string;
+        direction?: 'ASC' | 'DESC';
+    }[];
+    readonly frame?: string;
+    readonly maxDepth?: number;
+    readonly pathColumn?: string;
+    readonly cycleDetection?: boolean;
+    readonly selectColumn?: string;
+    readonly aggregate?: string;
+    readonly subqueryOperator?: string;
+    readonly traversal?: string;
+    readonly traversals?: readonly {
+        traversal: string;
+        targetColumn?: string;
+    }[];
+    readonly isRecursive?: boolean;
+    readonly fkColumn?: string;
+    readonly pkColumn?: string;
+    readonly expandRelation?: string;
+    readonly relationColumns?: readonly string[];
+    readonly columnAliases?: Readonly<Record<string, string>>;
+    readonly jsonPath?: readonly string[];
+    readonly jsonMode?: 'json' | 'text';
+    readonly _compiledFilterWhere?: _pgsql_types.Node;
+    readonly filterWhere?: _pgsql_types.Node;
+    readonly expressionIntent?: unknown;
+    readonly escape?: string;
+}
+/**
+ * Handler for WHERE clause conditions.
+ * Transforms condition decisions into PostgreSQL AST expressions.
+ */
+interface WhereHandler {
+    /** Operator(s) this handler supports */
+    readonly operators: readonly string[];
+    /**
+     * Compile a WHERE condition to AST.
+     * @param decision The condition decision
+     * @param ctx Immutable compiler context
+     * @param state Mutable compiler state
+     * @param dispatch Callback to compile nested conditions
+     * @returns PostgreSQL AST node for the condition
+     */
+    compile(decision: Decision, ctx: CompilerContext, state: CompilerState, dispatch: WhereDispatcher): Node;
+}
+/**
+ * Dispatcher for recursive WHERE compilation.
+ */
+type WhereDispatcher = (decision: Decision, ctx: CompilerContext, state: CompilerState) => Node;
+/**
+ * Handler for SELECT expressions.
+ * Transforms expression decisions into PostgreSQL AST nodes.
+ */
+interface ExpressionHandler {
+    /** Expression type(s) this handler supports */
+    readonly types: readonly string[];
+    /**
+     * Compile an expression to AST.
+     * @param decision The expression decision
+     * @param ctx Immutable compiler context
+     * @param state Mutable compiler state
+     * @returns PostgreSQL AST node for the expression
+     */
+    compile(decision: Decision, ctx: CompilerContext, state: CompilerState): Node;
+}
+/**
+ * Handler for include/relation strategies.
+ * Transforms include decisions into PostgreSQL constructs (JOIN, LATERAL, json_agg, CTE).
+ */
+interface IncludeHandler {
+    /** Strategy this handler implements */
+    readonly strategy: 'join' | 'lateral' | 'json_agg' | 'cte';
+    /**
+     * Compile an include to AST.
+     * @param decision The include decision
+     * @param ctx Immutable compiler context
+     * @param state Mutable compiler state
+     * @returns Object with modifications to apply
+     */
+    compile(decision: Decision, ctx: CompilerContext, state: CompilerState): IncludeResult;
+}
+/**
+ * Result of include compilation.
+ */
+interface IncludeResult {
+    /** Additional target list items (SELECT columns) */
+    targets?: Node[];
+    /** JOIN to add to FROM clause */
+    join?: Node;
+    /** Additional JOINs for cascaded includes (e.g., flat deep nesting) */
+    additionalJoins?: Node[];
+    /** CTE to add to WITH clause */
+    cte?: Node;
+    /** Subquery for LATERAL */
+    lateral?: Node;
+}
+
+/**
+ * PostgreSQL Schema Introspection (ADAPTER-006)
+ *
+ * Queries information_schema/pg_catalog to build ModelIR
+ * from an existing database. Supports:
+ * - Table/column/PK discovery
+ * - FK → bidirectional relation inference
+ * - Hierarchy detection (adjacency + edge-table)
+ * - Include/exclude filtering
+ *
+ * @module introspection
+ */
+
+/** Options for database introspection */
+interface IntrospectionOptions {
+    /** Tables to exclude (glob patterns: * matches any chars) */
+    readonly exclude?: readonly string[];
+    /** Tables to include (default: all). Applied before exclude. */
+    readonly include?: readonly string[];
+    /** Schema name to introspect (default: 'public') */
+    readonly schema?: string;
+}
+/** Hierarchy pattern detected during introspection */
+/**
+ * Hierarchy pattern detected during introspection.
+ * Alias of {@link HierarchyIR} from \@dbsp/types — kept here for
+ * public-API backwards compatibility (re-exported from \@dbsp/adapter-pgsql).
+ */
+type DetectedHierarchy = HierarchyIR;
+/** Extended ModelIR with hierarchy metadata */
+interface IntrospectedModelIR extends ModelIR {
+    readonly hierarchies: readonly DetectedHierarchy[];
+    readonly introspectedAt: Date;
+    readonly warnings: readonly string[];
+}
+declare function introspect(pool: Pool, options?: IntrospectionOptions): Promise<IntrospectedModelIR>;
+
+/**
+ * Mutation Compiler
+ *
+ * Compiles INSERT, UPDATE, and DELETE statements from plan decisions.
+ * Supports:
+ * - INSERT with values/from subquery
+ * - INSERT with RETURNING
+ * - UPDATE with SET and WHERE
+ * - DELETE with WHERE
+ * - RETURNING clause for all mutations
+ */
+
+/**
+ * Configuration for INSERT compilation
+ */
+interface InsertConfig {
+    /** Table to insert into */
+    table: string;
+    /** Columns to insert */
+    columns: string[];
+    /** Values for each column (array of rows) */
+    values: unknown[][];
+    /** Columns to return (RETURNING clause) */
+    returning?: string[];
+    /** Subquery for INSERT ... SELECT */
+    selectQuery?: Node;
+    /** Column database types for type-cast emission (e.g. range types) */
+    columnTypes?: Record<string, string>;
+}
+/**
+ * Configuration for UPDATE compilation
+ */
+interface UpdateConfig {
+    /** Table to update */
+    table: string;
+    /** Column-value pairs to set */
+    set: {
+        column: string;
+        value: unknown;
+    }[];
+    /** WHERE conditions */
+    where?: Decision[];
+    /** Columns to return (RETURNING clause) */
+    returning?: string[];
+    /** Column database types for type-cast emission (e.g. range types) */
+    columnTypes?: Record<string, string>;
+}
+/**
+ * Configuration for DELETE compilation
+ */
+interface DeleteConfig {
+    /** Table to delete from */
+    table: string;
+    /** WHERE conditions */
+    where?: Decision[];
+    /** Columns to return (RETURNING clause) */
+    returning?: string[];
+}
+/**
+ * Compile an INSERT statement from configuration.
+ */
+declare function compileInsert(config: InsertConfig, ctx: CompilerContext, state: CompilerState): Node;
+/**
+ * Compile an UPDATE statement from configuration.
+ */
+declare function compileUpdate(config: UpdateConfig, ctx: CompilerContext, state: CompilerState): Node;
+declare function compileDelete(config: DeleteConfig, ctx: CompilerContext, state: CompilerState): Node;
+/**
+ * Compile a mutation decision to AST.
+ * Determines mutation type from decision.type and delegates.
+ */
+declare function compileMutation(decision: Decision, ctx: CompilerContext, state: CompilerState): Node;
+
+/**
+ * Upsert (INSERT ... ON CONFLICT) Compiler
+ *
+ * Compiles UPSERT statements with ON CONFLICT handling.
+ * Supports:
+ * - ON CONFLICT DO NOTHING
+ * - ON CONFLICT DO UPDATE SET ...
+ * - Conflict target (columns or constraint name)
+ * - WHERE clause for conflict resolution
+ */
+
+/**
+ * Conflict resolution strategy
+ */
+type ConflictAction = 'nothing' | 'update';
+/**
+ * Conflict target specification
+ */
+interface ConflictTarget {
+    /** Column names that form the unique constraint */
+    columns?: string[];
+    /** Named constraint */
+    constraint?: string;
+    /** WHERE clause for partial index */
+    where?: Decision[];
+}
+/**
+ * Configuration for UPSERT compilation
+ */
+interface UpsertConfig {
+    /** Table to upsert into */
+    table: string;
+    /** Columns to insert */
+    columns: string[];
+    /** Values for each column (array of rows) */
+    values: unknown[][];
+    /** Conflict target (unique columns or constraint) */
+    conflictTarget: ConflictTarget;
+    /** What to do on conflict */
+    conflictAction: ConflictAction;
+    /** Columns to update on conflict (for 'update' action) */
+    updateColumns?: string[];
+    /** Use EXCLUDED.column for update values (default: true) */
+    useExcluded?: boolean;
+    /** Columns to return (RETURNING clause) */
+    returning?: string[];
+    /** Optional column type hints for unnest casting (schema-driven) */
+    columnTypes?: Record<string, string>;
+    /**
+     * Raw SQL expressions for specific update columns.
+     * These are injected verbatim into the ON CONFLICT DO UPDATE SET clause.
+     * Keys are logical column names (before naming plugin), values are raw SQL fragments.
+     *
+     * @warning SECURITY: fragments are inserted without parameterization.
+     *   Only use with hardcoded expressions. Never with user input.
+     *
+     * @example { last_parsed: 'now()', count: 'excluded.count + 1' }
+     */
+    updateExpressions?: Record<string, string>;
+}
+/**
+ * Build ON CONFLICT clause for INSERT statement.
+ */
+declare function buildOnConflictClause(config: UpsertConfig, ctx: CompilerContext, state: CompilerState): OnConflictClause;
+/**
+ * Compile a complete UPSERT statement.
+ */
+declare function compileUpsert(config: UpsertConfig, ctx: CompilerContext, state: CompilerState): Node;
+/**
+ * Build EXCLUDED.column reference.
+ * EXCLUDED is a special table alias in ON CONFLICT ... DO UPDATE
+ * that refers to the row that would have been inserted.
+ */
+declare function excludedRef(column: string, naming: {
+    toDatabase: (s: string) => string;
+}): Node;
+/**
+ * Build conditional update using COALESCE.
+ *
+ * Produces: COALESCE(EXCLUDED.col, table.col)
+ * This keeps existing value if new value is NULL.
+ */
+declare function conditionalUpdate(column: string, table: string, ctx: CompilerContext): Node;
+
+/**
+ * @module naming
+ * Utilities for resolving database names to logical model names.
+ *
+ * The ModelIR.getTable() method expects logical (camelCase) names,
+ * but the adapter often works with database (snake_case) names.
+ * This module bridges that gap.
+ */
+
+/**
+ * Resolve a database table name to the corresponding logical model name.
+ *
+ * Converts the DB name using the naming convention, then looks it up in the model.
+ * Falls back to exact match if conversion doesn't find a match.
+ *
+ * @param model - The model IR to search in
+ * @param dbName - Database table name (e.g. "post_comments")
+ * @param convention - Naming convention used by the adapter
+ * @returns The logical table name if found, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * // With camelCase convention:
+ * resolveLogicalName(model, "post_comments", "camelCase") // → "postComments"
+ * resolveLogicalName(model, "posts", "camelCase")         // → "posts"
+ * resolveLogicalName(model, "unknown", "camelCase")       // → undefined
+ * ```
+ */
+declare function resolveLogicalName(model: ModelIR, dbName: string, casing: DbCasing): string | undefined;
+
+/**
+ * ParamRef validation and helpers for PostgreSQL AST
+ *
+ * ParamRef nodes represent parameterized query placeholders ($1, $2, etc.)
+ * This module provides validation and creation helpers for safe AST construction.
+ */
+
+/**
+ * Validation result for ParamRef nodes
+ */
+interface ParamRefValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Validates a ParamRef node
+ *
+ * Rules:
+ * - `number` must be a positive integer (1-based indexing)
+ * - `number` must not exceed reasonable bounds (e.g., 65535)
+ */
+declare function validateParamRef(paramRef: ParamRef): ParamRefValidationResult;
+/**
+ * Creates a validated ParamRef node
+ * @throws Error if validation fails
+ */
+declare function createParamRef(number: number, location?: number): Node;
+/**
+ * Creates a TypeCast node wrapping a ParamRef
+ * Example: $1::integer, $2::text[]
+ */
+declare function createTypeCastParamRef(paramNumber: number, typeName: string, isArray?: boolean, location?: number): Node;
+/**
+ * Creates an A_Expr node for equality comparison with ParamRef
+ * Example: col = $1
+ */
+declare function createEqualityExpr(columnName: string, paramNumber: number, tableName?: string, location?: number): Node;
+/**
+ * Creates a FuncCall node for ANY() with ParamRef
+ * Example: col = ANY($1) for array parameter matching
+ */
+declare function createAnyExpr(columnName: string, paramNumber: number, tableName?: string, location?: number): Node;
+/**
+ * Collects all ParamRef nodes from an AST, validating each
+ * Returns validation results for all found ParamRefs
+ */
+declare function collectAndValidateParamRefs(node: unknown): {
+    paramRefs: Array<{
+        paramRef: ParamRef;
+        path: string;
+    }>;
+    validationResults: ParamRefValidationResult[];
+    allValid: boolean;
+};
+
+/**
+ * PgsqlAdapter - Implements the Adapter interface for PostgreSQL using native pg driver.
+ *
+ * This adapter wraps a pg Pool instance and provides the unified
+ * adapter interface for the db-semantic-planner ORM.
+ *
+ * @module pgsql-adapter
+ */
+
+/**
+ * Options for PgsqlAdapter.
+ */
+interface PgsqlAdapterOptions {
+    /** Schema name for multi-tenant queries */
+    readonly schemaName?: string;
+    /**
+     * DB column casing convention (intuitive semantics).
+     * - `'snake_case'`: DB columns are snake_case → transform to camelCase for JS
+     * - `'camelCase'`: DB columns are camelCase → no transformation
+     * - `'preserve'`: No transformation
+     */
+    readonly dbCasing?: DbCasing;
+    /** Optional model for WHERE compilation */
+    readonly model?: ModelIR;
+    /** Optional logger for debug/error messages */
+    readonly logger?: AdapterLogger;
+    /** Default primary key column name for convention fallbacks (default: 'id') */
+    readonly defaultPkColumnName?: string;
+    /** Convention for deriving FK column names: (tableName, pkName) => fkColumnName */
+    readonly deriveFkColumnName?: FkColumnDerivation;
+}
+/**
+ * Adapter implementation for PostgreSQL using native pg driver.
+ *
+ * @typeParam DB - Database schema type
+ *
+ * @example
+ * ```typescript
+ * import { Pool } from 'pg';
+ * import { createPgsqlAdapter } from '@dbsp/adapter-pgsql';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const adapter = createPgsqlAdapter(pool);
+ * const orm = createOrm({ model, adapter });
+ * ```
+ */
+declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
+    private readonly pool;
+    private readonly client;
+    private readonly schemaName;
+    private readonly _dbCasing;
+    private readonly naming;
+    private readonly model;
+    private readonly logger;
+    private readonly _capabilities;
+    private readonly defaultPk;
+    private readonly deriveFk;
+    /**
+     * Create a new PgsqlAdapter.
+     *
+     * @param pool - pg.Pool instance, PoolClient (transactions), or undefined (compile-only mode)
+     * @param options - Optional configuration
+     */
+    constructor(pool?: Pool | PoolClient | undefined, options?: PgsqlAdapterOptions);
+    /**
+     * Shared compilation dependencies — built lazily from adapter fields.
+     * Passed to compiler sub-modules instead of `this`.
+     */
+    /**
+     * Return a new PgsqlAdapterOptions that merges current config with overrides.
+     * Ensures that all configuration fields (logger, defaultPkColumnName,
+     * deriveFkColumnName, etc.) are propagated to scoped/transactional adapters.
+     */
+    private cloneOptions;
+    private buildCompileDeps;
+    /**
+     * Returns the pool/client executor, or throws if in compile-only mode.
+     */
+    private requireConnection;
+    /** Adapter capabilities for feature detection */
+    get capabilities(): AdapterCapabilities;
+    /** PostgreSQL dialect capabilities for planner strategy selection */
+    get dialectCapabilities(): DialectCapabilities;
+    /**
+     * DB column casing convention used by this adapter.
+     */
+    get dbCasing(): DbCasing;
+    /**
+     * Get the underlying pg Pool instance.
+     */
+    getPoolInstance(): Pool;
+    /**
+     * Compile a plan to executable SQL.
+     */
+    compile<T = unknown>(plan: PlanReport, options?: CompileOptions): CompiledQuery<T>;
+    /**
+     * Compile a plan with includes, returning subquery include metadata (DX-033).
+     */
+    compileWithIncludes<T = unknown>(plan: PlanReport, options?: CompileOptions): CompileResultWithIncludes<T>;
+    /**
+     * Compile a subquery include query for given parent IDs (DX-033).
+     * Generates: SELECT * FROM targetTable WHERE foreignKey IN ($1, $2, ...)
+     *
+     * @param info - Subquery include metadata
+     * @param parentIds - Parent record IDs to fetch related records for
+     * @param options - Compile options
+     * @returns Compiled query for fetching related records
+     */
+    compileSubqueryInclude(info: SubqueryIncludeInfo, parentIds: readonly unknown[], options?: CompileOptions): CompiledQuery;
+    /**
+     * Compile a FROM-less SELECT expression to SQL.
+     *
+     * Produces: SELECT <expr>
+     * Example: SELECT nextval('my_seq')
+     *
+     * @param expr - ExpressionIntent to evaluate
+     * @returns Compiled SQL and parameters
+     */
+    compileSelectExpression(expr: ExpressionIntent): CompiledQuery;
+    /**
+     * Compile an insert intent to executable SQL.
+     *
+     * Strategy switch (per CompileOptions):
+     * - rows <= batchThreshold (default 50): VALUES ($1,$2),($3,$4),...
+     * - rows > batchThreshold OR batchThreshold === 0: SELECT unnest($1::type[]),...
+     */
+    compileInsert(intent: InsertIntent, options?: CompileOptions): CompiledQuery;
+    /**
+     * Compile an insert-from intent to executable SQL (NQL-ALIGN).
+     * INSERT INTO target (cols) SELECT cols FROM source WHERE ... LIMIT ... RETURNING ...
+     */
+    compileInsertFrom(intent: InsertFromIntent, options?: CompileOptions): CompiledQuery;
+    /**
+     * Compile an update intent to executable SQL.
+     */
+    compileUpdate(intent: UpdateIntent, options?: CompileOptions): CompiledQuery;
+    /**
+     * Compile a batch update intent to executable SQL using unnest FROM strategy (BATCH-001).
+     *
+     * Generates:
+     *   UPDATE "table" SET "update_col" = t."update_col" [, "scalar_col" = $N]
+     *   FROM unnest(CAST($1 AS type[]), CAST($2 AS type[])) AS t("match_col", "update_col")
+     *   WHERE "table"."match_col" = t."match_col"
+     *   [RETURNING ...]
+     */
+    compileBatchUpdate(intent: BatchUpdateIntent, options?: CompileOptions): CompiledQuery;
+    /**
+     * Compile a delete intent to executable SQL.
+     */
+    compileDelete(intent: DeleteIntent, options?: CompileOptions): CompiledQuery;
+    /**
+     * Compile an upsert intent to executable SQL (DX-026).
+     */
+    compileUpsert(intent: UpsertIntent, options?: CompileOptions): CompiledQuery;
+    /**
+     * Compile an upsert-from intent to executable SQL (NQL-BIND).
+     * INSERT INTO target SELECT ... FROM source ON CONFLICT (cols) DO UPDATE SET ...
+     */
+    compileUpsertFrom(intent: UpsertFromIntent, options?: CompileOptions): CompiledQuery;
+    /**
+     * Compile a recursive CTE plan to executable SQL.
+     * Supports adjacency-list and edge-table traversal modes.
+     */
+    compileRecursive(report: RecursivePlanReport, model: ModelIR, options?: CompileOptions): CompiledQuery;
+    /**
+     * Compile a CTE query backed by unnest() arrays (BATCH-001 Block 5).
+     *
+     * Strategy: compile CTE nodes to SQL fragments, compile outer query
+     * independently (parameters starting at $1), then renumber outer params
+     * to start after CTE params and prepend WITH clause.
+     */
+    compileCteQuery(intent: CteQueryIntent, options?: CompileOptions): CompiledQuery;
+    /**
+     * Compile a set operation (UNION / INTERSECT / EXCEPT) to SQL.
+     */
+    compileSetOperation(intent: SetOperationIntent, model: ModelIR, _options?: CompileOptions): CompiledQuery;
+    /**
+     * Create a dump for observability.
+     */
+    createDump(plan: PlanReport, query: CompiledQuery, meta?: DumpMeta): Dump;
+    /**
+     * Execute a query and return all results.
+     * Results are transformed to use model naming convention (e.g., snake_case → camelCase)
+     */
+    execute<T>(query: CompiledQuery<T>): Promise<T[]>;
+    /**
+     * Transform result rows from database naming to model naming convention.
+     * For CamelCaseNamingPlugin: price_cents → priceCents
+     */
+    private transformResultRows;
+    /**
+     * Execute a query and return the first result or null.
+     */
+    executeOne<T>(query: CompiledQuery<T>): Promise<T | null>;
+    /**
+     * Execute a query and return the first result or throw.
+     */
+    executeOneOrThrow<T>(query: CompiledQuery<T>): Promise<T>;
+    /**
+     * Stream query results as an async iterable iterator.
+     * Uses PostgreSQL cursors for efficient streaming.
+     *
+     * Note: The cursor must be used within a transaction. If not already
+     * in a transaction, this method wraps the streaming in one.
+     *
+     * @param query - Compiled query to stream
+     * @param options - Stream options (chunkSize)
+     * @returns AsyncIterableIterator that yields rows one by one
+     */
+    stream<T>(query: CompiledQuery<T>, options?: AdapterStreamOptions): AsyncIterableIterator<T>;
+    /**
+     * Internal: Stream with an existing client using cursors.
+     */
+    private streamWithClient;
+    /**
+     * Introspect the database schema and return a ModelIR.
+     *
+     * @param options - Optional introspection options (schema, include/exclude filters)
+     * @returns IntrospectedModelIR with tables, relations, and hierarchy metadata
+     *
+     * @example
+     * ```typescript
+     * const model = await adapter.introspect();
+     * const model = await adapter.introspect({ schema: 'tenant_1' });
+     * const model = await adapter.introspect({ exclude: ['_prisma*'] });
+     * ```
+     */
+    introspect(options?: IntrospectionOptions): Promise<IntrospectedModelIR>;
+    /**
+     * Execute a callback within a database transaction.
+     */
+    transaction<T>(fn: (adapter: Adapter<DB>) => Promise<T>): Promise<T>;
+    /**
+     * Create a schema-scoped adapter for multi-tenant queries.
+     */
+    withSchema(schemaName: string): Adapter<DB>;
+    /**
+     * Execute raw SQL directly.
+     *
+     * ⚠️  WARNING: Use parameter placeholders ($1, $2, etc.) for all values.
+     */
+    executeRaw<T = unknown>(sql: string, parameters?: readonly unknown[]): Promise<T[]>;
+    /**
+     * Generate DDL statements from a ModelIR schema.
+     *
+     * Uses PostgreSQL AST nodes and pgsql-deparser for consistent SQL generation.
+     * Applies the naming plugin for identifier transformation.
+     *
+     * @param schema - The ModelIR schema to generate DDL from
+     * @param overrideOptions - Optional overrides for DDL generation (e.g., includeDropStatements)
+     * @returns Array of DDL statements in dependency order
+     */
+    generateDDL(schema: ModelIR, overrideOptions?: Partial<GenerateDDLOptions>): string[];
+    /**
+     * Execute a DDL statement directly (e.g. TRUNCATE, VACUUM, ALTER TABLE, CREATE INDEX).
+     *
+     * @throws Error if called on a compile-only adapter (no pool)
+     * @since DDL-TABLE-001
+     */
+    executeDDL(sql: string): Promise<void>;
+    /**
+     * Whether this adapter instance is scoped inside a transaction.
+     * Guards unsafe DDL operations (VACUUM, CREATE INDEX CONCURRENTLY).
+     *
+     * @since DDL-TABLE-001
+     */
+    get inTransaction(): boolean;
+    /**
+     * List all indexes on a table by querying pg_indexes.
+     *
+     * @param table - Table name
+     * @param schema - Schema name (defaults to adapter schema or 'public')
+     */
+    listIndexes(table: string, schema?: string, options?: {
+        namePattern?: string;
+    }): Promise<IndexInfo[]>;
+    /**
+     * Check whether an index with the given name exists on a table.
+     *
+     * @param name - Index name
+     * @param table - Table name
+     * @param schema - Schema name (defaults to adapter schema or 'public')
+     */
+    indexExists(name: string, table: string, schema?: string): Promise<boolean>;
+    /**
+     * Return the total storage size of a table in bytes.
+     *
+     * @param table - Table name
+     * @param schema - Schema name (defaults to adapter schema or 'public')
+     */
+    /**
+     * Return the total storage size of a table in bytes (includes indexes and TOAST).
+     *
+     * The table name is a SQL identifier — it is double-quoted, not parameterized,
+     * because PostgreSQL does not allow parameterized table names in FROM clauses.
+     *
+     * @param table - Table name
+     * @param schema - Schema name (defaults to adapter schema or 'public')
+     */
+    storageSize(table: string, schema?: string): Promise<number>;
+    /**
+     * Generate SQL for TRUNCATE TABLE.
+     * Implements TableDDLGeneratorAdapter.generateTruncate.
+     */
+    generateTruncate(table: string, schema?: string, options?: TruncateOptions): string;
+    /**
+     * Generate SQL for VACUUM.
+     * Implements TableDDLGeneratorAdapter.generateVacuum.
+     */
+    generateVacuum(table: string, schema?: string, options?: VacuumOptions): string;
+    /**
+     * Generate SQL for ALTER TABLE ... ALTER COLUMN.
+     * Implements TableDDLGeneratorAdapter.generateAlterColumn.
+     */
+    generateAlterColumn(table: string, column: string, options: AlterColumnOptions, schema?: string): string;
+    /**
+     * Generate SQL for CREATE INDEX.
+     * Implements TableDDLGeneratorAdapter.generateCreateIndex.
+     */
+    generateCreateIndex(table: string, options: CreateIndexOptions, schema?: string): string;
+    /**
+     * Generate SQL for DROP INDEX.
+     * Implements TableDDLGeneratorAdapter.generateDropIndex.
+     */
+    generateDropIndex(name: string, options?: DropIndexOptions): string;
+    /**
+     * Validate an identifier (table name, column name, schema name).
+     */
+    validateIdentifier(value: string, type: string): void;
+}
+/**
+ * Create a PgsqlAdapter from a pg Pool instance.
+ *
+ * @param pool - pg Pool instance
+ * @param options - Optional configuration
+ * @returns A new PgsqlAdapter instance
+ *
+ * @example
+ * ```typescript
+ * import { Pool } from 'pg';
+ * import { createPgsqlAdapter } from '@dbsp/adapter-pgsql';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const adapter = createPgsqlAdapter(pool);
+ *
+ * // With naming convention
+ * const adapter = createPgsqlAdapter(pool, { dbCasing: 'snake_case' });
+ * ```
+ */
+declare function createPgsqlAdapter<DB = unknown>(pool: Pool, options?: PgsqlAdapterOptions): PgsqlAdapter<DB>;
+/**
+ * Creates a compile-only PgsqlAdapter for SQL generation without a database connection.
+ *
+ * All compilation methods (compile, compileInsert, etc.), createDump(), and generateDDL()
+ * work normally. Execution methods (execute, stream, transaction, etc.) throw an error.
+ *
+ * @example
+ * ```typescript
+ * import { createPgsqlCompileOnlyAdapter } from '@dbsp/adapter-pgsql';
+ * import { createOrm } from '@dbsp/core';
+ *
+ * const adapter = createPgsqlCompileOnlyAdapter();
+ * const orm = createOrm({ model, adapter });
+ * const dump = await orm.select('users').dump();
+ * console.log(dump.sql);
+ * ```
+ */
+declare function createPgsqlCompileOnlyAdapter<DB = unknown>(options?: PgsqlAdapterOptions): CompileOnlyAdapter;
+
+/**
+ * Redact sensitive values in a query dump's `params` array before logging.
+ *
+ * Defense-in-depth helper: when application code may have inserted PII as
+ * literal parameter values (e.g. an email in a WHERE clause), this replaces
+ * any string value matching a configured pattern with the `replacement`
+ * placeholder. Non-string values are passed through unchanged.
+ */
+type RedactionPattern = string | RegExp;
+type RedactionConfig = {
+    /** Patterns to match against string param values. String = substring (case-insensitive); RegExp = `.test()`. */
+    readonly patterns: ReadonlyArray<RedactionPattern>;
+    /** Placeholder substituted for matched values. Default `'[REDACTED]'`. */
+    readonly replacement?: string;
+};
+/**
+ * Curated regex set for common PII shapes. Match against the value itself
+ * (not the column name), so they detect data shaped like an email / token /
+ * credit-card / SSN regardless of which `$N` slot it landed in.
+ *
+ * @stable Adding entries is non-breaking; removing one is a semver-major change
+ *   because callers may rely on a specific shape being redacted.
+ */
+declare const DEFAULT_REDACTION_PATTERNS: ReadonlyArray<RegExp>;
+/**
+ * Returns a NEW array of params with sensitive string values replaced.
+ * The input array is never mutated. Non-string values pass through unchanged.
+ */
+declare function redactParams(params: readonly unknown[], config: RedactionConfig): readonly unknown[];
+
+/**
+ * Set operation compiler (UNION / INTERSECT / EXCEPT)
+ *
+ * Recursively compiles a SetOperationIntent tree into a single SQL string
+ * with correctly renumbered positional parameters ($1, $2, ...).
+ */
+
+/**
+ * Compiled SQL with positional parameters.
+ */
+interface SetOperationResult {
+    readonly sql: string;
+    readonly parameters: readonly unknown[];
+}
+/**
+ * Function that compiles a single QueryIntent leaf to SQL + parameters.
+ * Provided by the caller to decouple from adapter internals.
+ */
+type LeafCompileFn = (query: QueryIntent) => {
+    sql: string;
+    parameters: readonly unknown[];
+};
+/**
+ * Recursively compile a SetOperationIntent to SQL with merged parameters.
+ *
+ * Each leaf QueryIntent is compiled via `compileFn`. When merging left and
+ * right branches, the right side's `$N` placeholders are renumbered so they
+ * don't collide with the left side's parameters.
+ *
+ * @param intent - The set operation intent (recursive tree)
+ * @param compileFn - Compiles a single QueryIntent to SQL + params
+ * @returns Combined SQL string and merged parameter array
+ *
+ * @example
+ * ```typescript
+ * const result = compileSetOperation(setOpIntent, (query) => {
+ *   const planReport = plan(query, model, { dialectCapabilities });
+ *   return adapter.compile(planReport, { model });
+ * });
+ * console.log(result.sql);        // (SELECT ...) UNION (SELECT ...)
+ * console.log(result.parameters);  // [...leftParams, ...rightParams]
+ * ```
+ */
+declare function compileSetOperation(intent: SetOperationIntent, compileFn: LeafCompileFn): SetOperationResult;
+/**
+ * Create a leaf compile function from adapter + model + capabilities.
+ *
+ * Convenience factory for the common case where you have a PgsqlAdapter
+ * and need a compileFn for `compileSetOperation`.
+ *
+ * @param adapter - Adapter with compile() and dialectCapabilities
+ * @param model - ModelIR schema
+ * @param planFn - The plan() function from @dbsp/core
+ */
+declare function createLeafCompileFn(adapter: {
+    compile(plan: PlanReport, options: {
+        model: ModelIR$1;
+    }): {
+        sql: string;
+        parameters: readonly unknown[];
+    };
+    dialectCapabilities: DialectCapabilities;
+}, model: ModelIR$1, planFn: (intent: QueryIntent, model: ModelIR$1, options: {
+    dialectCapabilities: DialectCapabilities;
+}) => PlanReport): LeafCompileFn;
+
+/**
+ * Cursor-Based Streaming Support
+ *
+ * Generates PostgreSQL cursor statements for streaming large result sets.
+ * Supports:
+ * - DECLARE CURSOR
+ * - FETCH (forward, backward, all)
+ * - CLOSE CURSOR
+ *
+ * Note: This generates AST nodes for cursor operations.
+ * Actual cursor execution requires a transaction context.
+ */
+
+/**
+ * Cursor scroll options.
+ */
+type CursorScrollOption = 'scroll' | 'no_scroll';
+/**
+ * Cursor hold option (whether cursor survives transaction commit).
+ */
+type CursorHoldOption = 'with_hold' | 'without_hold';
+/**
+ * Fetch direction for cursor.
+ */
+type FetchDirection = 'next' | 'prior' | 'first' | 'last' | 'absolute' | 'relative' | 'forward' | 'backward' | 'forward_all' | 'backward_all';
+/**
+ * Options for DECLARE CURSOR.
+ */
+interface CursorOptions {
+    /** Cursor name */
+    name: string;
+    /** The query to execute */
+    query: Node;
+    /** Scroll option (default: no_scroll) */
+    scroll?: CursorScrollOption;
+    /** Hold option (default: without_hold) */
+    hold?: CursorHoldOption;
+    /** Binary output (rarely used) */
+    binary?: boolean;
+}
+/**
+ * Options for FETCH.
+ */
+interface FetchOptions {
+    /** Cursor name */
+    cursorName: string;
+    /** Fetch direction */
+    direction?: FetchDirection;
+    /** Number of rows to fetch (for forward/backward) */
+    count?: number;
+}
+/**
+ * Build a DECLARE CURSOR statement.
+ *
+ * @param options - Cursor declaration options
+ * @returns DeclareCursorStmt AST node
+ *
+ * @example
+ * ```typescript
+ * const selectAst = { SelectStmt: { ... } };
+ * const cursorAst = buildDeclareCursor({
+ *   name: 'my_cursor',
+ *   query: selectAst,
+ *   scroll: 'no_scroll',
+ *   hold: 'without_hold'
+ * });
+ * // Produces: DECLARE my_cursor NO SCROLL CURSOR WITHOUT HOLD FOR SELECT ...
+ * ```
+ */
+declare function buildDeclareCursor(options: CursorOptions): Node;
+/**
+ * Build a FETCH statement.
+ *
+ * @param options - Fetch options
+ * @returns FetchStmt AST node
+ *
+ * @example
+ * ```typescript
+ * const fetchAst = buildFetch({
+ *   cursorName: 'my_cursor',
+ *   direction: 'forward',
+ *   count: 100
+ * });
+ * // Produces: FETCH FORWARD 100 FROM my_cursor
+ * ```
+ */
+declare function buildFetch(options: FetchOptions): Node;
+/**
+ * Build a CLOSE cursor statement.
+ *
+ * @param cursorName - Name of cursor to close (or '*' for all)
+ * @returns ClosePortalStmt AST node
+ */
+declare function buildCloseCursor(cursorName: string): Node;
+/**
+ * Build FETCH NEXT (single row).
+ */
+declare function buildFetchNext(cursorName: string): Node;
+/**
+ * Build FETCH FORWARD N (multiple rows).
+ */
+declare function buildFetchForward(cursorName: string, count: number): Node;
+/**
+ * Build FETCH ALL (remaining rows).
+ */
+declare function buildFetchAll(cursorName: string): Node;
+/**
+ * Build FETCH FIRST (move to start and get first row).
+ */
+declare function buildFetchFirst(cursorName: string): Node;
+/**
+ * Configuration for streaming query execution.
+ */
+interface StreamConfig {
+    /** Cursor name prefix (will be appended with unique ID) */
+    cursorPrefix?: string;
+    /** Batch size for each fetch (default: 100) */
+    batchSize?: number;
+    /** Whether cursor should survive transaction (default: false) */
+    withHold?: boolean;
+}
+/**
+ * Generate a unique cursor name.
+ *
+ * @param prefix - Cursor name prefix
+ * @returns Unique cursor name
+ */
+declare function generateCursorName(prefix?: string): string;
+/**
+ * Build all statements needed for streaming query execution.
+ *
+ * @param query - The SELECT query to stream
+ * @param config - Streaming configuration
+ * @returns Object with cursor name and statement builders
+ *
+ * @example
+ * ```typescript
+ * const { cursorName, declare, fetchBatch, close } = buildStreamingStatements(
+ *   selectAst,
+ *   { batchSize: 100 }
+ * );
+ *
+ * // In transaction:
+ * // 1. Execute declare
+ * // 2. Loop: execute fetchBatch, process rows, until empty
+ * // 3. Execute close
+ * ```
+ */
+declare function buildStreamingStatements(query: Node, config?: StreamConfig): {
+    cursorName: string;
+    declare: Node;
+    fetchBatch: Node;
+    fetchAll: Node;
+    close: Node;
+};
+
+/**
+ * Identifier Validation for adapter-pgsql
+ *
+ * Security layer to prevent SQL injection via identifiers.
+ * All table names, column names, schema names, and aliases MUST pass validation.
+ */
+/**
+ * Error thrown when an identifier fails validation.
+ */
+declare class InvalidIdentifierError extends Error {
+    readonly identifier: string;
+    readonly identifierType: string;
+    readonly reason: string;
+    constructor(identifier: string, identifierType: string, reason: string);
+}
+/**
+ * Validate that a string is a safe SQL identifier.
+ *
+ * Rules:
+ * 1. Must not be empty
+ * 2. Must not exceed 63 characters (PostgreSQL limit)
+ * 3. Must start with letter or underscore
+ * 4. Must contain only alphanumeric, underscore, or dollar sign
+ * 5. Must not contain null bytes or control characters
+ * 6. Reserved keywords are allowed (will be quoted)
+ *
+ * @param value The identifier to validate
+ * @param type Type of identifier (for error messages): 'table', 'column', 'schema', 'alias'
+ * @throws InvalidIdentifierError if validation fails
+ */
+declare function validateIdentifier(value: string, type: 'table' | 'column' | 'schema' | 'alias'): void;
+/**
+ * Check if an identifier is a SQL reserved keyword.
+ */
+declare function isReservedKeyword(value: string): boolean;
+/**
+ * Validate a schema-qualified identifier (schema.table).
+ *
+ * @param schemaTable String in format "schema.table" or just "table"
+ * @returns Object with validated schema and table names
+ * @throws InvalidIdentifierError if validation fails
+ */
+declare function validateQualifiedIdentifier(schemaTable: string): {
+    schema?: string;
+    table: string;
+};
+/**
+ * Batch validate multiple identifiers.
+ *
+ * @param identifiers Map of identifier values to their types
+ * @throws InvalidIdentifierError on first validation failure
+ */
+declare function validateIdentifiers(identifiers: Record<string, 'table' | 'column' | 'schema' | 'alias'>): void;
+/**
+ * Sanitize an identifier for safe logging/display.
+ * NOT for use in SQL - use validateIdentifier + AST helpers for that.
+ */
+declare function sanitizeForDisplay(value: string): string;
+
+export { type BatchValuesJoinDecision, CamelCaseNamingPlugin, type ChangeKind, type CompareSchemataOptions, type CompiledResult, type CompilerContext, type CompilerOptions, type CompilerState, type ConflictAction, type ConflictTarget, type CursorHoldOption, type CursorOptions, type CursorScrollOption, DEFAULT_PK_COLUMN, DEFAULT_REDACTION_PATTERNS, type Decision, type DeleteConfig, type DetectedHierarchy, type DiffSummary, type ExplainFormat, type ExplainOptions, type ExplainPlan, type ExpressionHandler, type FetchDirection, type FetchOptions, type FkColumnDerivation, type GenerateDDLOptions, IdentityNamingPlugin, type IncludeHandler, type IncludeResult, type InsertConfig, type IntrospectedModelIR, type IntrospectionOptions, InvalidIdentifierError, type JoinDecision, type LeafCompileFn, type MigrationRecord, type MigrationSQLOptions, type NamingPlugin, type ParamRefValidationResult, type ParsedMigrationFile, PgsqlAdapter, type PgsqlAdapterOptions, PlanCompiler, type PlanDecision, type PrecompiledJoinDecision, type RedactionConfig, type RedactionPattern, type SchemaChange, type SchemaDiff, type SetOperationResult, type SimplifiedPlanReport, type StreamConfig, type UpdateConfig, type UpsertConfig, type WhereDispatcher, type WhereHandler, acquireMigrationLock, bm25Search, booleanSearch, boost, buildCloseCursor, buildDeclareCursor, buildExplain, buildExplainAnalyzeJson, buildExplainPlan, buildExplainVerbose, buildFetch, buildFetchAll, buildFetchFirst, buildFetchForward, buildFetchNext, buildOnConflictClause, buildStreamingStatements, camelCaseNaming, collectAndValidateParamRefs, compareSchemata, compileDelete, compileInsert, compileMutation, compilePlan, compileSetOperation, compileUpdate, compileUpsert, conditionalUpdate, cosineDistance, createAnyExpr, createEqualityExpr, createLeafCompileFn, createParamRef, createPgsqlAdapter, createPgsqlCompileOnlyAdapter, createTypeCastParamRef, defaultFkDerivation, ensureMigrationsTable, excludedRef, generateCursorName, generateDDL, generateDownSQL, generateMigrationFile, generateMigrationSQL, generateSeries, getAppliedMigrations, getNamingPluginForDbCasing, getNextSchemaVersion, getRowEstimates, getTotalExecutionTime, identityNaming, innerProduct, introspect, isBatchValuesJoinDecision, isDestructiveDown, isJoinDecision, isMigrationApplied, isPrecompiledJoinDecision, isReservedKeyword, l2Distance, mapColumnType, mapOnDeleteAction, nextval, parse, parseExplainJson, parseMigrationFile, rawDistance, recordMigration, redactParams, releaseMigrationLock, removeMigrationRecord, resolveLogicalName, sanitizeForDisplay, score, validateIdentifier, validateIdentifiers, validateParamRef, validateQualifiedIdentifier, vectorDims, withMigrationLock };