@telorun/sql 0.5.1 → 0.7.0

package/README.md

@@ -54,20 +54,13 @@ metadata:
   description: |
     A complete feedback collection REST API — no code, pure YAML.
     Persists entries to SQLite and serves them over HTTP.
+imports:
+  Http: std/http-server@0.8.0
+  Sql: std/sql@0.5.1
 targets:
   - Migrations
   - Server
 ---
-kind: Telo.Import
-metadata:
-  name: Http
-source: std/http-server@0.5.0
----
-kind: Telo.Import
-metadata:
-  name: Sql
-source: std/sql@0.3.0
----
 # SQLite database — swap driver/host/database for PostgreSQL with zero YAML changes
 kind: Sql.Connection
 metadata:
@@ -127,7 +120,7 @@ routes:
               minLength: 1
             source:
               type: string
-          required: [text]
+          required: [ text ]
     handler:
       kind: Sql.Exec
       connection:
@@ -157,7 +150,7 @@ routes:
         kind: Sql.Connection
         name: Db
       from: feedback
-      columns: [id, text, source, score, created_at]
+      columns: [ id, text, source, score, created_at ]
       orderBy:
         - { column: created_at, direction: desc }
     response:
@@ -176,14 +169,14 @@ routes:
           properties:
             id:
               type: integer
-          required: [id]
+          required: [ id ]
     handler:
       kind: Sql.Select
       connection:
         kind: Sql.Connection
         name: Db
       from: feedback
-      columns: [id, text, source, score, created_at]
+      columns: [ id, text, source, score, created_at ]
       where:
         - { column: id, op: "=", value: "${{ request.params.id }}" }
     response:

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

@@ -1,15 +1,18 @@
 import { randomUUID } from "crypto";
-import { CompiledQuery, Kysely, PostgresDialect, SqliteDialect, } from "kysely";
+import { CompiledQuery, Kysely, PostgresDialect, SqliteAdapter, SqliteDialect, } from "kysely";
 import { Pool } from "pg";
 import { currentTxId, deleteTx, getTx, setTx, txStorage } from "./transaction-store.js";
 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,
                     }),
                 }),
             });
@@ -31,7 +34,7 @@ export class SqlConnectionResource {
             }
             this.sqlite = sqlite;
             this.db = new Kysely({
-                dialect: new SqliteDialect({
+                dialect: new TransactionalSqliteDialect({
                     database: this.sqlite,
                 }),
             });
@@ -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);
@@ -94,31 +113,19 @@ export class SqlConnectionResource {
         return this.db;
     }
 }
-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)}`);
+// Kysely's stock SQLite adapter reports `supportsTransactionalDdl = false`, so
+// its Migrator runs migrations without a transaction. SQLite does support
+// transactional DDL, so we flip the flag — letting the Migrator wrap the whole
+// migration batch in a single transaction, matching PostgreSQL.
+class TransactionalSqliteAdapter extends SqliteAdapter {
+    get supportsTransactionalDdl() {
+        return true;
     }
 }
-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;
+class TransactionalSqliteDialect extends SqliteDialect {
+    createAdapter() {
+        return new TransactionalSqliteAdapter();
+    }
 }
 function sslFromSslmode(mode) {
     switch (mode) {
@@ -138,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-migrations-controller.d.ts

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

package/dist/sql-migrations-controller.js

@@ -1,16 +1,24 @@
 import { CompiledQuery, Migrator, } from "kysely";
 import { resolveSqlConnection } from "./sql-connection-ref.js";
+function entryStatements(entry) {
+    return entry.statements ?? (entry.statement != null ? [entry.statement] : []);
+}
 class TeloMigrationProvider {
     migrations;
     constructor(migrations) {
         this.migrations = migrations;
     }
     async getMigrations() {
-        return Object.fromEntries(this.migrations.map((m) => [
-            m.name,
+        return Object.fromEntries(Object.entries(this.migrations).map(([name, statements]) => [
+            name,
             {
+                // Each statement runs as its own prepared statement on the migration
+                // transaction's connection, so a migration may hold multiple
+                // statements while the whole batch stays a single transaction.
                 async up(db) {
-                    await db.executeQuery(CompiledQuery.raw(m.sql));
+                    for (const statement of statements) {
+                        await db.executeQuery(CompiledQuery.raw(statement));
+                    }
                 },
             },
         ]));
@@ -25,17 +33,23 @@ class SqlMigrationsResource {
     }
     async run() {
         const conn = resolveSqlConnection(this.manifest.connection, this.ctx) ?? failMissingConnection();
-        const migrations = [];
+        const migrations = {};
+        // Legacy: standalone `Sql.Migration` resources in the same module scope.
         for (const [, { resource }] of this.ctx.moduleContext.resourceInstances) {
             if (resource.kind === "Sql.Migration") {
                 const version = (resource.version ?? resource.metadata.name);
-                migrations.push({
-                    name: version,
-                    sql: resource.sql,
-                });
+                migrations[version] = [resource.sql];
+            }
+        }
+        // Preferred: the keyed `migrations` map on this resource.
+        for (const [name, entry] of Object.entries(this.manifest.migrations ?? {})) {
+            const statements = entryStatements(entry);
+            if (statements.length === 0) {
+                throw new Error(`Sql.Migrations: migration '${name}' has no statement(s) — ` +
+                    `set 'statement' or a non-empty 'statements'`);
             }
+            migrations[name] = statements;
         }
-        migrations.sort((a, b) => a.name.localeCompare(b.name));
         const migrator = new Migrator({
             db: conn.kysely,
             provider: new TeloMigrationProvider(migrations),

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.5.1",
+  "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.16.0"
+    "@telorun/sdk": "0.21.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/sql-connection-controller.ts

@@ -1,9 +1,10 @@
-import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+import type { ResourceInstance } from "@telorun/sdk";
 import { randomUUID } from "crypto";
 import {
   CompiledQuery,
   Kysely,
   PostgresDialect,
+  SqliteAdapter,
   SqliteDialect,
   type QueryResult,
   type Transaction,
@@ -20,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({
@@ -45,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,
           }),
         }),
       });
@@ -58,7 +67,7 @@ export class SqlConnectionResource implements ResourceInstance {
       }
       this.sqlite = sqlite;
       this.db = new Kysely({
-        dialect: new SqliteDialect({
+        dialect: new TransactionalSqliteDialect({
           database: this.sqlite,
         }),
       });
@@ -97,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);
@@ -139,45 +171,25 @@ export class SqlConnectionResource implements ResourceInstance {
   }
 }
 
-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);
+// Kysely's stock SQLite adapter reports `supportsTransactionalDdl = false`, so
+// its Migrator runs migrations without a transaction. SQLite does support
+// transactional DDL, so we flip the flag — letting the Migrator wrap the whole
+// migration batch in a single transaction, matching PostgreSQL.
+class TransactionalSqliteAdapter extends SqliteAdapter {
+  override get supportsTransactionalDdl(): boolean {
+    return true;
+  }
 }
 
-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)}`,
-      );
+class TransactionalSqliteDialect extends SqliteDialect {
+  override createAdapter(): SqliteAdapter {
+    return new TransactionalSqliteAdapter();
   }
 }
 
