# BsqliteOpfsStorageProvider (`opfs`)

Package `Bit.Bsqlite` - `using Bit.Bsqlite.Storage.Opfs;`

Persists SQLite databases in the origin's private file system via OPFSCoopSyncVFS.

Chosen over AccessHandlePoolVFS because more than one connection may be open and the .db is a real file - export is a read. Access handles are worker-only, so the engine stays in a dedicated worker; probe and admin use the async file API and can run on the window.

Without an IJSRuntime the probe reports unavailable rather than throwing, so desktop tests and selection can move on and still explain themselves.

## Capabilities

Read off `new BsqliteOpfsStorageProvider().Capabilities`. The core enforces every one of them generically - it never tests a provider's name.

- **RequiredBuild** = `Synchronous` - The engine build this backend's VFS requires.
- **IsPersistent** = `true` - Whether data survives a page reload. Guarded because falling back to a non-persistent backend silently is a data-loss bug, so selection demands a separate opt-in for it.
- **SupportsMultipleConnections** = `true` - Whether more than one connection may be open against one database.
- **SupportsConcurrentReads** = `false` - Whether readers can proceed concurrently rather than being serialized.
- **SupportsRelaxedDurability** = `false` - Whether the backend can offer a durability level below full flush-on-commit. Relaxed durability is only offered to callers when this is true.
- **SupportsMultiDatabaseTransactions** = `false` - Whether a transaction may span ATTACHed databases. When false the core rejects cross-database transactions instead of letting them corrupt silently.
- **CanChangePageSize** = `true` - Whether PRAGMA page_size may be changed. Block-oriented backends fix the page size to their block size, and the core guards the pragma for any backend answering false.
- **SupportedContexts** = `DedicatedWorker` - Contexts this backend works in. Defaults to BsqliteExecutionContexts.DedicatedWorker, the only context in which v1 hosts the engine.

## What the guards refuse here

Each statement run through `BsqliteFeatureGuards.EnsureSupported` under the `BsqliteRuntimeLimits` a session on this backend gets:

- `PRAGMA journal_mode = WAL` - refused: WAL mode is not available in the browser: WebAssembly has no shared-memory primitives for it, and no web VFS implements it. Bsqlite uses DELETE or TRUNCATE journaling. Concurrent reads, where a backend offers them, are a VFS capability rather than a journal-mode setting.
- `ATTACH DATABASE 'other.db' AS other` - refused: ATTACH is not available on this storage backend: it cannot run a transaction that spans more than one database. Open each database on its own connection.
- `PRAGMA page_size = 8192` - accepted

## Modules

- VFS module: `./_content/Bit.Bsqlite/bit-bsqlite-opfs-vfs.js` (registers the `opfs-coop-sync` VFS)
- Probe and admin module, imported on the main thread: `./_content/Bit.Bsqlite/bit-bsqlite-opfs-admin.js`

Both are static web assets of the package, named relative to the document so an app served under a sub-path still finds them, 
and imported only once this backend is selected or probed; nothing needs adding to the host page.

## Registration

```csharp
using Bit.Bsqlite.Storage.Opfs;

builder.Services.AddBitBsqliteServices(sqlite => sqlite
    .AddStorageProvider<BsqliteOpfsStorageProvider>()
    .UseStorage(s => s.Prefer(BsqliteOpfsStorageProvider.ProviderName))
    .AddDatabase("app.db"));
```

More on this backend: `GetBsqliteDocument(name: "storage", section: "OPFS")`.