@devopsplaybook.io/common-utils 1.10.1 → 1.11.0-beta.24.d8f9aef

package/dist/src/PostgresDbUtils.js

@@ -33,9 +33,10 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PostgresSchemaDbUtils = void 0;
+exports.PostgresSchemaDbUtils = exports.POSTGRES_LOCK_KEYS = void 0;
 exports.PostgresDbUtilsSetOTel = PostgresDbUtilsSetOTel;
 exports.PostgresDbUtilsInit = PostgresDbUtilsInit;
+exports.PostgresDbUtilsWithAdvisoryLock = PostgresDbUtilsWithAdvisoryLock;
 exports.PostgresDbUtilsGetPool = PostgresDbUtilsGetPool;
 exports.PostgresDbUtilsExecSQL = PostgresDbUtilsExecSQL;
 exports.PostgresDbUtilsExecSQLFile = PostgresDbUtilsExecSQLFile;
@@ -45,6 +46,11 @@ exports.PostgresDbUtilsTransactionCommit = PostgresDbUtilsTransactionCommit;
 const pg_1 = require("pg");
 const fs = __importStar(require("fs-extra"));
 const api_1 = require("@opentelemetry/api");
+exports.POSTGRES_LOCK_KEYS = {
+    migration: 0x6d696772, // "migr"
+    auth_token: 0x61757468, // "auth"
+    users_bootstrap: 0x75736572, // "user"
+};
 // ---------------------------------------------------------------------------
 // Module-level state
 // ---------------------------------------------------------------------------
@@ -53,6 +59,115 @@ let tracer;
 let logger;
 let standardLogger;
 // ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** Build the connection options shared by every pool. */
+function buildPoolConfig(config, searchPath, max, keepAlive) {
+    const poolConfig = {
+        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,
+        max,
+        idleTimeoutMillis: 30000,
+        connectionTimeoutMillis: 10000,
+        keepAlive,
+    };
+    if (searchPath) {
+        poolConfig.options = `-c search_path=${searchPath}`;
+    }
+    if (config.DATABASE_POSTGRES_STATEMENT_TIMEOUT_MS) {
+        poolConfig.statement_timeout = config.DATABASE_POSTGRES_STATEMENT_TIMEOUT_MS;
+    }
+    if (config.DATABASE_POSTGRES_IDLE_IN_TRANSACTION_TIMEOUT_MS) {
+        poolConfig.idle_in_transaction_session_timeout =
+            config.DATABASE_POSTGRES_IDLE_IN_TRANSACTION_TIMEOUT_MS;
+    }
+    return poolConfig;
+}
+/**
+ * Run a callback while holding a session-level advisory lock on the given
+ * client. Replicas booting concurrently serialise on the lock instead of
+ * applying the same migration twice.
+ */
+async function withAdvisoryLockOnClient(client, lockKey, callback) {
+    await client.query("SELECT pg_advisory_lock($1)", [lockKey]);
+    try {
+        return await callback();
+    }
+    finally {
+        await client.query("SELECT pg_advisory_unlock($1)", [lockKey]).catch(() => {
+            // The connection may already be broken; the lock dies with it.
+        });
+    }
+}
+/** Run one query on a dedicated client with its own span. */
+async function queryOnClient(client, context, spanName, sql, params = []) {
+    const span = tracer.startSpan(spanName, context);
+    try {
+        const result = await client.query(sql, params);
+        return result.rows;
+    }
+    catch (error) {
+        span.setStatus({
+            code: api_1.SpanStatusCode.ERROR,
+            message: error.message,
+        });
+        throw error;
+    }
+    finally {
+        span.end();
+    }
+}
+/**
+ * Apply one SQL file on a dedicated client inside a transaction, together
+ * with its `metadata` version row when a version is given. On failure the
+ * transaction is rolled back: no partial state, no version row.
+ *
+ * Migration files must not contain their own transaction control statements.
+ */
+async function applyMigrationOnClient(client, context, filename, version) {
+    const span = tracer.startSpan("PostgresDbUtilsExecSQLFile", context);
+    try {
+        const sql = (await fs.readFile(filename)).toString();
+        await client.query("BEGIN");
+        try {
+            await client.query(sql);
+            if (version !== null) {
+                await client.query('INSERT INTO metadata ("type", "value", "dateCreated") VALUES ($1, $2, $3)', ["db_version", version, new Date().toISOString()]);
+            }
+            await client.query("COMMIT");
+        }
+        catch (error) {
+            await client.query("ROLLBACK").catch(() => {
+                // Connection failure: nothing to roll back.
+            });
+            throw error;
+        }
+    }
+    catch (error) {
+        span.setStatus({
+            code: api_1.SpanStatusCode.ERROR,
+            message: error.message,
+        });
+        throw error;
+    }
+    finally {
+        span.end();
+    }
+}
+/** Read the highest applied migration version (numeric, not lexicographic). */
+async function readAppliedVersion(client, context, spanName) {
+    // `metadata.value` has text affinity: a plain MAX(value) is lexicographic and
+    // ranks "9" above "10", which re-applies init-0010.sql on every boot.
+    const rows = await queryOnClient(client, context, spanName, "SELECT MAX(CAST(value AS INTEGER)) as version FROM metadata WHERE \"type\" = 'db_version'");
+    if (rows.length > 0 && rows[0].version !== null && rows[0].version !== undefined) {
+        return Number(rows[0].version);
+    }
+    return 0;
+}
+// ---------------------------------------------------------------------------
 // Class-based API – supports per-schema pools + shared runtime pool
 // ---------------------------------------------------------------------------
 /**
@@ -83,55 +198,50 @@ class PostgresSchemaDbUtils {
      */
     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);
