@telorun/sql 0.1.1 → 0.1.2

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

@@ -0,0 +1,69 @@
+import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+import type { SqlConnectionResource } from "./sql-connection-controller.js";
+import type { SqlResult } from "./sql-query-controller.js";
+import type { SqlTransactionResource } from "./sql-transaction-controller.js";
+type ColumnDef = string | {
+    column: string;
+    as?: string;
+} | {
+    expr: string;
+    as?: string;
+};
+type Op = "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "like" | "ilike" | "in" | "is_null" | "is_not_null";
+interface Condition {
+    when?: boolean;
+    column: string;
+    op: Op;
+    value?: unknown;
+    ref?: string;
+}
+interface RawClause {
+    when?: boolean;
+    sql: string;
+    bindings?: unknown[];
+}
+interface OrGroup {
+    when?: boolean;
+    or: WhereNode[];
+}
+interface AndGroup {
+    when?: boolean;
+    and: WhereNode[];
+}
+interface NotGroup {
+    when?: boolean;
+    not: WhereNode;
+}
+type WhereNode = Condition | RawClause | OrGroup | AndGroup | NotGroup;
+interface OrderByItem {
+    column: string;
+    direction?: "asc" | "desc";
+}
+interface SelectManifest {
+    metadata: {
+        name: string;
+        module: string;
+    };
+    connection?: SqlConnectionResource;
+    transaction?: SqlTransactionResource;
+    from: string;
+    columns?: ColumnDef[];
+    distinct?: boolean;
+    distinctOn?: string[];
+    where?: WhereNode[];
+    groupBy?: string[];
+    having?: WhereNode[];
+    orderBy?: OrderByItem[];
+    limit?: unknown;
+    offset?: unknown;
+    inputType?: string | Record<string, any>;
+}
+declare class SqlSelectResource implements ResourceInstance {
+    private readonly manifest;
+    private readonly ctx;
+    constructor(manifest: SelectManifest, ctx: ResourceContext);
+    invoke(input: unknown): Promise<SqlResult>;
+}
+export declare function register(): void;
+export declare function create(resource: SelectManifest, ctx: ResourceContext): Promise<SqlSelectResource>;
+export {};

package/dist/sql-select-controller.js

