@maestro-js/db 1.0.0-alpha.0

package/README.md

@@ -0,0 +1,386 @@
+# @maestro-js/db
+
+## Overview
+
+The `@maestro-js/db` package provides typed database access through the Maestro provider pattern. It wraps `mysql2` connection pools with parameterized query methods, automatic transactions, streaming result sets with backpressure, and structured logging. All queries use raw parameterized SQL -- there is no ORM.
+
+## Quick Setup
+
+```ts
+import { Db } from '@maestro-js/db'
+import { Log } from '@maestro-js/log'
+
+Db.Provider.register('default', Db.Provider.create({
+  driver: Db.drivers.mysql({
+    host: process.env.DB_HOST!,
+    user: process.env.DB_USER!,
+    password: process.env.DB_PASSWORD!,
+    database: process.env.DB_DATABASE!,
+    port: Number(process.env.DB_PORT ?? 3306)
+  })
+}))
+
+// Query immediately
+const users = await Db.select<User>('SELECT * FROM users WHERE active = ?', [true])
+```
+
+## Driver: MySQL (mysql2)
+
+The only built-in driver. Created via `Db.drivers.mysql(config)`.
+
+### Configuration
+
+```ts
+Db.drivers.mysql({
+  // Required
+  host: 'localhost',
+  user: 'root',
+  password: '',          // empty string is allowed, but the field is required
+  database: 'myapp',
+  port: 3306,
+
+  // Optional
+  connectionLimit: 10,   // max pool connections (default: 10)
+  debug: false,
+  multipleStatements: false,
+  ssl: undefined,        // string or tls.SecureContextOptions
+
+  // Optional loggers (default: Log.create())
+  connectionLogger: Log.create(),  // logs connection lifecycle events
+  queryLogger: Log.create()        // logs query start/complete/fail and transaction events
+})
+```
+
+### Type Casting
+
+The MySQL driver automatically casts:
+- `DATE` columns to ISO date strings
+- `TIME` columns to `iso-fns` time objects
+- `DATETIME` columns to ISO 8601 strings (UTC)
+- `TINYINT(1)` columns to booleans (`true`/`false`), with `null` preserved for nullable columns
+- JSON columns returned as strings (`jsonStrings: true`)
+- Decimal columns returned as numbers (`decimalNumbers: true`)
+
+### Connection Behavior
+
+- Pool uses `utf8mb4_0900_ai_ci` charset (MySQL 8.0+ default)
+- Connect timeout: 60 minutes
+- Connections are acquired with retry (up to 10 attempts, 1s delay)
+- Deadlock and lock-timeout errors are retried automatically (up to 3 attempts) for non-transaction queries
+
+## API Reference
+
+### select
+
+Execute a SELECT query and return typed results as an array.
+
+```ts
+select<T = Record<string, unknown>>(query: string, parameters?: any[]): Promise<T[]>
+```
+
+```ts
+interface User { id: number; name: string; active: boolean }
+
+const admins = await Db.select<User>('SELECT * FROM users WHERE role = ?', ['admin'])
+// [{ id: 1, name: 'Alice', active: true }, { id: 2, name: 'Bob', active: true }]
+```
+
+### selectIterable
+
+Execute a SELECT query and return a streaming async iterable with backpressure support. Uses `Helpers.AsyncIterableCollection` which provides `map`, `filter`, and `toArray` chainable methods.
+
+```ts
+selectIterable<T = Record<string, unknown>>(query: string, parameters?: any[]): Helpers.AsyncIterableCollection<T>
+```
+
+```ts
+const orders = Db.selectIterable<Order>('SELECT * FROM orders WHERE status = ?', ['pending'])
+
+for await (const order of orders) {
+  await processOrder(order)
+}
+
+// Or with chaining
+const names = await Db.selectIterable<User>('SELECT * FROM users')
+  .filter(user => user.active)
+  .map(user => user.name)
+  .toArray()
+```
+
+Backpressure: the driver pauses the MySQL connection when the internal row queue exceeds 3000 rows and resumes when it drains below that threshold.
+
+### insert
+
+Execute an INSERT query and return the affected row count and auto-increment ID.
+
+```ts
+insert(query: string, parameters?: any[]): Promise<{ affectedRows: number; insertId: number }>
+```
+
+```ts
+const { insertId } = await Db.insert(
+  'INSERT INTO users (name, email) VALUES (?, ?)',
+  ['Alice', 'alice@example.com']
+)
+// insertId: 42
+```
+
+### update
+
+Execute an UPDATE query and return matched and changed row counts.
+
+```ts
+update(query: string, parameters?: any[]): Promise<{ affectedRows: number; changedRows: number }>
+```
+
+```ts
+const { changedRows } = await Db.update(
+  'UPDATE users SET active = ? WHERE last_login < ?',
+  [false, '2024-01-01']
+)
+// changedRows: 15
+```
+
+### delete
+
+Execute a DELETE query and return the number of removed rows.
+
+```ts
+delete(query: string, parameters?: any[]): Promise<{ affectedRows: number }>
+```
+
+```ts
+const { affectedRows } = await Db.delete(
+  'DELETE FROM sessions WHERE expires_at < ?',
+  [new Date().toISOString()]
+)
+```
+
+### scalar
+
+Return the first column of the first row, or `null` if no results. Returns `null` both when the query returns zero rows and when the value itself is SQL NULL.
+
+```ts
+scalar<T = unknown>(query: string, parameters?: any[]): Promise<T | null>
+```
+
+```ts
+const count = await Db.scalar<number>('SELECT COUNT(*) FROM users WHERE active = ?', [true])
+// 42
+
+const name = await Db.scalar<string>('SELECT name FROM users WHERE id = ?', [999])
+// null (no matching row)
+```
+
+### statement
+
+Execute an arbitrary SQL statement and return the raw result. Use for DDL or other statements that do not fit the typed methods.
+
+```ts
+statement<T = unknown>(query: string, parameters?: any[]): Promise<T>
+```
+
+```ts
+await Db.statement('CREATE INDEX idx_users_email ON users (email)')
+```
+
+### transaction
+
+Wrap a callback in BEGIN/COMMIT/ROLLBACK. All `Db` calls awaited inside the callback share the same connection via `AsyncLocalStorage`. Nested transaction calls reuse the outer transaction (no savepoints).
+
+```ts
+transaction<T>(callback: () => Promise<T>): Promise<T>
+```
+
+```ts
+await Db.transaction(async () => {
+  await Db.update('UPDATE accounts SET balance = balance - ? WHERE id = ?', [100, fromId])
+  await Db.update('UPDATE accounts SET balance = balance + ? WHERE id = ?', [100, toId])
+})
+// Both updates commit together; if either throws, both roll back
+```
+
+### format
+
+Interpolate parameters into a query string for debugging. Does not execute the query.
+
+```ts
+format(query: string, params?: any[]): string
+```
+
+```ts
+const sql = Db.format('SELECT * FROM users WHERE id = ?', [42])
+// "SELECT * FROM users WHERE id = 42"
+```
+
+### destroy
+
+Close all connections in the pool and prevent new ones from being created.
+
+```ts
+destroy(): Promise<void>
+```
+
+## Common Patterns
+
+### Parameterized Queries
+
+Always use `?` placeholders. Never interpolate values into SQL strings.
+
+```ts
+// Correct
+const users = await Db.select<User>('SELECT * FROM users WHERE name = ?', ['Alice'])
+
+// WRONG - SQL injection risk
+const users = await Db.select<User>(`SELECT * FROM users WHERE name = '${name}'`)
+```
+
+### Avoid Table Name Aliases
+
+Write full table names in SQL queries instead of aliases when possible.
+
+```ts
+// Preferred
+await Db.select('SELECT users.name, orders.total FROM users JOIN orders ON orders.user_id = users.id')
+
+// Avoid
+await Db.select('SELECT u.name, o.total FROM users u JOIN orders o ON o.user_id = u.id')
+```
+
+### Transactions with Error Handling
+
+```ts
+try {
+  const orderId = await Db.transaction(async () => {
+    const { insertId } = await Db.insert(
+      'INSERT INTO orders (user_id, total) VALUES (?, ?)',
+      [userId, total]
+    )
+    await Db.insert(
+      'INSERT INTO order_items (order_id, product_id, quantity) VALUES (?, ?, ?)',
+      [insertId, productId, quantity]
+    )
+    await Db.update(
+      'UPDATE products SET stock = stock - ? WHERE id = ?',
+      [quantity, productId]
+    )
+    return insertId
+  })
+} catch (e) {
+  // All three statements rolled back
+}
+```
+
+### Streaming Large Result Sets
+
+Use `selectIterable` for queries returning many rows to avoid loading everything into memory.
+
+```ts
+const rows = Db.selectIterable<AuditLog>('SELECT * FROM audit_logs WHERE created_at > ?', ['2024-01-01'])
+
+let count = 0
+for await (const row of rows) {
+  await archiveToS3(row)
+  count++
+}
+```
+
+### Multiple Providers
+
+Register named providers for separate databases.
+
+```ts
+Db.Provider.register('default', Db.Provider.create({
+  driver: Db.drivers.mysql({ host: 'primary-db', user: 'app', password: '', database: 'myapp', port: 3306 })
+}))
+
+Db.Provider.register('analytics', Db.Provider.create({
+  driver: Db.drivers.mysql({ host: 'analytics-db', user: 'app', password: '', database: 'analytics', port: 3306 })
+}))
+
+// Use the default provider
+const users = await Db.select<User>('SELECT * FROM users')
+
+// Use a named provider
+const events = await Db.provider('analytics').select<Event>('SELECT * FROM events')
+```
+
+## Query Logging
+
+The MySQL driver emits structured log events via the `queryLogger` and `connectionLogger` options.
+
+Query logger events: `queryStarted`, `queryCompleted`, `queryFailed`, `transactionStarted`, `transactionCompleted`, `transactionFailed`. Each event includes the query ID, formatted query, duration (on completion/failure), and transaction ID when applicable.
+
+Connection logger events: `newConnection`, `connectionAcquisitionStarted`, `connectionAcquisitionCompleted`, `connectionAcquisitionFailed`.
+
+The log message type is exported as `Db.drivers.mysql.MysqlDbDriverLogMessageData`.
+
+## Testing
+
+The `@maestro-js/db` package does not currently have a mock driver or built-in tests. To test code that uses `Db`:
+
+1. **Use a real test database** -- spin up a MySQL instance (e.g., via Docker) and register a provider pointing to it.
+2. **Wrap tests in transactions** -- roll back after each test to keep the database clean.
+3. **Abstract database calls** -- write functions that accept a `Db.DbService` so you can substitute a test double.
+
+```ts
+// Test setup with a real database
+import { Db } from '@maestro-js/db'
+
+Db.Provider.register('default', Db.Provider.create({
+  driver: Db.drivers.mysql({
+    host: 'localhost',
+    user: 'test',
+    password: '',
+    database: 'myapp_test',
+    port: 3306
+  })
+}))
+
+// Clean up after tests
+afterAll(async () => {
+  await Db.destroy()
+})
+```
+
+## Cross-Package Integration
+
+### Depends On
+
+- **@maestro-js/service-registry** -- provider pattern (create, register, resolve)
+- **@maestro-js/log** -- structured logging for queries and connections
+- **@maestro-js/context** -- `AsyncLocalStorage`-based request context for scoping log data
+- **@maestro-js/helpers** -- retry logic, `AsyncIterableCollection` for streaming
+
+### Used By
+
+- **@maestro-js/queue** -- stores queue messages and job state in MySQL tables via `Db`
+
+### Works With
+
+- **@maestro-js/sql** -- provides query builder utilities (`Sql.where`, CTEs) that produce parameterized SQL strings compatible with `Db.select`, `Db.update`, etc.
+
+```ts
+import { Db } from '@maestro-js/db'
+import { Sql } from '@maestro-js/sql'
+
+const where = Sql.where({ active: true, role: 'admin' })
+const users = await Db.select<User>(`SELECT * FROM users ${where.sql}`, where.params)
+```
+
+## DbDriver Interface
+
+Implement this interface to create a custom driver.
+
+```ts
+interface DbDriver {
+  selectIterable(query: string, parameters?: any[]): AsyncIterable<Record<string, unknown>>
+  execute(
+    query: string,
+    parameters?: any[]
+  ): Promise<Record<string, unknown>[] | { affectedRows: number; changedRows: number; insertId: number }>
+  format(query: string, parameters: any[]): string
+  transaction<T>(callback: () => Promise<T>): Promise<T>
+  destroy(): Promise<void>
+}
+```

