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. 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 and cannot be protected by
it.
Functions
| Function | Description |
|---|---|
| startDbWorker | Starts the platform-agnostic Evolu DbWorker and owns its resources until startup is refused, the worker receives a dispose message, or its Run is aborted. |
Interfaces
| Interface | Description |
|---|---|
| CreateDbWorkerDep | - |
| 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 a tab running a newer deployment migrated the database while this tab still runs older code, or when the app was downgraded after a newer version migrated the local data. Update the app to a version that supports storedVersion and close all its tabs. |
Type Aliases
| Type Alias | Description |
|---|---|
| CreateDbWorker | - |
| DbWorker | - |
| DbWorkerDeps | - |