@telorun/sql 0.6.0 → 0.7.0

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

@@ -1,4 +1,4 @@
-import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+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";
@@ -8,30 +8,36 @@ interface PoolConfig {
     idleTimeoutMs?: number;
     connectionTimeoutMs?: number;
 }
-interface SqlConnectionManifest {
-    metadata: {
-        name: string;
-        module: string;
-    };
-    connectionString: string;
+export type SqlDriver = "postgres" | "sqlite";
+/** Native bind-placeholder syntax per driver: SQLite binds anonymous `?`,
+ *  PostgreSQL binds numbered `$1`, `$2`, … */
+export type PlaceholderStyle = "qmark" | "numbered";
+export interface SqlConnectionConfig {
+    driver: SqlDriver;
+    /** Required for `postgres`; ignored for `sqlite` (which opens via `sqlite`). */
+    connectionString?: string;
     pool?: PoolConfig;
 }
-export type SqlDriver = "postgres" | "sqlite";
 export declare class SqlConnectionResource implements ResourceInstance {
     readonly driver: SqlDriver;
     private readonly db;
     private readonly sqlite?;
-    constructor(m: SqlConnectionManifest, sqlite?: SqliteDb);
+    constructor(config: SqlConnectionConfig, 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;
 }
-export declare function register(): void;
-export declare function create(resource: SqlConnectionManifest, ctx: ResourceContext): Promise<SqlConnectionResource>;
+export declare function openSqliteDatabase(file?: string): Promise<SqliteDb>;
 export {};

package/dist/sql-connection-controller.js

@@ -6,10 +6,13 @@ export class SqlConnectionResource {
     driver;
     db;
     sqlite;
-    constructor(m, sqlite) {
-        this.driver = driverFromConnectionString(m.connectionString);
+    constructor(config, sqlite) {
+        this.driver = config.driver;
         if (this.driver === "postgres") {
-            const url = new URL(m.connectionString);
+            if (!config.connectionString) {
+                throw new Error("Sql: postgres connection requires a connectionString");
+            }
+            const url = new URL(config.connectionString);
             const ssl = sslFromSslmode(url.searchParams.get("sslmode"));
             url.searchParams.delete("sslmode");
             this.db = new Kysely({
@@ -17,10 +20,10 @@ export class SqlConnectionResource {
                     pool: new Pool({
                         connectionString: url.toString(),
                         ssl,
-                        min: m.pool?.min ?? 1,
-                        max: m.pool?.max ?? 10,
-                        idleTimeoutMillis: m.pool?.idleTimeoutMs,
-                        connectionTimeoutMillis: m.pool?.connectionTimeoutMs,
+                        min: config.pool?.min ?? 1,
+                        max: config.pool?.max ?? 10,
+                        idleTimeoutMillis: config.pool?.idleTimeoutMs,
+                        connectionTimeoutMillis: config.pool?.connectionTimeoutMs,
                     }),
                 }),
             });
@@ -61,6 +64,22 @@ 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++) {
+            sql += this.placeholder(i) + fragments[i];
+        }
+        return this.execute(sql, values, transaction);
+    }
+    placeholder(index) {
+        return this.placeholderStyle === "numbered" ? `$${index}` : "?";
+    }
     async executeScript(sql) {
         if (this.driver === "sqlite") {
             this.sqlite?.exec(sql);
@@ -108,32 +127,6 @@ class TransactionalSqliteDialect extends SqliteDialect {
         return new TransactionalSqliteAdapter();
     }
 }
-export function register() { }
-export async function create(resource, ctx) {
-    const sqlite = driverFromConnectionString(resource.connectionString) === "sqlite"
-        ? await openSqliteDatabase(sqliteTargetFromConnectionString(resource.connectionString))
-        : undefined;
-    return new SqlConnectionResource(resource, sqlite);
-}
-function driverFromConnectionString(connectionString) {
-    const scheme = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(connectionString)?.[1]?.toLowerCase();
-    switch (scheme) {
-        case "postgres":
-        case "postgresql":
-            return "postgres";
-        case "sqlite":
-            return "sqlite";
-        default:
-            throw new Error(`Sql.Connection: connectionString must start with a driver scheme — ` +
-                `'postgres://' or 'postgresql://' for PostgreSQL, 'sqlite:' for SQLite. ` +
-                `Got ${scheme ? `'${scheme}:'` : "a string with no scheme"}: ${JSON.stringify(connectionString)}`);
-    }
-}
-function sqliteTargetFromConnectionString(connectionString) {
-    const path = decodeURIComponent(new URL(connectionString).pathname);
-    // `sqlite:` / `sqlite://` with no path resolves to an in-memory database.
-    return path === "" || path === "/" ? ":memory:" : path;
-}
 function sslFromSslmode(mode) {
     switch (mode) {
         case null:
@@ -152,7 +145,7 @@ function sslFromSslmode(mode) {
                 `Use 'disable', 'require', 'verify-ca', or 'verify-full'.`);
     }
 }
-async function openSqliteDatabase(file = ":memory:") {
+export async function openSqliteDatabase(file = ":memory:") {
     // Auto-create the parent directory for file-backed databases. SQLite
     // drivers fail-fast when the directory doesn't exist; mirroring `mkdir
     // -p` here lets manifests use paths like `./tmp/foo.sqlite` without a

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

@@ -18,7 +18,7 @@ declare class SqlExecResource implements ResourceInstance {
     private readonly manifest;
     private readonly ctx;
     constructor(manifest: SqlExecManifest, ctx: ResourceContext);
-    invoke(input: any): Promise<SqlResult>;
+    invoke(input: unknown): Promise<SqlResult>;
 }
 export declare function register(): void;
 export declare function create(resource: SqlExecManifest, ctx: ResourceContext): Promise<SqlExecResource>;

package/dist/sql-exec-controller.js

@@ -1,4 +1,5 @@
 import { resolveSqlConnection } from "./sql-connection-ref.js";
+import { runSql } from "./sql-run.js";
 class SqlExecResource {
     manifest;
     ctx;
@@ -9,18 +10,14 @@ class SqlExecResource {
     async invoke(input) {
         const m = this.manifest;
         const ctx = this.ctx;
-        const expandedInput = ctx.expandValue(input, {});
         const connection = resolveSqlConnection(m.connection, ctx) ?? m.transaction?.getConnection();
         if (!connection) {
             throw new Error("Sql: either 'connection' or 'transaction' must be set");
         }
-        return runExec(connection, m.transaction, expandedInput.sql, expandedInput.bindings ?? []);
+        const result = await runSql(connection, m.transaction, input, ctx);
+        return { rows: result.rows, rowCount: connection.toRowCount(result) };
     }
 }
-async function runExec(connection, transaction, sql, params) {
-    const result = await connection.execute(sql, params, transaction);
-    return { rows: result.rows, rowCount: connection.toRowCount(result) };
-}
 export function register() { }
 export async function create(resource, ctx) {
     return new SqlExecResource(resource, ctx);

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

@@ -0,0 +1,19 @@
+import type { ResourceContext } from "@telorun/sdk";
+import { SqlConnectionResource } from "./sql-connection-controller.js";
+interface PoolConfig {
+    min?: number;
+    max?: number;
+    idleTimeoutMs?: number;
+    connectionTimeoutMs?: number;
+}
+interface PostgresConnectionManifest {
+    metadata: {
+        name: string;
+        module: string;
+    };
+    connectionString: string;
+    pool?: PoolConfig;
+}
+export declare function register(): void;
+export declare function create(resource: PostgresConnectionManifest, ctx: ResourceContext): Promise<SqlConnectionResource>;
+export {};

package/dist/sql-postgres-connection-controller.js

@@ -0,0 +1,9 @@
+import { SqlConnectionResource } from "./sql-connection-controller.js";
+export function register() { }
+export async function create(resource, ctx) {
+    return new SqlConnectionResource({
+        driver: "postgres",
+        connectionString: resource.connectionString,
+        pool: resource.pool,
+    });
+}

package/dist/sql-query-controller.js

@@ -1,4 +1,5 @@
 import { resolveSqlConnection } from "./sql-connection-ref.js";
+import { runSql } from "./sql-run.js";
 class SqlQueryResource {
     manifest;
     ctx;
@@ -9,18 +10,14 @@ class SqlQueryResource {
     async invoke(input) {
         const m = this.manifest;
         const ctx = this.ctx;
-        const expandedInput = ctx.expandValue(input, {});
         const connection = resolveConnection(m.connection, m.transaction, ctx);
-        return runQuery(connection, m.transaction, expandedInput.sql, expandedInput.bindings);
+        const result = await runSql(connection, m.transaction, input, ctx);
+        return { rows: result.rows, rowCount: result.rows.length };
     }
 }
 function resolveConnection(connection, transaction, ctx) {
     return (resolveSqlConnection(connection, ctx) ?? transaction?.getConnection() ?? failMissingConnection());
 }
-async function runQuery(connection, transaction, sql, params) {
-    const result = await connection.execute(sql, params, transaction);
-    return { rows: result.rows, rowCount: result.rows.length };
-}
 function failMissingConnection() {
     throw new Error("Sql: either 'connection' or 'transaction' must be set");
 }

package/dist/sql-run.d.ts

@@ -0,0 +1,16 @@
+import { type ResourceContext } from "@telorun/sdk";
+import type { QueryResult } from "kysely";
+import type { SqlConnectionResource } from "./sql-connection-controller.js";
+import type { SqlTransactionResource } from "./sql-transaction-controller.js";
+/** Execute the `sql` input of a Query/Exec resource against `connection`.
+ *
+ *  Two modes:
+ *  - **inline (`!sql` tag):** the expanded `sql` is a parameterized template —
+ *    each `${{ }}` is bound via the connection's native placeholder, never
+ *    spliced into the text.
+ *  - **escape hatch (`bindings` given):** `sql` is a literal string with
+ *    author-written `?` / `$n` placeholders and `bindings` bound positionally.
+ *
+ *  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>>>;

package/dist/sql-run.js

@@ -0,0 +1,27 @@
+import { InvokeError, isParameterizedSql } from "@telorun/sdk";
+/** Execute the `sql` input of a Query/Exec resource against `connection`.
+ *
+ *  Two modes:
+ *  - **inline (`!sql` tag):** the expanded `sql` is a parameterized template —
+ *    each `${{ }}` is bound via the connection's native placeholder, never
+ *    spliced into the text.
+ *  - **escape hatch (`bindings` given):** `sql` is a literal string with
+ *    author-written `?` / `$n` placeholders and `bindings` bound positionally.
+ *
+ *  Mixing a `!sql` template with `bindings` is rejected. A plain string `sql`
+ *  with neither is executed verbatim. */
+export async function runSql(connection, transaction, input, ctx) {
+    const expanded = ctx.expandValue(input, {});
+    const sql = expanded.sql;
+    const bindings = expanded.bindings;
+    const hasBindings = bindings !== undefined && bindings !== null;
+    if (isParameterizedSql(sql)) {
+        if (hasBindings) {
+            throw new InvokeError("ERR_INVALID_INPUT", "Sql: a `!sql` template cannot be combined with an explicit `bindings` array. " +
+                "Use one or the other — `!sql` binds each inline value automatically; " +
+                "`bindings` is for hand-written ? / $n placeholders.");
+        }
+        return connection.executeTemplate(sql.fragments, sql.values, transaction);
+    }
+    return connection.execute(sql, hasBindings ? bindings : [], transaction);
+}

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

@@ -0,0 +1,13 @@
+import type { ResourceContext } from "@telorun/sdk";
+import { SqlConnectionResource } from "./sql-connection-controller.js";
+interface SqliteConnectionManifest {
+    metadata: {
+        name: string;
+        module: string;
+    };
+    /** File path, or omitted / `:memory:` for an in-memory database. */
+    file?: string;
+}
+export declare function register(): void;
+export declare function create(resource: SqliteConnectionManifest, ctx: ResourceContext): Promise<SqlConnectionResource>;
+export {};

package/dist/sql-sqlite-connection-controller.js

@@ -0,0 +1,6 @@
+import { openSqliteDatabase, SqlConnectionResource } from "./sql-connection-controller.js";
+export function register() { }
+export async function create(resource, ctx) {
+    const sqlite = await openSqliteDatabase(resource.file ?? ":memory:");
+    return new SqlConnectionResource({ driver: "sqlite" }, sqlite);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/sql",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Telo SQL module - SQL database resource kinds for Telo manifests.",
   "keywords": [
     "telo",
@@ -22,9 +22,13 @@
   },
   "type": "module",
   "exports": {
-    "./sql-connection": {
-      "bun": "./src/sql-connection-controller.ts",
-      "import": "./dist/sql-connection-controller.js"
+    "./sql-postgres-connection": {
+      "bun": "./src/sql-postgres-connection-controller.ts",
+      "import": "./dist/sql-postgres-connection-controller.js"
+    },
+    "./sql-sqlite-connection": {
+      "bun": "./src/sql-sqlite-connection-controller.ts",
+      "import": "./dist/sql-sqlite-connection-controller.js"
     },
     "./sql-query": {
       "bun": "./src/sql-query-controller.ts",
@@ -70,7 +74,7 @@
     "@types/node": "^20.0.0",
     "@types/pg": "^8.0.0",
     "typescript": "^5.0.0",
-    "@telorun/sdk": "0.19.0"
+    "@telorun/sdk": "0.21.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/sql-connection-controller.ts

@@ -1,4 +1,4 @@
-import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+import type { ResourceInstance } from "@telorun/sdk";
 import { randomUUID } from "crypto";
 import {
   CompiledQuery,
@@ -21,24 +21,32 @@ interface PoolConfig {
   connectionTimeoutMs?: number;
 }
 
-interface SqlConnectionManifest {
-  metadata: { name: string; module: string };
-  connectionString: string;
+export type SqlDriver = "postgres" | "sqlite";
+
+/** Native bind-placeholder syntax per driver: SQLite binds anonymous `?`,
+ *  PostgreSQL binds numbered `$1`, `$2`, … */
+export type PlaceholderStyle = "qmark" | "numbered";
+
+export interface SqlConnectionConfig {
+  driver: SqlDriver;
+  /** Required for `postgres`; ignored for `sqlite` (which opens via `sqlite`). */
+  connectionString?: string;
   pool?: PoolConfig;
 }
 
-export type SqlDriver = "postgres" | "sqlite";
-
 export class SqlConnectionResource implements ResourceInstance {
   readonly driver: SqlDriver;
   private readonly db: Kysely<any>;
   private readonly sqlite?: SqliteDb;
 
-  constructor(m: SqlConnectionManifest, sqlite?: SqliteDb) {
-    this.driver = driverFromConnectionString(m.connectionString);
+  constructor(config: SqlConnectionConfig, sqlite?: SqliteDb) {
+    this.driver = config.driver;
 
     if (this.driver === "postgres") {
-      const url = new URL(m.connectionString);
+      if (!config.connectionString) {
+        throw new Error("Sql: postgres connection requires a connectionString");
+      }
+      const url = new URL(config.connectionString);
       const ssl = sslFromSslmode(url.searchParams.get("sslmode"));
       url.searchParams.delete("sslmode");
       this.db = new Kysely({
@@ -46,10 +54,10 @@ export class SqlConnectionResource implements ResourceInstance {
           pool: new Pool({
             connectionString: url.toString(),
             ssl,
-            min: m.pool?.min ?? 1,
-            max: m.pool?.max ?? 10,
-            idleTimeoutMillis: m.pool?.idleTimeoutMs,
-            connectionTimeoutMillis: m.pool?.connectionTimeoutMs,
+            min: config.pool?.min ?? 1,
+            max: config.pool?.max ?? 10,
+            idleTimeoutMillis: config.pool?.idleTimeoutMs,
+            connectionTimeoutMillis: config.pool?.connectionTimeoutMs,
           }),
         }),
       });
@@ -98,6 +106,29 @@ 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[],
+    transaction?: SqlTransactionResource,
+  ): Promise<QueryResult<T>> {
+    let sql = fragments[0] ?? "";
+    for (let i = 1; i < fragments.length; i++) {
+      sql += this.placeholder(i) + fragments[i];
+    }
+    return this.execute<T>(sql, values, transaction);
+  }
+
+  private placeholder(index: number): string {
+    return this.placeholderStyle === "numbered" ? `$${index}` : "?";
+  }
+
   async executeScript(sql: string): Promise<void> {
     if (this.driver === "sqlite") {
       this.sqlite?.exec(sql);
@@ -156,46 +187,10 @@ class TransactionalSqliteDialect extends SqliteDialect {
   }
 }
 
-export function register(): void {}
-
-export async function create(
-  resource: SqlConnectionManifest,
-  ctx: ResourceContext,
-): Promise<SqlConnectionResource> {
-  const sqlite =
-    driverFromConnectionString(resource.connectionString) === "sqlite"
-      ? await openSqliteDatabase(sqliteTargetFromConnectionString(resource.connectionString))
-      : undefined;
-  return new SqlConnectionResource(resource, sqlite);
-}
-
 type SslOption =
   | false
   | { rejectUnauthorized: boolean; checkServerIdentity?: () => undefined };
 
-function driverFromConnectionString(connectionString: string): SqlDriver {
-  const scheme = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(connectionString)?.[1]?.toLowerCase();
-  switch (scheme) {
-    case "postgres":
-    case "postgresql":
-      return "postgres";
-    case "sqlite":
-      return "sqlite";
-    default:
-      throw new Error(
-        `Sql.Connection: connectionString must start with a driver scheme — ` +
-          `'postgres://' or 'postgresql://' for PostgreSQL, 'sqlite:' for SQLite. ` +
-          `Got ${scheme ? `'${scheme}:'` : "a string with no scheme"}: ${JSON.stringify(connectionString)}`,
-      );
-  }
-}
-
-function sqliteTargetFromConnectionString(connectionString: string): string {
-  const path = decodeURIComponent(new URL(connectionString).pathname);
-  // `sqlite:` / `sqlite://` with no path resolves to an in-memory database.
-  return path === "" || path === "/" ? ":memory:" : path;
-}
-
 function sslFromSslmode(mode: string | null): SslOption {
   switch (mode) {
     case null:
@@ -217,7 +212,7 @@ function sslFromSslmode(mode: string | null): SslOption {
   }
 }
 
-async function openSqliteDatabase(file = ":memory:"): Promise<SqliteDb> {
+export async function openSqliteDatabase(file = ":memory:"): Promise<SqliteDb> {
   // Auto-create the parent directory for file-backed databases. SQLite
   // drivers fail-fast when the directory doesn't exist; mirroring `mkdir
   // -p` here lets manifests use paths like `./tmp/foo.sqlite` without a

package/src/sql-exec-controller.ts

@@ -2,6 +2,7 @@ import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
 import type { SqlConnectionResource } from "./sql-connection-controller.js";
 import { resolveSqlConnection } from "./sql-connection-ref.js";
 import type { SqlResult } from "./sql-query-controller.js";
+import { runSql } from "./sql-run.js";
 import type { SqlTransactionResource } from "./sql-transaction-controller.js";
 
 interface SqlExecManifest {
@@ -20,30 +21,20 @@ class SqlExecResource implements ResourceInstance {
     private readonly ctx: ResourceContext,
   ) {}
 
-  async invoke(input: any): Promise<SqlResult> {
+  async invoke(input: unknown): Promise<SqlResult> {
     const m = this.manifest;
     const ctx = this.ctx;
-    const expandedInput = ctx.expandValue(input, {});
 
     const connection = resolveSqlConnection(m.connection, ctx) ?? m.transaction?.getConnection();
     if (!connection) {
       throw new Error("Sql: either 'connection' or 'transaction' must be set");
     }
 
-    return runExec(connection, m.transaction, expandedInput.sql, expandedInput.bindings ?? []);
+    const result = await runSql(connection, m.transaction, input, ctx);
+    return { rows: result.rows, rowCount: connection.toRowCount(result) };
   }
 }
 
-async function runExec(
-  connection: SqlConnectionResource,
-  transaction: SqlTransactionResource | undefined,
-  sql: string,
-  params: unknown[],
-): Promise<SqlResult> {
-  const result = await connection.execute<Record<string, unknown>>(sql, params, transaction);
-  return { rows: result.rows, rowCount: connection.toRowCount(result) };
-}
-
 export function register(): void {}
 
 export async function create(

package/src/sql-postgres-connection-controller.ts

@@ -0,0 +1,28 @@
+import type { ResourceContext } from "@telorun/sdk";
+import { SqlConnectionResource } from "./sql-connection-controller.js";
+
+interface PoolConfig {
+  min?: number;
+  max?: number;
+  idleTimeoutMs?: number;
+  connectionTimeoutMs?: number;
+}
+
+interface PostgresConnectionManifest {
+  metadata: { name: string; module: string };
+  connectionString: string;
+  pool?: PoolConfig;
+}
+
+export function register(): void {}
+
+export async function create(
+  resource: PostgresConnectionManifest,
+  ctx: ResourceContext,
+): Promise<SqlConnectionResource> {
+  return new SqlConnectionResource({
+    driver: "postgres",
+    connectionString: resource.connectionString,
+    pool: resource.pool,
+  });
+}

package/src/sql-query-controller.ts

@@ -1,6 +1,7 @@
 import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
 import type { SqlConnectionResource } from "./sql-connection-controller.js";
 import { resolveSqlConnection } from "./sql-connection-ref.js";
+import { runSql } from "./sql-run.js";
 import type { SqlTransactionResource } from "./sql-transaction-controller.js";
 
 interface SqlQueryManifest {
@@ -27,10 +28,9 @@ class SqlQueryResource implements ResourceInstance {
   async invoke(input: unknown): Promise<SqlResult> {
     const m = this.manifest;
     const ctx = this.ctx;
-    const expandedInput = ctx.expandValue(input, {});
-
     const connection = resolveConnection(m.connection, m.transaction, ctx);
-    return runQuery(connection, m.transaction, expandedInput.sql, expandedInput.bindings);
+    const result = await runSql(connection, m.transaction, input, ctx);
+    return { rows: result.rows, rowCount: result.rows.length };
   }
 }
 
@@ -44,16 +44,6 @@ function resolveConnection(
   );
 }
 
-async function runQuery(
-  connection: SqlConnectionResource,
-  transaction: SqlTransactionResource | undefined,
-  sql: string,
-  params: unknown[],
-): Promise<SqlResult> {
-  const result = await connection.execute<Record<string, unknown>>(sql, params, transaction);
-  return { rows: result.rows, rowCount: result.rows.length };
-}
-
 function failMissingConnection(): never {
   throw new Error("Sql: either 'connection' or 'transaction' must be set");
 }

package/src/sql-run.ts

@@ -0,0 +1,49 @@
+import { InvokeError, isParameterizedSql, type ResourceContext } from "@telorun/sdk";
+import type { QueryResult } from "kysely";
+import type { SqlConnectionResource } from "./sql-connection-controller.js";
+import type { SqlTransactionResource } from "./sql-transaction-controller.js";
+
+/** Execute the `sql` input of a Query/Exec resource against `connection`.
+ *
+ *  Two modes:
+ *  - **inline (`!sql` tag):** the expanded `sql` is a parameterized template —
+ *    each `${{ }}` is bound via the connection's native placeholder, never
+ *    spliced into the text.
+ *  - **escape hatch (`bindings` given):** `sql` is a literal string with
+ *    author-written `?` / `$n` placeholders and `bindings` bound positionally.
+ *
+ *  Mixing a `!sql` template with `bindings` is rejected. A plain string `sql`
+ *  with neither is executed verbatim. */
+export async function runSql(
+  connection: SqlConnectionResource,
+  transaction: SqlTransactionResource | undefined,
+  input: unknown,
+  ctx: ResourceContext,
+): Promise<QueryResult<Record<string, unknown>>> {
+  const expanded = ctx.expandValue(input, {}) as { sql: unknown; bindings?: unknown[] };
+  const sql = expanded.sql;
+  const bindings = expanded.bindings;
+  const hasBindings = bindings !== undefined && bindings !== null;
+
+  if (isParameterizedSql(sql)) {
+    if (hasBindings) {
+      throw new InvokeError(
+        "ERR_INVALID_INPUT",
+        "Sql: a `!sql` template cannot be combined with an explicit `bindings` array. " +
+          "Use one or the other — `!sql` binds each inline value automatically; " +
+          "`bindings` is for hand-written ? / $n placeholders.",
+      );
+    }
+    return connection.executeTemplate<Record<string, unknown>>(
+      sql.fragments,
+      sql.values,
+      transaction,
+    );
+  }
+
+  return connection.execute<Record<string, unknown>>(
+    sql as string,
+    hasBindings ? (bindings as unknown[]) : [],
+    transaction,
+  );
+}

package/src/sql-sqlite-connection-controller.ts

@@ -0,0 +1,18 @@
+import type { ResourceContext } from "@telorun/sdk";
+import { openSqliteDatabase, SqlConnectionResource } from "./sql-connection-controller.js";
+
+interface SqliteConnectionManifest {
+  metadata: { name: string; module: string };
+  /** File path, or omitted / `:memory:` for an in-memory database. */
+  file?: string;
+}
+
+export function register(): void {}
+
+export async function create(
+  resource: SqliteConnectionManifest,
+  ctx: ResourceContext,
+): Promise<SqlConnectionResource> {
+  const sqlite = await openSqliteDatabase(resource.file ?? ":memory:");
+  return new SqlConnectionResource({ driver: "sqlite" }, sqlite);
+}