@telorun/sql 0.9.0 → 0.10.0

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { SqlConnectionResource, createSqlConnection, type SqlDriver, type PlaceholderStyle, } from "./sql-connection-controller.js";
+export { SqlConnectionBase } from "./sql-connection-base.js";
+export { quoteAnsiIdentifier, type PlaceholderStyle, type SqlConnection, type SqlDialect, } from "./sql-connection.js";
 export { isSqlConnection, resolveSqlConnection } from "./sql-connection-ref.js";
-export type { SqliteDb, SqliteStatement } from "./sqlite-driver-interface.js";

package/dist/index.js

@@ -1,2 +1,3 @@
-export { SqlConnectionResource, createSqlConnection, } from "./sql-connection-controller.js";
+export { SqlConnectionBase } from "./sql-connection-base.js";
+export { quoteAnsiIdentifier, } from "./sql-connection.js";
 export { isSqlConnection, resolveSqlConnection } from "./sql-connection-ref.js";

package/dist/sql-command-controller.d.ts

@@ -1,5 +1,5 @@
 import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
-import type { SqlConnectionResource } from "./sql-connection-controller.js";
+import type { SqlConnection } from "./sql-connection.js";
 import type { SqlResult } from "./sql-query-controller.js";
 import type { SqlTransactionResource } from "./sql-transaction-controller.js";
 interface SqlCommandManifest {
@@ -7,7 +7,7 @@ interface SqlCommandManifest {
         name: string;
         module: string;
     };
-    connection?: SqlConnectionResource;
+    connection?: SqlConnection;
     transaction?: SqlTransactionResource;
     inputs: {
         sql: string;

package/dist/sql-connection-base.d.ts

@@ -0,0 +1,29 @@
+import { type Kysely, type QueryResult } from "kysely";
+import type { SqlConnection, SqlDialect } from "./sql-connection.js";
+import type { SqlTransactionResource } from "./sql-transaction-controller.js";
+/**
+ * The dialect-neutral half of a connection: statement execution, transaction
+ * scoping, template binding and row-count normalization over a kysely instance.
+ *
+ * Backends extend it, supply their {@link SqlDialect}, and override only what is
+ * genuinely theirs — `teardown` for resources kysely does not own, `executeScript`
+ * where the driver has a native multi-statement path.
+ */
+export declare abstract class SqlConnectionBase implements SqlConnection {
+    readonly dialect: SqlDialect;
+    protected readonly db: Kysely<any>;
+    constructor(db: Kysely<any>, dialect: SqlDialect);
+    get kysely(): Kysely<any>;
+    init(): Promise<void>;
+    teardown(): Promise<void>;
+    transaction<T>(cb: () => Promise<T>): Promise<T>;
+    execute<T>(sql: string, params?: unknown[], transaction?: SqlTransactionResource): Promise<QueryResult<T>>;
+    executeTemplate<T>(fragments: string[], values: unknown[], transaction?: SqlTransactionResource): Promise<QueryResult<T>>;
+    /** Hand the whole script to the driver as one statement. Backends whose driver
+     *  needs a dedicated multi-statement entry point override this. */
+    executeScript(sql: string): Promise<void>;
+    toRowCount(result: QueryResult<unknown>): number;
+    snapshot(): Record<string, unknown>;
+    private placeholder;
+    private resolveExecutor;
+}

package/dist/{sql-connection-controller.js → sql-connection-base.js}

@@ -2,20 +2,22 @@ import { randomUUID } from "crypto";
 import { CompiledQuery } from "kysely";
 import { currentTxId, deleteTx, getTx, setTx, txStorage } from "./transaction-store.js";
 /**
- * Driver-agnostic SQL connection. The kysely instance (and, for SQLite, the
- * underlying database handle used by `executeScript`) is built by the driver
- * backend (`sql-postgres`, `sql-sqlite`) and handed in via
- * {@link createSqlConnection}. Everything here — execution, transactions,
- * placeholder style, row-count normalization — is transport-neutral.
+ * The dialect-neutral half of a connection: statement execution, transaction
+ * scoping, template binding and row-count normalization over a kysely instance.
+ *
+ * Backends extend it, supply their {@link SqlDialect}, and override only what is
+ * genuinely theirs — `teardown` for resources kysely does not own, `executeScript`
+ * where the driver has a native multi-statement path.
  */
-export class SqlConnectionResource {
-    driver;
+export class SqlConnectionBase {
+    dialect;
     db;
-    sqlite;
-    constructor(driver, db, sqlite) {
-        this.driver = driver;
+    constructor(db, dialect) {
+        this.dialect = dialect;
         this.db = db;
-        this.sqlite = sqlite;
+    }
+    get kysely() {
+        return this.db;
     }
     async init() {
         await this.db.connection().execute(async () => {
@@ -41,12 +43,6 @@ export class SqlConnectionResource {
         const executor = this.resolveExecutor(transaction);
         return executor.executeQuery(CompiledQuery.raw(sql, params));
     }
-    get placeholderStyle() {
-        return this.driver === "postgres" ? "numbered" : "qmark";
-    }
-    /** Assemble SQL from literal fragments by interleaving driver-native
-     *  placeholders, then bind `values` positionally. `fragments.length` must
-     *  equal `values.length + 1`. */
     async executeTemplate(fragments, values, transaction) {
         let sql = fragments[0] ?? "";
         for (let i = 1; i < fragments.length; i++) {
@@ -54,14 +50,9 @@ export class SqlConnectionResource {
         }
         return this.execute(sql, values, transaction);
     }
-    placeholder(index) {
-        return this.placeholderStyle === "numbered" ? `$${index}` : "?";
-    }
+    /** Hand the whole script to the driver as one statement. Backends whose driver
+     *  needs a dedicated multi-statement entry point override this. */
     async executeScript(sql) {
-        if (this.driver === "sqlite") {
-            this.sqlite?.exec(sql);
-            return;
-        }
         await this.execute(sql);
     }
     toRowCount(result) {
@@ -70,12 +61,12 @@ export class SqlConnectionResource {
         }
         return result.rows.length;
     }
-    get kysely() {
-        return this.db;
-    }
     snapshot() {
         return {};
     }
+    placeholder(index) {
+        return this.dialect.placeholderStyle === "numbered" ? `$${index}` : "?";
+    }
     resolveExecutor(transaction) {
         if (transaction) {
             transaction.assertActive();
@@ -90,12 +81,3 @@ export class SqlConnectionResource {
         return this.db;
     }
 }
-/**
- * Build a connection from a driver-constructed kysely instance. Driver backends
- * (`sql-postgres`, `sql-sqlite`) own dialect construction and call this; the
- * `sqlite` handle is required only for SQLite (its `executeScript` runs through
- * the native handle).
- */
-export function createSqlConnection(driver, db, sqlite) {
-    return new SqlConnectionResource(driver, db, sqlite);
-}

package/dist/sql-connection-ref.d.ts

@@ -1,11 +1,11 @@
 import type { KindRef, ResourceContext } from "@telorun/sdk";
-import type { SqlConnectionResource } from "./sql-connection-controller.js";
+import type { SqlConnection } from "./sql-connection.js";
 /** True when a value already exposes the connection contract (Phase-5 injected). */
-export declare function isSqlConnection(value: unknown): value is SqlConnectionResource;
+export declare function isSqlConnection(value: unknown): value is SqlConnection;
 /**
  * Resolve a `connection` `!ref` field to a live connection. The slot is optional
  * — an unset one yields `undefined` so the caller can fall back to a `transaction`
  * — but a slot that IS set must resolve. `describe` names the owning resource and
  * slot, so the failure points at a concrete manifest location.
  */
-export declare function resolveSqlConnection(value: SqlConnectionResource | KindRef<SqlConnectionResource> | undefined, ctx: ResourceContext, describe: () => string): SqlConnectionResource | undefined;
+export declare function resolveSqlConnection(value: SqlConnection | KindRef<SqlConnection> | undefined, ctx: ResourceContext, describe: () => string): SqlConnection | undefined;

package/dist/sql-connection.d.ts

@@ -0,0 +1,45 @@
+import type { ResourceInstance } from "@telorun/sdk";
+import type { Kysely, QueryResult } from "kysely";
+import type { SqlTransactionResource } from "./sql-transaction-controller.js";
+/** Native bind-placeholder syntax: SQLite binds anonymous `?`, PostgreSQL binds
+ *  numbered `$1`, `$2`, … */
+export type PlaceholderStyle = "qmark" | "numbered";
+/**
+ * Renders the SQL constructs that differ between database dialects. A backend
+ * supplies one; the `Sql.*` operations build statements through it and never
+ * branch on which database sits behind the connection.
+ */
+export interface SqlDialect {
+    readonly placeholderStyle: PlaceholderStyle;
+    /** Quote an identifier — table, column, alias. */
+    quoteIdentifier(name: string): string;
+    /** Render set membership. Dialects disagree: PostgreSQL binds the whole array
+     *  to a single placeholder, SQLite binds one per element. `column` arrives
+     *  already quoted. */
+    renderIn(column: string, values: unknown[], addParam: (value: unknown) => string): string;
+}
+/** ANSI identifier quoting (`"name"`), for the dialects that follow the standard. */
+export declare function quoteAnsiIdentifier(name: string): string;
+/**
+ * The contract every SQL backend satisfies and every `Sql.*` operation programs
+ * against. Backends (`sql-postgres`, `sql-sqlite`) own their own implementation
+ * — usually by extending {@link SqlConnectionBase} — so nothing in this module
+ * knows which databases exist.
+ */
+export interface SqlConnection extends ResourceInstance {
+    readonly dialect: SqlDialect;
+    /** The underlying kysely instance, when the backend is built on one —
+     *  {@link SqlConnectionBase} always provides it. Optional because the contract
+     *  must stay implementable by a driver kysely does not support; a consumer
+     *  that needs it (`Sql.Migrations`) checks and fails with a clear message. */
+    readonly kysely?: Kysely<any>;
+    execute<T>(sql: string, params?: unknown[], transaction?: SqlTransactionResource): Promise<QueryResult<T>>;
+    /** Assemble SQL from literal fragments by interleaving dialect-native
+     *  placeholders, then bind `values` positionally. */
+    executeTemplate<T>(fragments: string[], values: unknown[], transaction?: SqlTransactionResource): Promise<QueryResult<T>>;
+    /** Run a multi-statement script. */
+    executeScript(sql: string): Promise<void>;
+    transaction<T>(cb: () => Promise<T>): Promise<T>;
+    /** Rows affected by a write, normalized across drivers. */
+    toRowCount(result: QueryResult<unknown>): number;
+}

package/dist/sql-connection.js

@@ -0,0 +1,4 @@
+/** ANSI identifier quoting (`"name"`), for the dialects that follow the standard. */
+export function quoteAnsiIdentifier(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}

package/dist/sql-migrations-controller.d.ts

@@ -1,5 +1,5 @@
 import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
-import type { SqlConnectionResource } from "./sql-connection-controller.js";
+import type { SqlConnection } from "./sql-connection.js";
 interface MigrationEntry {
     statement?: string;
     statements?: string[];
@@ -9,7 +9,7 @@ interface SqlMigrationsManifest {
         name: string;
         module: string;
     };
-    connection: SqlConnectionResource;
+    connection: SqlConnection;
     migrations?: Record<string, MigrationEntry>;
 }
 declare class SqlMigrationsResource implements ResourceInstance {

package/dist/sql-migrations-controller.js

@@ -50,6 +50,11 @@ class SqlMigrationsResource {
             }
             migrations[name] = statements;
         }
+        if (!conn.kysely) {
+            throw new Error(`Sql.Migrations '${this.manifest.metadata.name}': the referenced connection is not ` +
+                `built on kysely, which this kind's migration runner requires. Use a backend that ` +
+                `extends SqlConnectionBase, or run the statements through Sql.Command.`);
+        }
         const migrator = new Migrator({
             db: conn.kysely,
             provider: new TeloMigrationProvider(migrations),

package/dist/sql-query-controller.d.ts

@@ -1,12 +1,12 @@
 import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
-import type { SqlConnectionResource } from "./sql-connection-controller.js";
+import type { SqlConnection } from "./sql-connection.js";
 import type { SqlTransactionResource } from "./sql-transaction-controller.js";
 interface SqlQueryManifest {
     metadata: {
         name: string;
         module: string;
     };
-    connection?: SqlConnectionResource;
+    connection?: SqlConnection;
     transaction?: SqlTransactionResource;
     inputs: {
         sql: string;

package/dist/sql-run.d.ts

@@ -1,6 +1,6 @@
 import { type ResourceContext } from "@telorun/sdk";
 import type { QueryResult } from "kysely";
-import type { SqlConnectionResource } from "./sql-connection-controller.js";
+import type { SqlConnection } from "./sql-connection.js";
 import type { SqlTransactionResource } from "./sql-transaction-controller.js";
 /** Execute the `sql` input of a Query/Exec resource against `connection`.
  *
@@ -13,4 +13,4 @@ import type { SqlTransactionResource } from "./sql-transaction-controller.js";
  *
  *  Mixing a `!sql` template with `bindings` is rejected. A plain string `sql`
  *  with neither is executed verbatim. */
-export declare function runSql(connection: SqlConnectionResource, transaction: SqlTransactionResource | undefined, input: unknown, ctx: ResourceContext): Promise<QueryResult<Record<string, unknown>>>;
+export declare function runSql(connection: SqlConnection, transaction: SqlTransactionResource | undefined, input: unknown, ctx: ResourceContext): Promise<QueryResult<Record<string, unknown>>>;

package/dist/sql-selection-controller.d.ts

@@ -1,5 +1,5 @@
 import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
-import type { SqlConnectionResource } from "./sql-connection-controller.js";
+import type { SqlConnection } from "./sql-connection.js";
 import type { SqlResult } from "./sql-query-controller.js";
 import type { SqlTransactionResource } from "./sql-transaction-controller.js";
 type ColumnDef = string | {
@@ -44,7 +44,7 @@ interface SelectManifest {
         name: string;
         module: string;
     };
-    connection?: SqlConnectionResource;
+    connection?: SqlConnection;
     transaction?: SqlTransactionResource;
     from: string;
     columns?: ColumnDef[];

package/dist/sql-selection-controller.js

@@ -24,17 +24,19 @@ class SqlSelectionResource {
         if (!connection) {
             throw new Error("Sql.Selection: either 'connection' or 'transaction' must be set");
         }
-        const { sql, params } = buildSelect(m, where, having, limit, offset, connection.driver);
+        const { sql, params } = buildSelect(m, where, having, limit, offset, connection.dialect);
         const result = await connection.execute(sql, params, m.transaction);
         return { rows: result.rows, rowCount: result.rows.length };
     }
 }
-function buildSelect(m, where, having, limit, offset, driver) {
+// ── SQL building ──────────────────────────────────────────────────────────────
+function buildSelect(m, where, having, limit, offset, dialect) {
     const params = [];
     const addParam = (value) => {
         params.push(value);
-        return `$${params.length}`;
+        return dialect.placeholderStyle === "numbered" ? `$${params.length}` : "?";
     };
+    const quoteIdent = (name) => dialect.quoteIdentifier(name);
     const parts = [];
     // SELECT [DISTINCT [ON (...)]]
     let selectClause = "SELECT";
@@ -44,12 +46,12 @@ function buildSelect(m, where, having, limit, offset, driver) {
     else if (m.distinctOn && m.distinctOn.length > 0) {
         selectClause += ` DISTINCT ON (${m.distinctOn.map(quoteIdent).join(", ")})`;
     }
-    const colList = m.columns && m.columns.length > 0 ? buildColumns(m.columns) : "*";
+    const colList = m.columns && m.columns.length > 0 ? buildColumns(m.columns, dialect) : "*";
     parts.push(`${selectClause} ${colList}`);
     // FROM
     parts.push(`FROM ${quoteIdent(m.from)}`);
     // WHERE
-    const whereStr = buildClauses(where, "AND", driver, addParam);
+    const whereStr = buildClauses(where, "AND", dialect, addParam);
     if (whereStr)
         parts.push(`WHERE ${whereStr}`);
     // GROUP BY
@@ -57,7 +59,7 @@ function buildSelect(m, where, having, limit, offset, driver) {
         parts.push(`GROUP BY ${m.groupBy.map(quoteIdent).join(", ")}`);
     }
     // HAVING
-    const havingStr = buildClauses(having, "AND", driver, addParam);
+    const havingStr = buildClauses(having, "AND", dialect, addParam);
     if (havingStr)
         parts.push(`HAVING ${havingStr}`);
     // ORDER BY
@@ -72,7 +74,8 @@ function buildSelect(m, where, having, limit, offset, driver) {
         parts.push(`OFFSET ${addParam(offset)}`);
     return { sql: parts.join("\n"), params };
 }
-function buildColumns(columns) {
+function buildColumns(columns, dialect) {
+    const quoteIdent = (name) => dialect.quoteIdentifier(name);
     return columns
         .map((c) => {
         if (typeof c === "string")
@@ -83,12 +86,12 @@ function buildColumns(columns) {
     })
         .join(", ");
 }
-function buildClauses(clauses, join, driver, addParam) {
+function buildClauses(clauses, join, dialect, addParam) {
     const parts = [];
     for (const clause of clauses) {
         if (clause.when === false)
             continue;
-        const built = buildClause(clause, driver, addParam);
+        const built = buildClause(clause, dialect, addParam);
         if (built !== null)
             parts.push(built);
     }
@@ -98,43 +101,38 @@ function buildClauses(clauses, join, driver, addParam) {
         return parts[0];
     return parts.join(` ${join} `);
 }
-function buildClause(node, driver, addParam) {
+function buildClause(node, dialect, addParam) {
     if ("not" in node) {
-        const inner = buildClause(node.not, driver, addParam);
+        const inner = buildClause(node.not, dialect, addParam);
         return inner ? `NOT (${inner})` : null;
     }
     if ("or" in node) {
-        const inner = buildClauses(node.or, "OR", driver, addParam);
+        const inner = buildClauses(node.or, "OR", dialect, addParam);
         return inner ? `(${inner})` : null;
     }
     if ("and" in node) {
-        const inner = buildClauses(node.and, "AND", driver, addParam);
+        const inner = buildClauses(node.and, "AND", dialect, addParam);
         return inner ? `(${inner})` : null;
     }
     if ("sql" in node) {
         return renumberFragment(node.sql, node.bindings ?? [], addParam);
     }
     if ("column" in node) {
-        return buildCondition(node, driver, addParam);
+        return buildCondition(node, dialect, addParam);
     }
     return null;
 }
-function buildCondition(c, driver, addParam) {
-    const col = quoteIdent(c.column);
+function buildCondition(c, dialect, addParam) {
+    const col = dialect.quoteIdentifier(c.column);
     switch (c.op) {
         case "is_null":
             return `${col} IS NULL`;
         case "is_not_null":
             return `${col} IS NOT NULL`;
-        case "in": {
-            if (driver === "postgres") {
-                return `${col} = ANY(${addParam(c.value)})`;
-            }
-            const placeholders = c.value.map((v) => addParam(v)).join(", ");
-            return `${col} IN (${placeholders})`;
-        }
+        case "in":
+            return dialect.renderIn(col, c.value, addParam);
         default: {
-            const rhs = c.ref !== undefined ? quoteIdent(c.ref) : addParam(c.value);
+            const rhs = c.ref !== undefined ? dialect.quoteIdentifier(c.ref) : addParam(c.value);
             return `${col} ${opToSql(c.op)} ${rhs}`;
         }
     }
@@ -142,9 +140,6 @@ function buildCondition(c, driver, addParam) {
 function renumberFragment(sql, bindings, addParam) {
     return sql.replace(/\$(\d+)/g, (_, idx) => addParam(bindings[Number(idx) - 1]));
 }
-function quoteIdent(name) {
-    return `"${name.replace(/"/g, '""')}"`;
-}
 function opToSql(op) {
     const map = {
         eq: "=",

package/dist/sql-transaction-controller.d.ts

@@ -1,11 +1,11 @@
 import type { Invocable, ResourceContext, ResourceInstance } from "@telorun/sdk";
-import type { SqlConnectionResource } from "./sql-connection-controller.js";
+import type { SqlConnection } from "./sql-connection.js";
 interface SqlTransactionManifest {
     metadata: {
         name: string;
         module: string;
     };
-    connection: SqlConnectionResource;
+    connection: SqlConnection;
     steps: Invocable;
     inputs?: Record<string, unknown>;
 }
@@ -13,7 +13,7 @@ export declare class SqlTransactionResource implements ResourceInstance {
     private readonly manifest;
     private readonly ctx;
     constructor(manifest: SqlTransactionManifest, ctx: ResourceContext);
-    getConnection(): SqlConnectionResource;
+    getConnection(): SqlConnection;
     assertActive(): void;
     invoke(input: unknown): Promise<unknown>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/sql",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Telo SQL module - SQL database resource kinds for Telo manifests.",
   "keywords": [
     "telo",
@@ -30,11 +30,6 @@
       "bun": "./src/index.ts",
       "import": "./dist/index.js"
     },
-    "./connection": {
-      "types": "./dist/sql-connection-controller.d.ts",
-      "bun": "./src/sql-connection-controller.ts",
-      "import": "./dist/sql-connection-controller.js"
-    },
     "./sql-query": {
       "bun": "./src/sql-query-controller.ts",
       "import": "./dist/sql-query-controller.js"
@@ -70,7 +65,7 @@
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
-    "@telorun/sdk": "0.54.0"
+    "@telorun/sdk": "0.58.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/index.ts

@@ -1,8 +1,8 @@
+export { SqlConnectionBase } from "./sql-connection-base.js";
 export {
-  SqlConnectionResource,
-  createSqlConnection,
-  type SqlDriver,
+  quoteAnsiIdentifier,
   type PlaceholderStyle,
-} from "./sql-connection-controller.js";
+  type SqlConnection,
+  type SqlDialect,
+} from "./sql-connection.js";
 export { isSqlConnection, resolveSqlConnection } from "./sql-connection-ref.js";
-export type { SqliteDb, SqliteStatement } from "./sqlite-driver-interface.js";

package/src/sql-command-controller.ts

@@ -1,5 +1,5 @@
 import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
-import type { SqlConnectionResource } from "./sql-connection-controller.js";
+import type { SqlConnection } from "./sql-connection.js";
 import { resolveSqlConnection } from "./sql-connection-ref.js";
 import type { SqlResult } from "./sql-query-controller.js";
 import { runSql } from "./sql-run.js";
@@ -7,7 +7,7 @@ import type { SqlTransactionResource } from "./sql-transaction-controller.js";
 
 interface SqlCommandManifest {
   metadata: { name: string; module: string };
-  connection?: SqlConnectionResource;
+  connection?: SqlConnection;
   transaction?: SqlTransactionResource;
   inputs: {
     sql: string;

package/src/{sql-connection-controller.ts → sql-connection-base.ts}

@@ -1,37 +1,32 @@
-import type { ResourceInstance } from "@telorun/sdk";
 import { randomUUID } from "crypto";
-import { CompiledQuery, Kysely, type QueryResult, type Transaction } from "kysely";
+import { CompiledQuery, type Kysely, type QueryResult, type Transaction } from "kysely";
+import type { SqlConnection, SqlDialect } from "./sql-connection.js";
 import type { SqlTransactionResource } from "./sql-transaction-controller.js";
-import type { SqliteDb } from "./sqlite-driver-interface.js";
 import { currentTxId, deleteTx, getTx, setTx, txStorage } from "./transaction-store.js";
 
-export type SqlDriver = "postgres" | "sqlite";
-
-/** Native bind-placeholder syntax per driver: SQLite binds anonymous `?`,
- *  PostgreSQL binds numbered `$1`, `$2`, … */
-export type PlaceholderStyle = "qmark" | "numbered";
-
 /**
- * Driver-agnostic SQL connection. The kysely instance (and, for SQLite, the
- * underlying database handle used by `executeScript`) is built by the driver
- * backend (`sql-postgres`, `sql-sqlite`) and handed in via
- * {@link createSqlConnection}. Everything here — execution, transactions,
- * placeholder style, row-count normalization — is transport-neutral.
+ * The dialect-neutral half of a connection: statement execution, transaction
+ * scoping, template binding and row-count normalization over a kysely instance.
+ *
+ * Backends extend it, supply their {@link SqlDialect}, and override only what is
+ * genuinely theirs — `teardown` for resources kysely does not own, `executeScript`
+ * where the driver has a native multi-statement path.
  */
-export class SqlConnectionResource implements ResourceInstance {
-  private readonly db: Kysely<any>;
-  private readonly sqlite?: SqliteDb;
+export abstract class SqlConnectionBase implements SqlConnection {
+  protected readonly db: Kysely<any>;
 
   constructor(
-    readonly driver: SqlDriver,
     db: Kysely<any>,
-    sqlite?: SqliteDb,
+    readonly dialect: SqlDialect,
   ) {
     this.db = db;
-    this.sqlite = sqlite;
   }
 
-  async init() {
+  get kysely(): Kysely<any> {
+    return this.db;
+  }
+
+  async init(): Promise<void> {
     await this.db.connection().execute(async () => {
       // just checking
     });
@@ -63,13 +58,6 @@ export class SqlConnectionResource implements ResourceInstance {
     return executor.executeQuery<T>(CompiledQuery.raw(sql, params));
   }
 
-  get placeholderStyle(): PlaceholderStyle {
-    return this.driver === "postgres" ? "numbered" : "qmark";
-  }
-
-  /** Assemble SQL from literal fragments by interleaving driver-native
-   *  placeholders, then bind `values` positionally. `fragments.length` must
-   *  equal `values.length + 1`. */
   async executeTemplate<T>(
     fragments: string[],
     values: unknown[],
@@ -82,16 +70,9 @@ export class SqlConnectionResource implements ResourceInstance {
     return this.execute<T>(sql, values, transaction);
   }
 
-  private placeholder(index: number): string {
-    return this.placeholderStyle === "numbered" ? `$${index}` : "?";
-  }
-
+  /** Hand the whole script to the driver as one statement. Backends whose driver
+   *  needs a dedicated multi-statement entry point override this. */
   async executeScript(sql: string): Promise<void> {
-    if (this.driver === "sqlite") {
-      this.sqlite?.exec(sql);
-      return;
-    }
-
     await this.execute(sql);
   }
 
@@ -103,14 +84,14 @@ export class SqlConnectionResource implements ResourceInstance {
     return result.rows.length;
   }
 
-  get kysely(): Kysely<any> {
-    return this.db;
-  }
-
   snapshot(): Record<string, unknown> {
     return {};
   }
 
+  private placeholder(index: number): string {
+    return this.dialect.placeholderStyle === "numbered" ? `$${index}` : "?";
+  }
+
   private resolveExecutor(transaction?: SqlTransactionResource): Kysely<any> {
     if (transaction) {
       transaction.assertActive();
@@ -127,17 +108,3 @@ export class SqlConnectionResource implements ResourceInstance {
     return this.db;
   }
 }
-
-/**
- * Build a connection from a driver-constructed kysely instance. Driver backends
- * (`sql-postgres`, `sql-sqlite`) own dialect construction and call this; the
- * `sqlite` handle is required only for SQLite (its `executeScript` runs through
- * the native handle).
- */
-export function createSqlConnection(
-  driver: SqlDriver,
-  db: Kysely<any>,
-  sqlite?: SqliteDb,
-): SqlConnectionResource {
-  return new SqlConnectionResource(driver, db, sqlite);
-}

package/src/sql-connection-ref.ts

@@ -1,9 +1,9 @@
 import type { KindRef, ResourceContext } from "@telorun/sdk";
-import type { SqlConnectionResource } from "./sql-connection-controller.js";
+import type { SqlConnection } from "./sql-connection.js";
 
 /** True when a value already exposes the connection contract (Phase-5 injected). */
-export function isSqlConnection(value: unknown): value is SqlConnectionResource {
-  return typeof (value as SqlConnectionResource | undefined)?.execute === "function";
+export function isSqlConnection(value: unknown): value is SqlConnection {
+  return typeof (value as SqlConnection | undefined)?.execute === "function";
 }
 
 /**
@@ -13,10 +13,10 @@ export function isSqlConnection(value: unknown): value is SqlConnectionResource
  * slot, so the failure points at a concrete manifest location.
  */
 export function resolveSqlConnection(
-  value: SqlConnectionResource | KindRef<SqlConnectionResource> | undefined,
+  value: SqlConnection | KindRef<SqlConnection> | undefined,
   ctx: ResourceContext,
   describe: () => string,
-): SqlConnectionResource | undefined {
+): SqlConnection | undefined {
   if (!value) return undefined;
   return ctx.resolveRef(value, isSqlConnection, describe, "std/sql#Connection");
 }

package/src/sql-connection.ts

@@ -0,0 +1,71 @@
+import type { ResourceInstance } from "@telorun/sdk";
+import type { Kysely, QueryResult } from "kysely";
+import type { SqlTransactionResource } from "./sql-transaction-controller.js";
+
+/** Native bind-placeholder syntax: SQLite binds anonymous `?`, PostgreSQL binds
+ *  numbered `$1`, `$2`, … */
+export type PlaceholderStyle = "qmark" | "numbered";
+
+/**
+ * Renders the SQL constructs that differ between database dialects. A backend
+ * supplies one; the `Sql.*` operations build statements through it and never
+ * branch on which database sits behind the connection.
+ */
+export interface SqlDialect {
+  readonly placeholderStyle: PlaceholderStyle;
+
+  /** Quote an identifier — table, column, alias. */
+  quoteIdentifier(name: string): string;
+
+  /** Render set membership. Dialects disagree: PostgreSQL binds the whole array
+   *  to a single placeholder, SQLite binds one per element. `column` arrives
+   *  already quoted. */
+  renderIn(
+    column: string,
+    values: unknown[],
+    addParam: (value: unknown) => string,
+  ): string;
+}
+
+/** ANSI identifier quoting (`"name"`), for the dialects that follow the standard. */
+export function quoteAnsiIdentifier(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+
+/**
+ * The contract every SQL backend satisfies and every `Sql.*` operation programs
+ * against. Backends (`sql-postgres`, `sql-sqlite`) own their own implementation
+ * — usually by extending {@link SqlConnectionBase} — so nothing in this module
+ * knows which databases exist.
+ */
+export interface SqlConnection extends ResourceInstance {
+  readonly dialect: SqlDialect;
+
+  /** The underlying kysely instance, when the backend is built on one —
+   *  {@link SqlConnectionBase} always provides it. Optional because the contract
+   *  must stay implementable by a driver kysely does not support; a consumer
+   *  that needs it (`Sql.Migrations`) checks and fails with a clear message. */
+  readonly kysely?: Kysely<any>;
+
+  execute<T>(
+    sql: string,
+    params?: unknown[],
+    transaction?: SqlTransactionResource,
+  ): Promise<QueryResult<T>>;
+
+  /** Assemble SQL from literal fragments by interleaving dialect-native
+   *  placeholders, then bind `values` positionally. */
+  executeTemplate<T>(
+    fragments: string[],
+    values: unknown[],
+    transaction?: SqlTransactionResource,
+  ): Promise<QueryResult<T>>;
+
+  /** Run a multi-statement script. */
+  executeScript(sql: string): Promise<void>;
+
+  transaction<T>(cb: () => Promise<T>): Promise<T>;
+
+  /** Rows affected by a write, normalized across drivers. */
+  toRowCount(result: QueryResult<unknown>): number;
+}

package/src/sql-migrations-controller.ts

@@ -6,7 +6,7 @@ import {
   type Migration,
   type MigrationProvider,
 } from "kysely";
-import type { SqlConnectionResource } from "./sql-connection-controller.js";
+import type { SqlConnection } from "./sql-connection.js";
 import { resolveSqlConnection } from "./sql-connection-ref.js";
 
 // A migration entry is one statement or an ordered list of statements; both
@@ -18,7 +18,7 @@ interface MigrationEntry {
 
 interface SqlMigrationsManifest {
   metadata: { name: string; module: string };
-  connection: SqlConnectionResource;
+  connection: SqlConnection;
   migrations?: Record<string, MigrationEntry>;
 }
 
@@ -82,6 +82,14 @@ class SqlMigrationsResource implements ResourceInstance {
       migrations[name] = statements;
     }
 
+    if (!conn.kysely) {
+      throw new Error(
+        `Sql.Migrations '${this.manifest.metadata.name}': the referenced connection is not ` +
+          `built on kysely, which this kind's migration runner requires. Use a backend that ` +
+          `extends SqlConnectionBase, or run the statements through Sql.Command.`,
+      );
+    }
+
     const migrator = new Migrator({
       db: conn.kysely,
       provider: new TeloMigrationProvider(migrations),

package/src/sql-query-controller.ts

@@ -1,12 +1,12 @@
 import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
-import type { SqlConnectionResource } from "./sql-connection-controller.js";
+import type { SqlConnection } from "./sql-connection.js";
 import { resolveSqlConnection } from "./sql-connection-ref.js";
 import { runSql } from "./sql-run.js";
 import type { SqlTransactionResource } from "./sql-transaction-controller.js";
 
 interface SqlQueryManifest {
   metadata: { name: string; module: string };
-  connection?: SqlConnectionResource;
+  connection?: SqlConnection;
   transaction?: SqlTransactionResource;
   inputs: {
     sql: string;
@@ -40,11 +40,11 @@ class SqlQueryResource implements ResourceInstance {
 }
 
 function resolveConnection(
-  connection: SqlConnectionResource | undefined,
+  connection: SqlConnection | undefined,
   transaction: SqlTransactionResource | undefined,
   ctx: ResourceContext,
   describe: () => string,
-): SqlConnectionResource {
+): SqlConnection {
   return (
     resolveSqlConnection(connection, ctx, describe) ??
     transaction?.getConnection() ??

package/src/sql-run.ts

@@ -1,6 +1,6 @@
 import { InvokeError, isParameterizedSql, type ResourceContext } from "@telorun/sdk";
 import type { QueryResult } from "kysely";
-import type { SqlConnectionResource } from "./sql-connection-controller.js";
+import type { SqlConnection } from "./sql-connection.js";
 import type { SqlTransactionResource } from "./sql-transaction-controller.js";
 
 /** Execute the `sql` input of a Query/Exec resource against `connection`.
@@ -15,7 +15,7 @@ import type { SqlTransactionResource } from "./sql-transaction-controller.js";
  *  Mixing a `!sql` template with `bindings` is rejected. A plain string `sql`
  *  with neither is executed verbatim. */
 export async function runSql(
-  connection: SqlConnectionResource,
+  connection: SqlConnection,
   transaction: SqlTransactionResource | undefined,
   input: unknown,
   ctx: ResourceContext,

package/src/sql-selection-controller.ts

@@ -1,5 +1,5 @@
 import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
-import type { SqlConnectionResource } from "./sql-connection-controller.js";
+import type { SqlConnection, SqlDialect } from "./sql-connection.js";
 import { resolveSqlConnection } from "./sql-connection-ref.js";
 import type { SqlResult } from "./sql-query-controller.js";
 import type { SqlTransactionResource } from "./sql-transaction-controller.js";
@@ -59,7 +59,7 @@ interface OrderByItem {
 
 interface SelectManifest {
   metadata: { name: string; module: string };
-  connection?: SqlConnectionResource;
+  connection?: SqlConnection;
   transaction?: SqlTransactionResource;
   from: string;
   columns?: ColumnDef[];
@@ -103,7 +103,7 @@ class SqlSelectionResource implements ResourceInstance {
       throw new Error("Sql.Selection: either 'connection' or 'transaction' must be set");
     }
 
-    const { sql, params } = buildSelect(m, where, having, limit, offset, connection.driver);
+    const { sql, params } = buildSelect(m, where, having, limit, offset, connection.dialect);
     const result = await connection.execute<Record<string, unknown>>(sql, params, m.transaction);
     return { rows: result.rows, rowCount: result.rows.length };
   }
@@ -111,21 +111,20 @@ class SqlSelectionResource implements ResourceInstance {
 
 // ── SQL building ──────────────────────────────────────────────────────────────
 
-type Driver = "postgres" | "sqlite";
-
 function buildSelect(
   m: SelectManifest,
   where: WhereNode[],
   having: WhereNode[],
   limit: unknown,
   offset: unknown,
-  driver: Driver,
+  dialect: SqlDialect,
 ): { sql: string; params: unknown[] } {
   const params: unknown[] = [];
   const addParam = (value: unknown): string => {
     params.push(value);
-    return `$${params.length}`;
+    return dialect.placeholderStyle === "numbered" ? `$${params.length}` : "?";
   };
+  const quoteIdent = (name: string): string => dialect.quoteIdentifier(name);
 
   const parts: string[] = [];
 
@@ -136,14 +135,14 @@ function buildSelect(
   } else if (m.distinctOn && m.distinctOn.length > 0) {
     selectClause += ` DISTINCT ON (${m.distinctOn.map(quoteIdent).join(", ")})`;
   }
-  const colList = m.columns && m.columns.length > 0 ? buildColumns(m.columns) : "*";
+  const colList = m.columns && m.columns.length > 0 ? buildColumns(m.columns, dialect) : "*";
   parts.push(`${selectClause} ${colList}`);
 
   // FROM
   parts.push(`FROM ${quoteIdent(m.from)}`);
 
   // WHERE
-  const whereStr = buildClauses(where, "AND", driver, addParam);
+  const whereStr = buildClauses(where, "AND", dialect, addParam);
   if (whereStr) parts.push(`WHERE ${whereStr}`);
 
   // GROUP BY
@@ -152,7 +151,7 @@ function buildSelect(
   }
 
   // HAVING
-  const havingStr = buildClauses(having, "AND", driver, addParam);
+  const havingStr = buildClauses(having, "AND", dialect, addParam);
   if (havingStr) parts.push(`HAVING ${havingStr}`);
 
   // ORDER BY
@@ -170,7 +169,8 @@ function buildSelect(
   return { sql: parts.join("\n"), params };
 }
 
-function buildColumns(columns: ColumnDef[]): string {
+function buildColumns(columns: ColumnDef[], dialect: SqlDialect): string {
+  const quoteIdent = (name: string): string => dialect.quoteIdentifier(name);
   return columns
     .map((c) => {
       if (typeof c === "string") return quoteIdent(c);
@@ -183,13 +183,13 @@ function buildColumns(columns: ColumnDef[]): string {
 function buildClauses(
   clauses: WhereNode[],
   join: "AND" | "OR",
-  driver: Driver,
+  dialect: SqlDialect,
   addParam: (v: unknown) => string,
 ): string | null {
   const parts: string[] = [];
   for (const clause of clauses) {
     if (clause.when === false) continue;
-    const built = buildClause(clause, driver, addParam);
+    const built = buildClause(clause, dialect, addParam);
     if (built !== null) parts.push(built);
   }
   if (parts.length === 0) return null;
@@ -199,46 +199,45 @@ function buildClauses(
 
 function buildClause(
   node: WhereNode,
-  driver: Driver,
+  dialect: SqlDialect,
   addParam: (v: unknown) => string,
 ): string | null {
   if ("not" in node) {
-    const inner = buildClause(node.not, driver, addParam);
+    const inner = buildClause(node.not, dialect, addParam);
     return inner ? `NOT (${inner})` : null;
   }
   if ("or" in node) {
-    const inner = buildClauses(node.or, "OR", driver, addParam);
+    const inner = buildClauses(node.or, "OR", dialect, addParam);
     return inner ? `(${inner})` : null;
   }
   if ("and" in node) {
-    const inner = buildClauses(node.and, "AND", driver, addParam);
+    const inner = buildClauses(node.and, "AND", dialect, addParam);
     return inner ? `(${inner})` : null;
   }
   if ("sql" in node) {
     return renumberFragment(node.sql, node.bindings ?? [], addParam);
   }
   if ("column" in node) {
-    return buildCondition(node, driver, addParam);
+    return buildCondition(node, dialect, addParam);
   }
   return null;
 }
 
-function buildCondition(c: Condition, driver: Driver, addParam: (v: unknown) => string): string {
-  const col = quoteIdent(c.column);
+function buildCondition(
+  c: Condition,
+  dialect: SqlDialect,
+  addParam: (v: unknown) => string,
+): string {
+  const col = dialect.quoteIdentifier(c.column);
   switch (c.op) {
     case "is_null":
       return `${col} IS NULL`;
     case "is_not_null":
       return `${col} IS NOT NULL`;
-    case "in": {
-      if (driver === "postgres") {
-        return `${col} = ANY(${addParam(c.value)})`;
-      }
-      const placeholders = (c.value as unknown[]).map((v) => addParam(v)).join(", ");
-      return `${col} IN (${placeholders})`;
-    }
+    case "in":
+      return dialect.renderIn(col, c.value as unknown[], addParam);
     default: {
-      const rhs = c.ref !== undefined ? quoteIdent(c.ref) : addParam(c.value);
+      const rhs = c.ref !== undefined ? dialect.quoteIdentifier(c.ref) : addParam(c.value);
       return `${col} ${opToSql(c.op)} ${rhs}`;
     }
   }
@@ -252,10 +251,6 @@ function renumberFragment(
   return sql.replace(/\$(\d+)/g, (_, idx) => addParam(bindings[Number(idx) - 1]));
 }
 
-function quoteIdent(name: string): string {
-  return `"${name.replace(/"/g, '""')}"`;
-}
-
 function opToSql(op: Op): string {
   const map: Record<string, string> = {
     eq: "=",

package/src/sql-transaction-controller.ts

@@ -1,11 +1,11 @@
 import type { Invocable, ResourceContext, ResourceInstance } from "@telorun/sdk";
-import type { SqlConnectionResource } from "./sql-connection-controller.js";
+import type { SqlConnection } from "./sql-connection.js";
 import { resolveSqlConnection } from "./sql-connection-ref.js";
 import { currentTxId } from "./transaction-store.js";
 
 interface SqlTransactionManifest {
   metadata: { name: string; module: string };
-  connection: SqlConnectionResource;
+  connection: SqlConnection;
   steps: Invocable;
   inputs?: Record<string, unknown>;
 }
@@ -16,7 +16,7 @@ export class SqlTransactionResource implements ResourceInstance {
     private readonly ctx: ResourceContext,
   ) {}
 
-  getConnection(): SqlConnectionResource {
+  getConnection(): SqlConnection {
     return (
       resolveSqlConnection(
         this.manifest.connection,

package/dist/sql-connection-controller.d.ts

@@ -1,43 +0,0 @@
-import type { ResourceInstance } from "@telorun/sdk";
-import { Kysely, type QueryResult } from "kysely";
-import type { SqlTransactionResource } from "./sql-transaction-controller.js";
-import type { SqliteDb } from "./sqlite-driver-interface.js";
-export type SqlDriver = "postgres" | "sqlite";
-/** Native bind-placeholder syntax per driver: SQLite binds anonymous `?`,
- *  PostgreSQL binds numbered `$1`, `$2`, … */
-export type PlaceholderStyle = "qmark" | "numbered";
-/**
- * Driver-agnostic SQL connection. The kysely instance (and, for SQLite, the
- * underlying database handle used by `executeScript`) is built by the driver
- * backend (`sql-postgres`, `sql-sqlite`) and handed in via
- * {@link createSqlConnection}. Everything here — execution, transactions,
- * placeholder style, row-count normalization — is transport-neutral.
- */
-export declare class SqlConnectionResource implements ResourceInstance {
-    readonly driver: SqlDriver;
-    private readonly db;
-    private readonly sqlite?;
-    constructor(driver: SqlDriver, db: Kysely<any>, sqlite?: SqliteDb);
-    init(): Promise<void>;
-    teardown(): Promise<void>;
-    transaction<T>(cb: () => Promise<T>): Promise<T>;
-    execute<T>(sql: string, params?: unknown[], transaction?: SqlTransactionResource): Promise<QueryResult<T>>;
-    get placeholderStyle(): PlaceholderStyle;
-    /** Assemble SQL from literal fragments by interleaving driver-native
-     *  placeholders, then bind `values` positionally. `fragments.length` must
-     *  equal `values.length + 1`. */
-    executeTemplate<T>(fragments: string[], values: unknown[], transaction?: SqlTransactionResource): Promise<QueryResult<T>>;
-    private placeholder;
-    executeScript(sql: string): Promise<void>;
-    toRowCount(result: QueryResult<unknown>): number;
-    get kysely(): Kysely<any>;
-    snapshot(): Record<string, unknown>;
-    private resolveExecutor;
-}
-/**
- * Build a connection from a driver-constructed kysely instance. Driver backends
- * (`sql-postgres`, `sql-sqlite`) own dialect construction and call this; the
- * `sqlite` handle is required only for SQLite (its `executeScript` runs through
- * the native handle).
- */
-export declare function createSqlConnection(driver: SqlDriver, db: Kysely<any>, sqlite?: SqliteDb): SqlConnectionResource;

package/dist/sqlite-driver-interface.d.ts

@@ -1,14 +0,0 @@
-export interface SqliteStatement {
-    readonly reader: boolean;
-    all(params: ReadonlyArray<unknown>): unknown[];
-    run(params: ReadonlyArray<unknown>): {
-        changes: number | bigint;
-        lastInsertRowid: number | bigint;
-    };
-    iterate(params: ReadonlyArray<unknown>): IterableIterator<unknown>;
-}
-export interface SqliteDb {
-    prepare(sql: string): SqliteStatement;
-    exec(sql: string): void;
-    close(): void;
-}

package/dist/sqlite-driver-interface.js

@@ -1 +0,0 @@
-export {};

package/src/sqlite-driver-interface.ts

@@ -1,15 +0,0 @@
-export interface SqliteStatement {
-  readonly reader: boolean;
-  all(params: ReadonlyArray<unknown>): unknown[];
-  run(params: ReadonlyArray<unknown>): {
-    changes: number | bigint;
-    lastInsertRowid: number | bigint;
-  };
-  iterate(params: ReadonlyArray<unknown>): IterableIterator<unknown>;
-}
-
-export interface SqliteDb {
-  prepare(sql: string): SqliteStatement;
-  exec(sql: string): void;
-  close(): void;
-}