@dbsp/adapter-pgsql 1.2.1 → 1.3.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 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 { ParamIntent, DialectCapabilities, ModelIR, DbCasing, ColumnIR, HierarchyIR, Adapter, AdapterLogger, AdapterCapabilities, PlanReport, CompiledNqlQuery, CompileOptions, CompiledQuery, CompileResultWithIncludes, SubqueryIncludeInfo, ExpressionIntent, InsertIntent, InsertFromIntent, UpdateIntent, BatchUpdateIntent, DeleteIntent, UpsertIntent, UpsertFromIntent, RecursivePlanReport, CteQueryIntent, SetOperationIntent, DumpMeta, Dump, AdapterStreamOptions, CompileOnlyAdapter, QueryIntent } from '@dbsp/types';
+import { ParamIntent, DialectCapabilities, ModelIR, DbCasing, ColumnIR, HierarchyIR, WhereIntent, Adapter, AdapterLogger, AdapterCapabilities, PlanReport, CompiledNqlQuery, 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';
@@ -89,6 +89,16 @@ declare const camelCaseNaming: CamelCaseNamingPlugin;
  */
 declare function getNamingPluginForDbCasing(casing: 'snake_case' | 'camelCase' | 'preserve'): NamingPlugin;
 
+/**
+ * Internal registry of NQL `| bind name` CTE names visible to a compile pass.
+ *
+ * Binding names are query-local identifiers, not physical tables. When an active
+ * schema is present, real table FROM sources must be schema-qualified, while CTE
+ * binding names must remain unqualified.
+ */
+
+type BindingNameRegistry = ReadonlySet<string>;
+
 /**
  * Simplified PlanDecision for the spike
  * (In production, import from @dbsp/core)
@@ -257,6 +267,8 @@ interface CompilerOptions {
     readonly deriveFkColumnName?: FkColumnDerivation;
     /** ModelIR for type-aware parameter casting in WHERE clauses */
     readonly model?: _dbsp_types.ModelIR;
+    /** Query-local CTE/binding names that must not be schema-qualified. */
+    readonly bindingNames?: BindingNameRegistry;
 }
 declare class PlanCompiler {
     private readonly naming;
@@ -264,6 +276,7 @@ declare class PlanCompiler {
     private readonly defaultPk;
     private readonly deriveFk;
     private readonly model;
+    private readonly bindingNames;
     /** Mutable state shared with extracted condition/value compilation functions */
     private state;
     /** Track root table for EXISTS FK correlation */
@@ -383,11 +396,21 @@ declare class PlanCompiler {
      * Returns undefined when neither expressionIntent nor column is present.
      */
     private compileOrderByDecision;
+    /**
+     * Compile a column reference that may use dotted 'relation.column' notation.
+     */
+    private compileRelationAwareColumnRef;
     /**
      * Compile a single groupBy decision into a ColumnRef AST node.
      * Supports dotted 'relation.column' notation for joined tables.
      */
     private compileGroupByDecision;
+    /**
+     * Compile a DISTINCT ON column into a ColumnRef AST node.
+     * Mirrors GROUP BY relation-alias resolution while preserving unqualified
+     * DISTINCT ON columns as unqualified references.
+     */
+    private compileDistinctOnColumn;
     /**
      * Assemble the final SelectStmt from all accumulated clause nodes.
      * Also handles the default SELECT *, CTEs, and row-level locking.
@@ -1060,6 +1083,8 @@ interface CompilerContext {
     readonly deriveFkColumnName?: FkColumnDerivation;
     /** Alias of the outer (parent) query — used for FieldRef scope:'outer' resolution in EXISTS subqueries */
     readonly outerAlias?: string;
+    /** Query-local CTE/binding names that must not be schema-qualified. */
+    readonly bindingNames?: BindingNameRegistry;
     /**
      * Optional callback to compile a QueryIntent into an AST Node (SubLink subselect).
      * Set by PlanCompiler when compiling selectCustomExpression — enables SubqueryExpressionIntent
@@ -1413,6 +1438,12 @@ interface UpsertConfig {
     conflictAction: ConflictAction;
     /** Columns to update on conflict (for 'update' action) */
     updateColumns?: string[];
+    /** Optional WHERE clause for ON CONFLICT DO UPDATE */
+    actionWhere?: Decision[];
+    /** Optional direct WHERE intent for ON CONFLICT DO UPDATE */
+    actionWhereIntent?: WhereIntent;
+    /** Compile the direct action WHERE intent using the caller's WHERE compiler */
+    compileActionWhere?: (where: WhereIntent, state: CompilerState) => Node;
     /** Use EXCLUDED.column for update values (default: true) */
     useExcluded?: boolean;
     /** Columns to return (RETURNING clause) */
@@ -1616,6 +1647,7 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
     private cloneOptions;
     private buildCompileDeps;
     private requireNqlCompileModel;
+    private assertNqlBindingNamesDisjointFromTables;
     private compileNqlMutation;
     private compileNqlBundleLeaf;
     private compileNqlBundle;
@@ -1720,6 +1752,7 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
      * Compile a set operation (UNION / INTERSECT / EXCEPT) to SQL.
      */
     compileSetOperation(intent: SetOperationIntent, model: ModelIR, options?: CompileOptions): CompiledQuery;
+    private compileSetOperationWithBindings;
     /**
      * Create a dump for observability.
      */