How does it work?

Your application will use a modified version of the SQLite library containing the LiteSync code to access your database.

The modifications on the SQLite library are internal and the interface is the same.

The LiteSync libraries will communicate to each other, exchanging transaction data.






Replication

The first time the app is open it will connect to the other node(s) and download a fresh copy of the database.

In a centralized topology the primary node will send the database copy to the secondary nodes.

Once it is downloaded the node starts the synchronization.



Synchronization

Once the nodes have the same base db they exchange transactions that were executed when they were off-line.

After this they enter in on-line mode and once a new transaction is executed in a node it is transferred to be executed in the connected nodes.

If the node is off-line then the transaction is stored in a local log to be exchanged later.



DO I NEED TO CHANGE MY APP CODE?

There are a few steps but basically we must change the URI string in the database opening from this:

“file:/path/to/app.db”

to something like this:

“file:/path/to/app.db?node=secondary&connect=tcp://server.ip:1234”

The good news is that LiteSync uses the native SQLite3 interface. It means that we don't need to use another API.



Connection

Each node has 2 options:

bind to an address
connect to the peer address

So you can choose which side will connect to the other. This is useful when one side is behind a router or firewall.



Supported Topologies


Centralized, Star Topology


In this topology we have a node in which all the other nodes will be connected to, so it must be on-line for the synchronization to take place.

Here are some example configurations:


The primary node can bind to an address and the secondary nodes connect to it.

Primary node:

"file:/home/user/app.db?node=primary&bind=tcp://0.0.0.0:1234"

Secondary Node: (in another device)

"file:/home/user/app.db?node=secondary&connect=tcp://server:1234"


The primary node can also connect to secondary nodes.

Primary node:

"file:/home/user/app.db?node=primary&connect=tcp://address1:port1,tcp://address2:port2"

Secondary Nodes: (each on a separate device)

"file:/home/user/app.db?node=secondary&bind=tcp://0.0.0.0:1234"


We can even use a mix of these 2 options.

Primary node:

"file:/home/user/app.db?node=primary&bind=tcp://0.0.0.0:1234&connect=tcp://address1:port1"

Secondary Node 1:

"file:/home/user/app.db?node=secondary&connect=tcp://server:1234"

Secondary Node 2:

"file:/home/user/app.db?node=secondary&bind=tcp://0.0.0.0:1234"



Synchronization Status

We can check the synchronization status using this command:

PRAGMA sync_status

It returns a JSON string.



Checking if the db is ready

If the app is being open for the first time on a device it can download a new copy of the database from another node. Until it is done we cannot access the db.

We can retrieve the sync status and check the db_is_ready variable.

Check the basic app examples bellow.



How to use it in my app?

There are 3 steps:

1  Replace the SQLite library with the one containing LiteSync

2  Change the URI connection string

3  Check for the db ready status

When compiling C and C++ apps you must link your application to the LiteSync library.

For other languages you must have the proper wrapper installed.



Primary node example

The primary node can be a normal application, exactly the same app as the secondary nodes but using a different URI.

Or we can use an app dedicated to be the primary node.

A basic standalone application used solely for the purpose of keeping a centralized db node would look like this:

Select a language -->



Basic app example

A basic app that writes to the local database would look like this:

Select a language -->



CURRENT LIMITATIONS

-Avoid using functions that return different values each time they are called, like random() and date('now')
-Only WAL mode is supported
-The database must always be open with synchronization enabled. If for some reason you don't want the synchronzation to occur then open the db without informing any peer to connect to.