@devopsplaybook.io/common-utils 1.0.0 → 1.1.0

package/README.md

@@ -169,6 +169,59 @@ Pool defaults: `max: 20`, `idleTimeoutMillis: 30000`, `connectionTimeoutMillis:
 
 ---
 
+#### `PostgresSchemaDbUtils` -- Multi-Schema PostgreSQL Access
+
+Class-based PostgreSQL utility that manages per-schema connection pools (used during migrations) and an optional shared runtime pool (used for application queries). Ideal for multi-schema setups where each module owns its own schema.
+
+```ts
+import { PostgresSchemaDbUtils } from "@devopsplaybook.io/common-utils";
+
+// Create one instance per schema
+const AuthDb = new PostgresSchemaDbUtils("AUTH");
+const DictionaryDb = new PostgresSchemaDbUtils("DICTIONARY");
+
+// Initialize OTel (once, shared across all instances)
+AuthDb.initOTel(tracer, logger);
+
+// Init schema pool (creates schema + runs migrations)
+await AuthDb.initSchema(span, config, path.resolve(__dirname, "../sql/auth"));
+await DictionaryDb.initSchema(span, config, path.resolve(__dirname, "../sql/dictionary"));
+
+// Init shared runtime pool (call on any instance)
+AuthDb.initRuntimePool(config);
+
+// Query using the schema-specific pool
+const users = await AuthDb.querySQL(span, "SELECT * FROM users WHERE id = $1", [userId]);
+
+// Or use the runtime pool for non-migration queries
+const rows = await AuthDb.querySQL(span, "SELECT ...", [], false);
+
+// Transactions
+await AuthDb.transaction(span, async (client) => {
+  await client.query("INSERT INTO ...", [...]);
+  await client.query("UPDATE ...", [...]);
+});
+
+// Cleanup
+await AuthDb.closeAll();
+```
+
+| Method                                              | Description                                         |
+| --------------------------------------------------- | --------------------------------------------------- |
+| `new PostgresSchemaDbUtils(schemaName)`             | Create instance for a specific schema               |
+| `initOTel(tracer, logger)`                          | Inject OTel instances (shared across all instances) |
+| `initSchema(context, config, sqlDir)`               | Create schema pool and run migrations               |
+| `initRuntimePool(config)`                           | Create shared runtime pool                          |
+| `execSQL(context, sql, params?, useSchemaPool?)`    | Execute write, returns `Promise<number>`            |
+| `execSQLFile(context, filename, useSchemaPool?)`    | Execute an entire SQL file                          |
+| `querySQL(context, sql, params?, useSchemaPool?)`   | Execute read, returns `Promise<any[]>`              |
+| `transaction(context, callback, useSchemaPool?)`    | Run callback inside a transaction                   |
+| `closeAll()`                                        | Close all pools managed by this instance            |
+
+`useSchemaPool` (default `true`) selects between the schema-specific pool (migrations) and the shared runtime pool (application queries).
+
+---
+
 #### `DbUtils` -- Unified Database Facade
 
 Dispatches to SQLite or Postgres based on `config.DATABASE_TYPE`. Write SQL using SQLite-style `?` placeholders; they are automatically converted to `$1, $2, ...` for Postgres.

package/dist/src/PostgresDbUtils.d.ts

@@ -11,6 +11,56 @@ export interface PostgresDbConfig {
     DATABASE_POSTGRES_PASSWORD: string;
     DATABASE_POSTGRES_DATABASE: string;
 }
+/**
+ * Class-based PostgreSQL utility that manages a schema-specific pool (used
+ * during migrations) and an optional shared runtime pool (used for
+ * application queries).
+ *
+ * Multiple instances can coexist, each bound to a different PostgreSQL
+ * schema, while sharing a single runtime pool that has all schemas in its
+ * `search_path`.
+ */
+export declare class PostgresSchemaDbUtils {
+    private schemaPool;
+    private runtimePool;
+    private readonly schemaName;
+    private readonly moduleLogger;
+    constructor(schemaName: string);
+    /**
+     * Create the schema-specific pool, ensure the schema exists, and apply
+     * any pending migration files from `sqlDir`.
+     */
+    initSchema(context: Span, config: PostgresDbConfig, sqlDir: string): Promise<void>;
+    /**
+     * Initialise (or replace) the shared runtime pool.
+     * Typically called once with a pool whose `search_path` includes all
+     * application schemas.
+     */
+    initRuntimePool(config: PostgresDbConfig, searchPath?: string): void;
+    /**
+     * Execute a write SQL statement with OTel tracing.
+     * @param useSchemaPool  When `true` use the schema-specific pool;
+     *                       otherwise use the runtime pool (default).
+     * @returns Number of rows changed.
+     */
+    execSQL(context: Span, sql: string, params?: any[], useSchemaPool?: boolean): Promise<number>;
+    /** Execute an entire SQL file (used for migrations). */
+    execSQLFile(context: Span, filename: string, useSchemaPool?: boolean): Promise<void>;
+    /**
+     * Execute a read SQL query with OTel tracing.
+     * @returns Array of row objects.
+     */
+    querySQL(context: Span, sql: string, params?: any[], useSchemaPool?: boolean): Promise<any[]>;
+    /**
+     * Run a callback inside a transaction.
+     */
+    transaction(context: Span, callback: (client: any) => Promise<void>, useSchemaPool?: boolean): Promise<void>;
+    /** Close both the schema pool and the runtime pool. */
+    closeAll(): Promise<void>;
+    private execSQLForSchema;
+    private execSQLFileForSchema;
+    private querySQLForSchema;
+}
 /**
  * Injects the OTel tracer and logger instances used by all Postgres operations.
  * Must be called once at startup, before {@link PostgresDbUtilsInit}.
@@ -19,17 +69,6 @@ export declare function PostgresDbUtilsSetOTel(tracerIn: StandardTracer, loggerI
 /**
  * Creates the Postgres connection pool and applies pending migration files
  * from `sqlDir`.
- *
- * Migration files must follow the naming convention `init-NNNN.sql` and are
- * applied in lexicographic order.  A `metadata` table tracks which migrations
- * have already been applied so they are idempotent.
- *
- * @param context  Parent OTel span.
- * @param config   Configuration with Postgres connection fields.
- * @param sqlDir   Absolute path to the directory containing SQL migration files
- *                 written for Postgres (with `$1,$2...` placeholders).
- *                 If migrations are SQLite-first, use `convertToPostgresPlaceholders`
- *                 before passing them.
  */
 export declare function PostgresDbUtilsInit(context: Span, config: PostgresDbConfig, sqlDir: string): Promise<void>;
 /** Returns the underlying `pg.Pool` instance. */

package/dist/src/PostgresDbUtils.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresSchemaDbUtils = void 0;
 exports.PostgresDbUtilsSetOTel = PostgresDbUtilsSetOTel;
 exports.PostgresDbUtilsInit = PostgresDbUtilsInit;
 exports.PostgresDbUtilsGetPool = PostgresDbUtilsGetPool;
@@ -44,35 +45,347 @@ exports.PostgresDbUtilsTransactionCommit = PostgresDbUtilsTransactionCommit;
 const pg_1 = require("pg");
 const fs = __importStar(require("fs-extra"));
 const api_1 = require("@opentelemetry/api");
+// ---------------------------------------------------------------------------
+// Module-level state
+// ---------------------------------------------------------------------------
 let pool;
 let tracer;
 let logger;
+let standardLogger;
+// ---------------------------------------------------------------------------
+// Class-based API – supports per-schema pools + shared runtime pool
+// ---------------------------------------------------------------------------
+/**
+ * Class-based PostgreSQL utility that manages a schema-specific pool (used
+ * during migrations) and an optional shared runtime pool (used for
+ * application queries).
+ *
+ * Multiple instances can coexist, each bound to a different PostgreSQL
+ * schema, while sharing a single runtime pool that has all schemas in its
+ * `search_path`.
+ */
+class PostgresSchemaDbUtils {
+    constructor(schemaName) {
+        this.schemaPool = null;
+        this.runtimePool = null;
+        this.schemaName = schemaName;
+        this.moduleLogger = standardLogger.createModuleLogger(`PostgresSchemaDbUtils[${schemaName}]`);
+    }
+    /**
+     * Create the schema-specific pool, ensure the schema exists, and apply
+     * any pending migration files from `sqlDir`.
+     */
+    async initSchema(context, config, sqlDir) {
+        const span = tracer.startSpan("PostgresSchemaDbUtilsInit", context);
+        const poolOptions = {
+            host: config.DATABASE_POSTGRES_HOST,
+            port: config.DATABASE_POSTGRES_PORT || 5432,
+            user: config.DATABASE_POSTGRES_USER,
+            password: config.DATABASE_POSTGRES_PASSWORD,
+            database: config.DATABASE_POSTGRES_DATABASE,
+            options: `-c search_path=${this.schemaName}`,
+            max: 5,
+            idleTimeoutMillis: 30000,
+            connectionTimeoutMillis: 10000,
+        };
+        if (this.schemaPool) {
+            this.moduleLogger.info("Closing existing schema pool");
+            await this.schemaPool.end().catch(() => {
+                // Ignore errors on close
+            });
+        }
+        this.schemaPool = new pg_1.Pool(poolOptions);
+        this.moduleLogger.info(`Schema pool initialized with search_path: ${this.schemaName}`);
+        // Create schema if not exists
+        await this.execSQLForSchema(span, `CREATE SCHEMA IF NOT EXISTS ${this.schemaName};`);
+        await this.execSQLForSchema(span, `SET search_path TO ${this.schemaName};`);
+        // Run init SQL files
+        await this.execSQLFileForSchema(span, `${sqlDir}/init-0000.sql`);
+        const initFiles = (await fs.readdir(sqlDir)).sort();
+        let dbVersionApplied = 0;
+        try {
+            const dbVersionQuery = await this.querySQLForSchema(span, "SELECT MAX(value) as version FROM metadata WHERE type='db_version'");
+            if (dbVersionQuery[0].version) {
+                dbVersionApplied = Number(dbVersionQuery[0].version);
+            }
+        }
+        catch {
+            // Table might not exist yet
+        }
+        this.moduleLogger.info(`Current DB Version: ${dbVersionApplied}`);
+        for (const initFile of initFiles) {
+            const regex = /init-(\d+)\.sql/g;
+            const match = regex.exec(initFile);
+            if (match) {
+                const dbVersionInitFile = Number(match[1]);
+                if (dbVersionInitFile > dbVersionApplied) {
+                    this.moduleLogger.info(`Applying migration: ${initFile}`);
+                    await this.execSQLFileForSchema(span, `${sqlDir}/${initFile}`);
+                    await this.querySQLForSchema(span, 'INSERT INTO metadata ("type", "value", "dateCreated") VALUES ($1, $2, $3)', ["db_version", dbVersionInitFile, new Date().toISOString()]);
+                }
+            }
+        }
+        span.end();
+    }
+    /**
+     * Initialise (or replace) the shared runtime pool.
+     * Typically called once with a pool whose `search_path` includes all
+     * application schemas.
+     */
+    initRuntimePool(config, searchPath) {
+        if (this.runtimePool) {
+            this.runtimePool.end().catch(() => {
+                // Ignore errors on close
+            });
+        }
+        this.runtimePool = new pg_1.Pool({
+            host: config.DATABASE_POSTGRES_HOST,
+            port: config.DATABASE_POSTGRES_PORT || 5432,
+            user: config.DATABASE_POSTGRES_USER,
+            password: config.DATABASE_POSTGRES_PASSWORD,
+            database: config.DATABASE_POSTGRES_DATABASE,
+            options: searchPath
+                ? `-c search_path=${searchPath}`
+                : `-c search_path=${this.schemaName}`,
+            max: 20,
+            idleTimeoutMillis: 30000,
+            connectionTimeoutMillis: 10000,
+            keepAlive: true,
+        });
+        this.moduleLogger.info(`Runtime pool initialized (search_path: ${searchPath || this.schemaName})`);
+    }
+    /**
+     * Execute a write SQL statement with OTel tracing.
+     * @param useSchemaPool  When `true` use the schema-specific pool;
+     *                       otherwise use the runtime pool (default).
+     * @returns Number of rows changed.
+     */
+    execSQL(context, sql, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    params = [], useSchemaPool = false) {
+        const span = tracer.startSpan("PostgresSchemaDbUtilsExecSQL", context);
+        const pool = useSchemaPool ? this.schemaPool : this.runtimePool;
+        if (!pool) {
+            throw new Error(`Pool not initialized${useSchemaPool ? ` for schema: ${this.schemaName}` : ""}`);
+        }
+        return new Promise((resolve, reject) => {
+            pool.query(sql, params, (error, result) => {
+                span.end();
+                if (error) {
+                    span.setStatus({
+                        code: api_1.SpanStatusCode.ERROR,
+                        message: error.message,
+                    });
+                    this.moduleLogger.error(`[${useSchemaPool ? this.schemaName : "RUNTIME"}] SQL EXEC ERROR: ${sql}`, error);
+                    reject(error);
+                }
+                else {
+                    resolve(result.rowCount || 0);
+                }
+            });
+        });
+    }
+    /** Execute an entire SQL file (used for migrations). */
+    async execSQLFile(context, filename, useSchemaPool = false) {
+        const span = tracer.startSpan("PostgresSchemaDbUtilsExecSQLFile", context);
+        const sql = (await fs.readFile(filename)).toString();
+        const pool = useSchemaPool ? this.schemaPool : this.runtimePool;
+        if (!pool) {
+            throw new Error(`Pool not initialized${useSchemaPool ? ` for schema: ${this.schemaName}` : ""}`);
+        }
+        return new Promise((resolve, reject) => {
+            pool.query(sql, (error) => {
+                span.end();
+                if (error) {
+                    span.setStatus({
+                        code: api_1.SpanStatusCode.ERROR,
+                        message: error.message,
+                    });
+                    reject(error);
+                }
+                else {
+                    resolve();
+                }
+            });
+        });
+    }
+    /**
+     * Execute a read SQL query with OTel tracing.
+     * @returns Array of row objects.
+     */
+    querySQL(context, sql, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    params = [], useSchemaPool = false) {
+        const span = tracer.startSpan("PostgresSchemaDbUtilsQuerySQL", context);
+        const pool = useSchemaPool ? this.schemaPool : this.runtimePool;
+        if (!pool) {
+            throw new Error(`Pool not initialized${useSchemaPool ? ` for schema: ${this.schemaName}` : ""}`);
+        }
+        return new Promise((resolve, reject) => {
+            pool.query(sql, params, (error, result) => {
+                span.end();
+                if (error) {
+                    span.setStatus({
+                        code: api_1.SpanStatusCode.ERROR,
+                        message: error.message,
+                    });
+                    this.moduleLogger.error(`[${useSchemaPool ? this.schemaName : "RUNTIME"}] SQL QUERY ERROR: ${sql}`, error);
+                    reject(error);
+                }
+                else {
+                    resolve(result.rows);
+                }
+            });
+        });
+    }
+    /**
+     * Run a callback inside a transaction.
+     */
+    async transaction(context, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    callback, useSchemaPool = false) {
+        const span = tracer.startSpan("PostgresSchemaDbUtilsTransaction", context);
+        const pool = useSchemaPool ? this.schemaPool : this.runtimePool;
+        if (!pool) {
+            throw new Error(`Pool not initialized${useSchemaPool ? ` for schema: ${this.schemaName}` : ""}`);
+        }
+        this.moduleLogger.info(`[${useSchemaPool ? this.schemaName : "RUNTIME"}] Starting transaction`);
+        const client = await pool.connect();
+        try {
+            await client.query("BEGIN");
+            await callback(client);
+            await client.query("COMMIT");
+            this.moduleLogger.info(`[${useSchemaPool ? this.schemaName : "RUNTIME"}] Transaction committed`);
+        }
+        catch (error) {
+            await client.query("ROLLBACK");
+            this.moduleLogger.error(`[${useSchemaPool ? this.schemaName : "RUNTIME"}] Transaction rolled back`, error);
+            throw error;
+        }
+        finally {
+            client.release();
+            span.end();
+        }
+    }
+    /** Close both the schema pool and the runtime pool. */
+    async closeAll() {
+        const promises = [];
+        if (this.schemaPool) {
+            this.moduleLogger.info("Closing schema pool");
+            promises.push(this.schemaPool.end().catch(() => {
+                this.moduleLogger.warn("Error closing schema pool");
+            }));
+            this.schemaPool = null;
+        }
+        if (this.runtimePool) {
+            this.moduleLogger.info("Closing runtime pool");
+            promises.push(this.runtimePool.end().catch(() => {
+                this.moduleLogger.warn("Error closing runtime pool");
+            }));
+            this.runtimePool = null;
+        }
+        await Promise.all(promises);
+        this.moduleLogger.info("All database pools closed");
+    }
+    // -- Internal helpers (schema pool only) ----------------------------------
+    execSQLForSchema(context, sql, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    params = []) {
+        const span = tracer.startSpan("PostgresSchemaDbUtilsExecSQLForSchema", context);
+        if (!this.schemaPool) {
+            throw new Error(`Pool not initialized for schema: ${this.schemaName}`);
+        }
+        return new Promise((resolve, reject) => {
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            this.schemaPool.query(sql, params, (error) => {
+                span.end();
+                if (error) {
+                    reject(error);
+                }
+                else {
+                    resolve();
+                }
+            });
+        });
+    }
+    async execSQLFileForSchema(context, filename) {
+        try {
+            const span = tracer.startSpan("PostgresSchemaDbUtilsExecSQLFileForSchema", context);
+            const sql = (await fs.readFile(filename)).toString();
+            if (!this.schemaPool) {
+                throw new Error(`Pool not initialized for schema: ${this.schemaName}`);
+            }
+            return new Promise((resolve, reject) => {
+                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                this.schemaPool.query(sql, (error) => {
+                    span.end();
+                    if (error) {
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        if (error.code === "ENOENT") {
+                            resolve();
+                        }
+                        else {
+                            reject(error);
+                        }
+                    }
+                    else {
+                        resolve();
+                    }
+                });
+            });
+        }
+        catch (error) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            if (error.code === "ENOENT") {
+                return;
+            }
+            throw error;
+        }
+    }
+    querySQLForSchema(context, sql, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    params = []) {
+        const span = tracer.startSpan("PostgresSchemaDbUtilsQuerySQLForSchema", context);
+        if (!this.schemaPool) {
+            throw new Error(`Pool not initialized for schema: ${this.schemaName}`);
+        }
+        return new Promise((resolve, reject) => {
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            this.schemaPool.query(sql, params, (error, result) => {
+                span.end();
+                if (error) {
+                    reject(error);
+                }
+                else {
+                    resolve(result.rows);
+                }
+            });
+        });
+    }
+}
+exports.PostgresSchemaDbUtils = PostgresSchemaDbUtils;
+// ---------------------------------------------------------------------------
+// Functional API – single-pool mode used by the DbUtils facade.
+// An internal PostgresSchemaDbUtils instance backs these functions so the
+// behaviour is identical to before.
+// ---------------------------------------------------------------------------
 /**
  * Injects the OTel tracer and logger instances used by all Postgres operations.
  * Must be called once at startup, before {@link PostgresDbUtilsInit}.
  */
 function PostgresDbUtilsSetOTel(tracerIn, loggerIn) {
     tracer = tracerIn;
+    standardLogger = loggerIn;
     logger = loggerIn.createModuleLogger("PostgresDbUtils");
 }
 /**
  * Creates the Postgres connection pool and applies pending migration files
  * from `sqlDir`.
- *
- * Migration files must follow the naming convention `init-NNNN.sql` and are
- * applied in lexicographic order.  A `metadata` table tracks which migrations
- * have already been applied so they are idempotent.
- *
- * @param context  Parent OTel span.
- * @param config   Configuration with Postgres connection fields.
- * @param sqlDir   Absolute path to the directory containing SQL migration files
- *                 written for Postgres (with `$1,$2...` placeholders).
- *                 If migrations are SQLite-first, use `convertToPostgresPlaceholders`
- *                 before passing them.
  */
 async function PostgresDbUtilsInit(context, config, sqlDir) {
     const span = tracer.startSpan("PostgresDbUtilsInit", context);
-    pool = new pg_1.Pool({
+    // Use the schema-level init but without schema creation (single-pool mode)
+    const poolOptions = {
         host: config.DATABASE_POSTGRES_HOST,
         port: config.DATABASE_POSTGRES_PORT || 5432,
         user: config.DATABASE_POSTGRES_USER,
@@ -82,7 +395,9 @@ async function PostgresDbUtilsInit(context, config, sqlDir) {
         idleTimeoutMillis: 30000,
         connectionTimeoutMillis: 10000,
         keepAlive: true,
-    });
+    };
+    // Create a simple pool directly for the functional API
+    pool = new pg_1.Pool(poolOptions);
     pool.on("error", (err) => {
         logger.error("PostgreSQL pool connection error", err);
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devopsplaybook.io/common-utils",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Shared utility modules for devopsplaybook.io projects (DB, Config, OTel context, system helpers)",
   "keywords": [
     "Open Telemetry",
@@ -24,7 +24,7 @@
     "@devopsplaybook.io/otel-utils": "^1.1.0",
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/sdk-trace-base": "^2.7.1",
-    "better-sqlite3": "^12.9.0",
+    "better-sqlite3": "^12.10.0",
     "fs-extra": "^11.3.5",
     "pg": "^8.21.0",
     "uuid": "^14.0.0"
@@ -34,15 +34,15 @@
     "@types/better-sqlite3": "^7.6.13",
     "@types/fs-extra": "^11.0.4",
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.9.1",
+    "@types/node": "^25.9.2",
     "@types/pg": "^8.20.0",
-    "@types/uuid": "^10.0.0",
-    "eslint": "^10.4.0",
+    "@types/uuid": "^11.0.0",
+    "eslint": "^10.4.1",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.11",
     "ts-node": "^10.9.2",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.59.4"
+    "typescript-eslint": "^8.60.1"
   },
   "publishConfig": {
     "access": "public"

package/src/PostgresDbUtils.ts

@@ -19,9 +19,466 @@ export interface PostgresDbConfig {
   DATABASE_POSTGRES_DATABASE: string;
 }
 
+// ---------------------------------------------------------------------------
+// Module-level state
+// ---------------------------------------------------------------------------
+
 let pool: Pool;
 let tracer: StandardTracer;
 let logger: ModuleLogger;
+let standardLogger: StandardLogger;
+
+// ---------------------------------------------------------------------------
+// Class-based API – supports per-schema pools + shared runtime pool
+// ---------------------------------------------------------------------------
+
+/**
+ * Class-based PostgreSQL utility that manages a schema-specific pool (used
+ * during migrations) and an optional shared runtime pool (used for
+ * application queries).
+ *
+ * Multiple instances can coexist, each bound to a different PostgreSQL
+ * schema, while sharing a single runtime pool that has all schemas in its
+ * `search_path`.
+ */
+export class PostgresSchemaDbUtils {
+  private schemaPool: Pool | null = null;
+  private runtimePool: Pool | null = null;
+  private readonly schemaName: string;
+  private readonly moduleLogger: ModuleLogger;
+
+  constructor(schemaName: string) {
+    this.schemaName = schemaName;
+    this.moduleLogger = standardLogger.createModuleLogger(
+      `PostgresSchemaDbUtils[${schemaName}]`,
+    );
+  }
+
+  /**
+   * Create the schema-specific pool, ensure the schema exists, and apply
+   * any pending migration files from `sqlDir`.
+   */
+  async initSchema(
+    context: Span,
+    config: PostgresDbConfig,
+    sqlDir: string,
+  ): Promise<void> {
+    const span = tracer.startSpan("PostgresSchemaDbUtilsInit", context);
+
+    const poolOptions = {
+      host: config.DATABASE_POSTGRES_HOST,
+      port: config.DATABASE_POSTGRES_PORT || 5432,
+      user: config.DATABASE_POSTGRES_USER,
+      password: config.DATABASE_POSTGRES_PASSWORD,
+      database: config.DATABASE_POSTGRES_DATABASE,
+      options: `-c search_path=${this.schemaName}`,
+      max: 5,
+      idleTimeoutMillis: 30000,
+      connectionTimeoutMillis: 10000,
+    };
+
+    if (this.schemaPool) {
+      this.moduleLogger.info("Closing existing schema pool");
+      await this.schemaPool.end().catch(() => {
+        // Ignore errors on close
+      });
+    }
+    this.schemaPool = new Pool(poolOptions);
+    this.moduleLogger.info(
+      `Schema pool initialized with search_path: ${this.schemaName}`,
+    );
+
+    // Create schema if not exists
+    await this.execSQLForSchema(
+      span,
+      `CREATE SCHEMA IF NOT EXISTS ${this.schemaName};`,
+    );
+    await this.execSQLForSchema(
+      span,
+      `SET search_path TO ${this.schemaName};`,
+    );
+
+    // Run init SQL files
+    await this.execSQLFileForSchema(span, `${sqlDir}/init-0000.sql`);
+    const initFiles = (await fs.readdir(sqlDir)).sort();
+    let dbVersionApplied = 0;
+
+    try {
+      const dbVersionQuery = await this.querySQLForSchema(
+        span,
+        "SELECT MAX(value) as version FROM metadata WHERE type='db_version'",
+      );
+      if (
+        (dbVersionQuery[0] as Record<string, unknown>).version
+      ) {
+        dbVersionApplied = Number(
+          (dbVersionQuery[0] as Record<string, unknown>).version,
+        );
+      }
+    } catch {
+      // Table might not exist yet
+    }
+
+    this.moduleLogger.info(`Current DB Version: ${dbVersionApplied}`);
+
+    for (const initFile of initFiles) {
+      const regex = /init-(\d+)\.sql/g;
+      const match = regex.exec(initFile);
+      if (match) {
+        const dbVersionInitFile = Number(match[1]);
+        if (dbVersionInitFile > dbVersionApplied) {
+          this.moduleLogger.info(`Applying migration: ${initFile}`);
+          await this.execSQLFileForSchema(span, `${sqlDir}/${initFile}`);
+          await this.querySQLForSchema(
+            span,
+            'INSERT INTO metadata ("type", "value", "dateCreated") VALUES ($1, $2, $3)',
+            ["db_version", dbVersionInitFile, new Date().toISOString()],
+          );
+        }
+      }
+    }
+
+    span.end();
+  }
+
+  /**
+   * Initialise (or replace) the shared runtime pool.
+   * Typically called once with a pool whose `search_path` includes all
+   * application schemas.
+   */
+  initRuntimePool(config: PostgresDbConfig, searchPath?: string): void {
+    if (this.runtimePool) {
+      this.runtimePool.end().catch(() => {
+        // Ignore errors on close
+      });
+    }
+    this.runtimePool = new Pool({
+      host: config.DATABASE_POSTGRES_HOST,
+      port: config.DATABASE_POSTGRES_PORT || 5432,
+      user: config.DATABASE_POSTGRES_USER,
+      password: config.DATABASE_POSTGRES_PASSWORD,
+      database: config.DATABASE_POSTGRES_DATABASE,
+      options: searchPath
+        ? `-c search_path=${searchPath}`
+        : `-c search_path=${this.schemaName}`,
+      max: 20,
+      idleTimeoutMillis: 30000,
+      connectionTimeoutMillis: 10000,
+      keepAlive: true,
+    });
+    this.moduleLogger.info(
+      `Runtime pool initialized (search_path: ${searchPath || this.schemaName})`,
+    );
+  }
+
+  /**
+   * Execute a write SQL statement with OTel tracing.
+   * @param useSchemaPool  When `true` use the schema-specific pool;
+   *                       otherwise use the runtime pool (default).
+   * @returns Number of rows changed.
+   */
+  execSQL(
+    context: Span,
+    sql: string,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    params: any[] = [],
+    useSchemaPool = false,
+  ): Promise<number> {
+    const span = tracer.startSpan("PostgresSchemaDbUtilsExecSQL", context);
+    const pool = useSchemaPool ? this.schemaPool : this.runtimePool;
+
+    if (!pool) {
+      throw new Error(
+        `Pool not initialized${useSchemaPool ? ` for schema: ${this.schemaName}` : ""}`,
+      );
+    }
+
+    return new Promise((resolve, reject) => {
+      pool.query(
+        sql,
+        params,
+        (error: Error | null, result: { rowCount: number | null }) => {
+          span.end();
+          if (error) {
+            span.setStatus({
+              code: SpanStatusCode.ERROR,
+              message: error.message,
+            });
+            this.moduleLogger.error(
+              `[${useSchemaPool ? this.schemaName : "RUNTIME"}] SQL EXEC ERROR: ${sql}`,
+              error,
+            );
+            reject(error);
+          } else {
+            resolve(result.rowCount || 0);
+          }
+        },
+      );
+    });
+  }
+
+  /** Execute an entire SQL file (used for migrations). */
+  async execSQLFile(
+    context: Span,
+    filename: string,
+    useSchemaPool = false,
+  ): Promise<void> {
+    const span = tracer.startSpan(
+      "PostgresSchemaDbUtilsExecSQLFile",
+      context,
+    );
+    const sql = (await fs.readFile(filename)).toString();
+    const pool = useSchemaPool ? this.schemaPool : this.runtimePool;
+
+    if (!pool) {
+      throw new Error(
+        `Pool not initialized${useSchemaPool ? ` for schema: ${this.schemaName}` : ""}`,
+      );
+    }
+
+    return new Promise((resolve, reject) => {
+      pool.query(sql, (error: Error | null) => {
+        span.end();
+        if (error) {
+          span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: error.message,
+          });
+          reject(error);
+        } else {
+          resolve();
+        }
+      });
+    });
+  }
+
+  /**
+   * Execute a read SQL query with OTel tracing.
+   * @returns Array of row objects.
+   */
+  querySQL(
+    context: Span,
+    sql: string,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    params: any[] = [],
+    useSchemaPool = false,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ): Promise<any[]> {
+    const span = tracer.startSpan("PostgresSchemaDbUtilsQuerySQL", context);
+    const pool = useSchemaPool ? this.schemaPool : this.runtimePool;
+
+    if (!pool) {
+      throw new Error(
+        `Pool not initialized${useSchemaPool ? ` for schema: ${this.schemaName}` : ""}`,
+      );
+    }
+
+    return new Promise((resolve, reject) => {
+      pool.query(
+        sql,
+        params,
+        (error: Error | null, result: { rows: unknown[] }) => {
+          span.end();
+          if (error) {
+            span.setStatus({
+              code: SpanStatusCode.ERROR,
+              message: error.message,
+            });
+            this.moduleLogger.error(
+              `[${useSchemaPool ? this.schemaName : "RUNTIME"}] SQL QUERY ERROR: ${sql}`,
+              error,
+            );
+            reject(error);
+          } else {
+            resolve(result.rows);
+          }
+        },
+      );
+    });
+  }
+
+  /**
+   * Run a callback inside a transaction.
+   */
+  async transaction(
+    context: Span,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    callback: (client: any) => Promise<void>,
+    useSchemaPool = false,
+  ): Promise<void> {
+    const span = tracer.startSpan(
+      "PostgresSchemaDbUtilsTransaction",
+      context,
+    );
+    const pool = useSchemaPool ? this.schemaPool : this.runtimePool;
+
+    if (!pool) {
+      throw new Error(
+        `Pool not initialized${useSchemaPool ? ` for schema: ${this.schemaName}` : ""}`,
+      );
+    }
+
+    this.moduleLogger.info(
+      `[${useSchemaPool ? this.schemaName : "RUNTIME"}] Starting transaction`,
+    );
+    const client = await pool.connect();
+    try {
+      await client.query("BEGIN");
+      await callback(client);
+      await client.query("COMMIT");
+      this.moduleLogger.info(
+        `[${useSchemaPool ? this.schemaName : "RUNTIME"}] Transaction committed`,
+      );
+    } catch (error) {
+      await client.query("ROLLBACK");
+      this.moduleLogger.error(
+        `[${useSchemaPool ? this.schemaName : "RUNTIME"}] Transaction rolled back`,
+        error as Error,
+      );
+      throw error;
+    } finally {
+      client.release();
+      span.end();
+    }
+  }
+
+  /** Close both the schema pool and the runtime pool. */
+  async closeAll(): Promise<void> {
+    const promises: Promise<void>[] = [];
+
+    if (this.schemaPool) {
+      this.moduleLogger.info("Closing schema pool");
+      promises.push(
+        this.schemaPool.end().catch(() => {
+          this.moduleLogger.warn("Error closing schema pool");
+        }),
+      );
+      this.schemaPool = null;
+    }
+
+    if (this.runtimePool) {
+      this.moduleLogger.info("Closing runtime pool");
+      promises.push(
+        this.runtimePool.end().catch(() => {
+          this.moduleLogger.warn("Error closing runtime pool");
+        }),
+      );
+      this.runtimePool = null;
+    }
+
+    await Promise.all(promises);
+    this.moduleLogger.info("All database pools closed");
+  }
+
+  // -- Internal helpers (schema pool only) ----------------------------------
+
+  private execSQLForSchema(
+    context: Span,
+    sql: string,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    params: any[] = [],
+  ): Promise<void> {
+    const span = tracer.startSpan(
+      "PostgresSchemaDbUtilsExecSQLForSchema",
+      context,
+    );
+
+    if (!this.schemaPool) {
+      throw new Error(`Pool not initialized for schema: ${this.schemaName}`);
+    }
+
+    return new Promise((resolve, reject) => {
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      this.schemaPool!.query(sql, params, (error: Error | null) => {
+        span.end();
+        if (error) {
+          reject(error);
+        } else {
+          resolve();
+        }
+      });
+    });
+  }
+
+  private async execSQLFileForSchema(
+    context: Span,
+    filename: string,
+  ): Promise<void> {
+    try {
+      const span = tracer.startSpan(
+        "PostgresSchemaDbUtilsExecSQLFileForSchema",
+        context,
+      );
+      const sql = (await fs.readFile(filename)).toString();
+
+      if (!this.schemaPool) {
+        throw new Error(`Pool not initialized for schema: ${this.schemaName}`);
+      }
+
+      return new Promise((resolve, reject) => {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        this.schemaPool!.query(sql, (error: Error | null) => {
+          span.end();
+          if (error) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            if ((error as any).code === "ENOENT") {
+              resolve();
+            } else {
+              reject(error);
+            }
+          } else {
+            resolve();
+          }
+        });
+      });
+    } catch (error) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      if ((error as any).code === "ENOENT") {
+        return;
+      }
+      throw error;
+    }
+  }
+
+  private querySQLForSchema(
+    context: Span,
+    sql: string,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    params: any[] = [],
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ): Promise<any[]> {
+    const span = tracer.startSpan(
+      "PostgresSchemaDbUtilsQuerySQLForSchema",
+      context,
+    );
+
+    if (!this.schemaPool) {
+      throw new Error(`Pool not initialized for schema: ${this.schemaName}`);
+    }
+
+    return new Promise((resolve, reject) => {
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      this.schemaPool!.query(
+        sql,
+        params,
+        (error: Error | null, result: { rows: unknown[] }) => {
+          span.end();
+          if (error) {
+            reject(error);
+          } else {
+            resolve(result.rows);
+          }
+        },
+      );
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Functional API – single-pool mode used by the DbUtils facade.
+// An internal PostgresSchemaDbUtils instance backs these functions so the
+// behaviour is identical to before.
+// ---------------------------------------------------------------------------
 
 /**
  * Injects the OTel tracer and logger instances used by all Postgres operations.
@@ -32,23 +489,13 @@ export function PostgresDbUtilsSetOTel(
   loggerIn: StandardLogger,
 ): void {
   tracer = tracerIn;
+  standardLogger = loggerIn;
   logger = loggerIn.createModuleLogger("PostgresDbUtils");
 }
 
 /**
  * Creates the Postgres connection pool and applies pending migration files
  * from `sqlDir`.
- *
- * Migration files must follow the naming convention `init-NNNN.sql` and are
- * applied in lexicographic order.  A `metadata` table tracks which migrations
- * have already been applied so they are idempotent.
- *
- * @param context  Parent OTel span.
- * @param config   Configuration with Postgres connection fields.
- * @param sqlDir   Absolute path to the directory containing SQL migration files
- *                 written for Postgres (with `$1,$2...` placeholders).
- *                 If migrations are SQLite-first, use `convertToPostgresPlaceholders`
- *                 before passing them.
  */
 export async function PostgresDbUtilsInit(
   context: Span,
@@ -57,7 +504,8 @@ export async function PostgresDbUtilsInit(
 ): Promise<void> {
   const span = tracer.startSpan("PostgresDbUtilsInit", context);
 
-  pool = new Pool({
+  // Use the schema-level init but without schema creation (single-pool mode)
+  const poolOptions = {
     host: config.DATABASE_POSTGRES_HOST,
     port: config.DATABASE_POSTGRES_PORT || 5432,
     user: config.DATABASE_POSTGRES_USER,
@@ -67,7 +515,10 @@ export async function PostgresDbUtilsInit(
     idleTimeoutMillis: 30000,
     connectionTimeoutMillis: 10000,
     keepAlive: true,
-  });
+  };
+
+  // Create a simple pool directly for the functional API
+  pool = new Pool(poolOptions);
 
   pool.on("error", (err: Error) => {
     logger.error("PostgreSQL pool connection error", err);