API reference / @evolu/common / Evolu/Internal / ClientStorage
Interface: ClientStorage
Defined in: packages/common/src/Evolu/Sync.ts:421
Common interface for both client and relay SQLite storages.
Evolu uses a Skiplist, which leverages SQLite indexes. The core logic is implemented in SQL, so it doesn't have to make roundtrips to the DB.
While the SQL implementation may look sophisticated, it's conceptually simple and LLMs can explain how it works. The Skiplist data structure is well explained in this Stack Overflow answer. The logic resembles Negentropy's C++ storage, except we use a Skiplist to leverage SQLite indexes, which makes the code simpler.
Note: A paid review by the SQLite team is planned, as they use the same algorithm for their rsync tool.
The ideal storage for a Relay should use an architecture like strfry (a KV storage), but with Skiplist to ensure that insertion order doesn't matter (local-first apps can often write in the past.)
The ideal client implementation should probably use the SQLite extension instead of SQL or even a KV storage, when such a thing for browsers/native will exist and will be faster than SQLite.
Scaling
The load can be distributed by deploying multiple relays, synchronized with each other, if necessary. One relay should handle hundreds of thousands of users, and when it goes down, nothing happens, because it will be synchronized later.
Extends
Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
|---|---|---|---|---|---|
deleteOwner | readonly | (ownerId) => boolean | Delete all data for the given Owner. Returns true on success, false on failure. | SqliteStorageBase.deleteOwner | packages/common/src/Evolu/Storage.ts:261 |
findLowerBound | readonly | (ownerId, begin, end, upperBound) => | number & Brand<"Int"> & Brand<"NonNegative"> | null | - | SqliteStorageBase.findLowerBound | packages/common/src/Evolu/Storage.ts:259 |
fingerprint | readonly | (ownerId, begin, end) => | Fingerprint | null | - | SqliteStorageBase.fingerprint | packages/common/src/Evolu/Storage.ts:257 |
fingerprintRanges | readonly | (ownerId, buckets, upperBound?) => | readonly FingerprintRange[] | null | Computes fingerprints with their upper bounds in one call. This function can be replaced with many fingerprint/findLowerBound calls, but implementations can leverage it for batching and more efficient fingerprint computation. | SqliteStorageBase.fingerprintRanges | packages/common/src/Evolu/Storage.ts:258 |
getSize | readonly | (ownerId) => | number & Brand<"Int"> & Brand<"NonNegative"> | null | - | SqliteStorageBase.getSize | packages/common/src/Evolu/Storage.ts:256 |
insertTimestamp | readonly | (ownerId, timestamp) => Result<void, SqliteError> | Inserts a timestamp for an owner into the skiplist-based storage. Must be idempotent - inserting the same timestamp multiple times has no effect after the first insertion. This is crucial for sync reliability as messages may be received and processed multiple times. | SqliteStorageBase.insertTimestamp | packages/common/src/Evolu/Storage.ts:251 |
iterate | readonly | (ownerId, begin, end, callback) => void | - | SqliteStorageBase.iterate | packages/common/src/Evolu/Storage.ts:260 |
readDbChange | readonly | (ownerId, timestamp) => | EncryptedDbChange | null | Read encrypted DbChanges from storage. | Storage.readDbChange | packages/common/src/Evolu/Storage.ts:110 |
setWriteKey | readonly | (ownerId, writeKey) => boolean | Sets the OwnerWriteKey for the given Owner. | Storage.setWriteKey | packages/common/src/Evolu/Storage.ts:91 |
validateWriteKey | readonly | (ownerId, writeKey) => boolean | Validates the OwnerWriteKey for the given Owner. Returns true if the write key is valid, false otherwise. | Storage.validateWriteKey | packages/common/src/Evolu/Storage.ts:85 |
writeMessages | readonly | (ownerId, messages) => Promise<boolean> | Write encrypted CrdtMessages to storage. Must use a mutex (per ownerId on Relay) to ensure sequential processing and proper protocol logic handling during sync operations. Returns true on success, false on failure. | Storage.writeMessages | packages/common/src/Evolu/Storage.ts:104 |