velocious 1.0.542 → 1.0.544

package/README.md

@@ -4,6 +4,7 @@
 * Database framework with familiar MVC concepts
 * Database models with migrations and validations
 * Database models that work almost the same in frontend and backend
+* Connection-scoped advisory locks with automatic cleanup before pooled connections are reused or closed (see [docs/advisory-locks.md](docs/advisory-locks.md))
 * Built-in record auditing for model lifecycle changes (see [docs/auditing.md](docs/auditing.md))
 * Declarative state machines for models, with typed event methods generated into the base model (see [docs/state-machine.md](docs/state-machine.md))
 * Migrations for schema changes and UTC datetime storage (see [docs/database-migrations.md](docs/database-migrations.md))
@@ -31,7 +32,7 @@
 * Trusted reverse proxy handling for `request.remoteAddress()` (see [docs/trusted-proxies.md](docs/trusted-proxies.md))
 * In-process driver schema metadata caching (see [docs/schema-metadata-cache.md](docs/schema-metadata-cache.md))
 * Planned local-first shared-resource sync architecture (see [docs/offline-sync.md](docs/offline-sync.md))
-* Named database connection checkouts, bounded pool waits, and debugging held connections (see [docs/database-connections.md](docs/database-connections.md))
+* Selective named database connection checkouts, bounded pool waits, and debugging held connections (see [docs/database-connections.md](docs/database-connections.md))
 * Optional built-in debug endpoint for inspecting server and database connection state (see [docs/debug-endpoint.md](docs/debug-endpoint.md))
 * Optional built-in API manifest endpoint describing every registered frontend-model resource as human- and machine-readable JSON (see [docs/api-manifest-endpoint.md](docs/api-manifest-endpoint.md))
 
@@ -2033,6 +2034,8 @@ import VelociousJob from "velocious/build/src/background-jobs/job.js"
 
 /** @augments {VelociousJob<[string, string]>} */
 export default class MyJob extends VelociousJob {
+  static databaseIdentifiers = ["default"]
+
   /**
    * @param {string} arg1
    * @param {string} arg2
@@ -2051,6 +2054,8 @@ Argument-less jobs use a bare `extends VelociousJob` with `async perform()` —
 default empty-tuple type argument keeps that working unchanged. Plain (unchecked)
 JavaScript can ignore the annotation entirely.
 
+Set `static databaseIdentifiers` when a job only needs specific configured databases. Velocious checks out only those connections around `perform` in every execution mode. Use `[]` for a job that needs no ambient database connection. Leaving the property undefined preserves the existing behavior of checking out every active database. See [Background Jobs](docs/background-jobs.md#database-connection-scopes).
+
 Queue a job:
 
 ```js

package/build/background-jobs/job-runner.js

@@ -105,7 +105,7 @@ export default async function runJobPayload(payload, {closeConnections = true, m
 
   try {
     try {
-      await configuration.withConnections({name: `Background job runner: ${payload.jobName}`}, async () => {
+      await configuration.withConnections({databaseIdentifiers: JobClass.databaseIdentifiers, name: `Background job runner: ${payload.jobName}`}, async () => {
         await perform.apply(jobInstance, payload.args || [])
       })
     } catch (error) {

package/build/background-jobs/job.js

@@ -13,6 +13,15 @@ import BackgroundJobsClient from "./client.js"
  * @template {Array<?>} [TArgs=[]]
  */
 export default class VelociousJob {
+  /**
+   * Database identifiers checked out while this job performs. Set an explicit
+   * list to avoid holding unrelated configured database connections, or `[]`
+   * when the job establishes any connections it needs itself. Left undefined,
+   * jobs retain the existing behavior of checking out every active database.
+   * @type {string[] | undefined}
+   */
+  static databaseIdentifiers = undefined
+
   /**
    * Queue this job class runs on. Subclasses set e.g. `static queue = "builds"`
    * to route onto a queue with its own cluster-wide concurrency cap (configured

package/build/background-jobs/worker.js

@@ -886,7 +886,7 @@ export default class BackgroundJobsWorker {
      * @type {(...args: Array<?>) => Promise<void>} */
     const perform = jobInstance.perform
 
-    await configuration.withConnections({name: `Background job worker inline: ${payload.jobName}`}, async () => {
+    await configuration.withConnections({databaseIdentifiers: JobClass.databaseIdentifiers, name: `Background job worker inline: ${payload.jobName}`}, async () => {
       await perform.apply(jobInstance, payload.args || [])
     })
   }

package/build/cli/commands/db/tenants/check.js

@@ -24,7 +24,7 @@ export default class DbTenantsCheck extends BaseCommand {
         })
       }
 
-      await this.getConfiguration().ensureConnections({name: `DB tenants check: ${helper.identifier}`}, async (dbs) => {
+      await this.getConfiguration().ensureConnections({databaseIdentifiers: [helper.identifier], name: `DB tenants check: ${helper.identifier}`}, async (dbs) => {
         const db = dbs[helper.identifier]
 
         if (!db) throw new Error(`Tenant database identifier ${helper.identifier} did not open a connection`)

package/build/cli/commands/db/tenants/migrate.js

@@ -22,20 +22,26 @@ export default class DbTenantsMigrate extends BaseCommand {
         databaseIdentifiers: [helper.identifier]
       })
 
-      await this.getConfiguration().ensureConnections({name: `DB tenants migrate: ${helper.identifier}`}, async () => {
+      let migrationsApplied = 0
+
+      await this.getConfiguration().ensureConnections({databaseIdentifiers: [helper.identifier], name: `DB tenants migrate: ${helper.identifier}`}, async () => {
         await migrator.prepare()
-        const migrationsApplied = await migrator.migrateFiles(migrations, digg(this.getEnvironmentHandler(), "requireMigration"))
+        migrationsApplied = await migrator.migrateFiles(migrations, digg(this.getEnvironmentHandler(), "requireMigration"))
+      })
+
+      const afterMigrateTenant = helper.provider.afterMigrateTenant
 
-        if (typeof helper.provider.afterMigrateTenant === "function") {
-          await helper.provider.afterMigrateTenant({
+      if (typeof afterMigrateTenant === "function") {
+        await this.getConfiguration().ensureConnections({name: `DB tenants after migrate: ${helper.identifier}`}, async () => {
+          await afterMigrateTenant({
             configuration: this.getConfiguration(),
             databaseConfiguration,
             identifier: helper.identifier,
             migrationsApplied,
             tenant
           })
-        }
-      })
+        })
+      }
     })
 
     if (this.args.testing) {

package/build/configuration.js

@@ -8,6 +8,7 @@
 /**
  * WithConnectionsOptionsType type.
  * @typedef {object} WithConnectionsOptionsType
+ * @property {string[]} [databaseIdentifiers] - Database identifiers to include in the connection scope.
  * @property {string} [name] - Human-readable name for the checked-out database connections.
  */
 
@@ -48,16 +49,17 @@ function currentWorkingDirectory() {
  * @param {WithConnectionsOptionsType | WithConnectionsCallbackType<T>} optionsOrCallback - Checkout options or callback function.
  * @param {WithConnectionsCallbackType<T> | undefined} callback - Callback function.
  * @param {string} defaultName - Default checkout name.
- * @returns {{name: string, callback: WithConnectionsCallbackType<T> | undefined}} Resolved checkout name and callback.
+ * @returns {{databaseIdentifiers: string[] | undefined, name: string, callback: WithConnectionsCallbackType<T> | undefined}} Resolved checkout options and callback.
  */
 function resolveWithConnectionsArgs(optionsOrCallback, callback, defaultName) {
   if (typeof optionsOrCallback == "function") {
     const actualCallback = /** @type {WithConnectionsCallbackType<T>} */ (optionsOrCallback)
 
-    return {name: defaultName, callback: actualCallback}
+    return {databaseIdentifiers: undefined, name: defaultName, callback: actualCallback}
   }
 
   return {
+    databaseIdentifiers: optionsOrCallback.databaseIdentifiers,
     name: optionsOrCallback.name || defaultName,
     callback
   }
@@ -2802,7 +2804,11 @@ export default class VelociousConfiguration {
    * @returns {Promise<T>} - Resolves with the callback result.
    */
   async withConnections(optionsOrCallback, callback) {
-    const {name, callback: actualWithConnectionsCallback} = resolveWithConnectionsArgs(optionsOrCallback, callback, "Configuration.withConnections")
+    const {
+      callback: actualWithConnectionsCallback,
+      databaseIdentifiers,
+      name
+    } = resolveWithConnectionsArgs(optionsOrCallback, callback, "Configuration.withConnections")
 
     if (!actualWithConnectionsCallback) throw new Error("withConnections requires a callback")
 
@@ -2814,7 +2820,7 @@ export default class VelociousConfiguration {
     return await this.withDatabaseIdentifierConnections({
       callback: actualWithConnectionsCallback,
       dbs,
-      identifiers: this.getDatabaseIdentifiers(),
+      identifiers: databaseIdentifiers ?? this.getDatabaseIdentifiers(),
       name,
       stackLabel: "withConnections"
     })
@@ -2858,15 +2864,16 @@ export default class VelociousConfiguration {
 
   /**
    * Runs get current connections.
+   * @param {string[]} [databaseIdentifiers] - Database identifiers to include.
    * @returns {Record<string, import("./database/drivers/base.js").default>} A map of database connections with identifier as key
    */
-  getCurrentConnections() {
+  getCurrentConnections(databaseIdentifiers = this.getDatabaseIdentifiers()) {
     /**
      * Dbs.
      * @type {{[key: string]: import("./database/drivers/base.js").default}} */
     const dbs = {}
 
-    for (const identifier of this.getDatabaseIdentifiers()) {
+    for (const identifier of databaseIdentifiers) {
       try {
         const pool = this.getDatabasePool(identifier)
         const currentConnection = pool.getCurrentContextConnection ? pool.getCurrentContextConnection() : pool.getCurrentConnection()
@@ -2950,12 +2957,17 @@ export default class VelociousConfiguration {
    * @returns {Promise<T>} - Resolves with the callback result.
    */
   async ensureConnections(optionsOrCallback, callback) {
-    const {name, callback: actualWithConnectionsCallback} = resolveWithConnectionsArgs(optionsOrCallback, callback, "Configuration.ensureConnections")
+    const {
+      callback: actualWithConnectionsCallback,
+      databaseIdentifiers,
+      name
+    } = resolveWithConnectionsArgs(optionsOrCallback, callback, "Configuration.ensureConnections")
 
     if (!actualWithConnectionsCallback) throw new Error("ensureConnections requires a callback")
 
-    const dbs = this.getCurrentConnections()
-    const missingIdentifiers = this.getDatabaseIdentifiers().filter((identifier) => {
+    const requestedIdentifiers = databaseIdentifiers ?? this.getDatabaseIdentifiers()
+    const dbs = this.getCurrentConnections(requestedIdentifiers)
+    const missingIdentifiers = requestedIdentifiers.filter((identifier) => {
       if (!dbs[identifier]) return true
 
       return !this.getDatabasePool(identifier).hasCurrentConnectionContext()

package/build/database/advisory-lock-runner.js

@@ -148,7 +148,9 @@ export default class AdvisoryLockRunner {
     try {
       return await callback(connection)
     } finally {
-      if (!connection.getArgs().getConnection) {
+      if (connection.getArgs().getConnection) {
+        await connection.releaseHeldAdvisoryLocks()
+      } else {
         await connection.close()
       }
     }

package/build/database/drivers/base.js

@@ -57,6 +57,7 @@
  * @property {string} [logName] - Query log subject.
  * @property {boolean} [logQuery] - Whether to log the query.
  * @property {boolean} [processListComment] - Whether to add process-list comments to the query.
+ * @property {boolean} [retry] - Whether retryable errors may retry the query; defaults to true.
  * @property {boolean} [sessionTimeZone] - Whether to ensure the configured database session time zone before the query.
  * @property {string} [sourceStack] - Stack captured at the caller boundary.
  */
@@ -170,6 +171,8 @@ export default class VelociousDatabaseDriversBase {
    * Active query.
    * @type {ActiveQueryState | null} */
   _activeQuery = null
+  /** @type {Map<string, number>} */
+  _heldAdvisoryLocks = new Map()
 
   /**
    * Runs constructor.
@@ -239,10 +242,40 @@ export default class VelociousDatabaseDriversBase {
   }
 
   /**
-   * Optional close hook for database drivers.
-   * @returns {Promise<void>} - Resolves when complete.
+   * Releases tracked advisory locks and closes the physical database connection.
+   * @returns {Promise<void>} - Resolves when cleanup and close complete.
    */
   async close() {
+    /** @type {Error | undefined} */
+    let advisoryLockError
+
+    try {
+      await this.releaseHeldAdvisoryLocks()
+    } catch (error) {
+      advisoryLockError = error instanceof Error ? error : new Error("Failed to release held advisory locks", {cause: error})
+    }
+
+    try {
+      await this._close()
+      this._heldAdvisoryLocks.clear()
+    } catch (error) {
+      const closeError = error instanceof Error ? error : new Error("Failed to close database connection", {cause: error})
+
+      if (advisoryLockError) {
+        throw new AggregateError([advisoryLockError, closeError], "Failed to release advisory locks and close database connection", {cause: error})
+      }
+
+      throw closeError
+    }
+
+    if (advisoryLockError) throw advisoryLockError
+  }
+
+  /**
+   * Driver-specific physical close hook.
+   * @returns {Promise<void>} - Resolves when the underlying connection closes.
+   */
+  async _close() {
     // No-op by default
   }
 
@@ -1127,7 +1160,7 @@ export default class VelociousDatabaseDriversBase {
 
         const retryInfo = this.retryableDatabaseError(error)
 
-        if (tries < maxTries && retryInfo.retry) {
+        if (options.retry !== false && tries < maxTries && retryInfo.retry) {
           if (retryInfo.reconnect) {
             if (this._transactionsCount > 0) {
               throw new Error(`Cannot reconnect while a transaction is active (${this._transactionsCount}). Original error: ${error.message}`, {cause: error})
@@ -1773,33 +1806,124 @@ export default class VelociousDatabaseDriversBase {
    * table locks; they are purely cooperative between callers that use the
    * same name and let you serialize functionality without blocking readers
    * or writers that do not participate in the same lock.
-   * @abstract
    * @param {string} name - Lock name.
-   * @param {{timeoutMs?: number | null}} [_args] - Optional timeout in milliseconds; `null` or undefined blocks forever.
+   * @param {{timeoutMs?: number | null}} [args] - Optional timeout in milliseconds; `null` or undefined blocks forever.
    * @returns {Promise<boolean>} - Resolves to true when the lock has been acquired, false if the timeout elapsed.
    */
-  acquireAdvisoryLock(name, _args = {}) {
-    throw new Error(`'acquireAdvisoryLock' not implemented for ${this.constructor.name}`)
+  async acquireAdvisoryLock(name, args = {}) {
+    const acquired = await this._acquireAdvisoryLock(name, args)
+
+    if (acquired) this._trackAdvisoryLock(name)
+
+    return acquired
   }
 
   /**
-   * Attempts to acquire a named advisory lock without blocking.
+   * Driver-specific blocking advisory-lock acquisition hook.
    * @abstract
    * @param {string} name - Lock name.
+   * @param {{timeoutMs?: number | null}} [_args] - Lock timeout options.
+   * @returns {Promise<boolean>} - Whether the lock was acquired.
+   */
+  _acquireAdvisoryLock(name, _args = {}) {
+    throw new Error(`'_acquireAdvisoryLock' not implemented for ${this.constructor.name}`)
+  }
+
+  /**
+   * Attempts to acquire a named advisory lock without blocking.
+   * @param {string} name - Lock name.
    * @returns {Promise<boolean>} - Resolves to true if the lock was acquired, false if it was already held.
    */
-  tryAcquireAdvisoryLock(name) { // eslint-disable-line no-unused-vars
-    throw new Error(`'tryAcquireAdvisoryLock' not implemented for ${this.constructor.name}`)
+  async tryAcquireAdvisoryLock(name) {
+    const acquired = await this._tryAcquireAdvisoryLock(name)
+
+    if (acquired) this._trackAdvisoryLock(name)
+
+    return acquired
   }
 
   /**
-   * Releases a named advisory lock previously acquired on this connection.
+   * Driver-specific non-blocking advisory-lock acquisition hook.
    * @abstract
    * @param {string} name - Lock name.
+   * @returns {Promise<boolean>} - Whether the lock was acquired.
+   */
+  _tryAcquireAdvisoryLock(name) { // eslint-disable-line no-unused-vars
+    throw new Error(`'_tryAcquireAdvisoryLock' not implemented for ${this.constructor.name}`)
+  }
+
+  /**
+   * Releases a named advisory lock previously acquired on this connection.
+   * @param {string} name - Lock name.
    * @returns {Promise<boolean>} - Resolves to true if the lock was held by this session and has now been released.
    */
-  releaseAdvisoryLock(name) { // eslint-disable-line no-unused-vars
-    throw new Error(`'releaseAdvisoryLock' not implemented for ${this.constructor.name}`)
+  async releaseAdvisoryLock(name) {
+    const released = await this._releaseAdvisoryLock(name)
+
+    if (released) {
+      this._untrackAdvisoryLock(name)
+    } else {
+      this._heldAdvisoryLocks.delete(name)
+    }
+
+    return released
+  }
+
+  /**
+   * Driver-specific advisory-lock release hook.
+   * @abstract
+   * @param {string} name - Lock name.
+   * @returns {Promise<boolean>} - Whether the lock was released.
+   */
+  _releaseAdvisoryLock(name) { // eslint-disable-line no-unused-vars
+    throw new Error(`'_releaseAdvisoryLock' not implemented for ${this.constructor.name}`)
+  }
+
+  /**
+   * Releases every advisory lock still tracked on this connection.
+   * @returns {Promise<void>} - Resolves when every tracked lock is released.
+   */
+  async releaseHeldAdvisoryLocks() {
+    /** @type {Error[]} */
+    const errors = []
+
+    for (const name of [...this._heldAdvisoryLocks.keys()]) {
+      while (this._heldAdvisoryLocks.has(name)) {
+        try {
+          await this.releaseAdvisoryLock(name)
+        } catch (error) {
+          errors.push(error instanceof Error ? error : new Error(`Failed to release advisory lock ${JSON.stringify(name)}`, {cause: error}))
+          break
+        }
+      }
+    }
+
+    if (errors.length == 1) throw errors[0]
+    if (errors.length > 1) throw new AggregateError(errors, "Failed to release held advisory locks")
+  }
+
+  /**
+   * Records one successful acquisition, including re-entrant acquisitions.
+   * @param {string} name - Lock name.
+   * @returns {void}
+   */
+  _trackAdvisoryLock(name) {
+    this._heldAdvisoryLocks.set(name, (this._heldAdvisoryLocks.get(name) || 0) + 1)
+  }
+
+  /**
+   * Removes one successful acquisition from the connection registry.
+   * @param {string} name - Lock name.
+   * @returns {void}
+   */
+  _untrackAdvisoryLock(name) {
+    const remainingCount = (this._heldAdvisoryLocks.get(name) || 0) - 1
+
+    if (remainingCount > 0) {
+      this._heldAdvisoryLocks.set(name, remainingCount)
+    } else {
+      this._heldAdvisoryLocks.delete(name)
+    }
   }
 
   /**

package/build/database/drivers/mssql/index.js

@@ -47,7 +47,7 @@ export default class VelociousDatabaseDriversMssql extends Base{
     }
   }
 
-  async close() {
+  async _close() {
     if (!this.connection) return
 
     const connection = this.connection
@@ -616,7 +616,7 @@ export default class VelociousDatabaseDriversMssql extends Base{
    * @param {{timeoutMs?: number | null}} [args] - Optional timeout in milliseconds; `null`, `undefined`, or negative blocks forever.
    * @returns {Promise<boolean>} - True if the lock was acquired, false if the timeout elapsed.
    */
-  async acquireAdvisoryLock(name, {timeoutMs} = {}) {
+  async _acquireAdvisoryLock(name, {timeoutMs} = {}) {
     const timeoutValue = typeof timeoutMs === "number" && timeoutMs >= 0 ? Math.ceil(timeoutMs) : -1
     const rows = await this.query(
       `DECLARE @velocious_advisory_lock_result INT; EXEC @velocious_advisory_lock_result = sp_getapplock @Resource = ${this.quote(name)}, @LockMode = 'Exclusive', @LockOwner = 'Session', @LockTimeout = ${timeoutValue}; SELECT @velocious_advisory_lock_result AS velocious_advisory_lock_result`
@@ -634,8 +634,8 @@ export default class VelociousDatabaseDriversMssql extends Base{
    * @param {string} name - Lock name.
    * @returns {Promise<boolean>} - True if the lock was acquired, false if it was already held.
    */
-  async tryAcquireAdvisoryLock(name) {
-    return await this.acquireAdvisoryLock(name, {timeoutMs: 0})
+  async _tryAcquireAdvisoryLock(name) {
+    return await this._acquireAdvisoryLock(name, {timeoutMs: 0})
   }
 
   /**
@@ -643,7 +643,7 @@ export default class VelociousDatabaseDriversMssql extends Base{
    * @param {string} name - Lock name.
    * @returns {Promise<boolean>} - True if the lock was held by this session and has now been released.
    */
-  async releaseAdvisoryLock(name) {
+  async _releaseAdvisoryLock(name) {
     const rows = await this.query(
       `DECLARE @velocious_advisory_lock_result INT; EXEC @velocious_advisory_lock_result = sp_releaseapplock @Resource = ${this.quote(name)}, @LockOwner = 'Session'; SELECT @velocious_advisory_lock_result AS velocious_advisory_lock_result`
     )

package/build/database/drivers/mysql/index.js

@@ -63,7 +63,7 @@ export default class VelociousDatabaseDriversMysql extends Base{
    * Runs close.
    * @returns {Promise<void>} - Resolves when complete.
    */
-  async close() {
+  async _close() {
     await this.pool?.end()
     this.pool = undefined
     this.resetCurrentSessionTimeZone()
@@ -574,7 +574,7 @@ export default class VelociousDatabaseDriversMysql extends Base{
    * @param {{timeoutMs?: number | null}} [args] - Optional timeout in milliseconds; `null`, `undefined`, or negative blocks for `MYSQL_INDEFINITE_LOCK_TIMEOUT_SECONDS`.
    * @returns {Promise<boolean>} - True if acquired, false if the timeout elapsed.
    */
-  async acquireAdvisoryLock(name, {timeoutMs} = {}) {
+  async _acquireAdvisoryLock(name, {timeoutMs} = {}) {
     const timeoutSeconds = typeof timeoutMs === "number" && timeoutMs >= 0
       ? Math.ceil(timeoutMs / 1000)
       : MYSQL_INDEFINITE_LOCK_TIMEOUT_SECONDS
@@ -593,7 +593,7 @@ export default class VelociousDatabaseDriversMysql extends Base{
    * @param {string} name - Lock name.
    * @returns {Promise<boolean>} - True if the lock was acquired, false if it was already held.
    */
-  async tryAcquireAdvisoryLock(name) {
+  async _tryAcquireAdvisoryLock(name) {
     const rows = await this.query(`SELECT GET_LOCK(${this.quote(name)}, 0) AS velocious_advisory_lock_result`)
     const result = rows?.[0]?.velocious_advisory_lock_result
 
@@ -609,8 +609,8 @@ export default class VelociousDatabaseDriversMysql extends Base{
    * @param {string} name - Lock name.
    * @returns {Promise<boolean>} - True if the lock was held by this session and has now been released.
    */
-  async releaseAdvisoryLock(name) {
-    const rows = await this.query(`SELECT RELEASE_LOCK(${this.quote(name)}) AS velocious_advisory_lock_result`)
+  async _releaseAdvisoryLock(name) {
+    const rows = await this.query(`SELECT RELEASE_LOCK(${this.quote(name)}) AS velocious_advisory_lock_result`, {retry: false})
     const result = rows?.[0]?.velocious_advisory_lock_result
 
     return Number(result) === 1

package/build/database/drivers/pgsql/index.js

@@ -60,7 +60,7 @@ export default class VelociousDatabaseDriversPgsql extends Base{
     return connectArgs
   }
 
-  async close() {
+  async _close() {
     await this.connection?.end()
     this.connection = undefined
     this._transactionsCount = 0
@@ -411,7 +411,7 @@ export default class VelociousDatabaseDriversPgsql extends Base{
    * @param {{timeoutMs?: number | null}} [args] - Optional timeout in milliseconds; `null`, `undefined`, or negative blocks forever.
    * @returns {Promise<boolean>} - True if the lock was acquired, false if the timeout elapsed.
    */
-  async acquireAdvisoryLock(name, {timeoutMs} = {}) {
+  async _acquireAdvisoryLock(name, {timeoutMs} = {}) {
     const key = this.advisoryLockKey(name)
 
     if (typeof timeoutMs !== "number" || timeoutMs < 0) {
@@ -423,7 +423,7 @@ export default class VelociousDatabaseDriversPgsql extends Base{
     const pollIntervalMs = 50
 
     while (true) {
-      if (await this.tryAcquireAdvisoryLock(name)) return true
+      if (await this._tryAcquireAdvisoryLock(name)) return true
       if (Date.now() >= deadline) return false
 
       const remaining = deadline - Date.now()
@@ -437,7 +437,7 @@ export default class VelociousDatabaseDriversPgsql extends Base{
    * @param {string} name - Lock name.
    * @returns {Promise<boolean>} - True if the lock was acquired, false if it was already held.
    */
-  async tryAcquireAdvisoryLock(name) {
+  async _tryAcquireAdvisoryLock(name) {
     const key = this.advisoryLockKey(name)
     const rows = await this.query(`SELECT pg_try_advisory_lock(${key}) AS velocious_advisory_lock_result`)
     const result = rows?.[0]?.velocious_advisory_lock_result
@@ -450,7 +450,7 @@ export default class VelociousDatabaseDriversPgsql extends Base{
    * @param {string} name - Lock name.
    * @returns {Promise<boolean>} - True if the lock was held by this session and has now been released.
    */
-  async releaseAdvisoryLock(name) {
+  async _releaseAdvisoryLock(name) {
     const key = this.advisoryLockKey(name)
     const rows = await this.query(`SELECT pg_advisory_unlock(${key}) AS velocious_advisory_lock_result`)
     const result = rows?.[0]?.velocious_advisory_lock_result

package/build/database/drivers/sqlite/base.js

@@ -385,7 +385,7 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
    * @param {{timeoutMs?: number | null}} [args] - Optional timeout in milliseconds; `null`, `undefined`, or negative blocks forever.
    * @returns {Promise<boolean>} - True if the lock was acquired, false if the timeout elapsed.
    */
-  async acquireAdvisoryLock(name, {timeoutMs} = {}) {
+  async _acquireAdvisoryLock(name, {timeoutMs} = {}) {
     const state = VelociousDatabaseDriversSqliteBase._advisoryLockState
 
     while (state.ownersByName.has(name)) {
@@ -445,7 +445,7 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
    * @param {string} name - Lock name.
    * @returns {Promise<boolean>} - True if the lock was acquired, false if it was already held.
    */
-  async tryAcquireAdvisoryLock(name) {
+  async _tryAcquireAdvisoryLock(name) {
     const state = VelociousDatabaseDriversSqliteBase._advisoryLockState
 
     if (state.ownersByName.has(name)) return false
@@ -464,7 +464,7 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
    * @param {string} name - Lock name.
    * @returns {Promise<boolean>} - True if the lock was held by this driver and has now been released.
    */
-  async releaseAdvisoryLock(name) {
+  async _releaseAdvisoryLock(name) {
     const state = VelociousDatabaseDriversSqliteBase._advisoryLockState
     const owner = state.ownersByName.get(name)
 

package/build/database/drivers/sqlite/index.js

@@ -62,7 +62,7 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
     return `VelociousDatabaseDriversSqlite---${args.name}`
   }
 
-  async close() {
+  async _close() {
     await this.connection?.close()
     this.connection = undefined
   }
@@ -105,10 +105,10 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
    * @param {{timeoutMs?: number | null}} [args] - Optional timeout in milliseconds; `null`, `undefined`, or negative blocks forever.
    * @returns {Promise<boolean>} - Whether the advisory lock was acquired.
    */
-  async acquireAdvisoryLock(name, {timeoutMs} = {}) {
+  async _acquireAdvisoryLock(name, {timeoutMs} = {}) {
     const deadline = typeof timeoutMs === "number" && timeoutMs >= 0 ? Date.now() + timeoutMs : null
     const remainingForInProcess = deadline !== null ? Math.max(0, deadline - Date.now()) : null
-    const inProcessAcquired = await super.acquireAdvisoryLock(name, {timeoutMs: remainingForInProcess})
+    const inProcessAcquired = await super._acquireAdvisoryLock(name, {timeoutMs: remainingForInProcess})
 
     if (!inProcessAcquired) return false
 
@@ -117,11 +117,11 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
       const fileAcquired = await this._acquireAdvisoryLockFile(name, {timeoutMs: remainingForFile})
 
       if (!fileAcquired) {
-        await super.releaseAdvisoryLock(name)
+        await super._releaseAdvisoryLock(name)
         return false
       }
     } catch (error) {
-      await super.releaseAdvisoryLock(name)
+      await super._releaseAdvisoryLock(name)
       throw error
     }
 
@@ -133,8 +133,8 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
    * @param {string} name - Lock name.
    * @returns {Promise<boolean>} - Whether the advisory lock was acquired immediately.
    */
-  async tryAcquireAdvisoryLock(name) {
-    const inProcessAcquired = await super.tryAcquireAdvisoryLock(name)
+  async _tryAcquireAdvisoryLock(name) {
+    const inProcessAcquired = await super._tryAcquireAdvisoryLock(name)
 
     if (!inProcessAcquired) return false
 
@@ -142,11 +142,11 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
       const fileAcquired = await this._tryAcquireAdvisoryLockFile(name)
 
       if (!fileAcquired) {
-        await super.releaseAdvisoryLock(name)
+        await super._releaseAdvisoryLock(name)
         return false
       }
     } catch (error) {
-      await super.releaseAdvisoryLock(name)
+      await super._releaseAdvisoryLock(name)
       throw error
     }
 
@@ -163,8 +163,8 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
    * @param {string} name - Lock name.
    * @returns {Promise<boolean>} - Whether the advisory lock was released.
    */
-  async releaseAdvisoryLock(name) {
-    const inProcessReleased = await super.releaseAdvisoryLock(name)
+  async _releaseAdvisoryLock(name) {
+    const inProcessReleased = await super._releaseAdvisoryLock(name)
 
     if (inProcessReleased) {
       await this._releaseAdvisoryLockFile(name)

package/build/database/drivers/sqlite/index.native.js

@@ -64,7 +64,7 @@ export default class VelociousDatabaseDriversSqliteNative extends Base {
     return connectArgs
   }
 
-  async close() {
+  async _close() {
     await this.connection.closeAsync()
     this.connection = undefined
   }

package/build/database/drivers/sqlite/index.web.js

@@ -48,7 +48,7 @@ export default class VelociousDatabaseDriversSqliteWeb extends Base {
     }
   }
 
-  async close() {
+  async _close() {
     await this.getConnection().close()
   }