API reference › @evolu/common › local‑first/Db

Platform-agnostic Evolu DbWorker.

Database version

Every database records dbVersion in evolu_version. The version describes Evolu's internal persisted format: the layout of its system tables and the meaning of the data stored in them. It is independent of the application schema, which evolves append-only through ensureSqliteSchema, and of the network protocol version, which is checked per message. Many Evolu releases can share one database version.

Bump dbVersion for any change that older code would misread, not only for changed SQL. A new quarantine reason, for example, changes what startup may replay even when its columns are additive. Each bump ships with a migration from the previous version; fresh databases are created at the latest layout directly.

Startup holds the database leader lock, then checks the stored version record before it reads the clock, ensures the application schema, or replays quarantine. Databases written before the version record existed hold one protocolVersion row instead; that known legacy layout is converted to version 1. A newer stored version refuses startup with UnsupportedDbVersionError. The refusal returns from the startup transaction before anything is written and is posted to the SharedWorker; the worker then exits and releases its resources. A database whose files another context keeps holding refuses startup the same way, before it is opened, with DatabaseHeldError; see WaitForDatabaseRelease. The single version row is created in the same transaction as the other system tables.

Code released before the version record existed never reads it. It recognizes an initialized database by the evolu_version table alone, so it opens a newer database and replays all quarantine regardless of reason, applying drift quarantine at once without advancing the clock. Renaming the table would make such code fail at startup instead. That was declined: the replay needs drift quarantine and an earlier release on the same device at once, and failing would break a rollback to an earlier release outright.

Failure

Once the worker holds its port, a throw that ends it, such as a startup that cannot open or read the database or a defect while applying sync, panics the worker, which reports it, and is posted to the SharedWorker as a refusal with an UnknownError before the database lock is released. The SharedWorker then treats the database as refused and tells its tabs instead of waiting for the worker forever. A mutation or a received sync batch that SQLite fails to store is answered with an UnknownError, as is each query or export that SQLite fails, and a received frame whose ranges SQLite fails to reconcile and an owner whose sync round SQLite fails to create are logged and reported as failed, so the database stays available. A subscribed query that SQLite fails does not fail its mutation, unless its error, such as an I/O error or no memory, made SQLite roll the transaction back; then the commit fails and the mutation is answered with an UnknownError. A dispose message, the SharedWorker ending, or an abort that is not a panic posts nothing. When a worker fails before it gets its port, such as a web worker whose script fails to load, the tab that hosts it posts the refusal in its place; see CreateDbWorker.

Functions

Function	Description
startDbWorker	Starts the platform-agnostic Evolu DbWorker and owns its resources until it refuses startup or fails, the worker receives a dispose message, the SharedWorker that requested it ends, or its Run is aborted.

Interfaces

Interface	Description
CreateDbWorkerDep	-
DatabaseHeldError	Another context kept holding the database's files, so the database did not open; see WaitForDatabaseRelease.
DbWorkerInit	-
UnsupportedDbVersionError	The stored database version is newer than this code supports. Newer code created or migrated the database, which is left unchanged. This happens when older code opens a database a newer build migrated, for example an older build loaded from a cache, or when the app was downgraded after a newer version migrated the local data. On the web, a refused tab reloads once for each stored version, so it loads the build the server now serves, and the error is reported when that build refuses too. Then close all tabs of the app, which lets a service worker replace a cached older build, or update the app to a version that supports storedVersion.
WaitForDatabaseReleaseDep	Dependency wrapper for WaitForDatabaseRelease.

Type Aliases

Type Alias	Description
CreateDbWorker	Creates the DbWorker that a tab hosts, which then receives its DbWorkerInit.
DbWorker	-
DbWorkerDeps	-
WaitForDatabaseRelease	Waits until no other context holds the files of the persistent database name, and fails with DatabaseHeldError when they stay held.