@powersync/web 2.1.1 → 2.2.0

package/src/db/adapters/memory-pool/vfs.ts

@@ -0,0 +1,293 @@
+// @ts-ignore
+import { FacadeVFS } from '@journeyapps/wa-sqlite/src/FacadeVFS.js';
+import * as VFS from '@journeyapps/wa-sqlite/src/VFS.js';
+import { emptyWalState, WalIndexChange, WalOverlayEntry, WriteAheadBuffers, WriteAheadState } from './shared.js';
+
+const mainDbSentinel = Symbol();
+
+export class InMemoryWriteAheadLog extends FacadeVFS {
+  // The main /database file is the only file for which we create a write-ahead log. All other files (including the
+  // journal) are local-only.
+  #openedFiles = new Map<number, LocalFile | typeof mainDbSentinel>();
+  #files = new Map<string, LocalFile | typeof mainDbSentinel>();
+
+  #tx: WriteAheadTransaction | undefined = undefined;
+  #newOverlayPagesToSendToMainTab = new Map<number, WalOverlayEntry>();
+
+  writeAheadState: WriteAheadState = emptyWalState();
+
+  constructor(
+    module: any,
+    readonly buffers: WriteAheadBuffers
+  ) {
+    super('InMemoryWriteAheadLog', module);
+    this.#files.set('/database', mainDbSentinel);
+  }
+
+  takeChanges(): WalIndexChange {
+    const added: (number | WalOverlayEntry)[] = [];
+    this.#newOverlayPagesToSendToMainTab.forEach((v, k) => {
+      added.push(k);
+      added.push(v);
+    });
+    this.#newOverlayPagesToSendToMainTab.clear();
+
+    return {
+      cleared: false,
+      walEnd: this.writeAheadState.walEnd,
+      fileSize: this.writeAheadState.fileSize,
+      added
+    };
+  }
+
+  jAccess(zName: string, _pFlags: number, pResOut: DataView) {
+    const file = this.#files.get(zName);
+    pResOut.setInt32(0, file != null ? 1 : 0, true);
+    return VFS.SQLITE_OK;
+  }
+
+  jOpen(zName: string | null, fileId: number, flags: number, pOutFlags: DataView): number {
+    if (flags & VFS.SQLITE_OPEN_MAIN_DB) {
+      this.#openedFiles.set(fileId, mainDbSentinel);
+    } else {
+      // Treat all other files, including the mostly unused journal as temporary.
+      zName ??= `tmp-${crypto.randomUUID()}`;
+
+      const existing = this.#files.get(zName);
+      if (existing != null) {
+        this.#openedFiles.set(fileId, existing);
+      } else {
+        if (!(flags & VFS.SQLITE_OPEN_CREATE)) {
+          return VFS.SQLITE_IOERR;
+        }
+
+        const newFile = new LocalFile(zName);
+        newFile.deleteOnClose = (flags & VFS.SQLITE_OPEN_DELETEONCLOSE) != 0;
+        this.#openedFiles.set(fileId, newFile);
+        this.#files.set(zName, newFile);
+      }
+    }
+
+    pOutFlags.setInt32(0, flags, true);
+    return VFS.SQLITE_OK;
+  }
+
+  jClose(fileid: number) {
+    const file = this.#openedFiles.get(fileid)!;
+    this.#openedFiles.delete(fileid);
+
+    if (file != mainDbSentinel && file.deleteOnClose) {
+      this.#files.delete(file.name);
+    }
+
+    return VFS.SQLITE_OK;
+  }
+
+  jRead(fileId: number, data: Uint8Array, offset: number) {
+    const file = this.#openedFiles.get(fileId)!;
+    let endOffset: number;
+    let readableBytes: number;
+
+    if (file == mainDbSentinel) {
+      const { fileSize, overlay } = this.writeAheadState;
+      const startOffset = Math.min(offset, fileSize);
+      endOffset = Math.min(fileSize, offset + data.byteLength);
+      readableBytes = endOffset - startOffset;
+
+      // Try reading from the write-ahead overlay first. A read on the database file is always a complete page, except
+      // when reading from the 100-byte header.
+      const page = overlay.get(offset < 100 ? 0 : offset);
+
+      if (page != null) {
+        const pageOffset = page.logOffset;
+        const source = new Uint8Array(
+          this.buffers.writeAheadLog,
+          offset < 100 ? pageOffset + offset : pageOffset,
+          readableBytes
+        );
+        data.set(source);
+      } else {
+        // Page is not in WAL overlay, read directly from underlying in-memory buffer.
+        data.set(new Uint8Array(this.buffers.database, startOffset, readableBytes));
+      }
+    } else {
+      const fileSize = file.size;
+      const startOffset = Math.min(offset, fileSize);
+      endOffset = Math.min(fileSize, offset + data.byteLength);
+      readableBytes = endOffset - startOffset;
+
+      if (readableBytes > 0) {
+        data.set(new Uint8Array(file.buffer, startOffset, readableBytes));
+      }
+    }
+
+    if (readableBytes < data.byteLength) {
+      data.fill(0, readableBytes); // Fill rest with zeroes.
+      return VFS.SQLITE_IOERR_SHORT_READ;
+    }
+
+    return VFS.SQLITE_OK;
+  }
+
+  jWrite(fileId: number, data: Uint8Array, offset: number): number {
+    const file = this.#openedFiles.get(fileId)!;
+    // wa-sqlite passes a proxy instead of a real Uint8Array.
+    const actualBuffer = data.subarray();
+
+    if (file === mainDbSentinel) {
+      // Write to the write-ahead overlay.
+      let didWrite = false;
+      if (this.#tx != null) {
+        didWrite = this.#tx.appendPage(offset, actualBuffer);
+      } else {
+        const tx = new WriteAheadTransaction(this.writeAheadState.walEnd, this.writeAheadState.fileSize, this.buffers);
+        didWrite = tx.appendPage(offset, actualBuffer);
+        this.#commit(tx);
+      }
+
+      return didWrite ? VFS.SQLITE_OK : VFS.SQLITE_FULL;
+    } else {
+      const writeLength = data.length;
+      const endOffset = offset + writeLength;
+      if (endOffset > file.buffer.byteLength) {
+        const didGrow = file.growBuffer(endOffset);
+        if (!didGrow) {
+          return VFS.SQLITE_FULL;
+        }
+      }
+
+      new Uint8Array(file.buffer, offset, writeLength).set(actualBuffer);
+      file.size = Math.max(file.size, endOffset);
+      return VFS.SQLITE_OK;
+    }
+  }
+
+  jTruncate(fileid: number, size: number): number {
+    const file = this.#openedFiles.get(fileid)!;
+
+    if (file === mainDbSentinel) {
+      this.writeAheadState.fileSize = Math.min(this.writeAheadState.fileSize, size);
+    } else {
+      file.size = Math.min(size, file.size);
+    }
+
+    return VFS.SQLITE_OK;
+  }
+
+  jFileSize(fileid: number, pSize64: DataView) {
+    const file = this.#openedFiles.get(fileid)!;
+
+    if (file === mainDbSentinel) {
+      pSize64.setBigInt64(0, BigInt(this.writeAheadState.fileSize), true);
+    } else {
+      pSize64.setBigInt64(0, BigInt(file.size), true);
+    }
+
+    return VFS.SQLITE_OK;
+  }
+
+  jDelete(name: string) {
+    if (name === '/database') {
+      return VFS.SQLITE_IOERR_DELETE;
+    }
+
+    this.#files.delete(name);
+    return VFS.SQLITE_OK;
+  }
+
+  jDeviceCharacteristics(): number {
+    return VFS.SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN | VFS.SQLITE_IOCAP_BATCH_ATOMIC;
+  }
+
+  jFileControl(fileid: number, op: number) {
+    const file = this.#openedFiles.get(fileid)!;
+    if (file !== mainDbSentinel) return VFS.SQLITE_NOTFOUND;
+
+    switch (op) {
+      case VFS.SQLITE_FCNTL_BEGIN_ATOMIC_WRITE:
+        this.#tx = new WriteAheadTransaction(this.writeAheadState.walEnd, this.writeAheadState.fileSize, this.buffers);
+        break;
+      case VFS.SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE:
+        this.#tx = undefined;
+        break;
+      case VFS.SQLITE_FCNTL_COMMIT_ATOMIC_WRITE:
+        this.#commit(this.#tx!);
+        this.#tx = undefined;
+        break;
+      default:
+        return VFS.SQLITE_NOTFOUND;
+    }
+
+    return VFS.SQLITE_OK;
+  }
+
+  #commit(tx: WriteAheadTransaction) {
+    this.writeAheadState.walEnd = tx.walEndOffset;
+    this.writeAheadState.fileSize = tx.fileSize;
+    tx.changedPages.forEach((walEntry, databaseOffset) => {
+      this.#newOverlayPagesToSendToMainTab.set(databaseOffset, walEntry);
+      this.writeAheadState.overlay.set(databaseOffset, walEntry);
+    });
+  }
+}
+
+class WriteAheadTransaction {
+  walEndOffset: number;
+  fileSize: number;
+  changedPages = new Map<number, WalOverlayEntry>();
+
+  constructor(
+    endOffset: number,
+    fileSize: number,
+    readonly buffers: WriteAheadBuffers
+  ) {
+    this.walEndOffset = endOffset;
+    this.fileSize = fileSize;
+  }
+
+  appendPage(offset: number, data: Uint8Array): boolean {
+    const currentEnd = this.walEndOffset;
+    const newEnd = currentEnd + data.length;
+
+    const wal = this.buffers.writeAheadLog;
+    if (newEnd > wal.byteLength) {
+      if (!this.#growWal(wal, newEnd)) return false;
+    }
+    this.fileSize = Math.max(this.fileSize, offset + data.length);
+    new Uint8Array(wal, currentEnd, data.length).set(data);
+
+    this.walEndOffset = newEnd;
+    this.changedPages.set(offset, { logOffset: currentEnd, size: data.length });
+    return true;
+  }
+
+  #growWal(buffer: SharedArrayBuffer, minSize: number) {
+    const newSize = Math.max(minSize, Math.min(2 * buffer.byteLength, buffer.maxByteLength));
+    if (newSize > buffer.maxByteLength) {
+      return false;
+    }
+
+    buffer.grow(newSize);
+    return true;
+  }
+}
+
+class LocalFile {
+  deleteOnClose = false;
+  name: string;
+  buffer = new ArrayBuffer(1024);
+  size: number = 0;
+
+  constructor(name: string) {
+    this.name = name;
+  }
+
+  growBuffer(minSize: number): boolean {
+    const newSize = Math.max(minSize, 2 * this.buffer.byteLength);
+    const newBuffer = new ArrayBuffer(newSize);
+
+    new Uint8Array(newBuffer).set(new Uint8Array(this.buffer));
+    this.buffer = newBuffer;
+    return true;
+  }
+}

