SQLite replication configuration

Configuration lives under the top-level sqlite-replication: key in client YAML, plus MQTT connection: settings.

Connection block

Required for sync — see topics and connection.

Field	Notes
`transport`	Must be `mqtt` for production
`server_url_env`	Broker URL (`ssl://…:8883` or `quic://…`)
`device_id_env`	Device name — not UUID
`root_topic_env`	Prefix for all sync topics
`mqtt.clean_session`	`false` — required for downlink buffer
`mqtt.tls.*_env`	mTLS cert paths

Optional JITR block under connection.jitr — see JITR enrollment.

sqlite-replication fields

Field	Default	Description
`source_db_path`	—	Inline path (dev); use `_env` in prod
`source_db_path_env`	—	e.g. `OMEGA_SOURCE_DB_PATH`
`state_db_path`	`{dataDir}/sqlite-replication/state.db`	Cursors, pause, buffer metadata
`state_db_path_env`	—	e.g. `OMEGA_STATE_DB_PATH` — set in production
`flush_interval`	`5s`	Batch flush tick
`local_retention_bytes`	256 MiB	Documented; not fully enforced yet
`table_strategies`	all tables → `rows`	Per-table override — set `telemetry` explicitly for time-series tables
`snapshot_on_first_run`	`false`	When `true`, Omega seeds a one-time initial snapshot into its local journal for row and telemetry tables before switching to incremental replication

table_strategies example

sqlite-replication:
  source_db_path_env: OMEGA_SOURCE_DB_PATH
  flush_interval: 5s
  table_strategies:
    order_events:
      strategy: rows
    device_state:
      strategy: rows
    sensor_timeseries:
      strategy: telemetry
      ts_column: ts
    sqlite_internal:
      strategy: ignore

Strategy values

Strategy	Behavior
`rows`	Trigger journal → `sync/rows/batch`
`telemetry`	Cursor batches → `sync/telemetry/batch`
`ignore`	Do not replicate

Security capabilities

Enable module in security.capabilities:

security:
  capabilities:
    sqlite-replication: true

Signed control should stay enabled in production:

security:
  signed_control:
    enabled: true

Tables requirements

User tables must have explicit PRIMARY KEY (rowid-only tables are out of scope).
System tables (sqlite_*) and Omega internals (__omega_*) are excluded automatically.
After DDL migrations, restart Omega to reinstall triggers.

Persistent state (state.db)

Omega stores per table:

State	Purpose
`last_published_commit_seq`	Journal cursor
`next_batch_seq` + telemetry cursor	Monotonic telemetry sequencing and resume point
`journal_epoch`	UUIDv7 — changes on journal reinit
`schema_hash` cache	Drift detection
Pause `server_watermark`	Resume after downlink
Backpressure buffer	Rows held while paused

Loss of state.db without backup can cause duplicate publishes (server dedupes) or cursor confusion — treat as part of device backup strategy.

Validation

export OMEGA_AUTH_TOKEN=test
make validate-client CLIENT=my-device
make codegen CLIENT=my-device   # validate only, no build

Module discovery

Omega auto-enrolls all non-system tables when table_strategies omits a table, and the default strategy is rows. Narrow with explicit ignore rules for scratch tables and set telemetry explicitly where needed.

Omega edge runtime

Device RPC

Edge SQLite sync

Edge agent (Omega)

Operate & query

Wire protocol reference

SQLite replication configuration

Connection block

sqlite-replication fields

table_strategies example

Strategy values

Security capabilities

Tables requirements

Persistent state (state.db)

Validation

Module discovery

​Connection block

​sqlite-replication fields

​table_strategies example

​Strategy values

​Security capabilities

​Tables requirements

​Persistent state (state.db)

​Validation

​Module discovery

​Related

Connection block

sqlite-replication fields

table_strategies example

Strategy values

Security capabilities

Tables requirements

Persistent state (state.db)

Validation

Module discovery

Related