Getting Started
For more information no how
vlcn
is able to merge databases that have had concurrent writes or been offline, see docs/background-concepts.
vlcn
aims to simplify device sync & collaborative applications by
- Pushing the complexity of eventual consistency and state merging to the database
- Exposing a declarative way choose what CRDTs to use on what tables
Most of the heavy lifting is done through the cr-sqlite
extension. cr-sqlite
is a run time loadable extension that augments SQLite
with the ability to merge databases that have had concurrent modifications or been offline for an indefinite period.
Configuring SQLite
There are two ways to use vlcn
& cr-sqlite
with SQLite
:
- Use an existing build of
SQLite
and load the required extensions at runtime - Use a bundled and pre-packaged build of
SQLite
Existing Build
vlcn
provides CR-SQLite
as a run time loadable extension to augment SQLite
. When using your existing build of SQLite
, you'll need to load the CR-SQLite
extension on each connection made to your database. You'll also need to unload it when disconnecting.
To obtain a copy of the extension:
rustup toolchain install nightly # make sure you have the rust nightly toolchain
git clone --recurse-submodules git@github.com:vlcn-io/cr-sqlite.git
cd cr-sqlite/core
make loadable
This will create a shared library at dist/crsqlite.[lib extension]
[lib extension]:
- Linux: .so
- Darwin / OS X: .dylib
- Windows: .dll
You can then copy that library to where you need it and load it into sqlite via the load_extension
command.
SELECT load_extension('crsqlite');
Be sure to unload the extension before terminating you database connection.
SELECT crsql_finalize();
Bundle
For browser environments, bundled sqlite + cr-sqlite builds are provided
For node you can use
Syncing Data
See docs/guide-sync for a step by step guide on how to create conflict free replicated relations and sync between databases.