docs/Developer Guide/Developer Guide/Concepts/Synchronisation.md
Trilium implements a bidirectional synchronization system that allows users to sync their note databases across multiple devices (desktop clients and server instances). The sync protocol is designed to handle:
graph TB
Desktop1[Desktop 1
Client]
Desktop2[Desktop 2
Client]
subgraph SyncServer["Sync Server"]
SyncService[Sync Service
- Entity Change Management
- Conflict Resolution
- Version Tracking]
SyncDB[(Database
entity_changes)]
end
Desktop1 <-->|WebSocket/HTTP| SyncService
Desktop2 <-->|WebSocket/HTTP| SyncService
SyncService --> SyncDB
Every modification to any entity (note, branch, attribute, etc.) creates an entity change record:
entity_changes (
id, -- Auto-increment ID
entityName, -- 'notes', 'branches', 'attributes', etc.
entityId, -- ID of the changed entity
hash, -- Content hash for integrity
isErased, -- If entity was erased (deleted permanently)
changeId, -- Unique change identifier
componentId, -- Unique component/widget identifier
instanceId, -- Process instance identifier
isSynced, -- Whether synced to server
utcDateChanged -- When change occurred
)
Key Properties:
Each Trilium installation tracks:
When an entity is modified:
// apps/server/src/services/entity_changes.ts
function addEntityChange(entityName, entityId, entity) {
const hash = calculateHash(entity)
const changeId = generateUUID()
sql.insert('entity_changes', {
entityName,
entityId,
hash,
changeId,
componentId: config.componentId,
instanceId: config.instanceId,
isSynced: 0,
utcDateChanged: now()
})
}
Entity modification triggers:
Step 1: Client Initiates Sync
// Client sends current sync version
POST /api/sync/check
{
"sourceId": "client-component-id",
"maxChangeId": 12345
}
Step 2: Server Responds with Status
// Server checks for changes
Response:
{
"entityChanges": 567, // Changes on server
"maxChangeId": 12890, // Server's max change ID
"outstandingPushCount": 23 // Client changes not yet synced
}
Step 3: Decision
entityChanges > 0: Pull changes from serveroutstandingPushCount > 0: Push changes to serverClient Requests Changes:
POST /api/sync/pull
{
"sourceId": "client-component-id",
"lastSyncedChangeId": 12345
}
Server Responds:
Response:
{
"notes": [
{ noteId: "abc", title: "New Note", ... }
],
"branches": [...],
"attributes": [...],
"revisions": [...],
"attachments": [...],
"entityChanges": [
{ entityName: "notes", entityId: "abc", changeId: "...", ... }
],
"maxChangeId": 12890
}
Client Processing:
Client Sends Changes:
POST /api/sync/push
{
"sourceId": "client-component-id",
"entities": [
{
"entity": {
"noteId": "xyz",
"title": "Modified Note",
...
},
"entityChange": {
"changeId": "change-uuid",
"entityName": "notes",
...
}
}
]
}
Server Processing:
Conflict Detection:
// Check if entity was modified on server since client's last sync
const serverEntity = becca.getNote(noteId)
const serverLastModified = serverEntity.utcDateModified
if (serverLastModified > clientSyncVersion) {
// CONFLICT!
resolveConflict(serverEntity, clientEntity)
}
1. Content Conflict
utcDateModified2. Structure Conflict
3. Attribute Conflict
Last-Write-Wins:
if (clientEntity.utcDateModified > serverEntity.utcDateModified) {
// Client wins, apply client changes
applyClientChange(clientEntity)
} else {
// Server wins, reject client change
// Client will pull server version on next sync
}
Tombstone Records:
entity_changesisErased = 1 for permanent deletionsChallenge: Encrypted content can't be synced without password
Solution:
Each entity can be in:
// apps/client/src/widgets/sync_status.ts
class SyncStatusWidget {
showSyncStatus() {
if (isConnected && allSynced) {
showIcon('synced')
} else if (isSyncing) {
showIcon('syncing-spinner')
} else {
showIcon('not-synced')
}
}
}
Only entities changed since last sync are transferred:
SELECT * FROM entity_changes
WHERE id > :lastSyncedChangeId
ORDER BY id ASC
LIMIT 1000
Changes sent in batches to reduce round trips:
const BATCH_SIZE = 1000
const changes = getUnsyncedChanges(BATCH_SIZE)
await syncBatch(changes)
// Only sync if hash differs
const localHash = calculateHash(localEntity)
const serverHash = getServerHash(entityId)
if (localHash !== serverHash) {
syncEntity(localEntity)
}
Large payloads compressed before transmission:
// Server sends compressed response
res.setHeader('Content-Encoding', 'gzip')
res.send(gzip(syncData))
Reported to the user and the sync will be retried after the interval passes.
Hash Verification:
// Verify entity hash matches
const calculatedHash = calculateHash(entity)
const receivedHash = entityChange.hash
if (calculatedHash !== receivedHash) {
throw new Error('Hash mismatch - data corruption detected')
}
Consistency Checks:
Required Options:
{
"syncServerHost": "https://sync.example.com",
"syncServerTimeout": 60000,
"syncProxy": "" // Optional HTTP proxy
}
Authentication:
Located at: apps/server/src/routes/api/sync.ts
Real-time sync via WebSocket:
// Server broadcasts change to all connected clients
ws.broadcast('frontend-update', {
lastSyncedPush,
entityChanges
})
// Client receives and processed the information.
Desktop:
Server:
User can trigger:
Sync stuck:
-- Reset sync state
UPDATE entity_changes SET isSynced = 0;
DELETE FROM options WHERE name LIKE 'sync%';
Hash mismatch:
Conflict loop:
Typical Sync Performance:
Factors: