@devopsplaybook.io/common-utils 1.0.0-beta.5.e74e0d9 → 1.1.0-beta.6.9ec503a

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-beta.5.e74e0d9",
+  "version": "1.1.0-beta.6.9ec503a",
   "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"