Rask.SQLite.Browser 0.23.1-alpha.0.66

Rask.SQLite.Browser

A real SQLite database inside a browser WebAssembly app — the same Microsoft.Data.Sqlite, and the same Entity Framework Core on top of it, that you would run on a server — persisted across reloads.

Why

A WASM app has no filesystem that survives a reload. SQLite still runs there: the native e_sqlite3 is linked into the app at publish, and the database file lives in the runtime's in-memory filesystem. What is missing is durability, and one owner. This package supplies both.

• Restored before anything opens it. A hosted service reads the newest snapshot out of IndexedDB and writes the file during StartAsync, so a service registered after it finds a populated database rather than an empty one.
• Written back on an interval and on page-hide, through SQLite's Online Backup API (Rask.SQLite.Snapshots) — never an unsafe file copy of a database someone might be writing to.
• Owned by exactly one tab. Every tab has its own copy of the in-memory filesystem, so two of them would hold two divergent databases and the last to snapshot would silently overwrite the other. A Web Lock elects one owner; the others run unpersisted and say so.

Use

builder.Services.AddRaskBrowserSqlite("app");
builder.Services.AddDbContextFactory<AppDbContext>(o =>
    o.UseSqlite(BrowserSqlite.ConnectionString("app")));

// From here on, nothing is browser-specific:
builder.Services.AddRaskJobs<AppDbContext>();

Register it before anything that opens the database — registration order is start order.

builder.Services.AddRaskBrowserSqlite("app", o =>
{
    o.SnapshotInterval = 10.Seconds;  // the real durability window
    o.Retain = 2;                                   // each snapshot costs a full database in quota
});

Full-text search

Ranked, word-aware search over the local database works the way it does on the server. Add Rask.SQLite.EntityFrameworkCore and put UseRaskFullTextSearch() after the plain UseSqlite — it registers only what search needs, none of the server's pragmas:

builder.Services.AddDbContextFactory<AppDbContext>(o => o
    .UseSqlite(BrowserSqlite.ConnectionString("app"))
    .UseRaskFullTextSearch());

var hits = await db.Set<Post>().Search(query).Take(20).ToListAsync();   // best match first

Declare the index with Rask.Data's HasFullTextSearch(p => new { p.Title, p.Body }) and apply migrations (Database.MigrateAsync()): the FTS5 index is built by a migration, and EnsureCreated creates none. FTS5 is compiled into the SQLite build that is linked into the WebAssembly app.

What to know before you rely on it

• Entity Framework Core needs its three assemblies rooted in a trimmed build. EF Core builds its model and queries by reflection, so trimmed without roots it fails with a MissingMethodException at the first EF call. Add <TrimmerRootAssembly Include="…"/> for Microsoft.EntityFrameworkCore, Microsoft.EntityFrameworkCore.Relational and Microsoft.EntityFrameworkCore.Sqlite, and suppress EF's own IL2026;IL2104 (plus WASM0001 for the SQLite natives). Microsoft.Data.Sqlite, this package, Rask.Data and Rask.SQLite.EntityFrameworkCore are trim-safe and need nothing. PublishTrimmed=false also works, at a much larger download.
• The durability window is the snapshot interval, not the page-hide flush. The browser does not wait for a pagehide handler, so a force-closed or crashed tab loses whatever changed since the last tick.
• Snapshots live in IndexedDB, which is evictable. The owning tab asks the browser to exempt the origin (navigator.storage.persist()) at startup; a refusal is logged and changes nothing else. Chromium decides on engagement without prompting, Firefox prompts — so an app that would rather choose its moment sets o.RequestPersistentStorage = false and calls IStorageEstimator.RequestPersistAsync() from a user-gesture handler instead.
• Non-owner tabs are not read-only — they are separate. They get their own empty in-memory database and never persist, which looks like data loss unless you say otherwise. Inject BrowserSqliteOwnership and tell the user: await ownership.Resolved gives the answer, and ownership.IsOwner is null while the election is still running so a normal boot never flashes a banner. When the owner closes, await ownership.Available completes so you can offer a reload — reloading is what takes ownership, since a waiting tab already opened its own empty database and the file cannot be swapped under live connections. Proxying a non-owner's writes to the owner is not implemented.
• Snapshots cost their full database size in the origin's storage quota, times Retain.
• Add <NoWarn>$(NoWarn);WASM0001</NoWarn> if you build with warnings as errors: the SQLite native build reports two varargs functions (sqlite3_config, sqlite3_db_config) that WASM cannot call. Neither is reached on the normal open/query/update paths.

Links

• Repository
• SQLite guide
• Full-text search guide