+            if (this.schemaPool) {
+                this.moduleLogger.info("Closing existing schema pool");
+                await this.schemaPool.end().catch(() => {
+                    // Ignore errors on close
+                });
             }
-        }
-        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()]);
-                }
+            const schemaPool = new pg_1.Pool(buildPoolConfig(config, this.schemaName, 5, false));
+            this.schemaPool = schemaPool;
+            this.moduleLogger.info(`Schema pool initialized with search_path: ${this.schemaName}`);
+            const client = await schemaPool.connect();
+            try {
+                await withAdvisoryLockOnClient(client, exports.POSTGRES_LOCK_KEYS.migration, async () => {
+                    await queryOnClient(client, span, "PostgresSchemaDbUtilsExecSQLForSchema", `CREATE SCHEMA IF NOT EXISTS ${this.schemaName};`);
+                    await queryOnClient(client, span, "PostgresSchemaDbUtilsExecSQLForSchema", `SET search_path TO ${this.schemaName};`);
+                    await applyMigrationOnClient(client, span, `${sqlDir}/init-0000.sql`, null);
+                    let dbVersionApplied = 0;
+                    try {
+                        dbVersionApplied = await readAppliedVersion(client, span, "PostgresSchemaDbUtilsQuerySQLForSchema");
+                    }
+                    catch {
+                        // The metadata table might not exist yet
+                    }
+                    this.moduleLogger.info(`Current DB Version: ${dbVersionApplied}`);
+                    const initFiles = (await fs.readdir(sqlDir)).sort();
+                    for (const initFile of initFiles) {
+                        const match = /init-(\d+)\.sql/.exec(initFile);
+                        if (match) {
+                            const dbVersionInitFile = Number(match[1]);
+                            if (dbVersionInitFile > dbVersionApplied) {
+                                this.moduleLogger.info(`Applying migration: ${initFile}`);
+                                await applyMigrationOnClient(client, span, `${sqlDir}/${initFile}`, dbVersionInitFile);
+                            }
+                        }
+                    }
+                });
+            }
+            finally {
+                client.release();
             }
         }
-        span.end();
+        finally {
+            span.end();
+        }
     }
     /**
      * Initialise (or replace) the shared runtime pool.
@@ -144,20 +254,7 @@ class PostgresSchemaDbUtils {
                 // 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.runtimePool = new pg_1.Pool(buildPoolConfig(config, searchPath || this.schemaName, 20, true));
         this.moduleLogger.info(`Runtime pool initialized (search_path: ${searchPath || this.schemaName})`);
     }
     /**
@@ -166,104 +263,117 @@ class PostgresSchemaDbUtils {
      *                       otherwise use the runtime pool (default).
      * @returns Number of rows changed.
      */
