@jordanalec/dtk 1.0.7 → 1.2.0

package/README.md

@@ -286,6 +286,57 @@ AWS credentials are resolved from the environment via the SDK default provider c
 
 ---
 
+### redis
+
+Reads and writes data in a Redis cache.
+
+```bash
+dtk add redis
+```
+
+Env vars appended to `.env.template`:
+
+```
+REDIS_URL=redis://localhost:6379
+```
+
+Usage:
+
+```ts
+await suite()
+  .redis({ url: process.env.REDIS_URL! })
+  .step("write", async (ctx) => {
+    await ctx.services.redis.set("key", "value", 3600);
+  })
+  .step("read", async (ctx) => {
+    const value = await ctx.services.redis.get("key");
+    console.log("value:", value);
+    return value;
+  })
+  .step("disconnect", async (ctx) => {
+    await ctx.services.redis.quit();
+  })
+  .run("stopOnError");
+```
+
+> **The `disconnect` step is required.** The Redis client holds an open TCP connection. Without calling `quit()`, the Node.js process will hang indefinitely after the runbook finishes. Always use `stopOnError` (not `throwOnError`) so that the `disconnect` step is guaranteed to run even when an earlier step fails.
+
+Available methods on `ctx.services.redis`:
+
+| Method | Description |
+|---|---|
+| `get(key)` | Returns the string value or `null` if the key does not exist |
+| `set(key, value, ttlSeconds?)` | Sets a key, with an optional TTL in seconds |
+| `del(key)` | Deletes a key, returns the number of keys removed |
+| `exists(key)` | Returns `true` if the key exists |
+| `expire(key, ttlSeconds)` | Sets a TTL on an existing key, returns `true` if applied |
+| `hset(key, field, value)` | Sets a field on a hash, returns the number of new fields added |
+| `hget(key, field)` | Returns a hash field value or `null` |
+| `keys(pattern)` | Returns all keys matching a glob pattern (e.g. `user:*`) |
+| `quit()` | Closes the connection -- must be called at the end of every runbook |
+
+---
+
 ### open-ai
 
 Lists models and sends responses via the OpenAI API.
@@ -318,6 +369,76 @@ await suite()
 
 ---
 
+### sql
+
+Runs raw SQL queries, executes statements, calls stored procedures, and runs transactions against PostgreSQL, MySQL, or MSSQL via knex.
+
+```bash
+dtk add sql
+```
+
+Env vars appended to `.env.template`:
+
+```
+SQL_CONNECTION_STRING=
+```
+
+Because the sql service holds an open connection pool, it must always be disconnected after use. Create the service outside the suite and call `disconnect()` in a `finally` block so it is guaranteed to run even when a step fails:
+
+```ts
+import "../load-env.js";
+import { suite } from "../suite.js";
+import { createSqlService } from "../services/sql.js";
+
+const sql = createSqlService({
+  client: 'pg', // or 'mysql2' or 'mssql'
+  connection: process.env.SQL_CONNECTION_STRING!,
+});
+
+try {
+  await suite()
+    .step("query", async () => {
+      const rows = await sql.query<{ id: number; name: string }>(
+        "SELECT id, name FROM users WHERE active = ?",
+        [true]
+      );
+      console.log(rows);
+      return rows;
+    })
+    .step("insert", async () => {
+      const affected = await sql.execute(
+        "INSERT INTO users (name, email, active) VALUES (?, ?, ?)",
+        ["Alice", "alice@example.com", true]
+      );
+      console.log("rows inserted:", affected);
+      return affected;
+    })
+    .step("transaction", async () => {
+      await sql.transaction(async (ops) => {
+        await ops.execute("UPDATE accounts SET balance = balance - ? WHERE id = ?", [100, 1]);
+        await ops.execute("UPDATE accounts SET balance = balance + ? WHERE id = ?", [100, 2]);
+      });
+    })
+    .run("stopOnError");
+} finally {
+  await sql.disconnect();
+}
+```
+
+Available methods on the sql service:
+
+| Method | Description |
+|---|---|
+| `query<T>(sql, params?)` | Runs a SELECT and returns the result rows as `T[]` |
+| `execute(sql, params?)` | Runs an INSERT / UPDATE / DELETE and returns the affected row count |
+| `callProc<T>(name, params?)` | Calls a stored procedure and returns result rows as `T[]` |
+| `transaction(fn)` | Runs `fn` inside a transaction; rolls back automatically on error |
+| `disconnect()` | Destroys the connection pool -- always call this in a `finally` block |
+
+Supported clients: `pg` (PostgreSQL), `mysql2` (MySQL / MariaDB), `mssql` (SQL Server).
+
+---
+
 ## Writing runbooks
 
 A runbook is a TypeScript file that uses the `suite()` builder to chain steps and run them in sequence.
@@ -728,4 +849,6 @@ templates/
     aws-dynamo/
     aws-s3/
     open-ai/
