refactor(persistence)!: run the web database on WebAssembly

[renefloor]

Replaces package:drift/web.dart, which drift has deprecated and put in bugfix-only mode, with package:drift/wasm.dart — and fixes persistence on WebAssembly builds along the way.

shared_db.dart selected the web implementation with if (dart.library.html), which is false under dart2wasm, so those apps silently resolved to unsupported_db.dart and threw UnsupportedError. The condition could not simply be switched to dart.library.js_interop while the old backend was in place, because package:drift/web.dart imports dart:html and that would have turned a runtime error into a compile failure. With the dependency replaced, one web implementation now serves dart2js and dart2wasm alike.

Note

Based on v11. The last commit cherry-picks the dart.library.js_interop fixes for stream_chat and stream_chat_flutter, which landed on master as #2940 but are not on v11 — without them a wasm build still dies in main() before persistence is reached. Expect that commit to drop out when master merges into v11.

Breaking changes

Web apps must serve two different files. sqlite3.wasm and drift_worker.js replace sql-wasm.js and sql-wasm.wasm in web/, and the sql-wasm.js script tag comes out of index.html — nothing replaces it, since drift starts the worker itself at runtime. Not a new kind of work: the README already required hosting the sql.js pair.

webUseExperimentalIndexedDb is removed in favour of webOptions. It named DriftWebStorage.indexedDbIfSupported, which does not exist in the new backend, so a deprecated shim could only have silently done nothing. drift now probes the browser and picks the most reliable storage itself.

The web cache is refilled once. Legacy sql.js storage cannot be read by the new backends. Its two localStorage keys are removed on connect to reclaim the space, since localStorage is capped near 5 MB. The moor_databases IndexedDB store used by the old experimental flag is deliberately left alone — that name is shared with any other database an app opened through drift's legacy web backend.

Two failure modes that needed handling

drift reports neither in a way a caller can act on, and both were traced through wasm_setup.dart:

• A missing drift_worker.js is swallowed into MissingBrowserFeature.workerError, and drift falls back to a database that answers every query and persists nothing. A smoke test cannot tell the difference. Now logged at SEVERE, naming the file and the URI it was looked up at.
• A missing sqlite3.wasm lets WasmDatabase.open resolve successfully and fails on the first query instead — inside a worker, mentioning neither the file nor where it was sought, at whatever DAO call happens first. Opening is therefore forced with one SELECT 1 so the failure lands at connect with both.

Because that eager open can also fail on a cache damaged by a killed tab, an unopenable database is discarded and reopened once before giving up. The local database is only a cache, so this costs one extra sync rather than blocking sign-in — while a genuine setup problem still fails loudly, because it fails the retry the same way.

What each browser actually gets

Which storage drift can use depends on cross-origin isolation, because opfsLocks needs SharedArrayBuffer. Everything works either way, so the headers are documented as a recommendation rather than a requirement:

Browser	Without COOP/COEP	With COOP/COEP
Firefox	origin private file system	origin private file system
Chrome / Edge	IndexedDB, shared between tabs	origin private file system
Safari	IndexedDB, shared between tabs	origin private file system

Testing

Every judgement call — which log level a storage mode deserves, what each message says — lives in web_options.dart and web_storage_diagnostics.dart, which are free of web-only imports and take plain strings rather than drift's enums. That is deliberate: package:drift/wasm.dart imports dart:js_interop, so a signature naming WasmStorageImplementation could not be imported from a VM test at all. Both files are at 100% coverage; package coverage is 97.88% against the 95 gate.

web_db.dart keeps // coverage:ignore-file — the browser probe cannot run under flutter test, and flutter test --coverage does not support --platform, so browser tests would contribute nothing to the lcov CI reads.

Verified by hand, since no CI job builds web:

• flutter build web and flutter build web --wasm for the persistence example; flutter build web for sample_app and the UI example.
• Real Chrome, dart2js: chose sharedIndexedDb, no errors, full write path. Persistence proven across restarts — cold run cids=0, then cids=1 with 15 cached messages read back, 2.1 MB of IndexedDB on disk.
• dart2wasm, cross-origin isolated: chose opfsLocks at INFO with no error, confirming the with-headers row above.
• Discard-and-retry: exercised against a real opfsLocks database with an injected first-attempt failure — warning logged, database discarded, second open succeeded, ~27 ms, no throw.
• sample_app boots and renders fully under dart2wasm with the cherry-picked fixes in place.

Not verified: Firefox and Safari, so their rows remain reasoned from drift's probe conditions rather than observed.

🤖 Generated with Claude Code

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}