Skip to content
Synchro

First synchronization

This tutorial uses one private note and the authenticated user alice. You will read the note locally, change it offline, and observe the synchronized result.

Use a disposable database and test identities. Do not run this tutorial against production data. The examples describe the Synchro 0.4.0-rc.4 interfaces. Use local-consumer artifacts until the matching release is available.

1. Prepare the server

Section titled “1. Prepare the server”

Complete server setup. That guide creates the synchro_quickstart database, registers public.notes, starts the adapter, and inserts the first note.

The first note has this identity:

id:       00000000-0000-4000-8000-000000000001
owner_id: alice

The registered membership function puts the note in user:alice. Connect assigns that scope from the authenticated identity, not from a client-supplied scope name.

2. Open the first client

Section titled “2. Open the first client”

Follow the initialization example for your platform:

Use the server URL and test token from server setup. Use a new writable SQLite database and a stable client ID. Never share one client ID between independent installations.

Complete the initial synchronization before querying notes. Creating the client or opening SQLite does not prove that the server schema and rows have arrived.

The initial query must return the note above with owner_id equal to alice. An empty result is not a successful tutorial outcome.

3. Edit offline

Section titled “3. Edit offline”

Stop synchronization with the client’s stop() method. Keep the local database open.

Use the platform’s execute method with bound parameters:

UPDATE notes SET body = ?
WHERE id = ?

Bind Edited offline and 00000000-0000-4000-8000-000000000001, in that order. Read the row again through the client. Its body must now be Edited offline, even though synchronization is stopped.

The local write and its queued mutation commit together. Do not write directly to Synchro metadata tables.

4. Synchronize and verify the server

Section titled “4. Synchronize and verify the server”

Restart synchronization with start(). Then run the platform’s syncNow() call as shown in its initialization example. Wait for that call to complete successfully. Do not replace completion with an arbitrary sleep.

In a PostgreSQL session connected to synchro_quickstart, run:

SELECT id, owner_id, body
FROM public.notes
WHERE id = '00000000-0000-4000-8000-000000000001';

The query must return alice and Edited offline. The server observation proves that the local write reached PostgreSQL. An empty local pending queue alone does not prove that result.

5. Verify another client

Section titled “5. Verify another client”

Initialize another client with a different client ID and a different local database path. Authenticate as alice and complete its first synchronization.

Read the same note. Its body must be Edited offline. This verifies that the server change reaches an independent local database.

6. Finish

Section titled “6. Finish”

Stop and close both clients. Stop the tutorial adapter using the procedure in server setup. Remove only the disposable database and local files created for this tutorial.

Continue

Section titled “Continue”