+    redis/
+    sql/
 ```

package/dist/add.js

@@ -12,6 +12,8 @@ const PLUGIN_MAP = {
     'aws-dynamo': 'aws-dynamo',
     'aws-s3': 'aws-s3',
     'open-ai': 'open-ai',
+    'redis': 'redis',
+    'sql': 'sql',
 };
 export const addCommand = new Command('add')
     .description('Add a service plugin to the project')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jordanalec/dtk",
-  "version": "1.0.7",
+  "version": "1.2.0",
   "description": "CLI scaffolding tool for generating self-contained TypeScript runbook projects",
   "keywords": [
     "cli",
@@ -45,6 +45,8 @@
     "axios": "^1.6.0",
     "dotenv": "^16.4.0",
     "jest": "^30.3.0",
+    "knex": "^3.1.0",
+    "redis": "^4.7.1",
     "ts-jest": "^29.4.9",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0"

package/templates/init/GUIDE.md

@@ -382,6 +382,57 @@ AWS credentials are picked up automatically from `AWS_ACCESS_KEY_ID` and `AWS_SE
 
 ---
 
+### redis
+
+Reads and writes data in a Redis cache.
+
+```bash
+dtk add redis
+```
+
+Required env vars:
+
+```
+REDIS_URL=redis://localhost:6379
+```
+
+Usage:
+
+```ts
+await suite()
+  .redis({ url: process.env.REDIS_URL! })
+  .step("write", async (ctx) => {
+    await ctx.services.redis.set("key", "value", 3600);
+  })
+  .step("read", async (ctx) => {
+    const value = await ctx.services.redis.get("key");
+    console.log("value:", value);
+    return value;
+  })
+  .step("disconnect", async (ctx) => {
+    await ctx.services.redis.quit();
+  })
+  .run("stopOnError");
+```
+
+> **The `disconnect` step is required.** The Redis client holds an open TCP connection. Without calling `quit()`, the Node.js process will hang indefinitely after the runbook finishes. Always use `stopOnError` (not `throwOnError`) so that the `disconnect` step is guaranteed to run even when an earlier step fails.
+
+Available methods on `ctx.services.redis`:
+
+| Method | Description |
+|---|---|
+| `get(key)` | Returns the string value or `null` if the key does not exist |
+| `set(key, value, ttlSeconds?)` | Sets a key, with an optional TTL in seconds |
+| `del(key)` | Deletes a key, returns the number of keys removed |
+| `exists(key)` | Returns `true` if the key exists |
+| `expire(key, ttlSeconds)` | Sets a TTL on an existing key, returns `true` if applied |
+| `hset(key, field, value)` | Sets a field on a hash, returns the number of new fields added |
+| `hget(key, field)` | Returns a hash field value or `null` |
+| `keys(pattern)` | Returns all keys matching a glob pattern (e.g. `user:*`) |
+| `quit()` | Closes the connection -- must be called at the end of every runbook |
+
+---
+
 ### open-ai
 
 Lists models and sends responses via the OpenAI API.
@@ -410,6 +461,76 @@ await suite()
 
 ---
 
+### sql
+
+Runs raw SQL queries, executes statements, calls stored procedures, and runs transactions against PostgreSQL, MySQL, or MSSQL via knex.
+
+```bash
+dtk add sql
+```
+
+Required env vars:
+
+```
+SQL_CONNECTION_STRING=
+```
+
+Because the sql service holds an open connection pool, it must always be disconnected after use. Create the service outside the suite and call `disconnect()` in a `finally` block so it is guaranteed to run even when a step fails:
+
+```ts
+import "../load-env.js";
+import { suite } from "../suite.js";
+import { createSqlService } from "../services/sql.js";
+
+const sql = createSqlService({
+  client: 'pg', // or 'mysql2' or 'mssql'
+  connection: process.env.SQL_CONNECTION_STRING!,
+});
+
+try {
+  await suite()
+    .step("query", async () => {
+      const rows = await sql.query<{ id: number; name: string }>(
+        "SELECT id, name FROM users WHERE active = ?",
+        [true]
+      );
+      console.log(rows);
+      return rows;
+    })
+    .step("insert", async () => {
+      const affected = await sql.execute(
+        "INSERT INTO users (name, email, active) VALUES (?, ?, ?)",
+        ["Alice", "alice@example.com", true]
+      );
+      console.log("rows inserted:", affected);
+      return affected;
+    })
+    .step("transaction", async () => {
+      await sql.transaction(async (ops) => {
+        await ops.execute("UPDATE accounts SET balance = balance - ? WHERE id = ?", [100, 1]);
+        await ops.execute("UPDATE accounts SET balance = balance + ? WHERE id = ?", [100, 2]);
+      });
+    })
+    .run("stopOnError");
+} finally {
+  await sql.disconnect();
+}
+```
+
+Available methods on the sql service:
+
+| Method | Description |
+|---|---|
+| `query<T>(sql, params?)` | Runs a SELECT and returns the result rows as `T[]` |
+| `execute(sql, params?)` | Runs an INSERT / UPDATE / DELETE and returns the affected row count |
+| `callProc<T>(name, params?)` | Calls a stored procedure and returns result rows as `T[]` |
+| `transaction(fn)` | Runs `fn` inside a transaction; rolls back automatically on error |
+| `disconnect()` | Destroys the connection pool -- always call this in a `finally` block |
+
+Supported clients: `pg` (PostgreSQL), `mysql2` (MySQL / MariaDB), `mssql` (SQL Server).
+
+---
+
 ## Writing a custom service
 
 If there is no plugin for the service you need, wire one in manually. Four files are involved.