-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;
-}
+type SslOption =
+  | false
+  | { rejectUnauthorized: boolean; checkServerIdentity?: () => undefined };
 
 function sslFromSslmode(mode: string | null): SslOption {
   switch (mode) {
@@ -200,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-migrations-controller.ts

@@ -9,26 +9,38 @@ import {
 import type { SqlConnectionResource } from "./sql-connection-controller.js";
 import { resolveSqlConnection } from "./sql-connection-ref.js";
 
+// A migration entry is one statement or an ordered list of statements; both
+// forms normalize to a non-empty array of single statements.
+interface MigrationEntry {
+  statement?: string;
+  statements?: string[];
+}
+
 interface SqlMigrationsManifest {
   metadata: { name: string; module: string };
   connection: SqlConnectionResource;
+  migrations?: Record<string, MigrationEntry>;
 }
 
-interface MigrationEntry {
-  name: string;
-  sql: string;
+function entryStatements(entry: MigrationEntry): string[] {
+  return entry.statements ?? (entry.statement != null ? [entry.statement] : []);
 }
 
 class TeloMigrationProvider implements MigrationProvider {
-  constructor(private readonly migrations: MigrationEntry[]) {}
+  constructor(private readonly migrations: Record<string, string[]>) {}
 
   async getMigrations(): Promise<Record<string, Migration>> {
     return Object.fromEntries(
-      this.migrations.map((m) => [
-        m.name,
+      Object.entries(this.migrations).map(([name, statements]) => [
+        name,
         {
+          // Each statement runs as its own prepared statement on the migration
+          // transaction's connection, so a migration may hold multiple
+          // statements while the whole batch stays a single transaction.
           async up(db: Kysely<any>): Promise<void> {
-            await db.executeQuery(CompiledQuery.raw(m.sql));
+            for (const statement of statements) {
+              await db.executeQuery(CompiledQuery.raw(statement));
+            }
           },
         },
       ]),
@@ -46,17 +58,25 @@ class SqlMigrationsResource implements ResourceInstance {
     const conn =
       resolveSqlConnection(this.manifest.connection, this.ctx) ?? failMissingConnection();
 
-    const migrations: MigrationEntry[] = [];
+    const migrations: Record<string, string[]> = {};
+    // Legacy: standalone `Sql.Migration` resources in the same module scope.
     for (const [, { resource }] of this.ctx.moduleContext.resourceInstances) {
       if (resource.kind === "Sql.Migration") {
         const version = (resource.version ?? resource.metadata.name) as string;
-        migrations.push({
-          name: version,
-          sql: resource.sql as string,
-        });
+        migrations[version] = [resource.sql as string];
+      }
+    }
+    // Preferred: the keyed `migrations` map on this resource.
+    for (const [name, entry] of Object.entries(this.manifest.migrations ?? {})) {
+      const statements = entryStatements(entry);
+      if (statements.length === 0) {
+        throw new Error(
+          `Sql.Migrations: migration '${name}' has no statement(s) — ` +
+            `set 'statement' or a non-empty 'statements'`,
+        );
       }
+      migrations[name] = statements;
     }
-    migrations.sort((a, b) => a.name.localeCompare(b.name));
 
     const migrator = new Migrator({
       db: conn.kysely,

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);
+}