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.


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.


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.


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


to something like this:


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


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:


Secondary Node: (in another device)


The primary node can also connect to secondary nodes.

Primary node:


Secondary Nodes: (each on a separate device)


We can even use a mix of these 2 options.

Primary node:


Secondary Node 1:


Secondary Node 2:


Peer-to-Peer Topology

The fully-connected peer-to-peer network is made between primary nodes.

We need to inform the total number of nodes on the network manually on each node (for now)

The direction of connections must also be informed (which nodes will connect to which)

Here is an example of a network with 3 nodes:

Node 1:


Node 2:

"file:db2.db?node=primary&total_primary_nodes=3&bind=tcp:// connect=tcp://"

Node 3:

"file:db3.db?node=primary&total_primary_nodes=3&bind=tcp:// connect=tcp://,tcp://"

Mixed Topology

In this topology we have more than one primary nodes connected as peers and many secondary nodes connected to them.

The configuration for the primary nodes is the same as above, in the peer-to-peer topology.

Each secondary node will be connected to a single primary node at a given time. We can inform the address of many primary nodes so they choose one randomly. If the connection to a primary node drops, it will connect to another one.

Here is an example URI for a secondary node:


Synchronization Status

We can check the synchronization status using this command:

PRAGMA sync_status

It returns a JSON string.

Synchronization Notification

Your application can be notified when the local database is updated due to synchronization with remote nodes. The notification is done via a user-defined function.

Select a language -->

Important: The notification function is called by the worker thread. The application should NOT use the db connection inside the notification function and it must return as fast as possible! The application can transfer the notification to the main thread before returning.

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 -->


1  Avoid using functions that return different values each time they are called, like random() and date('now')

2  AUTOINCREMENT keyword is not supported

3  We must use just a single connection to each database file. Do not let many apps access the same database file. Each instance must use its own db file, and then they will be replicated and synchronized using LiteSync