-    execSQL(context, sql, params = [], useSchemaPool = false) {
+    async execSQL(context, sql, 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}` : ""}`);
+        let targetPool = null;
+        try {
+            targetPool = useSchemaPool ? this.schemaPool : this.runtimePool;
+            if (!targetPool) {
+                throw new Error(`Pool not initialized${useSchemaPool ? ` for schema: ${this.schemaName}` : ""}`);
+            }
+            const result = await targetPool.query(sql, params);
+            return result.rowCount || 0;
         }
-        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);
-                }
+        catch (error) {
+            span.setStatus({
+                code: api_1.SpanStatusCode.ERROR,
+                message: error.message,
             });
-        });
+            if (targetPool) {
+                this.moduleLogger.error(`[${useSchemaPool ? this.schemaName : "RUNTIME"}] SQL EXEC ERROR: ${sql}`, error);
+            }
+            throw error;
+        }
+        finally {
+            span.end();
+        }
     }
-    /** Execute an entire SQL file (used for migrations). */
+    /**
+     * Execute an entire SQL file (used for migrations).
+     * Migration files must not contain their own transaction control statements.
+     */
     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}` : ""}`);
+        let targetPool = null;
+        try {
+            targetPool = useSchemaPool ? this.schemaPool : this.runtimePool;
+            if (!targetPool) {
+                throw new Error(`Pool not initialized${useSchemaPool ? ` for schema: ${this.schemaName}` : ""}`);
+            }
+            const sql = (await fs.readFile(filename)).toString();
+            await targetPool.query(sql);
         }
-        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();
-                }
+        catch (error) {
+            span.setStatus({
+                code: api_1.SpanStatusCode.ERROR,
+                message: error.message,
             });
-        });
+            throw error;
+        }
+        finally {
+            span.end();
+        }
     }
     /**
      * Execute a read SQL query with OTel tracing.
      * @returns Array of row objects.
      */
-    querySQL(context, sql, params = [], useSchemaPool = false) {
+    async querySQL(context, sql, 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}` : ""}`);
+        let targetPool = null;
+        try {
+            targetPool = useSchemaPool ? this.schemaPool : this.runtimePool;
+            if (!targetPool) {
+                throw new Error(`Pool not initialized${useSchemaPool ? ` for schema: ${this.schemaName}` : ""}`);
+            }
+            const result = await targetPool.query(sql, params);
+            return result.rows;
         }
