Persistence
Local speed. Central durability.
Bridges embedded databases and central standalone servers. Supports write-through and write-behind modes with offline operation and automatic conflict resolution.
Persistence bridges a local WeftKit engine image and a central cluster. It enables the "site-local" architecture pattern: your application reads and writes to a fast on-prem or edge engine container, while Persistence transparently synchronizes changes to a remote cluster.
Persistence handles the hardest problems in distributed systems: offline operation, reconnect sync, and conflict resolution. Two built-in conflict resolution strategies — Last-Write-Wins (LWW) and state-based CRDTs — cover the majority of use cases. Custom resolvers can be declared in the container's config.
How It Works
Step-by-step walkthrough of the internal architecture.
Write Interception
Persistence intercepts writes to the local engine container. In write-through mode, it synchronously confirms with the remote. In write-behind mode, it queues for async sync.
Offline Queue
When the remote Standalone is unreachable, writes are queued locally. The queue survives application restarts via WAL persistence.
Reconnect Sync
On reconnect, the offline queue is replayed to the remote. Bandwidth throttling prevents overwhelming the network on reconnect.
Conflict Detection
Vector clocks and logical timestamps detect concurrent modifications. Conflicts are resolved by the configured strategy before applying.
Sync Confirmation
Sync position is tracked with monotonic cursors. Partial sync on crash is safe — sync restarts from last confirmed position.
Use Cases
Common deployment patterns and scenarios.
Mobile Local-First Apps
Run a full database on the device with transparent cloud sync. Works offline, syncs on reconnect.
IoT Edge Devices
Collect sensor data locally, sync to central analytics store when connectivity is available.
Desktop Applications
Rich local data with cloud backup and multi-device sync for collaborative desktop software.
Field Service Applications
Offline-capable apps for workers in locations with intermittent connectivity.
Configuration Reference
TOML configuration options for this component.
[persistence]
# Remote Standalone endpoint
remote_endpoint = "postgres://weftkit:secret@db.example.com:20000/mydb"
# Sync mode: "write_through" | "write_behind"
mode = "write_behind"
# Sync interval for write-behind mode
sync_interval_ms = 5000
# Conflict resolution: "lww" | "crdt" | "custom"
conflict_resolution = "lww"
# Maximum offline queue size (bytes)
max_queue_bytes = 104857600 # 100 MB