velocious 1.0.474 → 1.0.475

package/src/database/drivers/base.js

@@ -50,6 +50,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} [sessionTimeZone] - Whether to ensure the configured database session time zone before the query.
  * @property {string} [sourceStack] - Stack captured at the caller boundary.
  */
 
@@ -237,6 +238,14 @@ export default class VelociousDatabaseDriversBase {
     // No-op by default
   }
 
+  /**
+   * Flushes pending writes that the driver delayed for persistence.
+   * @returns {Promise<void>} - Resolves when pending writes are durable.
+   */
+  async flushPendingWrites() {
+    // No-op by default
+  }
+
   /**
    * Runs set connection checkout name.
    * @param {string | undefined} name - Human-readable name for this active checkout.
@@ -1041,12 +1050,14 @@ export default class VelociousDatabaseDriversBase {
     let result
 
     try {
+      const runQueryActualWithHooks = async () => await this._queryActualWithHooks(querySql, options)
+
       if (requestTiming && tries === 1) {
-        result = await requestTiming.measureDbQuery(async () => await this._queryActual(querySql))
+        result = await requestTiming.measureDbQuery(runQueryActualWithHooks)
       } else if (requestTiming) {
-        result = await requestTiming.measure("db", async () => await this._queryActual(querySql))
+        result = await requestTiming.measure("db", runQueryActualWithHooks)
       } else {
-        result = await this._queryActual(querySql)
+        result = await runQueryActualWithHooks()
       }
     } finally {
       this._activeQuery = previousActiveQuery
@@ -1070,6 +1081,42 @@ export default class VelociousDatabaseDriversBase {
     return result
   }
 
+  /**
+   * Runs query actual with before/after hooks.
+   * @param {string} sql - SQL string.
+   * @param {QueryOptions} options - Query options.
+   * @returns {Promise<QueryResultType>} - Resolves with the query.
+   */
+  async _queryActualWithHooks(sql, options) {
+    await this.beforeQuery(sql, options)
+
+    try {
+      return await this._queryActual(sql)
+    } finally {
+      await this.afterQuery(sql, options)
+    }
+  }
+
+  /**
+   * Hook that runs immediately before a SQL query is sent to the driver.
+   * @param {string} _sql - SQL string.
+   * @param {QueryOptions} _options - Query options.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async beforeQuery(_sql, _options) {
+    // No-op by default
+  }
+
+  /**
+   * Hook that runs immediately after a SQL query has completed or failed.
+   * @param {string} _sql - SQL string.
+   * @param {QueryOptions} _options - Query options.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async afterQuery(_sql, _options) {
+    // No-op by default
+  }
+
   /**
    * Runs get debug snapshot.
    * @returns {DatabaseConnectionDebugSnapshot} - Diagnostic snapshot for this connection.
@@ -1504,6 +1551,7 @@ export default class VelociousDatabaseDriversBase {
         }
       }
     })
+    await this.flushPendingWrites()
   }
 
   /**

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

@@ -30,15 +30,20 @@ import Update from "./sql/update.js"
 const MYSQL_INDEFINITE_LOCK_TIMEOUT_SECONDS = 60 * 60 * 24 * 365
 
 export default class VelociousDatabaseDriversMysql extends Base{
+  /** @type {string | null} */
+  _desiredSessionTimeZone = "+00:00"
+
+  /** @type {string | null} */
+  _currentSessionTimeZone = null
+
   /**
    * Runs connect.
    * @returns {Promise<void>} - Resolves when complete.
    */
   async connect() {
+    this.resetCurrentSessionTimeZone()
     this.pool = mysql.createPool(Object.assign({connectionLimit: 1}, this.connectArgs()))
     this.pool.on("error", this.onPoolError)
-
-    await this.setSessionTimezoneToUtc()
   }
 
   /**
@@ -56,6 +61,7 @@ export default class VelociousDatabaseDriversMysql extends Base{
   async close() {
     await this.pool?.end()
     this.pool = undefined
+    this.resetCurrentSessionTimeZone()
   }
 
   /**
@@ -64,7 +70,7 @@ export default class VelociousDatabaseDriversMysql extends Base{
    * @returns {Promise<void>} - Resolves when complete.
    */
   async setConnectionCheckoutName(name) {
-    await this.query(`SET @velocious_connection_checkout_name = ${name === undefined ? "NULL" : this.quote(name)}`, {logName: "Set Connection Checkout Name", processListComment: false})
+    await this.query(`SET @velocious_connection_checkout_name = ${name === undefined ? "NULL" : this.quote(name)}`, {logName: "Set Connection Checkout Name", processListComment: false, sessionTimeZone: false})
     await super.setConnectionCheckoutName(name)
   }
 
@@ -73,16 +79,77 @@ export default class VelociousDatabaseDriversMysql extends Base{
    * @returns {Promise<void>} - Resolves when complete.
    */
   async clearConnectionCheckoutName() {
-    await this.query("SET @velocious_connection_checkout_name = NULL", {logName: "Clear Connection Checkout Name", processListComment: false})
+    await this.query("SET @velocious_connection_checkout_name = NULL", {logName: "Clear Connection Checkout Name", processListComment: false, sessionTimeZone: false})
     await super.clearConnectionCheckoutName()
   }
 
   /**
-   * Sets the database session timezone to UTC so bare timestamp literals store UTC instants.
+   * Hook before every query.
+   * @param {string} _sql - SQL string.
+   * @param {import("../base.js").QueryOptions} options - Query options.
    * @returns {Promise<void>} - Resolves when complete.
    */
-  async setSessionTimezoneToUtc() {
-    await this.query("SET time_zone = '+00:00'", {logName: "Set Session Time Zone", processListComment: false})
+  async beforeQuery(_sql, options) {
+    if (options.sessionTimeZone !== false) await this.ensureSessionTimeZone()
+  }
+
+  /**
+   * Gets the desired database session time zone for this connection context.
+   * @returns {string | null} - Desired session time zone.
+   */
+  getDesiredSessionTimeZone() {
+    return this._desiredSessionTimeZone
+  }
+
+  /**
+   * Sets the desired database session time zone without querying MySQL immediately.
+   * @param {string | null} timeZone - Desired session time zone.
+   */
+  setDesiredSessionTimeZone(timeZone) {
+    this._desiredSessionTimeZone = timeZone
+  }
+
+  /**
+   * Gets the database session time zone last confirmed through SET time_zone.
+   * @returns {string | null} - Current known session time zone.
+   */
+  getCurrentSessionTimeZone() {
+    return this._currentSessionTimeZone
+  }
+
+  /**
+   * Clears the current known database session time zone when the physical connection changes.
+   */
+  resetCurrentSessionTimeZone() {
+    this._currentSessionTimeZone = null
+  }
+
+  /**
+   * Ensures MySQL has the desired session time zone before user SQL runs.
+   * @returns {Promise<boolean>} - True when SET time_zone was executed.
+   */
+  async ensureSessionTimeZone() {
+    const desiredSessionTimeZone = this.getDesiredSessionTimeZone()
+
+    if (desiredSessionTimeZone === null || this.getCurrentSessionTimeZone() === desiredSessionTimeZone) return false
+
+    await this.setSessionTimeZone(desiredSessionTimeZone)
+
+    return true
+  }
+
+  /**
+   * Sets the database session time zone if it changed from the last confirmed value.
+   * @param {string} timeZone - Session time zone value accepted by MySQL.
+   * @returns {Promise<boolean>} - True when SET time_zone was executed.
+   */
+  async setSessionTimeZone(timeZone) {
+    if (this.getCurrentSessionTimeZone() === timeZone) return false
+
+    await this._queryActual(`SET time_zone = ${this.quote(timeZone)}`)
+    this._currentSessionTimeZone = timeZone
+
+    return true
   }
 
   /**

package/src/database/drivers/sqlite/connection-sql-js.js

@@ -8,16 +8,28 @@ export default class VelociousDatabaseDriversSqliteConnectionSqlJs {
    * Runs constructor.
    * @param {import("../base.js").default} driver - Database driver instance.
    * @param {import("sql.js").Database} connection - Connection.
+   * @param {import("./web-persistence.js").SqliteWebPersistence} persistence - Database persistence adapter.
    */
-  constructor(driver, connection) {
+  constructor(driver, connection, persistence) {
     this.connection = connection
     this.driver = driver
+    this.persistence = persistence
   }
 
   async close() {
-    await this.saveDatabase()
+    await this.flushDatabaseSave()
     await this.connection.close()
   }
+
+  /**
+   * Flushes any debounced database save and waits until persistence is complete.
+   * @returns {Promise<void>} - Resolves when the current database bytes are stored.
+   */
+  async flushDatabaseSave() {
+    this.saveDatabaseDebounce.clear()
+    await this.saveDatabase()
+  }
+
   /**
    * Runs query.
    * @param {string} sql - SQL string.
@@ -36,10 +48,9 @@ export default class VelociousDatabaseDriversSqliteConnectionSqlJs {
   }
 
   saveDatabase = async () => {
-    const localStorageContent = this.connection.export()
+    const databaseContent = this.connection.export()
 
-    // @ts-expect-error
-    await this.driver.betterLocalStorage.set(this.driver.localStorageName(), localStorageContent)
+    await this.persistence.save(databaseContent)
   }
 
   saveDatabaseDebounce = debounce(this.saveDatabase, 500)

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

@@ -1,8 +1,8 @@
 // @ts-check
 
-import BetterLocalStorage from "better-localstorage"
 import ConnectionSqlJs from "./connection-sql-js.js"
 import initSqlJs from "sql.js"
+import {createSqliteWebPersistence, deleteSqliteWebPersistences, sqliteWebPersistenceKey} from "./web-persistence.js"
 
 import Base from "./base.js"
 
@@ -12,10 +12,6 @@ import Base from "./base.js"
  */
 
 export default class VelociousDatabaseDriversSqliteWeb extends Base {
-  /**
-   * Better local storage.
-   * @type {BetterLocalStorage | undefined} */
-  betterLocalStorage = undefined
   /**
    * Connection.
    * @type {ConnectionSqlJs | undefined} */
@@ -39,16 +35,14 @@ export default class VelociousDatabaseDriversSqliteWeb extends Base {
     this.args = this.getArgs()
 
     if (!this.args.getConnection) {
-      this.betterLocalStorage ||= new BetterLocalStorage()
-
       if (this.args.reset) {
-        await this.betterLocalStorage.delete(this.localStorageName())
+        await deleteSqliteWebPersistences({databaseName: this.databaseName()})
       }
 
+      const persistence = await createSqliteWebPersistence({databaseName: this.databaseName()})
       const SQL = await initSqlJs({locateFile: this.sqlJsLocateFile()})
-
-      const databaseContent = await this.betterLocalStorage.get(this.localStorageName())
-      const connectionSqlJs = new ConnectionSqlJs(this, new SQL.Database(databaseContent))
+      const databaseContent = await persistence.load()
+      const connectionSqlJs = new ConnectionSqlJs(this, new SQL.Database(databaseContent), persistence)
 
       this._connection = connectionSqlJs
     }
@@ -58,6 +52,18 @@ export default class VelociousDatabaseDriversSqliteWeb extends Base {
     await this.getConnection().close()
   }
 
+  /**
+   * Flushes pending SQL.js local persistence writes.
+   * @returns {Promise<void>} - Resolves when pending writes are durable.
+   */
+  async flushPendingWrites() {
+    if (!this.args?.getConnection) {
+      if (!this._connection) throw new Error("SQLite web connection has not been initialized")
+
+      await this._connection.flushDatabaseSave()
+    }
+  }
+
   /**
    * Runs get connection.
    * @returns {ConnectionSqlJs | SqliteWebConnection} - The connection.
@@ -72,11 +78,19 @@ export default class VelociousDatabaseDriversSqliteWeb extends Base {
   }
 
   localStorageName() {
-    if (!this.args?.name) {
-      throw new Error("No name given in arguments for SQLite Web database")
-    }
+    return sqliteWebPersistenceKey(this.databaseName())
+  }
+
+  /**
+   * Returns the configured database name.
+   * @returns {string} - Database name.
+   */
+  databaseName() {
+    const name = this.args?.name
+
+    if (typeof name !== "string" || name.length < 1) throw new Error("No name given in arguments for SQLite Web database")
 
-    return `VelociousDatabaseDriversSqliteWeb---${this.args?.name}`
+    return name
   }
 
   /**