Edge SQLite sync (also called edge replication) mirrors data from a SQLite database on your device into Golain cloud storage. Changes are captured on the device, sent over MQTT, governed on the server, and materialized into queryable mirror tables or telemetry series. This is not a file-level SQLite backup. The cloud stores governed, typed projections — not a copy of yourDocumentation Index
Fetch the complete documentation index at: https://docs.ilyama.golain.io/llms.txt
Use this file to discover all available pages before exploring further.
.db file.
Who this is for
| Role | Start here |
|---|---|
| Fleet operator / platform admin | How it works → Schema review workflow |
| Edge engineer shipping Omega | Omega setup → Configuration |
| Integrator building a custom agent | Wire protocol reference |
| SRE / on-call | Troubleshooting |
At a glance
Core concepts
Lineage
One sync relationship per device + SQLite table. Tracks active/paused status and materialization health.
Staging
Rows held in cloud storage while schema is under review or lineage is paused — not lost.
Schema review
Human approval when a table’s schema is new or changed. You decide which columns mirror to the cloud.
Materialization
Approved rows land in
edge_mirror_* tables or telemetry — queryable from the platform.Components
| Piece | Repository | Role |
|---|---|---|
Omega sqlite-replication module | golain-io/omega | Triggers, journal, MQTT publish, pause/resume on device |
| MQTT broker | golain-io/ilyama | mTLS auth, topic ACL, ingress to worker queue |
| Integration worker | ilyama | Ingest, classify schema, stage, review RPC, replay, mirror DDL |
| HTTP API + platform-tui | ilyama | Operator governance and inspection |
ilyama-edge (omega/clients/ilyama-edge.yaml).
Typical first-time flow
- Register device in console or
platform-tui— note device name (used as MQTT client ID / topic segment). - Provision mTLS certs for the device (cert worker or JITR — see provisioning checklist).
- Configure Omega with
OMEGA_SOURCE_DB_PATH, broker URL,OMEGA_ROOT_TOPIC, TLS paths. - Start Omega — module installs triggers on user tables; first batches arrive in cloud.
- Approve schema — default policy queues review on first sight of a table; claim + approve in Edge Sync.
- Query data — mirror rows via API/TUI or QueryScript after materialization.
With default governance policy, the first batch from a new table triggers a schema review and the lineage enters paused until you approve. The device can keep sending; the cloud stages rows server-side during review.
Documentation map
Concepts
- How it works — end-to-end pipeline
- Lineages and staging
- Schema governance
- Registry coalescing — project/fleet-wide schema sharing
- Backpressure — pause/resume when backlog grows
Edge agent
Operations
- Schema review workflow — step-by-step operator guide
- platform-tui Edge Sync
- HTTP API
- Querying synced data
- Troubleshooting
Wire protocol (integrators)
Normative spec in source: ilyama edge-client-guide.Current limitations
Document these when planning production rollouts:| Area | Limitation |
|---|---|
| Omega telemetry batches | sync/telemetry/batch flush is not fully implemented — use strategy: rows for time-series-shaped tables |
| Bootstrap snapshot | snapshot_on_first_run flag exists but is not implemented — only mutations after Omega starts replicate |
| Secondary upload flow | Presigned URL bootstrap/spill path specified but not implemented in Omega |
| platform-tui approve shortcut | Dev TUI approve mirrors a single column — use HTTP API for full column_actions in production |
| Authz on mirror reads | Product-level authorized reads for mirror tables still evolving |