velocious 1.0.474 → 1.0.476

package/README.md

@@ -8,6 +8,8 @@
 * Migrations for schema changes and UTC datetime storage (see [docs/database-migrations.md](docs/database-migrations.md))
 * Controllers and views for HTTP endpoints
 * Frontend-model transport for creating, updating, querying, and subscribing to query-filtered lifecycle events over HTTP/WebSocket, with structured per-attribute validation error responses (see [docs/frontend-models.md](docs/frontend-models.md))
+* Client-side offline sync mutation logs and frontend-model optimistic queueing primitives (see [docs/offline-sync.md](docs/offline-sync.md))
+* SQLite web persistence that automatically prefers OPFS, then IndexedDB, and migrates legacy persisted bytes when possible (see [docs/sqlite-web-persistence.md](docs/sqlite-web-persistence.md))
 * Expo / Metro compatibility guidance and a real Expo export check (see [docs/expo-metro-compatibility.md](docs/expo-metro-compatibility.md))
 * Gap-less positional lists with automatic reordering via `actsAsList` (see [docs/acts-as-list.md](docs/acts-as-list.md))
 * Rails-style nested-attribute writes on frontend-model `save()` (see [docs/nested-attributes.md](docs/nested-attributes.md))
@@ -22,6 +24,7 @@
 * EJS-backed mailers with delivery, queueing, and payload rendering support (see [docs/mailers.md](docs/mailers.md))
 * 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))
 * Optional built-in debug endpoint for inspecting server and database connection state (see [docs/debug-endpoint.md](docs/debug-endpoint.md))
 
@@ -580,7 +583,7 @@ Use `await FrontendModelBase.waitForIdle()` when a test harness or app lifecycle
 Frontend-model HTTP requests always use `credentials: "include"` so shared custom commands can set session cookies without app-level transport overrides.
 
 Unexpected frontend-model endpoint failures stay client-safe in production with `errorMessage: "Request failed."`.
-Invalid client query descriptors, such as unknown `select`, `where`, `search`, `joins`, `group`, `sort`, `pluck`, or Ransack attributes, return the specific frontend-model query error message with `velocious.code: "frontend-model-query-error"` and are not emitted as framework errors.
+Invalid client query descriptors, such as unknown `select`, `where`, `search`, `joins`, `preload`, `group`, `sort`, `pluck`, or Ransack attributes, return the specific frontend-model query error message with `velocious.code: "frontend-model-query-error"` and are not emitted as framework errors.
 In `development` and `test`, Velocious also includes `debugErrorClass`, `debugErrorMessage`, and `debugBacktrace` fields so browser/system-test failures are easier to diagnose without exposing those details in production.
 Other non-production environments, such as `staging`, keep the same client-safe default unless you explicitly opt in with `exposeInternalErrorsToClients: true`:
 