package/dist/index.d.ts

@@ -0,0 +1,256 @@
+import { Helpers } from '@maestro-js/helpers';
+import tls from 'node:tls';
+import { Log } from '@maestro-js/log';
+
+interface DbDriver {
+    selectIterable(query: string, parameters?: any[]): AsyncIterable<Record<string, unknown>>;
+    execute(query: string, parameters?: any[]): Promise<Record<string, unknown>[] | {
+        affectedRows: number;
+        changedRows: number;
+        insertId: number;
+    }>;
+    format(query: string, parameters: any[]): string;
+    transaction<T>(callback: () => Promise<T>): Promise<T>;
+    destroy(): Promise<void>;
+}
+
+type MysqlDbDriverLogMessageData = [
+    {
+        event: 'queryStarted';
+        queryId: string;
+        formattedQuery: string;
+        query: string;
+        params: any[];
+        transactionId: string | null;
+    } | {
+        event: 'queryCompleted';
+        queryId: string;
+        formattedQuery: string;
+        query: string;
+        params: any[];
+        durationMs: number;
+        rowCount: number;
+        transactionId: string | null;
+    } | {
+        event: 'queryFailed';
+        queryId: string;
+        formattedQuery: string;
+        query: string;
+        params: any[];
+        durationMs: number;
+        error: unknown;
+        transactionId: string | null;
+    } | {
+        event: 'transactionStarted';
+        transactionId: string;
+    } | {
+        event: 'transactionFailed';
+        transactionId: string;
+        durationMs: number;
+        error: unknown;
+    } | {
+        event: 'transactionCompleted';
+        transactionId: string;
+        durationMs: number;
+    }
+];
+interface MysqlDbDriverConfig {
+    host: string;
+    user: string;
+    password: string;
+    database: string;
+    port: number;
+    connectionLimit?: number;
+    debug?: boolean;
+    multipleStatements?: boolean;
+    ssl?: string | (tls.SecureContextOptions & {
+        rejectUnauthorized?: boolean | undefined;
+    }) | undefined;
+    connectionLogger?: Log.LogFunctions<[
+        {
+            event: 'newConnection';
+            connectionCount: number;
+            connectionThreadId: number | null;
+        } | {
+            event: 'connectionAcquisitionStarted';
+            queryId: string;
+        } | {
+            event: 'connectionAcquisitionCompleted';
+            queryId: string;
+            connectionId: number | undefined;
+            connectDurationMs: number;
+        } | {
+            event: 'connectionAcquisitionFailed';
+            queryId: string;
+            connectDurationMs: number;
+            error: unknown;
+        }
+    ]>;
+    queryLogger?: Log.LogFunctions<MysqlDbDriverLogMessageData>;
+}
+declare function mysqlDbDriver(config: MysqlDbDriverConfig): DbDriver;
+
+type KeysWithFallback = keyof Db.Provider.Keys extends never ? {
+    default: unknown;
+} : Db.Provider.Keys;
+/**
+ * Creates a new connection pool using the supplied options.
+ */
+declare function create({ driver }: Db.Provider.DbServiceConfig): Db.DbService;
+declare function provider(key: Db.Provider.Key): {
+    transaction: <T>(callback: () => Promise<T>) => Promise<T>;
+    format: (query: string, params?: any[]) => string;
+    select: <T = Record<string, unknown>>(query: string, parameters?: any[]) => Promise<T[]>;
+    selectIterable: <T = Record<string, unknown>>(query: string, parameters?: any[]) => Helpers.AsyncIterableCollection<T>;
+    insert: (query: string, parameters?: any[]) => Promise<{
+        affectedRows: number;
+        insertId: number;
+    }>;
+    update: (query: string, parameters?: any[]) => Promise<{
+        affectedRows: number;
+        changedRows: number;
+    }>;
+    delete: (query: string, parameters?: any[]) => Promise<{
+        affectedRows: number;
+    }>;
+    statement: <T = unknown>(query: string, parameters?: any[]) => Promise<T>;
+    scalar: <T = unknown>(query: string, parameters?: any[]) => Promise<T | null>;
+    destroy: () => Promise<void>;
+};
+/**
+ * Database access with typed query methods, transactions, and streaming.
+ *
+ * Provides a driver-based interface to SQL databases via the provider pattern.
+ * Create a driver (e.g. `Db.drivers.mysql()`), wrap it in `Db.Provider.create()`,
+ * and register it. The `Db` facade spreads the `'default'` provider so query
+ * methods can be called directly. Any database can be supported by implementing
+ * the `DbDriver` interface.
+ *
+ * @example
+ * ```ts
+ * Db.Provider.register('default', Db.Provider.create({
+ *   driver: Db.drivers.mysql({
+ *     host: 'localhost', user: 'root', password: '', database: 'myapp', port: 3306
+ *   })
+ * }))
+ *
+ * const users = await Db.select<User>('SELECT * FROM users WHERE active = ?', [true])
+ * const { insertId } = await Db.insert('INSERT INTO users (name) VALUES (?)', ['Alice'])
+ * const count = await Db.scalar<number>('SELECT COUNT(*) FROM users')
+ *
+ * await Db.transaction(async () => {
+ *   await Db.update('UPDATE accounts SET balance = balance - ? WHERE id = ?', [100, fromId])
+ *   await Db.update('UPDATE accounts SET balance = balance + ? WHERE id = ?', [100, toId])
+ * })
+ * ```
+ */
+declare namespace Db {
+    /** The pluggable database backend interface that drivers must implement */
+    type Driver = DbDriver;
+    /**
+     * Typed query API for executing SQL against a database.
+     *
+     * All methods accept parameterized queries with `?` placeholders for safe
+     * parameter escaping. Each method returns a result shape matching the SQL
+     * operation:
+     *
+     * - **Select** – returns typed row arrays via {@link select} or streaming rows via {@link selectIterable}
+     * - **Mutate** – {@link insert}, {@link update}, and `delete` return affected/changed row counts
+     * - **Scalar** – {@link scalar} returns the first column of the first row
+     * - **Transaction** – {@link transaction} wraps a callback in BEGIN/COMMIT/ROLLBACK
+     *
+     * @example
+     * ```ts
+     * const users = await Db.select<User>('SELECT * FROM users WHERE role = ?', ['admin'])
+     * const { insertId } = await Db.insert('INSERT INTO users (name) VALUES (?)', ['Alice'])
+     * await Db.transaction(async () => {
+     *   await Db.update('UPDATE products SET stock = stock - ? WHERE id = ?', [1, productId])
+     * })
+     * ```
+     */
+    interface DbService {
+        /** Executes a SELECT query and returns typed results as an array */
+        select<T = Record<string, unknown>>(query: string, parameters?: any[]): Promise<T[]>;
+        /** Executes a SELECT query and returns a streaming async iterable with backpressure */
+        selectIterable<T = Record<string, unknown>>(query: string, parameters?: any[]): Helpers.AsyncIterableCollection<T>;
+        /** Executes an INSERT query and returns the affected row count and auto-increment ID */
+        insert(query: string, parameters?: any[]): Promise<{
+            affectedRows: number;
+            insertId: number;
+        }>;
+        /** Executes an UPDATE query and returns the matched and changed row counts */
+        update(query: string, parameters?: any[]): Promise<{
+            affectedRows: number;
+            changedRows: number;
+        }>;
+        /** Executes a DELETE query and returns the number of removed rows */
+        delete(query: string, parameters?: any[]): Promise<{
+            affectedRows: number;
+        }>;
+        /** Executes an arbitrary SQL statement and returns the raw result */
+        statement<T = unknown>(query: string, parameters?: any[]): Promise<T>;
+        /**
+         * Returns the first column of the first row, or `null` if no results.
+         *
+         * Note: returns `null` both when the query returns zero rows and when the
+         * value itself is SQL NULL. Use `select()` if you need to distinguish
+         * between "no rows" and "row with a NULL value".
+         */
+        scalar<T = unknown>(query: string, parameters?: any[]): Promise<T | null>;
+        /** Wraps the callback in a database transaction — commits on success, rolls back on exception */
+        transaction: <T>(callback: () => Promise<T>) => Promise<T>;
+        /** Interpolates parameters into a query string for debugging — does not execute the query */
+        format: (query: string, params?: any[]) => string;
+        /** Closes all connections in the pool and prevents new ones from being created */
+        destroy: () => Promise<void>;
+    }
+    namespace drivers {
+        namespace mysql {
+            /** Log event data emitted by the MySQL driver for query and transaction lifecycle events */
+            type MysqlDbDriverLogMessageData = MysqlDbDriverLogMessageData;
+        }
+    }
+    namespace Provider {
+        interface DbServiceConfig {
+            driver: Driver;
+        }
+        type Key = keyof KeysWithFallback;
+        interface Keys {
+        }
+    }
+}
+/**
+ * Database access with typed query methods, transactions, and streaming.
+ * Call `Db.Provider.create({ driver })` and register it, then query via `Db.select()`, `Db.insert()`, etc.
+ * A MySQL driver is included via `Db.drivers.mysql()`, or supply your own `DbDriver` implementation.
+ */
+declare const Db: {
+    Provider: {
+        create: typeof create;
+        register: (name: Db.Provider.Key, item: Db.DbService) => void;
+    };
+    provider: typeof provider;
+    select: <T = Record<string, unknown>>(query: string, parameters?: any[]) => Promise<T[]>;
+    selectIterable: <T = Record<string, unknown>>(query: string, parameters?: any[]) => Helpers.AsyncIterableCollection<T>;
+    insert: (query: string, parameters?: any[]) => Promise<{
+        affectedRows: number;
+        insertId: number;
+    }>;
+    update: (query: string, parameters?: any[]) => Promise<{
+        affectedRows: number;
+        changedRows: number;
+    }>;
+    delete: (query: string, parameters?: any[]) => Promise<{
+        affectedRows: number;
+    }>;
+    statement: <T = unknown>(query: string, parameters?: any[]) => Promise<T>;
+    scalar: <T = unknown>(query: string, parameters?: any[]) => Promise<T | null>;
+    format: (query: string, params?: any[]) => string;
+    transaction: <T>(callback: () => Promise<T>) => Promise<T>;
+    destroy: () => Promise<void>;
+    drivers: {
+        mysql: typeof mysqlDbDriver;
+    };
+};
+
+export { Db };