@@ -0,0 +1,194 @@
+import { resolveSqlConnection } from "./sql-connection-ref.js";
+// ── Controller ────────────────────────────────────────────────────────────────
+class SqlSelectResource {
+    manifest;
+    ctx;
+    constructor(manifest, ctx) {
+        this.manifest = manifest;
+        this.ctx = ctx;
+    }
+    async invoke(input) {
+        const m = this.manifest;
+        const ctx = this.ctx;
+        const inputs = {
+            ...extractDefaults(m.inputType, ctx),
+            ...(input ?? {}),
+        };
+        const expandCtx = { inputs };
+        const where = ctx.expandValue(m.where ?? [], expandCtx);
+        const having = ctx.expandValue(m.having ?? [], expandCtx);
+        const limit = m.limit != null ? ctx.expandValue(m.limit, expandCtx) : undefined;
+        const offset = m.offset != null ? ctx.expandValue(m.offset, expandCtx) : undefined;
+        const connection = resolveSqlConnection(m.connection, ctx) ?? m.transaction?.getConnection();
+        if (!connection) {
+            throw new Error("Sql.Select: either 'connection' or 'transaction' must be set");
+        }
+        const { sql, params } = buildSelect(m, where, having, limit, offset, connection.driver);
+        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) {
+    const params = [];
+    const addParam = (value) => {
+        params.push(value);
+        return `$${params.length}`;
+    };
+    const parts = [];
+    // SELECT [DISTINCT [ON (...)]]
+    let selectClause = "SELECT";
+    if (m.distinct) {
+        selectClause += " DISTINCT";
+    }
+    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) : "*";
+    parts.push(`${selectClause} ${colList}`);
+    // FROM
+    parts.push(`FROM ${quoteIdent(m.from)}`);
+    // WHERE
+    const whereStr = buildClauses(where, "AND", driver, addParam);
+    if (whereStr)
+        parts.push(`WHERE ${whereStr}`);
+    // GROUP BY
+    if (m.groupBy && m.groupBy.length > 0) {
+        parts.push(`GROUP BY ${m.groupBy.map(quoteIdent).join(", ")}`);
+    }
+    // HAVING
+    const havingStr = buildClauses(having, "AND", driver, addParam);
+    if (havingStr)
+        parts.push(`HAVING ${havingStr}`);
+    // ORDER BY
+    if (m.orderBy && m.orderBy.length > 0) {
+        const orderParts = m.orderBy.map((o) => `${quoteIdent(o.column)} ${(o.direction ?? "asc").toUpperCase()}`);
+        parts.push(`ORDER BY ${orderParts.join(", ")}`);
+    }
+    // LIMIT / OFFSET
+    if (limit != null)
+        parts.push(`LIMIT ${addParam(limit)}`);
+    if (offset != null)
+        parts.push(`OFFSET ${addParam(offset)}`);
+    return { sql: parts.join("\n"), params };
+}
+function buildColumns(columns) {
+    return columns
+        .map((c) => {
+        if (typeof c === "string")
+            return quoteIdent(c);
+        if ("expr" in c)
+            return c.as ? `${c.expr} AS ${quoteIdent(c.as)}` : c.expr;
+        return c.as ? `${quoteIdent(c.column)} AS ${quoteIdent(c.as)}` : quoteIdent(c.column);
+    })
+        .join(", ");
+}
+function buildClauses(clauses, join, driver, addParam) {
+    const parts = [];
+    for (const clause of clauses) {
+        if (clause.when === false)
+            continue;
+        const built = buildClause(clause, driver, addParam);
+        if (built !== null)
+            parts.push(built);
+    }
+    if (parts.length === 0)
+        return null;
+    if (parts.length === 1)
+        return parts[0];
+    return parts.join(` ${join} `);
+}
+function buildClause(node, driver, addParam) {
+    if ("not" in node) {
+        const inner = buildClause(node.not, driver, addParam);
+        return inner ? `NOT (${inner})` : null;
+    }
+    if ("or" in node) {
+        const inner = buildClauses(node.or, "OR", driver, addParam);
+        return inner ? `(${inner})` : null;
+    }
+    if ("and" in node) {
+        const inner = buildClauses(node.and, "AND", driver, 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 null;
+}
+function buildCondition(c, driver, addParam) {
+    const col = quoteIdent(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})`;
+        }
+        default: {
+            const rhs = c.ref !== undefined ? quoteIdent(c.ref) : addParam(c.value);
+            return `${col} ${opToSql(c.op)} ${rhs}`;
+        }
+    }
+}
+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: "=",
+        ne: "<>",
+        lt: "<",
+        lte: "<=",
+        gt: ">",
+        gte: ">=",
+        like: "LIKE",
+        ilike: "ILIKE",
+    };
+    const sql = map[op];
+    if (!sql)
+        throw new Error(`Sql.Select: unknown operator '${op}'`);
+    return sql;
+}
+// ── Exports ───────────────────────────────────────────────────────────────────
+function extractDefaults(inputType, ctx) {
+    if (!inputType)
+        return {};
+    // Resolve schema: string ref → look up, inline object → use directly
+    let schema;
+    if (typeof inputType === "string") {
+        schema = ctx.lookupSchema(inputType);
+    }
+    else if (inputType.schema && typeof inputType.schema === "object") {
+        schema = inputType.schema;
+    }
+    else {
+        schema = inputType;
+    }
+    if (!schema || typeof schema !== "object")
+        return {};
+    const props = schema.properties;
+    if (!props)
+        return {};
+    const defaults = {};
+    for (const [key, def] of Object.entries(props)) {
+        if (def && typeof def === "object" && "default" in def) {
+            defaults[key] = def.default;
+        }
+    }
+    return defaults;
+}
+export function register() { }
+export async function create(resource, ctx) {
+    return new SqlSelectResource(resource, ctx);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/sql",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "exports": {
     "./sql-connection": {
@@ -11,6 +11,10 @@
       "bun": "./src/sql-query-controller.ts",
       "import": "./dist/sql-query-controller.js"
     },
+    "./sql-select": {
+      "bun": "./src/sql-select-controller.ts",
+      "import": "./dist/sql-select-controller.js"
+    },
     "./sql-exec": {
       "bun": "./src/sql-exec-controller.ts",
       "import": "./dist/sql-exec-controller.js"
@@ -33,13 +37,14 @@
     }
   },
   "files": [
-    "dist/**"
+    "dist",
+    "src/**"
   ],
   "dependencies": {
     "better-sqlite3": "^12.8.0",
     "pg": "^8.20.0",
     "kysely": "^0.28.15",
-    "@telorun/sdk": "0.2.6"
+    "@telorun/sdk": "0.2.7"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.0.0",

package/src/sql-connection-controller.ts

@@ -0,0 +1,169 @@
+import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+import { randomUUID } from "crypto";
+import {
+  CompiledQuery,
+  Kysely,
+  PostgresDialect,
+  SqliteDialect,
+  type QueryResult,
+  type Transaction,
+} from "kysely";
+import { Pool } from "pg";
+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";
+
+interface PoolConfig {
+  min?: number;
+  max?: number;
+  idleTimeoutMs?: number;
+  connectionTimeoutMs?: number;
+}
+
+interface SqlConnectionManifest {
+  metadata: { name: string; module: string };
+  driver: "postgres" | "sqlite";
+  connectionString?: string;
+  host?: string;
+  port?: number;
+  database?: string;
+  user?: string;
+  password?: string;
+  ssl?: boolean;
+  file?: string;
+  pool?: PoolConfig;
+}
+
+export type SqlDriver = SqlConnectionManifest["driver"];
+
+export class SqlConnectionResource implements ResourceInstance {
+  readonly driver: SqlDriver;
+  private readonly db: Kysely<any>;
+  private readonly sqlite?: SqliteDb;
+
+  constructor(m: SqlConnectionManifest, sqlite?: SqliteDb) {
+    this.driver = m.driver;
+
+    if (m.driver === "postgres") {
+      this.db = new Kysely({
+        dialect: new PostgresDialect({
+          pool: new Pool({
+            ...(m.connectionString
+              ? { connectionString: m.connectionString }
+              : { host: m.host, port: m.port ?? 5432, database: m.database, user: m.user, password: m.password }),
+            ssl: m.ssl ? { rejectUnauthorized: false } : false,
+            min: m.pool?.min ?? 1,
+            max: m.pool?.max ?? 10,
+            idleTimeoutMillis: m.pool?.idleTimeoutMs,
+            connectionTimeoutMillis: m.pool?.connectionTimeoutMs,
+          }),
+        }),
+      });
+    } else if (m.driver === "sqlite") {
+      if (!sqlite) {
+        throw new Error("Sql: sqlite database was not initialized");
+      }
+      this.sqlite = sqlite;
+      this.db = new Kysely({
+        dialect: new SqliteDialect({
+          database: this.sqlite,
+        }),
+      });
+    } else {
+      throw new Error("Invalid SQL Connection driver");
+    }
+  }
+
+  async init() {
+    await this.db.connection().execute(async () => {
+      // just checking
+    });
+  }
+
+  async teardown(): Promise<void> {
+    await this.db.destroy();
+  }
+
+  async transaction<T>(cb: () => Promise<T>): Promise<T> {
+    const txId = randomUUID();
+
+    return this.db.transaction().execute(async (trx: Transaction<any>) => {
+      setTx(txId, { executor: trx });
+      try {
+        return await txStorage.run(txId, cb);
+      } finally {
+        deleteTx(txId);
+      }
+    });
+  }
+
+  async execute<T>(
+    sql: string,
+    params: unknown[] = [],
+    transaction?: SqlTransactionResource,
+  ): Promise<QueryResult<T>> {
+    const executor = this.resolveExecutor(transaction);
+    return executor.executeQuery<T>(CompiledQuery.raw(sql, params));
+  }
+
+  async executeScript(sql: string): Promise<void> {
+    if (this.driver === "sqlite") {
+      this.sqlite?.exec(sql);
+      return;
+    }
+
+    await this.execute(sql);
+  }
+
+  toRowCount(result: QueryResult<unknown>): number {
+    if (result.numAffectedRows !== undefined) {
+      return Number(result.numAffectedRows);
+    }
+
+    return result.rows.length;
+  }
+
+  get kysely(): Kysely<any> {
+    return this.db;
+  }
+
+  snapshot(): Record<string, unknown> {
+    return {};
+  }
+
+  private resolveExecutor(transaction?: SqlTransactionResource): Kysely<any> {
+    if (transaction) {
+      transaction.assertActive();
+    }
+
+    const txId = currentTxId();
+    if (txId) {
+      const entry = getTx(txId);
+      if (entry) {
+        return entry.executor as Kysely<any>;
+      }
+    }
+
+    return this.db;
+  }
+}
+
+export function register(): void {}
+
+export async function create(
+  resource: SqlConnectionManifest,
+  ctx: ResourceContext,
+): Promise<SqlConnectionResource> {
+  const sqlite = resource.driver === "sqlite" ? await openSqliteDatabase(resource.file) : undefined;
+  return new SqlConnectionResource(resource, sqlite);
+}
+
+async function openSqliteDatabase(file = ":memory:"): Promise<SqliteDb> {
+  if (typeof Bun !== "undefined") {
+    const { openDatabase } = await import("./sqlite-driver-bun.js");
+    return openDatabase(file);
+  }
+
+  const { openDatabase } = await import("./sqlite-driver-node.js");
+  return openDatabase(file);
+}

package/src/sql-connection-ref.ts

@@ -0,0 +1,25 @@
+import type { ResourceContext } from "@telorun/sdk";
+import type { SqlConnectionResource } from "./sql-connection-controller.js";
+
+interface ConnectionRef {
+  name: string;
+}
+
+export function resolveSqlConnection(
+  value: SqlConnectionResource | ConnectionRef | undefined,
+  ctx: ResourceContext,
+): SqlConnectionResource | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  if (typeof (value as SqlConnectionResource).execute === "function") {
+    return value as SqlConnectionResource;
+  }
+
+  if (typeof (value as ConnectionRef).name !== "string") {
+    throw new Error("Sql: invalid connection reference");
+  }
+
+  return ctx.moduleContext.getInstance((value as ConnectionRef).name) as SqlConnectionResource;
+}

package/src/sql-exec-controller.ts

@@ -0,0 +1,54 @@
+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 type { SqlTransactionResource } from "./sql-transaction-controller.js";
+
+interface SqlExecManifest {
+  metadata: { name: string; module: string };
+  connection?: SqlConnectionResource;
+  transaction?: SqlTransactionResource;
+  inputs: {
+    sql: string;
+    bindings?: unknown[];
+  };
+}
+
+class SqlExecResource implements ResourceInstance {
+  constructor(
+    private readonly manifest: SqlExecManifest,
+    private readonly ctx: ResourceContext,
+  ) {}
+
+  async invoke(input: any): 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 ?? []);
+  }
+}
+
+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(
+  resource: SqlExecManifest,
+  ctx: ResourceContext,
+): Promise<SqlExecResource> {
+  return new SqlExecResource(resource, ctx);
+}

package/src/sql-migration-controller.ts

@@ -0,0 +1,20 @@
+import type { ResourceInstance } from "@telorun/sdk";
+
+interface SqlMigrationManifest {
+  metadata: { name: string; module: string };
+  sql: string;
+}
+
+class SqlMigrationResource implements ResourceInstance {
+  constructor(readonly manifest: SqlMigrationManifest) {}
+
+  snapshot(): Record<string, unknown> {
+    return {};
+  }
+}
+
+export function register(): void {}
+
+export async function create(resource: SqlMigrationManifest): Promise<SqlMigrationResource> {
+  return new SqlMigrationResource(resource);
+}

package/src/sql-migrations-controller.ts

@@ -0,0 +1,85 @@
+import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+import {
+  CompiledQuery,
+  Migrator,
+  type Kysely,
+  type Migration,
+  type MigrationProvider,
+} from "kysely";
+import type { SqlConnectionResource } from "./sql-connection-controller.js";
+import { resolveSqlConnection } from "./sql-connection-ref.js";
+
+interface SqlMigrationsManifest {
+  metadata: { name: string; module: string };
+  connection: SqlConnectionResource;
+}
+
+interface MigrationEntry {
+  name: string;
+  sql: string;
+}
+
+class TeloMigrationProvider implements MigrationProvider {
+  constructor(private readonly migrations: MigrationEntry[]) {}
+
+  async getMigrations(): Promise<Record<string, Migration>> {
+    return Object.fromEntries(
+      this.migrations.map((m) => [
+        m.name,
+        {
+          async up(db: Kysely<any>): Promise<void> {
+            await db.executeQuery(CompiledQuery.raw(m.sql));
+          },
+        },
+      ]),
+    );
+  }
+}
+
+class SqlMigrationsResource implements ResourceInstance {
+  constructor(
+    private readonly manifest: SqlMigrationsManifest,
+    private readonly ctx: ResourceContext,
+  ) {}
+
+  async run(): Promise<void> {
+    const conn =
+      resolveSqlConnection(this.manifest.connection, this.ctx) ?? failMissingConnection();
+
+    const migrations: MigrationEntry[] = [];
+    for (const [, { resource }] of this.ctx.moduleContext.resourceInstances) {
+      if (resource.kind === "Sql.Migration") {
+        migrations.push({
+          name: resource.metadata.name as string,
+          sql: resource.sql as string,
+        });
+      }
+    }
+    migrations.sort((a, b) => a.name.localeCompare(b.name));
+
+    const migrator = new Migrator({
+      db: conn.kysely,
+      provider: new TeloMigrationProvider(migrations),
+      migrationTableName: "migrations",
+      migrationLockTableName: "migration_locks",
+    });
+
+    const { error } = await migrator.migrateToLatest();
+    if (error) {
+      throw error;
+    }
+  }
+}
+
+function failMissingConnection(): never {
+  throw new Error("Sql.Migrations: missing connection");
+}
+
+export function register(): void {}
+
+export async function create(
+  resource: SqlMigrationsManifest,
+  ctx: ResourceContext,
+): Promise<SqlMigrationsResource> {
+  return new SqlMigrationsResource(resource, ctx);
+}

package/src/sql-query-controller.ts

@@ -0,0 +1,68 @@
+import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+import type { SqlConnectionResource } from "./sql-connection-controller.js";
+import { resolveSqlConnection } from "./sql-connection-ref.js";
+import type { SqlTransactionResource } from "./sql-transaction-controller.js";
+
+interface SqlQueryManifest {
+  metadata: { name: string; module: string };
+  connection?: SqlConnectionResource;
+  transaction?: SqlTransactionResource;
+  inputs: {
+    sql: string;
+    bindings?: unknown[];
+  };
+}
+
+export interface SqlResult {
+  rows: Record<string, unknown>[];
+  rowCount: number;
+}
+
+class SqlQueryResource implements ResourceInstance {
+  constructor(
+    private readonly manifest: SqlQueryManifest,
+    private readonly ctx: ResourceContext,
+  ) {}
+
+  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);
+  }
+}
+
+function resolveConnection(
+  connection: SqlConnectionResource | undefined,
+  transaction: SqlTransactionResource | undefined,
+  ctx: ResourceContext,
+): SqlConnectionResource {
+  return (
+    resolveSqlConnection(connection, ctx) ?? transaction?.getConnection() ?? failMissingConnection()
+  );
+}
+
+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");
+}
+
+export function register(): void {}
+
+export async function create(
+  resource: SqlQueryManifest,
+  ctx: ResourceContext,
+): Promise<SqlQueryResource> {
+  return new SqlQueryResource(resource, ctx);
+}

package/src/sql-select-controller.ts

@@ -0,0 +1,311 @@
+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 type { SqlTransactionResource } from "./sql-transaction-controller.js";
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+type ColumnDef = string | { column: string; as?: string } | { expr: string; as?: string };
+
+type Op =
+  | "eq"
+  | "ne"
+  | "lt"
+  | "lte"
+  | "gt"
+  | "gte"
+  | "like"
+  | "ilike"
+  | "in"
+  | "is_null"
+  | "is_not_null";
+
+interface Condition {
+  when?: boolean;
+  column: string;
+  op: Op;
+  value?: unknown;
+  ref?: string;
+}
+
+interface RawClause {
+  when?: boolean;
+  sql: string;
+  bindings?: unknown[];
+}
+
+interface OrGroup {
+  when?: boolean;
+  or: WhereNode[];
+}
+
+interface AndGroup {
+  when?: boolean;
+  and: WhereNode[];
+}
+
+interface NotGroup {
+  when?: boolean;
+  not: WhereNode;
+}
+
+type WhereNode = Condition | RawClause | OrGroup | AndGroup | NotGroup;
+
+interface OrderByItem {
+  column: string;
+  direction?: "asc" | "desc";
+}
+
+interface SelectManifest {
+  metadata: { name: string; module: string };
+  connection?: SqlConnectionResource;
+  transaction?: SqlTransactionResource;
+  from: string;
+  columns?: ColumnDef[];
+  distinct?: boolean;
+  distinctOn?: string[];
+  where?: WhereNode[];
+  groupBy?: string[];
+  having?: WhereNode[];
+  orderBy?: OrderByItem[];
+  limit?: unknown;
+  offset?: unknown;
+  inputType?: string | Record<string, any>;
+}
+
+// ── Controller ────────────────────────────────────────────────────────────────
+
+class SqlSelectResource implements ResourceInstance {
+  constructor(
+    private readonly manifest: SelectManifest,
+    private readonly ctx: ResourceContext,
+  ) {}
+
+  async invoke(input: unknown): Promise<SqlResult> {
+    const m = this.manifest;
+    const ctx = this.ctx;
+    const inputs = {
+      ...extractDefaults(m.inputType, ctx),
+      ...((input as Record<string, unknown>) ?? {}),
+    };
+    const expandCtx = { inputs };
+
+    const where = ctx.expandValue(m.where ?? [], expandCtx) as WhereNode[];
+    const having = ctx.expandValue(m.having ?? [], expandCtx) as WhereNode[];
+    const limit = m.limit != null ? ctx.expandValue(m.limit, expandCtx) : undefined;
+    const offset = m.offset != null ? ctx.expandValue(m.offset, expandCtx) : undefined;
+
+    const connection = resolveSqlConnection(m.connection, ctx) ?? m.transaction?.getConnection();
+    if (!connection) {
+      throw new Error("Sql.Select: either 'connection' or 'transaction' must be set");
+    }
+
+    const { sql, params } = buildSelect(m, where, having, limit, offset, connection.driver);
+    const result = await connection.execute<Record<string, unknown>>(sql, params, m.transaction);
+    return { rows: result.rows, rowCount: result.rows.length };
+  }
+}
+
+// ── SQL building ──────────────────────────────────────────────────────────────
+
+type Driver = "postgres" | "sqlite";
+
+function buildSelect(
+  m: SelectManifest,
+  where: WhereNode[],
+  having: WhereNode[],
+  limit: unknown,
+  offset: unknown,
+  driver: Driver,
+): { sql: string; params: unknown[] } {
+  const params: unknown[] = [];
+  const addParam = (value: unknown): string => {
+    params.push(value);
+    return `$${params.length}`;
+  };
+
+  const parts: string[] = [];
+
+  // SELECT [DISTINCT [ON (...)]]
+  let selectClause = "SELECT";
+  if (m.distinct) {
+    selectClause += " DISTINCT";
+  } 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) : "*";
+  parts.push(`${selectClause} ${colList}`);
+
+  // FROM
+  parts.push(`FROM ${quoteIdent(m.from)}`);
+
+  // WHERE
+  const whereStr = buildClauses(where, "AND", driver, addParam);
+  if (whereStr) parts.push(`WHERE ${whereStr}`);
+
+  // GROUP BY
+  if (m.groupBy && m.groupBy.length > 0) {
+    parts.push(`GROUP BY ${m.groupBy.map(quoteIdent).join(", ")}`);
+  }
+
+  // HAVING
+  const havingStr = buildClauses(having, "AND", driver, addParam);
+  if (havingStr) parts.push(`HAVING ${havingStr}`);
+
+  // ORDER BY
+  if (m.orderBy && m.orderBy.length > 0) {
+    const orderParts = m.orderBy.map(
+      (o) => `${quoteIdent(o.column)} ${(o.direction ?? "asc").toUpperCase()}`,
+    );
+    parts.push(`ORDER BY ${orderParts.join(", ")}`);
+  }
+
+  // LIMIT / OFFSET
+  if (limit != null) parts.push(`LIMIT ${addParam(limit)}`);
+  if (offset != null) parts.push(`OFFSET ${addParam(offset)}`);
+
+  return { sql: parts.join("\n"), params };
+}
+
+function buildColumns(columns: ColumnDef[]): string {
+  return columns
+    .map((c) => {
+      if (typeof c === "string") return quoteIdent(c);
+      if ("expr" in c) return c.as ? `${c.expr} AS ${quoteIdent(c.as)}` : c.expr;
+      return c.as ? `${quoteIdent(c.column)} AS ${quoteIdent(c.as)}` : quoteIdent(c.column);
+    })
+    .join(", ");
+}
+
+function buildClauses(
+  clauses: WhereNode[],
+  join: "AND" | "OR",
+  driver: Driver,
+  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);
+    if (built !== null) parts.push(built);
+  }
+  if (parts.length === 0) return null;
+  if (parts.length === 1) return parts[0];
+  return parts.join(` ${join} `);
+}
+
+function buildClause(
+  node: WhereNode,
+  driver: Driver,
+  addParam: (v: unknown) => string,
+): string | null {
+  if ("not" in node) {
+    const inner = buildClause(node.not, driver, addParam);
+    return inner ? `NOT (${inner})` : null;
+  }
+  if ("or" in node) {
+    const inner = buildClauses(node.or, "OR", driver, addParam);
+    return inner ? `(${inner})` : null;
+  }
+  if ("and" in node) {
+    const inner = buildClauses(node.and, "AND", driver, 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 null;
+}
+
+function buildCondition(c: Condition, driver: Driver, addParam: (v: unknown) => string): string {
+  const col = quoteIdent(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})`;
+    }
+    default: {
+      const rhs = c.ref !== undefined ? quoteIdent(c.ref) : addParam(c.value);
+      return `${col} ${opToSql(c.op)} ${rhs}`;
+    }
+  }
+}
+
+function renumberFragment(
+  sql: string,
+  bindings: unknown[],
+  addParam: (v: unknown) => string,
+): string {
+  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: "=",
+    ne: "<>",
+    lt: "<",
+    lte: "<=",
+    gt: ">",
+    gte: ">=",
+    like: "LIKE",
+    ilike: "ILIKE",
+  };
+  const sql = map[op];
+  if (!sql) throw new Error(`Sql.Select: unknown operator '${op}'`);
+  return sql;
+}
+
+// ── Exports ───────────────────────────────────────────────────────────────────
+
+function extractDefaults(
+  inputType: string | Record<string, any> | undefined,
+  ctx: ResourceContext,
+): Record<string, unknown> {
+  if (!inputType) return {};
+
+  // Resolve schema: string ref → look up, inline object → use directly
+  let schema: Record<string, any> | undefined;
+  if (typeof inputType === "string") {
+    schema = ctx.lookupSchema(inputType) as Record<string, any> | undefined;
+  } else if (inputType.schema && typeof inputType.schema === "object") {
+    schema = inputType.schema;
+  } else {
+    schema = inputType;
+  }
+
+  if (!schema || typeof schema !== "object") return {};
+  const props = schema.properties as Record<string, any> | undefined;
+  if (!props) return {};
+
+  const defaults: Record<string, unknown> = {};
+  for (const [key, def] of Object.entries(props)) {
+    if (def && typeof def === "object" && "default" in def) {
+      defaults[key] = def.default;
+    }
+  }
+  return defaults;
+}
+
+export function register(): void {}
+
+export async function create(
+  resource: SelectManifest,
+  ctx: ResourceContext,
+): Promise<SqlSelectResource> {
+  return new SqlSelectResource(resource, ctx);
+}

