syncengine::SyncEngine Class

Detailed Description

SyncEngine is the main entry point for the sync library. Clients write to their own local SQLite database. When changes are made, the engine captures a binary changeset using the SQLite Session Extension, annotates it with a hybrid logical clock (HLC) timestamp and the client's schema version, and writes it to a shared folder. Other clients watch the folder and apply incoming changesets with automatic conflict resolution.

Recommended Usage (QSQLITE_SYNC driver)

The library ships a QSQLITE_SYNC driver plugin which works almost exactly like Qt's built-in QSQLITE driver. The difference? SQLite Session Extension support.

Once set up, use QSqlDatabase and QSqlQuery as normal and the database changes will push any local changes to the shared folder automatically.

To pull and apply changes from remote clients, users can either configure it to happen automatically via the start() method, or call the sync() method manually.

// Open with the QSQLITE_SYNC driver.
QSqlDatabase db = QSqlDatabase::addDatabase("QSQLITE_SYNC");
db.setDatabaseName("myapp.db");
db.open();

// Create the sync engine with a shared folder and client ID.
SyncEngine engine(db, "/shared/folder", "client-id");
engine.setSchemaVersion(1);
engine.start();

// Use QSqlQuery as you normally would for database operations.
// Writes are pushed to the shared folder automatically.
QSqlQuery q(db);
q.exec("CREATE TABLE IF NOT EXISTS items (id INTEGER PRIMARY KEY, name TEXT)");
q.exec("INSERT INTO items (name) VALUES ('hello')");
q.prepare("INSERT INTO items (name) VALUES (?)");
q.bindValue(0, "world");
q.exec();

// Call sync() to pull and apply changes from other clients.
engine.sync();

Transactions, QSqlTableModel, and all other Qt SQL classes work as expected.

Fallback Usage (without QSQLITE_SYNC driver)

If the driver plugin is not available (e.g., Qt source tree not installed), the engine falls back to a parallel connection and requires beginWrite() / endWrite() calls to track changes:

SyncEngine engine("/path/to/local.db", "/shared/folder", "client-id");
engine.start();
engine.beginWrite();
engine.database()->exec("INSERT INTO items (name) VALUES ('hello')");
engine.endWrite();

Pushing and Pulling

Sync has two directions – pushing local changes out and pulling remote changes in – and they work differently:

Pushing (automatic). When users write to the database via QSqlQuery, the engine's commit hook captures the changes and writes a changeset file to the shared folder immediately.

Pulling (manual or timed). Remote changesets sitting in the shared folder are NOT applied automatically in the background. Users control when they're applied by calling sync(), either manually or on a timer:

// Option 1: auto-pull on a timer.
// start() accepts an interval in milliseconds (default: 1000ms).
engine.start(5000);  // pull every 5 seconds

// Option 2: pull manually whenever you want.
engine.start(0);     // disable the timer
engine.sync();       // pull now

Users should generally prefer explicit pulling. This is because applying remote changes modifies the local database, which could affect in-progress queries or UI state. By controlling the timing, users can pull at safe points, for example before or after a UI update.

Listen for the syncCompleted signal to be notified of potential changes:

connect(&engine, &SyncEngine::syncCompleted, [&](int count) {
    if (count > 0)
        model->select();  // refresh QSqlTableModel
});

Schema Versioning

The engine embeds a schema version in each changeset filename. Clients reject changesets from a newer schema version and emit syncErrorOccurred() with VersionMismatch and an actionable upgrade message. Rejected changesets remain in the shared folder and are automatically retried after the client upgrades.

engine.setSchemaVersion(2);  // Ideally set before start()

Conflict Resolution

When two clients modify the same row, conflicts are resolved using hybrid logical clock (HLC) timestamps: the change with the higher HLC wins. Equal HLCs are broken by client ID for deterministic convergence.

In practice, this means the last client to write after syncing will win. Syncing advances a client's HLC to be at least as high as all received changesets, so any subsequent local write is guaranteed to have a higher HLC than anything previously synced. The net effect is that the most recent write from a client that is up-to-date takes priority.