-        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);
-                }
+        catch (error) {
+            span.setStatus({
+                code: api_1.SpanStatusCode.ERROR,
+                message: error.message,
             });
-        });
+            if (targetPool) {
+                this.moduleLogger.error(`[${useSchemaPool ? this.schemaName : "RUNTIME"}] SQL QUERY ERROR: ${sql}`, error);
+            }
+            throw error;
+        }
+        finally {
+            span.end();
+        }
     }
     /**
      * Run a callback inside a transaction.
      */
     async transaction(context, 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();
+        let client = null;
         try {
+            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`);
+            client = await pool.connect();
             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);
+            if (client) {
+                await client.query("ROLLBACK").catch(() => {
+                    // Connection failure: nothing to roll back.
+                });
+                this.moduleLogger.error(`[${useSchemaPool ? this.schemaName : "RUNTIME"}] Transaction rolled back`, error);
+            }
             throw error;
         }
         finally {
-            client.release();
+            if (client) {
+                client.release();
+            }
             span.end();
         }
     }
@@ -287,78 +397,10 @@ class PostgresSchemaDbUtils {
         await Promise.all(promises);
         this.moduleLogger.info("All database pools closed");
     }
-    // -- Internal helpers (schema pool only) ----------------------------------
-    execSQLForSchema(context, sql, 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) => {
-            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) => {
-                this.schemaPool.query(sql, (error) => {
-                    span.end();
-                    if (error) {
-                        if (error.code === "ENOENT") {
-                            resolve();
-                        }
-                        else {
-                            reject(error);
-                        }
-                    }
-                    else {
-                        resolve();
-                    }
-                });
-            });
-        }
-        catch (error) {
-            if (error.code === "ENOENT") {
-                return;
-            }
-            throw error;
-        }
-    }
-    querySQLForSchema(context, sql, 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) => {
-            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.
@@ -372,47 +414,59 @@ function PostgresDbUtilsSetOTel(tracerIn, loggerIn) {
 /**
  * Creates the Postgres connection pool and applies pending migration files
  * from `sqlDir`.
+ *
+ * Migrations are applied under a session-level advisory lock (concurrently
+ * booting replicas serialise instead of double-applying) and each file plus
+ * its `db_version` row runs in its own transaction: a failing migration is
+ * rolled back and never recorded.
  */
 async function PostgresDbUtilsInit(context, config, sqlDir) {
     const span = tracer.startSpan("PostgresDbUtilsInit", context);
-    // 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,
-        password: config.DATABASE_POSTGRES_PASSWORD,
-        database: config.DATABASE_POSTGRES_DATABASE,
-        max: 20,
-        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);
-    });
-    await PostgresDbUtilsExecSQLFile(span, `${sqlDir}/init-0000.sql`);
-    const initFiles = (await fs.readdir(sqlDir)).sort();
-    let dbVersionApplied = 0;
-    const dbVersionQuery = await PostgresDbUtilsQuerySQL(span, "SELECT MAX(value) as version FROM metadata WHERE \"type\" = 'db_version'");
-    if (dbVersionQuery.length > 0 && dbVersionQuery[0].version) {
-        dbVersionApplied = Number(dbVersionQuery[0].version);
-    }
-    logger.info(`Current DB Version: ${dbVersionApplied}`, span);
-    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) {
-                logger.info(`Loading init file: ${initFile}`, span);
-                await PostgresDbUtilsExecSQLFile(span, `${sqlDir}/${initFile}`);
-                await PostgresDbUtilsQuerySQL(span, 'INSERT INTO metadata ("type", "value", "dateCreated") VALUES ($1, $2, $3)', ["db_version", dbVersionInitFile, new Date().toISOString()]);
-            }
+    try {
+        pool = new pg_1.Pool(buildPoolConfig(config, undefined, 20, true));
+        pool.on("error", (err) => {
+            logger.error("PostgreSQL pool connection error", err);
+        });
+        const client = await pool.connect();
+        try {
+            await withAdvisoryLockOnClient(client, exports.POSTGRES_LOCK_KEYS.migration, async () => {
+                await applyMigrationOnClient(client, span, `${sqlDir}/init-0000.sql`, null);
+                const dbVersionApplied = await readAppliedVersion(client, span, "PostgresDbUtilsQuerySQL");
+                logger.info(`Current DB Version: ${dbVersionApplied}`, span);
+                const initFiles = (await fs.readdir(sqlDir)).sort();
+                for (const initFile of initFiles) {
+                    const match = /init-(\d+)\.sql/.exec(initFile);
+                    if (match) {
+                        const dbVersionInitFile = Number(match[1]);
+                        if (dbVersionInitFile > dbVersionApplied) {
+                            logger.info(`Loading init file: ${initFile}`, span);
+                            await applyMigrationOnClient(client, span, `${sqlDir}/${initFile}`, dbVersionInitFile);
+                        }
+                    }
+                }
+            });
         }
+        finally {
+            client.release();
+        }
+    }
+    finally {
+        span.end();
+    }
+}
+/**
+ * Run a callback while holding a Postgres advisory lock, serialising the
+ * callback across every replica of every service booting against the same
+ * database (used for the `auth_token` and first-user bootstrap races).
+ */
+async function PostgresDbUtilsWithAdvisoryLock(lock, callback) {
+    const client = await pool.connect();
+    try {
+        return await withAdvisoryLockOnClient(client, exports.POSTGRES_LOCK_KEYS[lock], callback);
+    }
+    finally {
+        client.release();
     }
-    span.end();
 }
 /** Returns the underlying `pg.Pool` instance. */
 function PostgresDbUtilsGetPool() {
@@ -422,102 +476,101 @@ function PostgresDbUtilsGetPool() {
  * Execute a write SQL statement with OTel tracing.
  * @returns Number of rows changed.
  */
-function PostgresDbUtilsExecSQL(context, sql, params = []) {
+async function PostgresDbUtilsExecSQL(context, sql, params = []) {
     const span = tracer.startSpan("PostgresDbUtilsExecSQL", context);
-    return new Promise((resolve, reject) => {
-        pool.query(sql, params, (error, result) => {
-            if (error) {
-                span.setStatus({
-                    code: api_1.SpanStatusCode.ERROR,
-                    message: error.message,
-                });
-                span.end();
-                reject(error);
-            }
-            else {
-                span.addEvent(`Impacted Rows: ${result.rowCount || 0}`);
-                span.end();
-                resolve(result.rowCount || 0);
-            }
+    try {
+        const result = await pool.query(sql, params);
+        span.addEvent(`Impacted Rows: ${result.rowCount || 0}`);
+        return result.rowCount || 0;
+    }
+    catch (error) {
+        span.setStatus({
+            code: api_1.SpanStatusCode.ERROR,
+            message: error.message,
         });
-    });
+        throw error;
+    }
+    finally {
+        span.end();
+    }
 }
-/** Execute an entire SQL file (used for migrations). */
+/**
+ * Execute an entire SQL file (used for migrations).
+ * Migration files must not contain their own transaction control statements.
+ */
 async function PostgresDbUtilsExecSQLFile(context, filename) {
     const span = tracer.startSpan("PostgresDbUtilsExecSQLFile", context);
-    const sql = (await fs.readFile(filename)).toString();
-    return new Promise((resolve, reject) => {
-        pool.query(sql, (error) => {
-            if (error) {
-                span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: error.message });
-                span.end();
-                reject(error);
-            }
-            else {
-                span.end();
-                resolve();
-            }
+    try {
+        const sql = (await fs.readFile(filename)).toString();
+        await pool.query(sql);
+    }
+    catch (error) {
+        span.setStatus({
+            code: api_1.SpanStatusCode.ERROR,
+            message: error.message,
         });
-    });
+        throw error;
+    }
+    finally {
+        span.end();
+    }
 }
 /**
  * Execute a read SQL query with OTel tracing.
  * @returns Array of row objects.
  */
-function PostgresDbUtilsQuerySQL(context, sql, params = [], debug = false) {
+async function PostgresDbUtilsQuerySQL(context, sql, params = [], debug = false) {
     const span = tracer.startSpan("PostgresDbUtilsQuerySQL", context);
     if (debug) {
         console.log(sql);
     }
-    return new Promise((resolve, reject) => {
-        pool.query(sql, params, (error, result) => {
-            if (error) {
-                span.setStatus({
-                    code: api_1.SpanStatusCode.ERROR,
-                    message: error.message,
-                });
-                logger.error(`SQL ERROR: ${sql}`, error, span);
-                span.end();
-                reject(error);
-            }
-            else {
-                span.end();
-                resolve(result.rows);
-            }
+    try {
+        const result = await pool.query(sql, params);
+        return result.rows;
+    }
+    catch (error) {
+        span.setStatus({
+            code: api_1.SpanStatusCode.ERROR,
+            message: error.message,
         });
-    });
+        logger.error(`SQL ERROR: ${sql}`, error, span);
+        throw error;
+    }
+    finally {
+        span.end();
+    }
 }
 /** Start a transaction. */
-function PostgresDbUtilsTransactionStart(context) {
+async function PostgresDbUtilsTransactionStart(context) {
     const span = tracer.startSpan("PostgresDbUtilsTransactionStart", context);
-    return new Promise((resolve, reject) => {
-        pool.query("BEGIN", (error) => {
-            if (error) {
-                span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: error.message });
-                span.end();
-                reject(error);
-            }
-            else {
-                span.end();
-                resolve();
-            }
+    try {
+        await pool.query("BEGIN");
+    }
+    catch (error) {
+        span.setStatus({
+            code: api_1.SpanStatusCode.ERROR,
+            message: error.message,
         });
-    });
+        throw error;
+    }
+    finally {
+        span.end();
+    }
 }
 /** Commit a transaction. */
-function PostgresDbUtilsTransactionCommit(context) {
+async function PostgresDbUtilsTransactionCommit(context) {
     const span = tracer.startSpan("PostgresDbUtilsTransactionCommit", context);
-    return new Promise((resolve, reject) => {
-        pool.query("COMMIT", (error) => {
-            if (error) {
-                span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: error.message });
-                span.end();
-                reject(error);
-            }
-            else {
-                span.end();
-                resolve();
-            }
+    try {
+        await pool.query("COMMIT");
+    }
+    catch (error) {
+        span.setStatus({
+            code: api_1.SpanStatusCode.ERROR,
+            message: error.message,
         });
-    });
+        throw error;
+    }
+    finally {
+        span.end();
+    }
 }