package/src/sql-transaction-controller.ts

@@ -0,0 +1,62 @@
+import type { Invocable, ResourceContext, ResourceInstance } from "@telorun/sdk";
+import type { SqlConnectionResource } from "./sql-connection-controller.js";
+import { resolveSqlConnection } from "./sql-connection-ref.js";
+import { currentTxId } from "./transaction-store.js";
+
+interface SqlTransactionManifest {
+  metadata: { name: string; module: string };
+  connection: SqlConnectionResource;
+  steps: Invocable;
+  inputs?: Record<string, unknown>;
+}
+
+export class SqlTransactionResource implements ResourceInstance {
+  constructor(
+    private readonly manifest: SqlTransactionManifest,
+    private readonly ctx: ResourceContext,
+  ) {}
+
+  getConnection(): SqlConnectionResource {
+    return (
+      resolveSqlConnection(this.manifest.connection, this.ctx) ??
+      failMissingConnection(this.manifest.metadata.name)
+    );
+  }
+
+  assertActive(): void {
+    if (!currentTxId()) {
+      throw new Error(
+        `Sql.Transaction '${this.manifest.metadata.name}': used outside an active transaction`,
+      );
+    }
+  }
+
+  async invoke(input: unknown): Promise<unknown> {
+    const m = this.manifest;
+    const ctx = this.ctx;
+
+    // Flat nesting: if already inside a transaction, reuse it
+    if (currentTxId()) {
+      const expandedInputs = ctx.expandValue(m.inputs ?? {}, input ?? {});
+      return m.steps.invoke(expandedInputs);
+    }
+
+    const conn = this.getConnection();
+    const expandedInputs = ctx.expandValue(m.inputs ?? {}, input ?? {});
+
+    return conn.transaction(() => m.steps.invoke(expandedInputs));
+  }
+}
+
+function failMissingConnection(name: string): never {
+  throw new Error(`Sql.Transaction '${name}': missing connection`);
+}
+
+export function register(): void {}
+
+export async function create(
+  resource: SqlTransactionManifest,
+  ctx: ResourceContext,
+): Promise<SqlTransactionResource> {
+  return new SqlTransactionResource(resource, ctx);
+}

