@dbsp/adapter-pgsql 1.2.1 → 1.4.0

package/README.md

@@ -42,6 +42,10 @@ const { sql, params } = orm.select('users').where(eq('active', true)).dump();
 // sql, params — no Pool needed
 ```
 
+### Direct NQL bundles
+
+`adapter.compile(compiledNqlBundle, options)` trusts that direct `CompiledNqlQuery` bundles are well-formed and semantically validated by the NQL compiler. The adapter still enforces SQL safety for emitted binding names, including identifier validation and binding/table or binding/binding collision checks before emitting `WITH` CTEs.
+
 ## Key features
 
 - **Parameterized queries** — All user values use `$N` positional parameters; no SQL injection surface

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)
@@ -251,12 +261,15 @@ interface CompiledResult {
 interface CompilerOptions {
     readonly naming?: NamingPlugin;
     readonly schema?: string;
+    readonly dialectCapabilities?: DialectCapabilities;
     /** 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;
+    /** Query-local CTE/binding names that must not be schema-qualified. */
+    readonly bindingNames?: BindingNameRegistry;
 }
 declare class PlanCompiler {
     private readonly naming;
@@ -264,6 +277,8 @@ declare class PlanCompiler {
     private readonly defaultPk;
     private readonly deriveFk;
     private readonly model;
+    private readonly dialectCapabilities;
+    private readonly bindingNames;
     /** Mutable state shared with extracted condition/value compilation functions */
     private state;
     /** Track root table for EXISTS FK correlation */
@@ -287,6 +302,7 @@ declare class PlanCompiler {
      */
     private usedJoinAliases;
     constructor(options?: CompilerOptions);
+    private childCompilerOptions;
     /** Build immutable context for handler-based WHERE compilation */
     private handlerCtx;
     private findAliasForLegacySourceTable;
@@ -330,6 +346,7 @@ declare class PlanCompiler {
     private createHandlerContext;
     /** Build a fresh HandlerCompilerState sharing the current parameter array. */
     private createHandlerState;
+    private schemaForRangeVar;
     private compileExpressionSubquery;
     private compileGenericNqlFunction;
     private compileNqlFunctionArg;
@@ -383,11 +400,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.
@@ -1044,6 +1071,8 @@ interface CompilerContext {
     readonly naming: NamingPlugin;
     /** Schema name for table qualification (optional) */
     readonly schema?: string;
+    /** Dialect capabilities for adapter-layer SQL surface gates */
+    readonly dialectCapabilities?: DialectCapabilities;
     /** Root table name for the query */
     readonly rootTable: string;
     /** Current table alias (for JOINs) */
@@ -1060,6 +1089,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 +1444,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 +1653,7 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
     private cloneOptions;
     private buildCompileDeps;
     private requireNqlCompileModel;
+    private assertNqlBindingNamesDisjointFromTables;
     private compileNqlMutation;
     private compileNqlBundleLeaf;
     private compileNqlBundle;
@@ -1637,6 +1675,11 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
     getPoolInstance(): Pool;
     /**
      * Compile a plan to executable SQL.
+     *
+     * When passed a direct `CompiledNqlQuery`, the adapter trusts that the bundle
+     * has already been semantically validated by the NQL compiler. This method
+     * still performs adapter-owned SQL safety checks for emitted binding names
+     * before CTE emission.
      */
     compile<T = unknown>(plan: PlanReport | CompiledNqlQuery, options?: CompileOptions): CompiledQuery<T>;
     /**
@@ -1720,6 +1763,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.
      */