package/dist/index.js

@@ -0,0 +1,588 @@
+// src/index.ts
+import { Helpers as Helpers2 } from "@maestro-js/helpers";
+import { ServiceRegistry } from "@maestro-js/service-registry";
+
+// src/mysql-db-driver.ts
+import { timeFns } from "iso-fns2";
+import mysql from "mysql2";
+import assert from "assert";
+import { AsyncLocalStorage } from "async_hooks";
+import { randomUUID } from "crypto";
+import "tls";
+import { Context } from "@maestro-js/context";
+import { Helpers } from "@maestro-js/helpers";
+import { Log } from "@maestro-js/log";
+function mysqlDbDriver(config) {
+  const connectionLogger = config?.connectionLogger ?? Log.create();
+  const queryLogger = config?.queryLogger ?? Log.create();
+  const transactionContext = new AsyncLocalStorage();
+  function getPoolConnection() {
+    return new Promise((resolve, reject) => {
+      pool.getConnection((err, connection) => {
+        if (err) reject(err);
+        else resolve(connection);
+      });
+    });
+  }
+  async function _getConnection() {
+    return Helpers.retry(
+      async () => {
+        const contextValue = transactionContext.getStore();
+        if (contextValue) {
+          return contextValue;
+        } else {
+          const connection = await getPoolConnection();
+          return {
+            id: connection.threadId,
+            release() {
+              connection.release();
+            },
+            beginTransaction() {
+              return new Promise((resolve, reject) => {
+                connection.beginTransaction((err) => {
+                  if (err) reject(err);
+                  else resolve();
+                });
+              });
+            },
+            commit() {
+              return new Promise((resolve, reject) => {
+                connection.commit((err) => {
+                  if (err) reject(err);
+                  else resolve();
+                });
+              });
+            },
+            rollback() {
+              return new Promise((resolve, reject) => {
+                connection.rollback((err) => {
+                  if (err) reject(err);
+                  else resolve();
+                });
+              });
+            },
+            query(queryStr, params) {
+              return params ? connection.query(queryStr, params) : connection.query(queryStr);
+            },
+            pause() {
+              return connection.pause();
+            },
+            resume() {
+              return connection.resume();
+            },
+            currentTransaction: null
+          };
+        }
+      },
+      {
+        maxAttempts: 10,
+        delay: 1e3
+      }
+    );
+  }
+  assert.ok(config.host);
+  assert.ok(config.user);
+  assert.ok(
+    config.password !== void 0 && config.password !== null,
+    "config.password is required (empty string is allowed)"
+  );
+  assert.ok(config.database);
+  assert.ok(config.port);
+  const pool = mysql.createPool({
+    host: config.host,
+    user: config.user,
+    password: config.password,
+    database: config.database,
+    port: config.port,
+    connectionLimit: config.connectionLimit ?? 10,
+    connectTimeout: 60 * 60 * 1e3,
+    waitForConnections: true,
+    queueLimit: 0,
+    timezone: "Z",
+    debug: false,
+    multipleStatements: config.multipleStatements,
+    ssl: config.ssl,
+    typeCast: typeCastHandler,
+    // Use utf8mb4_0900_ai_ci (MySQL 8.0+ default)
+    // This prevents collation mismatch errors when string literals are compared with column values
+    charset: "utf8mb4_0900_ai_ci",
+    jsonStrings: true,
+    decimalNumbers: true
+  });
+  let connectionCount = 0;
+  pool.on("connection", function(connection) {
+    connectionCount++;
+    connectionLogger.info({
+      event: "newConnection",
+      connectionCount,
+      connectionThreadId: connection.threadId
+    });
+  });
+  async function transaction(callback) {
+    const connection = await _getConnection();
+    if (connection.currentTransaction) {
+      try {
+        const result = await callback();
+        return result;
+      } catch (e) {
+        connection.currentTransaction.transactionError = e;
+        throw e;
+      }
+    } else {
+      const currentTransaction = { transactionError: null, queries: [], id: randomUUID() };
+      const contextValue = {
+        id: connection.id,
+        release() {
+        },
+        beginTransaction(...args) {
+          if (currentTransaction?.transactionError) {
+            throw new Error("This transaction has already been rolled back");
+          }
+          return connection.beginTransaction(...args);
+        },
+        async commit(...args) {
+          if (currentTransaction?.transactionError) {
+            throw new Error("This transaction has already been rolled back");
+          }
+          await Promise.all(currentTransaction.queries);
+          return connection.commit(...args);
+        },
+        async rollback(...args) {
+          if (!currentTransaction?.transactionError) {
+            await Promise.all(currentTransaction.queries);
+            return connection.rollback(...args);
+          }
+        },
+        query(...args) {
+          let resolve = () => {
+          };
+          currentTransaction.queries.push(
+            new Promise((r) => {
+              resolve = r;
+            })
+          );
+          if (currentTransaction?.transactionError) {
+            throw new Error("This transaction has already been rolled back");
+          }
+          const result = connection.query(...args);
+          result.on("end", resolve);
+          return result;
+        },
+        pause() {
+          return connection.pause();
+        },
+        resume() {
+          return connection.resume();
+        },
+        currentTransaction
+      };
+      const transactionStartTime = (/* @__PURE__ */ new Date()).getTime();
+      try {
+        await connection.beginTransaction();
+        queryLogger.info({
+          event: "transactionStarted",
+          transactionId: contextValue.currentTransaction.id
+        });
+        const result = await transactionContext.run(contextValue, async () => {
+          return callback();
+        });
+        if (currentTransaction.transactionError) {
+          throw currentTransaction.transactionError;
+        }
+        await contextValue.commit();
+        const duration = (/* @__PURE__ */ new Date()).getTime() - transactionStartTime;
+        queryLogger.info({
+          event: "transactionCompleted",
+          transactionId: contextValue.currentTransaction.id,
+          durationMs: duration
+        });
+        return result;
+      } catch (e) {
+        currentTransaction.transactionError = e;
+        await Promise.allSettled(
+          currentTransaction.queries.map((q) => Promise.race([q, new Promise((r) => setTimeout(r, 1e3))]))
+        );
+        await connection.rollback();
+        const duration = (/* @__PURE__ */ new Date()).getTime() - transactionStartTime;
+        queryLogger.info({
+          event: "transactionFailed",
+          transactionId: contextValue.currentTransaction.id,
+          durationMs: duration,
+          error: e
+        });
+        throw e;
+      } finally {
+        connection.release();
+      }
+    }
+  }
+  function format(query, params = []) {
+    const formattedSql = mysql.format(query, params);
+    return formattedSql;
+  }
+  async function getConnectionForQuery(queryId) {
+    const connectStartTime = (/* @__PURE__ */ new Date()).getTime();
+    connectionLogger.info({
+      event: "connectionAcquisitionStarted",
+      queryId
+    });
+    try {
+      const connection = await _getConnection();
+      connectionLogger.info({
+        event: "connectionAcquisitionCompleted",
+        queryId,
+        connectionId: connection.id,
+        connectDurationMs: (/* @__PURE__ */ new Date()).getTime() - connectStartTime
+      });
+      return connection;
+    } catch (e) {
+      connectionLogger.error({
+        event: "connectionAcquisitionFailed",
+        queryId,
+        connectDurationMs: (/* @__PURE__ */ new Date()).getTime() - connectStartTime,
+        error: e
+      });
+      throw e;
+    }
+  }
+  function executeQueryOnConnection({
+    query,
+    queryId,
+    params,
+    connection
+  }) {
+    const formatted = mysql.format(query, params);
+    const queryStartTime = (/* @__PURE__ */ new Date()).getTime();
+    const context = Context.getStore();
+    queryLogger.info({
+      event: "queryStarted",
+      queryId,
+      formattedQuery: formatted,
+      query,
+      params,
+      transactionId: connection.currentTransaction?.id ?? null
+    });
+    let streamError = null;
+    const queryStream = params ? connection.query(`/*SqlQueryTiming: ${queryId}*/` + query, params) : connection.query(`/*SqlQueryTiming: ${queryId}*/` + query);
+    let rowCount = 0;
+    queryStream.on("result", () => {
+      rowCount++;
+    });
+    queryStream.on("end", () => {
+      Context.runWith(context, () => {
+        if (!streamError) {
+          const duration = (/* @__PURE__ */ new Date()).getTime() - queryStartTime;
+          queryLogger.info({
+            event: "queryCompleted",
+            queryId,
+            durationMs: duration,
+            formattedQuery: formatted,
+            query,
+            params,
+            rowCount,
+            transactionId: connection.currentTransaction?.id ?? null
+          });
+        }
+      });
+    });
+    queryStream.on("error", (error) => {
+      Context.runWith(context, () => {
+        streamError = error;
+        queryLogger.error({
+          event: "queryFailed",
+          queryId,
+          durationMs: (/* @__PURE__ */ new Date()).getTime() - queryStartTime,
+          formattedQuery: formatted,
+          query,
+          params,
+          error,
+          transactionId: connection.currentTransaction?.id ?? null
+        });
+      });
+    });
+    return queryStream;
+  }
+  function selectIterable(query, params = []) {
+    const queryId = randomUUID();
+    return {
+      async *[Symbol.asyncIterator]() {
+        const connection = await getConnectionForQuery(queryId);
+        const queryStream = executeQueryOnConnection({
+          query,
+          queryId,
+          params,
+          connection
+        });
+        let isComplete = false;
+        let streamError = null;
+        const rowQueue = [];
+        let resolveNext = null;
+        let isPaused = false;
+        const MAX_QUEUE_SIZE = 3e3;
+        queryStream.on("result", (row) => {
+          if (isComplete) {
+            return;
+          }
+          if (rowQueue.length || !isOkPacket(row)) {
+            rowQueue.push(row);
+          }
+          if (rowQueue.length >= MAX_QUEUE_SIZE && !isPaused) {
+            isPaused = true;
+            connection.pause();
+          }
+          if (resolveNext) {
+            const resolve = resolveNext;
+            resolveNext = null;
+            resolve();
+          }
+        });
+        queryStream.on("end", () => {
+          isComplete = true;
+          if (resolveNext) {
+            const resolve = resolveNext;
+            resolveNext = null;
+            resolve();
+          }
+        });
+        queryStream.on("error", (error) => {
+          streamError = error;
+          if (resolveNext) {
+            const resolve = resolveNext;
+            resolveNext = null;
+            resolve();
+          }
+        });
+        try {
+          while (!isComplete && !streamError) {
+            if (rowQueue.length > 0) {
+              const row = rowQueue.shift();
+              if (isPaused && rowQueue.length < MAX_QUEUE_SIZE - 25) {
+                isPaused = false;
+                connection.resume();
+              }
+              yield row;
+            } else {
+              await new Promise((resolve) => {
+                resolveNext = resolve;
+              });
+            }
+          }
+          while (rowQueue.length > 0) {
+            yield rowQueue.shift();
+          }
+          if (isPaused) {
+            connection.resume();
+          }
+          if (streamError) {
+            throw streamError;
+          }
+        } finally {
+          isComplete = true;
+          rowQueue.length = 0;
+          if (isPaused) {
+            connection.resume();
+          }
+          connection.release();
+          if (resolveNext) {
+            const resolve = resolveNext;
+            resolveNext = null;
+            resolve();
+          }
+        }
+      }
+    };
+  }
+  async function execute(query, params = []) {
+    const queryId = randomUUID();
+    const isInTransaction = !!transactionContext.getStore();
+    const results = await Helpers.retry(
+      async () => {
+        const connection = await getConnectionForQuery(queryId);
+        const queryStream = executeQueryOnConnection({ query, params, queryId, connection });
+        const promise = new Promise((resolve, reject) => {
+          const rowQueue = [];
+          let okPacket = null;
+          queryStream.on("result", (row, ...rest) => {
+            if (rowQueue.length || !isOkPacket(row)) {
+              rowQueue.push(row);
+            } else {
+              okPacket = row;
+            }
+          });
+          queryStream.on("error", (error) => reject(error));
+          queryStream.on("end", () => {
+            if (!rowQueue.length && okPacket) {
+              resolve({
+                affectedRows: okPacket.affectedRows ?? NaN,
+                changedRows: okPacket.changedRows ?? NaN,
+                insertId: okPacket.insertId ?? NaN
+              });
+            } else {
+              resolve(rowQueue);
+            }
+          });
+        });
+        return await promise.finally(() => connection.release());
+      },
+      {
+        maxAttempts: 3,
+        delay: 0,
+        shouldRetry: (err) => "code" in err && err.code === "ER_LOCK_DEADLOCK" && !isInTransaction || "code" in err && err.code === "ER_LOCK_WAIT_TIMEOUT" || err instanceof Error && err.message.includes("Please retry") || err instanceof Error && err.message.includes("Try restarting transaction") && !isInTransaction
+      }
+    );
+    return results;
+  }
+  async function destroy() {
+    await new Promise((resolve, reject) => {
+      pool.end((err) => {
+        if (err) reject(err);
+        else resolve();
+      });
+    });
+  }
+  return { transaction, format, execute, selectIterable, destroy };
+}
+var typeCastHandler = (field, next) => {
+  if (field.type === "DATE") {
+    const stringRepresentation = field.string();
+    return stringRepresentation;
+  }
+  if (field.type === "TIME") {
+    const stringRepresentation = field.string();
+    const res = stringRepresentation === null ? null : timeFns.from(stringRepresentation);
+    return res;
+  }
+  if (field.type === "DATETIME") {
+    const stringRepresentation = field.string();
+    try {
+      const res = stringRepresentation === null ? null : (/* @__PURE__ */ new Date(`${stringRepresentation}Z`)).toISOString();
+      return res;
+    } catch (e) {
+      throw new Error(`Failed to parse DATETIME value "${stringRepresentation}" for ${field.table}.${field.name}`, {
+        cause: e
+      });
+    }
+  }
+  if (field.type === "TINY" && field.length === 1) {
+    const num = field.string();
+    if (num === null) {
+      return null;
+    }
+    if (!isNaN(num)) {
+      const bool = Number(num) === 1;
+      return bool;
+    }
+  }
+  return next();
+};
+function isOkPacket(entry) {
+  if (entry && typeof entry === "object") {
+    return ["fieldCount", "changedRows", "affectedRows", "insertId", "serverStatus", "warningStatus", "info"].every(
+      (field) => field in entry
+    );
+  } else {
+    return false;
+  }
+}
+
+// src/index.ts
+function create({ driver }) {
+  async function transaction(callback) {
+    return driver.transaction(callback);
+  }
+  function format(query, params = []) {
+    const formattedSql = driver.format(query, params);
+    return formattedSql;
+  }
+  async function scalar(query, params) {
+    const results = await driver.execute(query, params);
+    const item = Array.isArray(results) && results.length ? results[0] ?? {} : {};
+    const scalarKey = Object.keys(item).length ? Object.keys(item)[0] ?? "" : "";
+    return item[scalarKey] ?? null;
+  }
+  async function select(query, params) {
+    const results = await driver.execute(query, params);
+    return Array.isArray(results) ? results : [];
+  }
+  function selectIterable(query, params) {
+    const iterable = driver.selectIterable(query, params);
+    return Helpers2.AsyncIterableCollection.from(iterable);
+  }
+  async function insert(query, params) {
+    const results = await driver.execute(query, params);
+    if (Array.isArray(results)) {
+      throw new Error("insert() received a result set. Use select() for queries that return rows.");
+    }
+    return { affectedRows: results.affectedRows, insertId: results.insertId };
+  }
+  async function update(query, params) {
+    const results = await driver.execute(query, params);
+    if (Array.isArray(results)) {
+      throw new Error("update() received a result set. Use select() for queries that return rows.");
+    }
+    return { affectedRows: results.affectedRows, changedRows: results.changedRows };
+  }
+  async function deleteRows(query, params) {
+    const results = await driver.execute(query, params);
+    if (Array.isArray(results)) {
+      throw new Error("delete() received a result set. Use select() for queries that return rows.");
+    }
+    return { affectedRows: results.affectedRows };
+  }
+  return {
+    transaction,
+    format,
+    select,
+    selectIterable,
+    insert,
+    update,
+    delete: deleteRows,
+    scalar,
+    async statement(query, params) {
+      const result = await driver.execute(query, params);
+      return result;
+    },
+    destroy: () => driver.destroy()
+  };
+}
+var registry = ServiceRegistry.createRegistry(ServiceRegistry.proxyFunctionsForObject);
+var Provider = {
+  create,
+  register: registry.register
+};
+function provider(key) {
+  const service = registry.resolve(key);
+  return {
+    transaction: service.transaction,
+    format: service.format,
+    select: service.select,
+    selectIterable: service.selectIterable,
+    insert: service.insert,
+    update: service.update,
+    delete: service.delete,
+    statement: service.statement,
+    scalar: service.scalar,
+    destroy: service.destroy
+  };
+}
+var facade = provider("default");
+var Db = {
+  Provider,
+  provider,
+  select: facade.select,
+  selectIterable: facade.selectIterable,
+  insert: facade.insert,
+  update: facade.update,
+  delete: facade.delete,
+  statement: facade.statement,
+  scalar: facade.scalar,
+  format: facade.format,
+  transaction: facade.transaction,
+  destroy: facade.destroy,
+  drivers: {
+    mysql: mysqlDbDriver
+  }
+};
+export {
+  Db
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@maestro-js/db",
+  "description": "Use when working with @maestro-js/db, the database access package for Maestro. Covers MySQL driver setup, parameterized SQL queries (select, insert, update, delete, scalar, statement), transactions with automatic commit/rollback, streaming results via selectIterable, connection pooling, query formatting, and the provider pattern for multiple database instances. Maestro uses raw parameterized SQL with no ORM. Depends on service-registry and log. Used by queue for message storage. Works with the sql package for query builders.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "iso-fns2": "npm:iso-fns@2.0.0-alpha.26",
+    "mysql2": "^3.15.3",
+    "@maestro-js/context": "1.0.0-alpha.0",
+    "@maestro-js/log": "1.0.0-alpha.0",
+    "@maestro-js/helpers": "1.0.0-alpha.0",
+    "@maestro-js/service-registry": "1.0.0-alpha.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.11"
+  },
+  "version": "1.0.0-alpha.0",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "repository": "https://github.com/Marcato-Partners/maestro-js",
+  "scripts": {
+    "build": "tsup --config ../../tsup.config.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "echo 'No tests yet'",
+    "format": "prettier --write src/",
+    "lint": "prettier --check src/"
+  }
+}