package/src/db/adapters/memory-pool/worker.ts

@@ -0,0 +1,53 @@
+import * as Comlink from 'comlink';
+import { applyWalChanges, DatabaseServer, WalIndexChange, WriteAheadBuffers } from './shared.js';
+import { RawQueryResult } from '@powersync/common';
+import { InMemoryWriteAheadLog } from './vfs.js';
+import { RawSqliteConnection, RawWaSqliteDatabaseOptions, RawWebResult } from '../wa-sqlite/RawSqliteConnection.js';
+import { WASQLiteVFS } from '../wa-sqlite/vfs.js';
+import { TemporaryStorageOption } from '../options.js';
+
+class MemoryDatabaseServer implements DatabaseServer {
+  #vfs!: InMemoryWriteAheadLog;
+  #connection!: RawSqliteConnection;
+
+  async open(buffers: WriteAheadBuffers, options: Partial<RawWaSqliteDatabaseOptions>): Promise<void> {
+    const { default: factory } = await import('@journeyapps/wa-sqlite/dist/wa-sqlite.mjs');
+    const module = await factory();
+    const vfs = (this.#vfs = new InMemoryWriteAheadLog(module, buffers));
+
+    const connection = new RawSqliteConnection({
+      encryptionKey: undefined,
+      vfs: WASQLiteVFS.InMemoryVfs,
+      // Unused, since we register our own VFS. Only needed to satisfy the type.
+      temporaryStorage: TemporaryStorageOption.MEMORY,
+      cacheSizeKb: 50 * 1024,
+      preparedStatementsCache: 0,
+      ...options,
+      // The rest of these options is not overridable: The VFS handles /database reads and writes in a special way and
+      // there can only be one database per buffers instance.
+      filename: '/database',
+      readonly: false
+    });
+    await connection.initWithModule(module, vfs);
+    this.#connection = connection;
+  }
+
+  async updateWalState(overlay: WalIndexChange): Promise<void> {
+    const currentState = this.#vfs.writeAheadState;
+    applyWalChanges(currentState, overlay);
+  }
+
+  async executeRaw(query: string, params?: any[] | undefined): Promise<RawQueryResult> {
+    return await this.#connection.execute(query, params);
+  }
+
+  async executeBatch(query: string, params: any[][]): Promise<RawWebResult[]> {
+    return await this.#connection.executeBatch(query, params);
+  }
+
+  async takeWalChanges(): Promise<WalIndexChange> {
+    return this.#vfs.takeChanges();
+  }
+}
+
+Comlink.expose(new MemoryDatabaseServer());

package/src/db/adapters/options.ts

@@ -88,6 +88,14 @@ export interface WebSpecificOpenOptions {
    * A worker will be initialized if none is provided
    */
   workerPort?: MessagePort | undefined;
+
+  /**
+   * If set to a value greater than zero, the worker will cache prepared statements to avoid preparing them every time
+   * a query runs.
+   *
+   * Defaults to 0 (disabling the cache).
+   */
+  preparedStatementsCache?: number;
 }
 
 export interface ResolvedWebSQLOpenOptions extends SQLOpenOptions, WebSpecificOpenOptions {}

package/src/db/adapters/wa-sqlite/RawSqliteConnection.ts

@@ -4,6 +4,7 @@ import { loadModuleAndVfs, WASQLiteVFS } from './vfs.js';
 import { TemporaryStorageOption } from '../options.js';
 import { RawQueryResult, SqliteValue } from '@powersync/common';
 import { maxPathNameLength } from '../resolveAndValidateOptions.js';
+import { PreparedStatementCache } from './StatementCache.js';
 
 export interface RawWebResult extends Required<RawQueryResult> {
   autocommit: boolean;
@@ -24,6 +25,10 @@ export interface RawWaSqliteDatabaseOptions {
   encryptionKey: string | undefined;
   temporaryStorage: TemporaryStorageOption;
   cacheSizeKb: number;
+  /**
+   * The amount of prepared statements to cache, or 0 to disable caching.
+   */
+  preparedStatementsCache: number;
 }
 
 /**
@@ -34,19 +39,30 @@ export interface RawWaSqliteDatabaseOptions {
  */
 export class RawSqliteConnection {
   private _sqliteAPI: SQLiteAPI | null = null;
+  private sqlite3_stmt_isexplain!: (stmt: number) => 0 | 1 | 2;
+
   /**
    * The `sqlite3*` connection pointer.
    */
   private db: number = 0;
+  private statementCache: PreparedStatementCache | null;
 
-  constructor(readonly options: RawWaSqliteDatabaseOptions) {}
+  constructor(readonly options: RawWaSqliteDatabaseOptions) {
+    this.statementCache =
+      options.preparedStatementsCache > 0 ? new PreparedStatementCache(options.preparedStatementsCache) : null;
+  }
 
   get isOpen(): boolean {
     return this.db != 0;
   }
 
   async init() {
-    const api = (this._sqliteAPI = await this.openSQLiteAPI());
+    const { module, vfs } = await loadModuleAndVfs(this.options);
+    await this.initWithModule(module, vfs);
+  }
+
+  async initWithModule(module: any, vfs: any) {
+    const api = (this._sqliteAPI = await this.openSQLiteAPI(module, vfs));
     this.db = await api.open_v2(
       this.options.filename,
       this.options.readonly ? 1 /* SQLITE_OPEN_READONLY */ : 6 /* SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE */
@@ -61,9 +77,10 @@ export class RawSqliteConnection {
     await this.executeRaw(`SELECT powersync_update_hooks('install');`);
   }
 
-  private async openSQLiteAPI(): Promise<SQLiteAPI> {
-    const { module, vfs } = await loadModuleAndVfs(this.options);
+  private async openSQLiteAPI(module: any, vfs: SQLiteVFS): Promise<SQLiteAPI> {
     vfs.mxPathname = maxPathNameLength;
+
+    this.sqlite3_stmt_isexplain = module.cwrap('sqlite3_stmt_isexplain', 'int', ['int']);
     const sqlite3 = WaSqliteFactory(module);
     sqlite3.vfs_register(vfs, true);
     /**
@@ -143,7 +160,7 @@ export class RawSqliteConnection {
   async executeRaw(sql: string, bindings?: any[]): Promise<RawResultSet[]> {
     const results = [];
     const api = this.requireSqlite();
-    for await (const stmt of api.statements(this.db, sql)) {
+    for await (const stmt of this.cachedStatements(api, sql)) {
       let columns;
 
       const rs = await this.stepThroughStatement(api, stmt, bindings ?? [], columns);
@@ -194,8 +211,56 @@ export class RawSqliteConnection {
 
   async close() {
     if (this.isOpen) {
-      await this.requireSqlite().close(this.db);
+      const api = this.requireSqlite();
+
+      if (this.statementCache) {
+        for (const stmt of this.statementCache.drain()) {
+          await api.finalize(stmt);
+        }
+      }
+
+      await api.close(this.db);
       this.db = 0;
     }
   }
+
+  private async *cachedStatements(api: SQLiteAPI, sql: string): AsyncIterable<number> {
+    {
+      const existing = this.statementCache?.lookup(sql);
+      if (existing != null) {
+        yield existing;
+        return;
+      }
+    }
+
+    const inner = api.statements(this.db, sql, { unscoped: true });
+    const preparedStatements: number[] = [];
+
+    try {
+      for await (const stmt of inner) {
+        preparedStatements.push(stmt);
+        yield stmt;
+      }
+    } finally {
+      // We can only cache statements if the sql text corresponds to a single statement, otherwise it's not clear what
+      // portion of the original sql text to use as a key.
+      if (preparedStatements.length === 1 && this.statementCache) {
+        const stmt = preparedStatements[0];
+        // Don't cache EXPLAIN statements, their result becomes invalid after schema changes.
+        if (this.sqlite3_stmt_isexplain(stmt) == 0) {
+          const evicted = this.statementCache.addStatement(sql, stmt);
+          if (evicted != null) {
+            await api.finalize(evicted);
+          }
+
+          return;
+        }
+      }
+
+      // We're not caching statements, so finalize them.
+      for (const stmt of preparedStatements) {
+        await api.finalize(stmt);
+      }
+    }
+  }
 }

package/src/db/adapters/wa-sqlite/StatementCache.ts

@@ -0,0 +1,50 @@
+export class PreparedStatementCache {
+  readonly #size: number;
+  // Note that Map preserves insertion order, which allows using it as an LRU
+  // cache (with the first element being the first element to evict).
+  readonly #statements = new Map<string, number>();
+
+  constructor(size: number) {
+    this.#size = size;
+  }
+
+  /**
+   * Attempts to look up the cached sql statement, if it's currently cached.
+   */
+  lookup(sql: string): number | null {
+    const foundStatement = this.#statements.get(sql);
+    if (foundStatement != null) {
+      // Delete and re-insert to move to the end (most-recently-used position).
+      this.#statements.delete(sql);
+      this.#statements.set(sql, foundStatement);
+      return foundStatement;
+    }
+
+    return null;
+  }
+
+  /**
+   * Adds a new statement into the cache.
+   *
+   * If that exceeds the target size of the statement cache, returns an old statement to evict.
+   * The caller is responsible for freeing that statement.
+   */
+  addStatement(sql: string, statement: number): number | null {
+    this.#statements.set(sql, statement);
+
+    if (this.#statements.size > this.#size) {
+      for (const [k, v] of this.#statements.entries()) {
+        this.#statements.delete(k);
+        return v;
+      }
+    }
+
+    return null;
+  }
+
+  drain(): number[] {
+    const values = [...this.#statements.values()];
+    this.#statements.clear();
+    return values;
+  }
+}

package/src/db/adapters/wa-sqlite/WASQLiteOpenFactory.ts

@@ -67,8 +67,16 @@ export class WASQLiteOpenFactory implements SQLOpenFactory {
   }
 
   async openConnection(): Promise<PoolConnection> {
-    const { enableMultiTabs, useWebWorker, vfs, dbFilename, encryptionKey, temporaryStorage, cacheSizeKb } =
-      this.options;
+    const {
+      enableMultiTabs,
+      useWebWorker,
+      vfs,
+      dbFilename,
+      encryptionKey,
+      temporaryStorage,
+      cacheSizeKb,
+      preparedStatementsCache
+    } = this.options;
 
     if (!enableMultiTabs) {
       this.logger.log({ level: LogLevels.warn, message: 'Multiple tabs are not enabled in this browser' });
@@ -85,7 +93,9 @@ export class WASQLiteOpenFactory implements SQLOpenFactory {
         vfs,
         encryptionKey,
         temporaryStorage,
-        cacheSizeKb
+        cacheSizeKb,
+        // TODO: Enable prepared statement cache by default?
+        preparedStatementsCache: preparedStatementsCache ?? 0
       };
     }
 
@@ -140,10 +150,12 @@ export class WASQLiteOpenFactory implements SQLOpenFactory {
         // This VFS supports concurrent reads, so we can open additional workers to host read-only connections for
         // concurrent reads / writes.
         const additionalReadersCount = this.options.additionalReaders ?? 1;
+
+        const additionalReaderPromises: Promise<DatabaseClient>[] = [];
         for (let i = 0; i < additionalReadersCount; i++) {
-          const reader = await openDatabaseWorker(true);
-          additionalReaders.push(reader);
+          additionalReaderPromises.push(openDatabaseWorker(true));
         }
+        additionalReaders.push(...(await Promise.all(additionalReaderPromises)));
       }
     } else {
       // Don't use a web worker. Instead, open the MultiDatabaseServer a worker would use locally.

package/src/worker/db/MultiDatabaseServer.ts

@@ -5,6 +5,7 @@ import { getNavigatorLocks } from '../../shared/navigator.js';
 import { RawSqliteConnection, RawWaSqliteDatabaseOptions } from '../../db/adapters/wa-sqlite/RawSqliteConnection.js';
 import { ConcurrentSqliteConnection } from '../../db/adapters/wa-sqlite/ConcurrentConnection.js';
 import { WASQLiteVFS } from '../../db/adapters/wa-sqlite/vfs.js';
+import { Mutex } from '@powersync/shared-internals';
 
 const OPEN_DB_LOCK = 'open-wasqlite-db';
 
@@ -18,7 +19,8 @@ export interface ConnectToMultiDatabaseServerOptions {
  * Shared state to manage multiple database connections hosted by a worker.
  */
 export class MultiDatabaseServer {
-  private activeDatabases = new Map<string, DatabaseServer>();
+  readonly #activeDatabases = new Map<string, DatabaseServer>();
+  readonly #localOpenLock = new Mutex();
 
   constructor(readonly logger: PowerSyncLogger) {}
 
@@ -38,7 +40,7 @@ export class MultiDatabaseServer {
 
   async connectToExisting(name: string, lockName: string): Promise<ClientConnectionView> {
     return getNavigatorLocks().request(OPEN_DB_LOCK, async () => {
-      const server = this.activeDatabases.get(name);
+      const server = this.#activeDatabases.get(name);
       if (server == null) {
         throw new Error(`connectToExisting(${name}) failed because the worker doesn't own a database with that name.`);
       }
@@ -55,7 +57,7 @@ export class MultiDatabaseServer {
 
     for (let count = 0; count < maxAttempts - 1; count++) {
       try {
-        server = await this.databaseOpenAttempt(logger, options);
+        server = await this.#databaseOpenAttempt(logger, options);
       } catch (error) {
         this.logger.log({
           level: LogLevels.warn,
@@ -67,24 +69,22 @@ export class MultiDatabaseServer {
     }
 
     // Final attempt if we haven't been able to open the server - rethrow errors if we still can't open.
-    server ??= await this.databaseOpenAttempt(logger, options);
+    server ??= await this.#databaseOpenAttempt(logger, options);
     return server.connect(lockName);
   }
 
-  private async databaseOpenAttempt(
-    logger: PowerSyncLogger,
-    options: RawWaSqliteDatabaseOptions
-  ): Promise<DatabaseServer> {
-    return getNavigatorLocks().request(OPEN_DB_LOCK, async () => {
-      const { filename, readonly, vfs } = options;
-
-      let server: DatabaseServer | undefined = this.activeDatabases.get(filename);
+  async #databaseOpenAttempt(logger: PowerSyncLogger, options: RawWaSqliteDatabaseOptions): Promise<DatabaseServer> {
+    const { filename, readonly, vfs } = options;
+    // We don't need navigator locks for shared workers because all queries run in this shared worker exclusively.
+    // For read-only connections, we use a VFS that supports concurrent reads (so a single lock on the connection is
+    // fine). In-memory databases either run in a shared worker or aren't shared across tabs at all, so the internal
+    // lock is enough.
+    const needsNavigatorLocks = !(isSharedWorker || readonly || vfs == WASQLiteVFS.InMemoryVfs);
+    const activeDatabases = this.#activeDatabases;
+
+    async function openDatabase() {
+      let server: DatabaseServer | undefined = activeDatabases.get(filename);
       if (server == null) {
-        // We don't need navigator locks for shared workers because all queries run in this shared worker exclusively.
-        // For read-only connections, we use a VFS that supports concurrent reads (so a single lock on the connection is
-        // fine). In-memory databases either run in a shared worker or aren't shared across tabs at all, so the internal
-        // lock is enough.
-        const needsNavigatorLocks = !(isSharedWorker || readonly || vfs == WASQLiteVFS.InMemoryVfs);
         const connection = new RawSqliteConnection(options);
         const withSafeConcurrency = new ConcurrentSqliteConnection(connection, needsNavigatorLocks);
 
@@ -101,21 +101,29 @@ export class MultiDatabaseServer {
         }
         returnLease();
 
-        const onClose = () => this.activeDatabases.delete(filename);
+        const onClose = () => activeDatabases.delete(filename);
         server = new DatabaseServer({
           inner: withSafeConcurrency,
           logger,
           onClose
         });
-        this.activeDatabases.set(filename, server);
+        activeDatabases.set(filename, server);
       }
 
       return server;
-    });
+    }
+
+    if (needsNavigatorLocks) {
+      return getNavigatorLocks().request(OPEN_DB_LOCK, openDatabase);
+    } else {
+      // Even if we don't need navigator locks, this avoids a race between the activeDatabases.get() call, the async
+      // open logic and the final activeDatabases.set() step.
+      return this.#localOpenLock.runExclusive(openDatabase);
+    }
   }
 
   closeAll() {
-    const existingDatabases = [...this.activeDatabases.values()];
+    const existingDatabases = [...this.#activeDatabases.values()];
     return Promise.all(
       existingDatabases.map((db) => {
         db.forceClose();