package/templates/init/README.md

@@ -37,7 +37,7 @@ Install the dtk CLI if you haven't already, then run from this directory:
 dtk add <plugin>
 ```
 
-Available plugins: `aws-sqs`, `aws-sns`, `aws-dynamo`, `aws-s3`, `open-ai`
+Available plugins: `aws-sqs`, `aws-sns`, `aws-dynamo`, `aws-s3`, `open-ai`, `redis`, `sql`
 
 Each plugin adds a service, wires it into the suite, appends env vars to `.env.template`, creates an example runbook, and installs dependencies automatically.
 

package/templates/plugins/redis/env.txt

@@ -0,0 +1 @@
+REDIS_URL=

package/templates/plugins/redis/example.ts

@@ -0,0 +1,37 @@
+import "../load-env.js";
+import { suite } from "../suite.js";
+
+await suite()
+  .redis({
+    url: process.env.REDIS_URL!,
+  })
+  .step("write-session", async (ctx) => {
+    await ctx.services.redis.set("session:abc123", JSON.stringify({ userId: 42, role: "admin" }), 3600);
+    console.log("session written with 1h TTL");
+  })
+  .step("read-session", async (ctx) => {
+    const raw = await ctx.services.redis.get("session:abc123");
+    const session = raw ? JSON.parse(raw) : null;
+    console.log("session:", session);
+    return session;
+  })
+  .step("check-existence", async (ctx) => {
+    const exists = await ctx.services.redis.exists("session:abc123");
+    console.log("session exists:", exists);
+    return exists;
+  })
+  .step("hash-metadata", async (ctx) => {
+    await ctx.services.redis.hset("user:42", "lastSeen", new Date().toISOString());
+    const lastSeen = await ctx.services.redis.hget("user:42", "lastSeen");
+    console.log("user:42 lastSeen:", lastSeen);
+    return lastSeen;
+  })
+  .step("list-session-keys", async (ctx) => {
+    const keys = await ctx.services.redis.keys("session:*");
+    console.log("active sessions:", keys);
+    return keys;
+  })
+  .step("disconnect", async (ctx) => {
+    await ctx.services.redis.quit();
+  })
+  .run("stopOnError");

package/templates/plugins/redis/plugin.json

@@ -0,0 +1,36 @@
+{
+  "name": "redis",
+  "description": "Redis -- get, set, del, exists, expire, hset, hget, keys",
+  "dependencies": {
+    "redis": "^4.7.0"
+  },
+  "files": [
+    { "src": "service.ts", "dest": "src/services/redis.ts" },
+    { "src": "types.ts", "dest": "src/types/redis.ts" },
+    { "src": "service.test.ts", "dest": "src/services/redis.test.ts" }
+  ],
+  "env": "env.txt",
+  "example": "example.ts",
+  "transforms": {
+    "service.ts": [
+      { "from": "./types.js", "to": "../types/redis.js" }
+    ],
+    "service.test.ts": [
+      { "from": "./service.js", "to": "./redis.js" }
+    ]
+  },
+  "patches": {
+    "src/suite.ts": {
+      "imports": [
+        "import { createRedisService } from \"./services/redis.js\";",
+        "import type { RedisConfig } from \"./types/redis.js\";"
+      ],
+      "configs": "  private redisConfig?: RedisConfig;",
+      "methods": "  redis(config: RedisConfig): this { this.redisConfig = config; return this; }",
+      "services": "        redis: createRedisService(this.redisConfig),"
+    },
+    "src/types/suite.ts": {
+      "service-types": "    redis: { get(key: string): Promise<string | null>; set(key: string, value: string, ttlSeconds?: number): Promise<void>; del(key: string): Promise<number>; exists(key: string): Promise<boolean>; expire(key: string, ttlSeconds: number): Promise<boolean>; hset(key: string, field: string, value: string): Promise<number>; hget(key: string, field: string): Promise<string | null>; keys(pattern: string): Promise<string[]>; quit(): Promise<void>; };"
+    }
+  }
+}

package/templates/plugins/redis/service.test.ts

@@ -0,0 +1,149 @@
+import { createRedisService } from './service.js';
+
+jest.mock('redis');
+import { createClient } from 'redis';
+
+const mockClient = {
+  connect: jest.fn().mockResolvedValue(undefined),
+  get: jest.fn(),
+  set: jest.fn().mockResolvedValue('OK'),
+  del: jest.fn(),
+  exists: jest.fn(),
+  expire: jest.fn(),
+  hSet: jest.fn(),
+  hGet: jest.fn(),
+  keys: jest.fn(),
+  quit: jest.fn().mockResolvedValue(undefined),
+};
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  (createClient as jest.Mock).mockReturnValue(mockClient);
+  mockClient.connect.mockResolvedValue(undefined);
+});
+
+describe('createRedisService', () => {
+  const config = { url: 'redis://localhost:6379' };
+
+  it('connects to redis using the provided url', async () => {
+    mockClient.get.mockResolvedValue('value');
+    const redis = createRedisService(config);
+    await redis.get('key');
+    expect(createClient).toHaveBeenCalledWith({ url: config.url });
+    expect(mockClient.connect).toHaveBeenCalledTimes(1);
+  });
+
+  it('reuses the same client across multiple calls', async () => {
+    mockClient.get.mockResolvedValue('value');
+    const redis = createRedisService(config);
+    await redis.get('key1');
+    await redis.get('key2');
+    expect(mockClient.connect).toHaveBeenCalledTimes(1);
+  });
+
+  it('get returns the value for an existing key', async () => {
+    mockClient.get.mockResolvedValue('hello');
+    const redis = createRedisService(config);
+    const result = await redis.get('greeting');
+    expect(result).toBe('hello');
+    expect(mockClient.get).toHaveBeenCalledWith('greeting');
+  });
+
+  it('get returns null for a missing key', async () => {
+    mockClient.get.mockResolvedValue(null);
+    const redis = createRedisService(config);
+    const result = await redis.get('missing');
+    expect(result).toBeNull();
+  });
+
+  it('set calls client.set without EX when no ttl is given', async () => {
+    const redis = createRedisService(config);
+    await redis.set('key', 'value');
+    expect(mockClient.set).toHaveBeenCalledWith('key', 'value');
+  });
+
+  it('set calls client.set with EX option when ttl is given', async () => {
+    const redis = createRedisService(config);
+    await redis.set('key', 'value', 60);
+    expect(mockClient.set).toHaveBeenCalledWith('key', 'value', { EX: 60 });
+  });
+
+  it('del returns the number of deleted keys', async () => {
+    mockClient.del.mockResolvedValue(1);
+    const redis = createRedisService(config);
+    const result = await redis.del('key');
+    expect(result).toBe(1);
+    expect(mockClient.del).toHaveBeenCalledWith('key');
+  });
+
+  it('exists returns true when key is present', async () => {
+    mockClient.exists.mockResolvedValue(1);
+    const redis = createRedisService(config);
+    const result = await redis.exists('key');
+    expect(result).toBe(true);
+  });
+
+  it('exists returns false when key is absent', async () => {
+    mockClient.exists.mockResolvedValue(0);
+    const redis = createRedisService(config);
+    const result = await redis.exists('missing');
+    expect(result).toBe(false);
+  });
+
+  it('expire returns true when the timeout was set', async () => {
+    mockClient.expire.mockResolvedValue(true);
+    const redis = createRedisService(config);
+    const result = await redis.expire('key', 300);
+    expect(result).toBe(true);
+    expect(mockClient.expire).toHaveBeenCalledWith('key', 300);
+  });
+
+  it('hset returns the number of new fields added', async () => {
+    mockClient.hSet.mockResolvedValue(1);
+    const redis = createRedisService(config);
+    const result = await redis.hset('hash', 'field', 'value');
+    expect(result).toBe(1);
+    expect(mockClient.hSet).toHaveBeenCalledWith('hash', 'field', 'value');
+  });
+
+  it('hget returns the field value', async () => {
+    mockClient.hGet.mockResolvedValue('stored');
+    const redis = createRedisService(config);
+    const result = await redis.hget('hash', 'field');
+    expect(result).toBe('stored');
+  });
+
+  it('hget returns null when field is undefined', async () => {
+    mockClient.hGet.mockResolvedValue(undefined);
+    const redis = createRedisService(config);
+    const result = await redis.hget('hash', 'missing');
+    expect(result).toBeNull();
+  });
+
+  it('keys returns matching key names', async () => {
+    mockClient.keys.mockResolvedValue(['user:1', 'user:2']);
+    const redis = createRedisService(config);
+    const result = await redis.keys('user:*');
+    expect(result).toEqual(['user:1', 'user:2']);
+    expect(mockClient.keys).toHaveBeenCalledWith('user:*');
+  });
+
+  it('quit disconnects the client and clears it', async () => {
+    mockClient.get.mockResolvedValue('value');
+    mockClient.quit = jest.fn().mockResolvedValue(undefined);
+    const redis = createRedisService(config);
+    await redis.get('key');
+    await redis.quit();
+    expect(mockClient.quit).toHaveBeenCalledTimes(1);
+  });
+
+  it('quit is a no-op when client was never connected', async () => {
+    const redis = createRedisService(config);
+    await expect(redis.quit()).resolves.toBeUndefined();
+  });
+
+  it('throws when any method is called without config', async () => {
+    const redis = createRedisService();
+    await expect(redis.get('key')).rejects.toThrow('redis service is not configured');
+  });
+});

package/templates/plugins/redis/service.ts

@@ -0,0 +1,66 @@
+import { createClient } from "redis";
+import type { RedisConfig } from "./types.js";
+
+export function createRedisService(config?: RedisConfig) {
+  const ensureConfig = () => {
+    if (!config) throw new Error("redis service is not configured -- call .redis(config) on the suite");
+  };
+
+  let client: ReturnType<typeof createClient> | null = null;
+
+  const getClient = async () => {
+    ensureConfig();
+    if (!client) {
+      client = createClient({ url: config!.url });
+      await client.connect();
+    }
+    return client;
+  };
+
+  return {
+    get: async (key: string): Promise<string | null> => {
+      const c = await getClient();
+      return c.get(key);
+    },
+    set: async (key: string, value: string, ttlSeconds?: number): Promise<void> => {
+      const c = await getClient();
+      if (ttlSeconds !== undefined) {
+        await c.set(key, value, { EX: ttlSeconds });
+      } else {
+        await c.set(key, value);
+      }
+    },
+    del: async (key: string): Promise<number> => {
+      const c = await getClient();
+      return c.del(key);
+    },
+    exists: async (key: string): Promise<boolean> => {
+      const c = await getClient();
+      const count = await c.exists(key);
+      return count > 0;
+    },
+    expire: async (key: string, ttlSeconds: number): Promise<boolean> => {
+      const c = await getClient();
+      return c.expire(key, ttlSeconds);
+    },
+    hset: async (key: string, field: string, value: string): Promise<number> => {
+      const c = await getClient();
+      return c.hSet(key, field, value);
+    },
+    hget: async (key: string, field: string): Promise<string | null> => {
+      const c = await getClient();
+      const result = await c.hGet(key, field);
+      return result ?? null;
+    },
+    keys: async (pattern: string): Promise<string[]> => {
+      const c = await getClient();
+      return c.keys(pattern);
+    },
+    quit: async (): Promise<void> => {
+      if (client) {
+        await client.quit();
+        client = null;
+      }
+    },
+  };
+}

package/templates/plugins/redis/types.ts

@@ -0,0 +1,3 @@
+export interface RedisConfig {
+  url: string;
+}

package/templates/plugins/sql/env.txt

@@ -0,0 +1 @@
+SQL_CONNECTION_STRING=

package/templates/plugins/sql/example.ts

@@ -0,0 +1,49 @@
+import "../load-env.js";
+import { suite } from "../suite.js";
+import { createSqlService } from "../services/sql.js";
+
+type User = { id: number; name: string; email: string; };
+type TransferResult = { status: string; };
+
+const sql = createSqlService({
+  client: 'pg', // change to 'mysql2' or 'mssql' as needed
+  connection: process.env.SQL_CONNECTION_STRING!,
+});
+
+try {
+  await suite()
+    .step("query-users", async () => {
+      const users = await sql.query<User>(
+        "SELECT id, name, email FROM users WHERE active = ?",
+        [true]
+      );
+      console.log("active users:", users);
+      return users;
+    })
+    .step("insert-user", async () => {
+      const affected = await sql.execute(
+        "INSERT INTO users (name, email, active) VALUES (?, ?, ?)",
+        ["Alice", "alice@example.com", true]
+      );
+      console.log("rows inserted:", affected);
+      return affected;
+    })
+    .step("call-stored-proc", async () => {
+      const result = await sql.callProc<TransferResult>(
+        "usp_activate_user",
+        [42]
+      );
+      console.log("proc result:", result);
+      return result;
+    })
+    .step("transfer-in-transaction", async () => {
+      await sql.transaction(async (ops) => {
+        await ops.execute("UPDATE accounts SET balance = balance - ? WHERE id = ?", [100, 1]);
+        await ops.execute("UPDATE accounts SET balance = balance + ? WHERE id = ?", [100, 2]);
+      });
+      console.log("transfer complete");
+    })
+    .run("stopOnError");
+} finally {
+  await sql.disconnect();
+}

package/templates/plugins/sql/plugin.json

@@ -0,0 +1,40 @@
+{
+  "name": "sql",
+  "description": "SQL -- query, execute, callProc, transaction across pg / mysql2 / mssql",
+  "dependencies": {
+    "knex": "^3.1.0",
+    "pg": "^8.13.0",
+    "mysql2": "^3.11.0",
+    "mssql": "^11.0.1"
+  },
+  "files": [
+    { "src": "service.ts", "dest": "src/services/sql.ts" },
+    { "src": "types.ts", "dest": "src/types/sql.ts" },
+    { "src": "service.test.ts", "dest": "src/services/sql.test.ts" }
+  ],
+  "env": "env.txt",
+  "example": "example.ts",
+  "transforms": {
+    "service.ts": [
+      { "from": "./types.js", "to": "../types/sql.js" }
+    ],
+    "service.test.ts": [
+      { "from": "./service.js", "to": "./sql.js" }
+    ]
+  },
+  "patches": {
+    "src/suite.ts": {
+      "imports": [
+        "import { createSqlService } from \"./services/sql.js\";",
+        "import type { SqlConfig } from \"./types/sql.js\";"
+      ],
+      "configs": "  private sqlConfig?: SqlConfig;",
+      "methods": "  sql(config: SqlConfig): this { this.sqlConfig = config; return this; }",
+      "services": "        sql: createSqlService(this.sqlConfig),"
+    },
+    "src/types/suite.ts": {
+      "type-imports": "import type { SqlOps } from \"./sql.js\";",
+      "service-types": "    sql: { query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>; execute(sql: string, params?: unknown[]): Promise<number>; callProc<T = Record<string, unknown>>(name: string, params?: unknown[]): Promise<T[]>; transaction<T>(fn: (ops: SqlOps) => Promise<T>): Promise<T>; disconnect(): Promise<void>; };"
+    }
+  }
+}

package/templates/plugins/sql/service.test.ts

@@ -0,0 +1,224 @@
+import { createSqlService } from './service.js';
+
+jest.mock('knex');
+import knexLib from 'knex';
+
+const mockTrxRaw = jest.fn();
+const mockTrx = { raw: mockTrxRaw };
+
+const mockRaw = jest.fn();
+const mockDestroy = jest.fn().mockResolvedValue(undefined);
+const mockTransaction = jest.fn();
+
+const mockDb = {
+  raw: mockRaw,
+  destroy: mockDestroy,
+  transaction: mockTransaction,
+};
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  (knexLib as unknown as jest.Mock).mockReturnValue(mockDb);
+  mockDestroy.mockResolvedValue(undefined);
+});
+
+describe('createSqlService', () => {
+  describe('configuration', () => {
+    it('throws when any method is called without config', async () => {
+      const sql = createSqlService();
+      await expect(sql.query('SELECT 1')).rejects.toThrow('sql service is not configured');
+    });
+
+    it('creates a knex instance with the provided client and connection', async () => {
+      mockRaw.mockResolvedValue({ rows: [] });
+      const sql = createSqlService({ client: 'pg', connection: 'postgresql://localhost/test' });
+      await sql.query('SELECT 1');
+      expect(knexLib).toHaveBeenCalledWith({ client: 'pg', connection: 'postgresql://localhost/test' });
+    });
+
+    it('reuses the same knex instance across multiple calls', async () => {
+      mockRaw.mockResolvedValue({ rows: [] });
+      const sql = createSqlService({ client: 'pg', connection: 'postgresql://localhost/test' });
+      await sql.query('SELECT 1');
+      await sql.query('SELECT 2');
+      expect(knexLib).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('query', () => {
+    it('returns result.rows for pg', async () => {
+      mockRaw.mockResolvedValue({ rows: [{ id: 1 }] });
+      const sql = createSqlService({ client: 'pg', connection: '' });
+      const result = await sql.query('SELECT * FROM users');
+      expect(result).toEqual([{ id: 1 }]);
+    });
+
+    it('returns result[0] for mysql2', async () => {
+      mockRaw.mockResolvedValue([[{ id: 1 }], []]);
+      const sql = createSqlService({ client: 'mysql2', connection: '' });
+      const result = await sql.query('SELECT * FROM users');
+      expect(result).toEqual([{ id: 1 }]);
+    });
+
+    it('returns result[0] for mssql', async () => {
+      mockRaw.mockResolvedValue([[{ id: 1 }]]);
+      const sql = createSqlService({ client: 'mssql', connection: '' });
+      const result = await sql.query('SELECT * FROM users');
+      expect(result).toEqual([{ id: 1 }]);
+    });
+
+    it('passes sql and params to raw', async () => {
+      mockRaw.mockResolvedValue({ rows: [] });
+      const sql = createSqlService({ client: 'pg', connection: '' });
+      await sql.query('SELECT * FROM users WHERE id = ?', [42]);
+      expect(mockRaw).toHaveBeenCalledWith('SELECT * FROM users WHERE id = ?', [42]);
+    });
+
+    it('defaults params to empty array when omitted', async () => {
+      mockRaw.mockResolvedValue({ rows: [] });
+      const sql = createSqlService({ client: 'pg', connection: '' });
+      await sql.query('SELECT 1');
+      expect(mockRaw).toHaveBeenCalledWith('SELECT 1', []);
+    });
+  });
+
+  describe('execute', () => {
+    it('returns rowCount for pg', async () => {
+      mockRaw.mockResolvedValue({ rowCount: 3 });
+      const sql = createSqlService({ client: 'pg', connection: '' });
+      const result = await sql.execute('DELETE FROM users WHERE active = ?', [false]);
+      expect(result).toBe(3);
+    });
+
+    it('returns affectedRows for mysql2', async () => {
+      mockRaw.mockResolvedValue([{ affectedRows: 2 }]);
+      const sql = createSqlService({ client: 'mysql2', connection: '' });
+      const result = await sql.execute('UPDATE users SET active = ?', [true]);
+      expect(result).toBe(2);
+    });
+
+    it('returns rowsAffected[0] for mssql', async () => {
+      mockRaw.mockResolvedValue({ rowsAffected: [5] });
+      const sql = createSqlService({ client: 'mssql', connection: '' });
+      const result = await sql.execute('INSERT INTO logs (msg) VALUES (?)', ['test']);
+      expect(result).toBe(5);
+    });
+
+    it('returns 0 when pg rowCount is null', async () => {
+      mockRaw.mockResolvedValue({ rowCount: null });
+      const sql = createSqlService({ client: 'pg', connection: '' });
+      const result = await sql.execute('SELECT 1');
+      expect(result).toBe(0);
+    });
+  });
+
+  describe('callProc', () => {
+    it('uses CALL syntax for pg', async () => {
+      mockRaw.mockResolvedValue({ rows: [] });
+      const sql = createSqlService({ client: 'pg', connection: '' });
+      await sql.callProc('my_proc', [1, 'test']);
+      expect(mockRaw).toHaveBeenCalledWith('CALL my_proc(?, ?)', [1, 'test']);
+    });
+
+    it('uses CALL syntax for mysql2', async () => {
+      mockRaw.mockResolvedValue([[[]], {}]);
+      const sql = createSqlService({ client: 'mysql2', connection: '' });
+      await sql.callProc('my_proc', [1]);
+      expect(mockRaw).toHaveBeenCalledWith('CALL my_proc(?)', [1]);
+    });
+
+    it('uses EXEC syntax for mssql', async () => {
+      mockRaw.mockResolvedValue([[{ result: 1 }]]);
+      const sql = createSqlService({ client: 'mssql', connection: '' });
+      await sql.callProc('usp_my_proc', [1, 2]);
+      expect(mockRaw).toHaveBeenCalledWith('EXEC usp_my_proc ?, ?', [1, 2]);
+    });
+
+    it('uses EXEC without params for mssql when no params given', async () => {
+      mockRaw.mockResolvedValue([[{ result: 1 }]]);
+      const sql = createSqlService({ client: 'mssql', connection: '' });
+      await sql.callProc('usp_my_proc');
+      expect(mockRaw).toHaveBeenCalledWith('EXEC usp_my_proc', []);
+    });
+
+    it('returns result.rows for pg', async () => {
+      mockRaw.mockResolvedValue({ rows: [{ status: 'ok' }] });
+      const sql = createSqlService({ client: 'pg', connection: '' });
+      const result = await sql.callProc('my_proc', []);
+      expect(result).toEqual([{ status: 'ok' }]);
+    });
+
+    it('returns result[0] for mssql', async () => {
+      mockRaw.mockResolvedValue([[{ status: 'ok' }]]);
+      const sql = createSqlService({ client: 'mssql', connection: '' });
+      const result = await sql.callProc('usp_my_proc', []);
+      expect(result).toEqual([{ status: 'ok' }]);
+    });
+
+    it('returns the first result set for mysql2', async () => {
+      mockRaw.mockResolvedValue([[[{ status: 'ok' }], {}], []]);
+      const sql = createSqlService({ client: 'mysql2', connection: '' });
+      const result = await sql.callProc('my_proc', []);
+      expect(result).toEqual([{ status: 'ok' }]);
+    });
+  });
+
+  describe('transaction', () => {
+    it('calls knex transaction and passes SqlOps to fn', async () => {
+      mockTrxRaw.mockResolvedValue({ rows: [{ id: 1 }] });
+      mockTransaction.mockImplementation((fn: (trx: typeof mockTrx) => Promise<unknown>) => fn(mockTrx));
+
+      const sql = createSqlService({ client: 'pg', connection: '' });
+      const result = await sql.transaction(async (ops) => ops.query('SELECT 1'));
+
+      expect(mockTransaction).toHaveBeenCalledTimes(1);
+      expect(result).toEqual([{ id: 1 }]);
+    });
+
+    it('ops.execute within transaction uses the transaction executor', async () => {
+      mockTrxRaw.mockResolvedValue({ rowCount: 2 });
+      mockTransaction.mockImplementation((fn: (trx: typeof mockTrx) => Promise<unknown>) => fn(mockTrx));
+
+      const sql = createSqlService({ client: 'pg', connection: '' });
+      const affected = await sql.transaction(async (ops) => ops.execute('DELETE FROM tmp'));
+
+      expect(mockTrxRaw).toHaveBeenCalledWith('DELETE FROM tmp', []);
+      expect(affected).toBe(2);
+    });
+
+    it('ops.callProc within transaction uses the transaction executor', async () => {
+      mockTrxRaw.mockResolvedValue({ rows: [] });
+      mockTransaction.mockImplementation((fn: (trx: typeof mockTrx) => Promise<unknown>) => fn(mockTrx));
+
+      const sql = createSqlService({ client: 'pg', connection: '' });
+      await sql.transaction(async (ops) => ops.callProc('my_proc', [1]));
+
+      expect(mockTrxRaw).toHaveBeenCalledWith('CALL my_proc(?)', [1]);
+    });
+  });
+
+  describe('disconnect', () => {
+    it('destroys the knex instance and clears the reference', async () => {
+      mockRaw.mockResolvedValue({ rows: [] });
+      const sql = createSqlService({ client: 'pg', connection: '' });
+      await sql.query('SELECT 1');
+      await sql.disconnect();
+      expect(mockDestroy).toHaveBeenCalledTimes(1);
+    });
+
+    it('is a no-op when never connected', async () => {
+      const sql = createSqlService({ client: 'pg', connection: '' });
+      await expect(sql.disconnect()).resolves.toBeUndefined();
+      expect(mockDestroy).not.toHaveBeenCalled();
+    });
+
+    it('creates a new knex instance after reconnecting following disconnect', async () => {
+      mockRaw.mockResolvedValue({ rows: [] });
+      const sql = createSqlService({ client: 'pg', connection: '' });
+      await sql.query('SELECT 1');
+      await sql.disconnect();
+      await sql.query('SELECT 1');
+      expect(knexLib).toHaveBeenCalledTimes(2);
+    });
+  });
+});

package/templates/plugins/sql/service.ts

@@ -0,0 +1,87 @@
+import knex, { Knex } from 'knex';
+import type { SqlConfig, SqlOps } from './types.js';
+
+export function createSqlService(config?: SqlConfig) {
+  const ensureConfig = () => {
+    if (!config) throw new Error("sql service is not configured -- call .sql(config) on the suite");
+  };
+
+  let db: Knex | null = null;
+
+  const getDb = (): Knex => {
+    ensureConfig();
+    if (!db) {
+      db = knex({ client: config!.client, connection: config!.connection });
+    }
+    return db;
+  };
+
+  const extractRows = <T>(result: unknown): T[] => {
+    if (config!.client === 'pg') return (result as { rows: T[] }).rows;
+    return ((result as unknown[])[0] as T[]) ?? [];
+  };
+
+  const extractAffected = (result: unknown): number => {
+    if (config!.client === 'pg') return (result as { rowCount: number }).rowCount ?? 0;
+    if (config!.client === 'mssql') return (result as { rowsAffected: number[] }).rowsAffected?.[0] ?? 0;
+    return ((result as [{ affectedRows: number }])[0]?.affectedRows) ?? 0;
+  };
+
+  const buildCallSql = (name: string, params: unknown[]): string => {
+    const placeholders = params.map(() => '?').join(', ');
+    return config!.client === 'mssql'
+      ? `EXEC ${name}${params.length ? ` ${placeholders}` : ''}`
+      : `CALL ${name}(${placeholders})`;
+  };
+
+  const extractProcRows = <T>(result: unknown): T[] => {
+    if (config!.client === 'pg') return (result as { rows: T[] }).rows;
+    if (config!.client === 'mssql') return ((result as unknown[])[0] as T[]) ?? [];
+    // mysql2 procs return [[resultSet, OkPacket], fields] -- first element of resultSet is the rows
+    const first = ((result as unknown[][])[0])?.[0];
+    return (Array.isArray(first) ? first : (result as unknown[])[0]) as T[];
+  };
+
+  const bind = (params?: unknown[]) => (params ?? []) as any[];
+
+  const makeOps = (executor: Knex | Knex.Transaction): SqlOps => ({
+    async query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]> {
+      const result = await executor.raw(sql, bind(params));
+      return extractRows<T>(result);
+    },
+    async execute(sql: string, params?: unknown[]): Promise<number> {
+      const result = await executor.raw(sql, bind(params));
+      return extractAffected(result);
+    },
+    async callProc<T = Record<string, unknown>>(name: string, params?: unknown[]): Promise<T[]> {
+      const bound = bind(params);
+      const result = await executor.raw(buildCallSql(name, bound), bound);
+      return extractProcRows<T>(result);
+    },
+  });
+
+  return {
+    async query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]> {
+      const result = await getDb().raw(sql, bind(params));
+      return extractRows<T>(result);
+    },
+    async execute(sql: string, params?: unknown[]): Promise<number> {
+      const result = await getDb().raw(sql, bind(params));
+      return extractAffected(result);
+    },
+    async callProc<T = Record<string, unknown>>(name: string, params?: unknown[]): Promise<T[]> {
+      const bound = bind(params);
+      const result = await getDb().raw(buildCallSql(name, bound), bound);
+      return extractProcRows<T>(result);
+    },
+    async transaction<T>(fn: (ops: SqlOps) => Promise<T>): Promise<T> {
+      return getDb().transaction(trx => fn(makeOps(trx)));
+    },
+    async disconnect(): Promise<void> {
+      if (db) {
+        await db.destroy();
+        db = null;
+      }
+    },
+  };
+}

package/templates/plugins/sql/types.ts

@@ -0,0 +1,10 @@
+export interface SqlConfig {
+  client: 'pg' | 'mysql2' | 'mssql';
+  connection: string | Record<string, unknown>;
+}
+
+export interface SqlOps {
+  query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+  execute(sql: string, params?: unknown[]): Promise<number>;
+  callProc<T = Record<string, unknown>>(name: string, params?: unknown[]): Promise<T[]>;
+}