@@ -605,7 +608,9 @@ configuration.addClientErrorPayloadReporter(async ({error, requestDetails, conte
 
 `requestDetails` includes `httpMethod`, `path`, and a parsed `body` snapshot when available. The body snapshot redacts common secret keys, truncates large strings and arrays, summarizes uploaded files and buffers without bytes, and compacts oversized frontend-model batches while preserving `requestId`, `model`, `commandType` / `customPath`, and payload shape.
 
-For sqlite web databases, Velocious defaults to `https://sql.js.org/dist/<file>` for `sql.js` wasm loading. You can override wasm resolution per database config with `locateFile`:
+For sqlite web databases, Velocious automatically picks the best browser persistence backend it can use: OPFS when a smoke test succeeds, then IndexedDB. Existing persisted bytes in a worse backend are migrated into the selected backend when possible. If neither OPFS nor IndexedDB is usable, Velocious keeps the legacy localStorage-style backend as a compatibility fallback. See [docs/sqlite-web-persistence.md](docs/sqlite-web-persistence.md) for the backend selection details.
+
+Velocious defaults to `https://sql.js.org/dist/<file>` for `sql.js` wasm loading. You can override wasm resolution per database config with `locateFile`:
 
 ```js
 import SqliteDriver from "velocious/build/src/database/drivers/sqlite/index.web.js"
@@ -718,6 +723,8 @@ Task.validates("name", {presence: true, uniqueness: true})
 export default Task
 ```
 
+Generated belongs-to setters synchronize the loaded relationship and foreign key before save, so `task.setProject(project)` updates `task.projectId()`, `task.changes()`, callbacks, and scoped features such as `actsAsList`. Custom relationship primary keys are also used after autosaving an assigned new or dirty related record. Generated backend write attributes accept belongs-to relationship names for `create` and `update` payloads. See [docs/relationships.md](docs/relationships.md#assigning-belongs-to-relationships).
+
 Translated models also get a `currentTranslation` `hasOne` relationship scoped to the first available row in the current locale fallback order. See [docs/translations.md](docs/translations.md) for preloading and frontend-model sorting behavior.
 
 Async class APIs initialize record metadata on first use when a model has not
@@ -1071,6 +1078,7 @@ export default class CreateEvents extends Migration {
   }
 
   async down() {
+    await this.removeIndex("task_translations", ["task_id", "locale"])
     await this.dropTable("task_translations")
     await this.dropTable("examples")
     await this.dropTable("tasks")

package/build/configuration-types.js

@@ -320,6 +320,7 @@
  * @property {string[]} [relationships] - Relationship names to expose in frontend models. Type and target model are inferred from the backend model's registered relationships.
  * @property {string} [primaryKey] - Primary key attribute name.
  * @property {FrontendModelResourceServerConfiguration} [server] - Optional legacy backend behavior overrides for built-in frontend actions.
+ * @property {FrontendModelResourceSyncConfiguration | boolean} [sync] - Optional safe local/offline sync policy metadata. `policy` participates in the hash but is not exposed to generated frontend config/manifest.
  */
 
 /**
@@ -338,13 +339,49 @@
  */
 
 /**
- * @typedef {Omit<FrontendModelResourceConfiguration, "abilities" | "builtInCollectionCommands" | "builtInMemberCommands" | "collectionCommands" | "commands" | "memberCommands"> & {
+ * JSON value accepted by sync policy metadata/hash inputs.
+ * @typedef {null | string | number | boolean | unknown[] | Record<string, unknown>} FrontendModelSyncJsonValue
+ */
+
+/**
+ * Frontend-model local/offline sync policy config. `metadata` is exposed to
+ * frontends and peers; `policy` is hashed but intentionally omitted from
+ * frontend-safe manifests.
+ * @typedef {object} FrontendModelResourceSyncConfiguration
+ * @property {boolean} [enabled] - Whether the resource is sync-enabled. Defaults to true when `sync` is configured.
+ * @property {string[]} [operations] - Sync operation names such as `index`, `find`, `create`, `update`, custom domain commands, etc.
+ * @property {string | number} [policyVersion] - App-controlled policy version used as a stable change signal.
+ * @property {Record<string, FrontendModelSyncJsonValue>} [metadata] - Safe frontend-visible metadata.
+ * @property {Record<string, FrontendModelSyncJsonValue>} [policy] - Deterministic non-secret policy inputs included in the policy hash only.
+ */
+
+/**
+ * Velocious sync configuration.
+ * @typedef {object} VelociousSyncConfiguration
+ * @property {import("./sync/device-identity.js").SyncJsonWebKey | null} [deviceCertificateBackendPublicKey] - Public backend key used to verify offline device certificates for sync replay.
+ * @property {Array<import("./sync/offline-grant.js").OfflineGrantSigningKey>} offlineGrantSigningKeys - Signing keys used to issue and verify offline grants. Secrets must never be exposed to clients.
+ * @property {number} [offlineGrantTtlMs] - Default offline grant TTL in milliseconds. Defaults to 24 hours.
+ */
+
+/**
+ * Frontend-safe normalized sync metadata.
+ * @typedef {object} NormalizedFrontendModelResourceSyncConfiguration
+ * @property {boolean} enabled - Whether the resource is sync-enabled.
+ * @property {string[]} operations - Sorted, duplicate-free sync operation names.
+ * @property {string | null} policyVersion - App-controlled policy version, or null.
+ * @property {string} policyHash - Deterministic sha256 hash of safe policy inputs.
+ * @property {Record<string, FrontendModelSyncJsonValue>} [metadata] - Safe frontend-visible metadata.
+ */
+
+/**
+ * @typedef {Omit<FrontendModelResourceConfiguration, "abilities" | "builtInCollectionCommands" | "builtInMemberCommands" | "collectionCommands" | "commands" | "memberCommands" | "sync"> & {
  *   abilities: FrontendModelResourceAbilitiesConfiguration
  *   builtInCollectionCommands: Record<string, string>
  *   builtInMemberCommands: Record<string, string>
  *   collectionCommands: Record<string, string>
  *   commandMetadata: Record<string, {args: Array<{name: string, type: string}>, returnType: string | null}>
  *   memberCommands: Record<string, string>
+ *   sync?: NormalizedFrontendModelResourceSyncConfiguration
  * }} NormalizedFrontendModelResourceConfiguration
  */
 
@@ -471,6 +508,7 @@
  * @property {string[]} locales - Supported locales.
  * @property {LocaleFallbacksType} localeFallbacks - Locale fallback map.
  * @property {StructureSqlConfiguration} [structureSql] - Structure SQL generation configuration.
+ * @property {VelociousSyncConfiguration} [sync] - Local/offline sync framework configuration.
  * @property {TenantResolverType} [tenantResolver] - Resolver for creating request-scoped tenant context objects.
  * @property {TenantDatabaseResolverType} [tenantDatabaseResolver] - Resolver for deriving tenant-specific database config overrides.
  * @property {Record<string, TenantDatabaseProviderType>} [tenantDatabaseProviders] - Tenant database lifecycle providers keyed by database identifier.

package/build/configuration.js

@@ -20,6 +20,7 @@ import VelociousWebsocketChannelSubscribers from "./http-server/websocket-channe
 import {CurrentConfigurationNotSetError, currentConfiguration, setCurrentConfiguration} from "./current-configuration.js"
 import {requestDetails} from "./error-reporting/request-details.js"
 import {frontendModelResourceClassFromDefinition, frontendModelResourceConfigurationFromDefinition, frontendModelResourcesForBackendProject} from "./frontend-models/resource-definition.js"
+import {currentOfflineGrantSigningKey, normalizeOfflineGrantSigningKey} from "./sync/offline-grant.js"
 import PluginRoutes from "./routes/plugin-routes.js"
 import restArgsError from "./utils/rest-args-error.js"
 import {validateTimeZone} from "./time-zone.js"
@@ -126,7 +127,7 @@ export default class VelociousConfiguration {
    * Runs constructor.
    * @param {import("./configuration-types.js").ConfigurationArgsType} args - Configuration arguments.
    */
-  constructor({abilityResolver, abilityResources, attachments, autoload = true, backgroundJobs, backendProjects, beacon, cookieSecret, cors, database, debug = false, debugEndpoint = false, directory, enforceTenantDatabaseScopes = true, environment, environmentHandler, exposeInternalErrorsToClients = false, httpServer, initializeModels, initializers, locale, localeFallbacks, locales, logging, mailerBackend, requestTimeoutMs, routeResolverHooks, scheduledBackgroundJobs, structureSql, tenantDatabaseProviders, tenantDatabaseResolver, tenantResolver, testing, timeZone, timezoneOffsetMinutes, trustedProxies, websocketChannelResolver, websocketMessageHandlerResolver, ...restArgs}) {
+  constructor({abilityResolver, abilityResources, attachments, autoload = true, backgroundJobs, backendProjects, beacon, cookieSecret, cors, database, debug = false, debugEndpoint = false, directory, enforceTenantDatabaseScopes = true, environment, environmentHandler, exposeInternalErrorsToClients = false, httpServer, initializeModels, initializers, locale, localeFallbacks, locales, logging, mailerBackend, requestTimeoutMs, routeResolverHooks, scheduledBackgroundJobs, structureSql, sync, tenantDatabaseProviders, tenantDatabaseResolver, tenantResolver, testing, timeZone, timezoneOffsetMinutes, trustedProxies, websocketChannelResolver, websocketMessageHandlerResolver, ...restArgs}) {
     restArgsError(restArgs)
 
     this._abilityResolver = abilityResolver
@@ -189,6 +190,7 @@ export default class VelociousConfiguration {
     this._trustedProxies = trustedProxies
     this._requestTimeoutMs = requestTimeoutMs
     this._structureSql = structureSql
+    this._sync = this._normalizeSyncConfiguration(sync)
     this._tenantDatabaseProviders = tenantDatabaseProviders || {}
     this._tenantDatabaseResolver = tenantDatabaseResolver
     this._tenantResolver = tenantResolver
@@ -380,6 +382,49 @@ export default class VelociousConfiguration {
     return this._cookieSecret
   }
 
+  /**
+   * Runs get sync configuration.
+   * @returns {import("./configuration-types.js").VelociousSyncConfiguration} - Sync configuration.
+   */
+  getSyncConfiguration() {
+    return this._sync
+  }
+
+  /**
+   * Runs current offline grant signing key.
+   * @returns {import("./sync/offline-grant.js").OfflineGrantSigningKey} - Current signing key.
+   */
+  currentOfflineGrantSigningKey() {
+    const signingKeys = this.getSyncConfiguration().offlineGrantSigningKeys
+
+    return currentOfflineGrantSigningKey(signingKeys)
+  }
+
+  /**
+   * Normalizes sync configuration.
+   * @param {import("./configuration-types.js").VelociousSyncConfiguration | undefined} sync - Sync configuration.
+   * @returns {import("./configuration-types.js").VelociousSyncConfiguration} - Normalized sync configuration.
+   */
+  _normalizeSyncConfiguration(sync) {
+    const deviceCertificateBackendPublicKey = sync?.deviceCertificateBackendPublicKey || null
+    const offlineGrantSigningKeys = sync?.offlineGrantSigningKeys || []
+    const offlineGrantTtlMs = sync?.offlineGrantTtlMs
+
+    if (deviceCertificateBackendPublicKey !== null && (typeof deviceCertificateBackendPublicKey !== "object" || Array.isArray(deviceCertificateBackendPublicKey))) {
+      throw new Error("sync.deviceCertificateBackendPublicKey must be a public JSON Web Key object")
+    }
+    if (!Array.isArray(offlineGrantSigningKeys)) throw new Error("sync.offlineGrantSigningKeys must be an array")
+    if (offlineGrantTtlMs !== undefined && (!Number.isInteger(offlineGrantTtlMs) || offlineGrantTtlMs <= 0)) {
+      throw new Error("sync.offlineGrantTtlMs must be a positive integer number of milliseconds")
+    }
+
+    return {
+      deviceCertificateBackendPublicKey,
+      offlineGrantSigningKeys: offlineGrantSigningKeys.map((key) => normalizeOfflineGrantSigningKey(key)),
+      offlineGrantTtlMs: offlineGrantTtlMs || 24 * 60 * 60 * 1000
+    }
+  }
+
   /**
    * Runs get database configuration.
    * @returns {Record<string, import("./configuration-types.js").DatabaseConfigurationType>} - The database configuration.

package/build/database/drivers/base.js

@@ -9,6 +9,12 @@
  * @property {boolean} [unique] - Whether the index should enforce uniqueness.
  * @property {string} tableName - Name of the table to add the index to.
  */
+/**
+ * RemoveIndexSqlArgs type.
+ * @typedef {object} RemoveIndexSqlArgs
+ * @property {string} name - Index name to drop.
+ * @property {string} tableName - Name of the table the index belongs to.
+ */
 /**
  * DropTableSqlArgsType type.
  * @typedef {object} DropTableSqlArgsType
@@ -50,6 +56,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 +244,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.
@@ -298,6 +313,16 @@ export default class VelociousDatabaseDriversBase {
     throw new Error("'createIndexSQLs' not implemented")
   }
 
+  /**
+   * Runs remove index sqls.
+   * @abstract
+   * @param {RemoveIndexSqlArgs} indexData - Index data.
+   * @returns {Promise<string[]>} - Resolves with SQL statements.
+   */
+  async removeIndexSQLs(indexData) { // eslint-disable-line no-unused-vars
+    throw new Error("'removeIndexSQLs' not implemented")
+  }
+
   /**
    * Runs create table.
    * @param {import("../table-data/index.js").default} tableData - Table data.
@@ -1041,12 +1066,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 +1097,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 +1567,7 @@ export default class VelociousDatabaseDriversBase {
         }
       }
     })
+    await this.flushPendingWrites()
   }
 
   /**

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

@@ -15,6 +15,7 @@ import Options from "./options.js"
 import mssql from "mssql"
 import net from "node:net"
 import QueryParser from "./query-parser.js"
+import RemoveIndex from "./sql/remove-index.js"
 import Table from "./table.js"
 import StructureSql from "./structure-sql.js"
 import timeout from "awaitery/build/timeout.js"
@@ -113,6 +114,18 @@ export default class VelociousDatabaseDriversMssql extends Base{
     return await createIndex.toSQLs()
   }
 
+  /**
+   * Runs remove index sqls.
+   * @param {import("../base.js").RemoveIndexSqlArgs} indexData - Index data.
+   * @returns {Promise<string[]>} - Resolves with SQL statements.
+   */
+  async removeIndexSQLs(indexData) {
+    const removeArgs = Object.assign({driver: this}, indexData)
+    const removeIndex = new RemoveIndex(removeArgs)
+
+    return await removeIndex.toSQLs()
+  }
+
   /**
    * Runs create table sql.
    * @param {import("../../table-data/index.js").default} tableData - Table data.

package/build/database/drivers/mssql/sql/remove-index.js

@@ -0,0 +1,6 @@
+// @ts-check
+
+import RemoveIndexBase from "../../../query/remove-index-base.js"
+
+export default class VelociousDatabaseConnectionDriversMssqlSqlRemoveIndex extends RemoveIndexBase {
+}

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

@@ -14,6 +14,7 @@ import Options from "./options.js"
 import mysql from "mysql"
 import query from "./query.js"
 import QueryParser from "./query-parser.js"
+import RemoveIndex from "./sql/remove-index.js"
 import Table from "./table.js"
 import StructureSql from "./structure-sql.js"
 import Upsert from "./sql/upsert.js"
@@ -30,15 +31,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 +62,7 @@ export default class VelociousDatabaseDriversMysql extends Base{
   async close() {
     await this.pool?.end()
     this.pool = undefined
+    this.resetCurrentSessionTimeZone()
   }
 
   /**
@@ -64,7 +71,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 +80,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
   }
 
   /**
@@ -160,6 +228,18 @@ export default class VelociousDatabaseDriversMysql extends Base{
     return await createIndex.toSQLs()
   }
 
+  /**
+   * Runs remove index sqls.
+   * @param {import("../base.js").RemoveIndexSqlArgs} indexData - Index data.
+   * @returns {Promise<string[]>} - Resolves with SQL statements.
+   */
+  async removeIndexSQLs(indexData) {
+    const removeArgs = Object.assign({driver: this}, indexData)
+    const removeIndex = new RemoveIndex(removeArgs)
+
+    return await removeIndex.toSQLs()
+  }
+
   /**
    * Runs create table sql.
    * @param {import("../../table-data/index.js").default} tableData - Table data.

package/build/database/drivers/mysql/sql/remove-index.js

@@ -0,0 +1,6 @@
+// @ts-check
+
+import RemoveIndexBase from "../../../query/remove-index-base.js"
+
+export default class VelociousDatabaseConnectionDriversMysqlSqlRemoveIndex extends RemoveIndexBase {
+}

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

@@ -14,6 +14,7 @@ import DropTable from "./sql/drop-table.js"
 import Insert from "./sql/insert.js"
 import Options from "./options.js"
 import QueryParser from "./query-parser.js"
+import RemoveIndex from "./sql/remove-index.js"
 import Table from "./table.js"
 import StructureSql from "./structure-sql.js"
 import Upsert from "./sql/upsert.js"
@@ -149,6 +150,18 @@ export default class VelociousDatabaseDriversPgsql extends Base{
     return await createIndex.toSQLs()
   }
 
+  /**
+   * Runs remove index sqls.
+   * @param {import("../base.js").RemoveIndexSqlArgs} indexData - Index data.
+   * @returns {Promise<string[]>} - Resolves with SQL statements.
+   */
+  async removeIndexSQLs(indexData) {
+    const removeArgs = Object.assign({driver: this}, indexData)
+    const removeIndex = new RemoveIndex(removeArgs)
+
+    return await removeIndex.toSQLs()
+  }
+
   /**
    * Runs create table sql.
    * @param {import("../../table-data/index.js").default} tableData - Table data.

package/build/database/drivers/pgsql/sql/remove-index.js

@@ -0,0 +1,6 @@
+// @ts-check
+
+import RemoveIndexBase from "../../../query/remove-index-base.js"
+
+export default class VelociousDatabaseConnectionDriversPgsqlSqlRemoveIndex extends RemoveIndexBase {
+}

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

@@ -12,6 +12,7 @@ import escapeString from "sql-escape-string"
 import Insert from "./sql/insert.js"
 import Options from "./options.js"
 import QueryParser from "./query-parser.js"
+import RemoveIndex from "./sql/remove-index.js"
 import Table from "./table.js"
 import StructureSql from "./structure-sql.js"
 import Upsert from "./sql/upsert.js"
@@ -55,6 +56,18 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
     return await createIndex.toSQLs()
   }
 
+  /**
+   * Runs remove index sqls.
+   * @param {import("../base.js").RemoveIndexSqlArgs} indexData - Index data.
+   * @returns {Promise<string[]>} - Resolves with SQL statements.
+   */
+  async removeIndexSQLs(indexData) {
+    const removeArgs = Object.assign({driver: this}, indexData)
+    const removeIndex = new RemoveIndex(removeArgs)
+
+    return await removeIndex.toSQLs()
+  }
+
   /**
    * Runs create table sql.
    * @abstract

package/build/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)