'Hello, World!' Sync Overview
Once you've set up your environment, try on Ditto and perform your first peer‑to‑peer sync.
Intended to get you oriented, this article provides a streamlined process for integrating sync functionality within your app.
If you prefer building and exploring through a task app, chat app, and so on, see Example Projects Overview.
Before you can begin syncing data offline, set up authentication and then start the sync process:
From the top-most scope of your app's codebase, add the following to set up authentication and start syncing offline.
Replace YOUR_APP_ID and YOUR_PLAYGROUND_TOKEN with your access credentials available from the portal. (See Step 1: Get Sync Credentials)
Insert a document in your local Ditto store by calling the Execute API method on the store namespace with a local INSERT INTO query, specifying the document to insert.
For example, inserting a new document with a single field "color" set to "blue":
Establish a local listener, known as a store observer, for realtime monitoring and response to updates in your local Ditto store.
For example, you can set up a store observer to asynchronously display profile updates to end users when they modify their profiles.
To set up a store observer:
Call the Register Observer API method on the store namespace.
Include a local SELECT query specifying the document collection you want to watch and define a callback function to handle changes.
For example, watching documents from the cars collection in the Ditto store:
Register a remote listener, known as a sync subscription, by calling the Register Subscription API method on the sync namespace.
For example, creating a subscription to sync updates made to documents in the cars collection with color set to blue:
In Ditto, there is a clear distinction between traditional CREATE, READ, UPDATE, and DELETE (CRUD) database operations and data sync:
- To perform CRUD, you execute local data operations against store namespace.
- To perform sync, you execute remote data operations against the sync namespace.
To complete your understanding, the following graphic illustrates how sync subscriptions and store observers work together in practice:
Before you can sync offline, you must integrate sync functionality in your codebase. (See Integrating Sync Functionality)
Once integrated, you initiate a sync subscription request from your local Ditto store to remote peers.
The associated query specifying the data you want to watch then propagates to each end-user device connected within the mesh network:
When the data you've subscribed to changes on a remote peer — whether through insertions, updates, or deletions — the remote peer automatically syncs these delta changes to your local Ditto store over the mesh network:
Combining store observers with your sync subscriptions ensures that you receive updates from remote stores, enabling you to quickly respond in your app:
For more information, see any of the following: