Skip to main content

The adapters

The three adapters keep the same contract, so most apps only need the line that opens the database (see Which adapter). This page is for what is specific to each one: setup, what is stored where, and the lower-level storages.

Each adapter is a bridge to a storage package. The adapter stores CRDT changes and snapshots in that package's database, and nothing else. How to install, configure and run the database itself (native libraries, Flutter setup, platforms, file locations) is in the documentation of that package:

AdapterBuilt onRead its docs for
crdt_lf_sqlitesqlite3the native SQLite library on each platform
crdt_lf_hivehiveHive.init and the storage folder, in Dart and in Flutter
crdt_lf_driftdriftopening a database on each platform (QueryExecutor)

Install and open​

crdt_lf_sqlite stores the documents in a SQLite database opened with sqlite3. Set up sqlite3 for your platforms as its documentation explains, then:

dart pub add crdt_lf_sqlite
import 'package:crdt_lf_sqlite/crdt_lf_sqlite.dart';

// Open (or create) a database file...
final backend = CRDTSqlite.open('./my_app_data.db');

// ...or an in-memory database (useful for tests).
final memory = CRDTSqlite.memory();

// ...or a connection you already manage.
final shared = CRDTSqlite.fromDatabase(myDatabase);

backend.close();

Then backend.openDocument(id) and the rest of Persistence work the same on all three.

How data is stored​

One database file holds every document, in three tables:

CREATE TABLE changes (
document_id TEXT NOT NULL,
author TEXT NOT NULL,
hlc_l INTEGER NOT NULL,
hlc_c INTEGER NOT NULL,
bytes BLOB NOT NULL,
PRIMARY KEY (document_id, author, hlc_l, hlc_c)
);

CREATE TABLE snapshots (
document_id TEXT NOT NULL,
snapshot_id TEXT NOT NULL,
bytes BLOB NOT NULL,
PRIMARY KEY (document_id, snapshot_id)
);

CREATE TABLE peers (
document_id TEXT NOT NULL,
peer_id TEXT NOT NULL,
PRIMARY KEY (document_id)
);

A change is named by its author and its clock, not by one text id. An OperationId is a peer and a clock, and kept apart SQL can compare it, which is what a version vector asks. The primary key is then already the index that comparison wants. The clock takes two columns because l is 48 bits and c is 16: together they stay inside the 53 bits an integer keeps exactly in JavaScript.

  • Transactions. storageForDocument hands back a CRDTSqliteDocumentStorage, which backs transaction() with a real SQLite transaction: a prune drops the covered changes and rewrites the survivors, and either all of it lands or none of it does. It is built on savepoints, so a batch that opens a transaction of its own nests inside instead of failing.
  • Closing. close() on a document storage does nothing on purpose: one database file holds every document, so the connection is CRDTSqlite.close()'s to release.
  • Schema version. The database carries its schema version in PRAGMA user_version, and this build writes version 2. A database written by 0.2.0 is version 1: it has no peers table and names a change with a single change_id column. The first open rebuilds it inside one savepoint, so half a rebuilt table is never left behind. The split reads the old column and not the stored bytes, so a change whose blob this build cannot decode migrates all the same.

The lower-level storages​

backend.openDocument uses three storages per document. You can use them directly, for example to read part of the log or to build your own opening.

Every method answers on the spot: getChanges() gives a List<Change>, saveChange() gives void.

final changes = backend.changeStorageForDocument('doc-123');
changes.saveChanges([change1, change2]);
final all = changes.getChanges();
final missing = changes.getChanges(newerThan: theirVersion);
print('Total changes: ${changes.count}');

final snapshots = backend.snapshotStorageForDocument('doc-123');
snapshots.saveSnapshot(snapshot);
final latest = snapshots.getSnapshots();

final peers = backend.peerIdStorageForDocument('doc-123');
final document = CRDTDocument(
documentId: 'doc-123',
peerId: peers.loadOrCreate() as PeerId, // synchronous here
);

getChanges takes the two version-vector bounds newerThan and upTo: see Reading part of the log. Read the identity before building the document, because the id has to exist first (see Peer identity).

Examples​