package/src/sqlite-driver-bun.ts

@@ -0,0 +1,34 @@
+import { Database } from "bun:sqlite";
+import type { SqliteDb } from "./sqlite-driver-interface.js";
+
+export function openDatabase(file: string): SqliteDb {
+  const db = new Database(file);
+
+  return {
+    prepare(sql: string) {
+      const stmt = db.prepare(sql);
+      return {
+        reader: true,
+        all(params: ReadonlyArray<unknown>) {
+          return stmt.all(...(params as any[]));
+        },
+        run(params: ReadonlyArray<unknown>) {
+          const result = stmt.run(...(params as any[]));
+          return {
+            changes: result.changes,
+            lastInsertRowid: result.lastInsertRowid,
+          };
+        },
+        iterate(params: ReadonlyArray<unknown>) {
+          return stmt.iterate(...(params as any[])) as IterableIterator<unknown>;
+        },
+      };
+    },
+    exec(sql: string) {
+      db.exec(sql);
+    },
+    close() {
+      db.close();
+    },
+  };
+}

package/src/sqlite-driver-interface.ts

@@ -0,0 +1,15 @@
+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/src/sqlite-driver-node.ts

@@ -0,0 +1,35 @@
+import Database from "better-sqlite3";
+import type { SqliteDb } from "./sqlite-driver-interface.js";
+
+export function openDatabase(file: string): SqliteDb {
+  const db = new Database(file);
+
+  return {
+    prepare(sql: string) {
+      const stmt = db.prepare(sql);
+
+      return {
+        reader: stmt.reader,
+        all(params: ReadonlyArray<unknown>) {
+          return stmt.all(...(params as unknown[]));
+        },
+        run(params: ReadonlyArray<unknown>) {
+          const result = stmt.run(...(params as unknown[]));
+          return {
+            changes: result.changes,
+            lastInsertRowid: result.lastInsertRowid,
+          };
+        },
+        iterate(params: ReadonlyArray<unknown>) {
+          return stmt.iterate(...(params as unknown[])) as IterableIterator<unknown>;
+        },
+      };
+    },
+    exec(sql: string) {
+      db.exec(sql);
+    },
+    close() {
+      db.close();
+    },
+  };
+}

package/src/transaction-store.ts

@@ -0,0 +1,20 @@
+import { AsyncLocalStorage } from "async_hooks";
+
+export interface TxEntry {
+  executor: unknown;
+}
+
+const txMap = new Map<string, TxEntry>();
+export const txStorage = new AsyncLocalStorage<string>();
+
+export const setTx = (id: string, entry: TxEntry): void => {
+  txMap.set(id, entry);
+};
+
+export const getTx = (id: string): TxEntry | undefined => txMap.get(id);
+
+export const deleteTx = (id: string): void => {
+  txMap.delete(id);
+};
+
+export const currentTxId = (): string | undefined => txStorage.getStore();