Omega setup for SQLite sync

SQLite sync replicates a device’s application SQLite database to the platform: Omega installs change-capture triggers on the tables you name, batches the changes, and ships them over MQTT. This page is the device side — enabling the module and writing its config. For the connection, TLS, and enrollment that every device needs, see Configure and Connect.

1. Build

SQLite replication is a core dependency — always compiled, nothing to enable at build time. Any build has it, including a slimmed --no-default-features SKU:

cargo build --release -p omega-agent

See Build Omega for the full feature model.

2. Enable the module

In the profile, list the module and grant its capability. The module id and the capability key are the same string, sqlite-replication:

modules:
  required:
    - sqlite-replication

security:
  capabilities:
    sqlite-replication: true

Both are required. A module without a matching capability grant has its control messages rejected; a capability the build doesn’t provide is fatal at load. The module has no dependencies on other modules.

3. Point it at the database

Add a sqlite-replication: section. The only required field is the path to your application’s SQLite file:

sqlite-replication:
  source_db_path: /var/lib/myapp/data.db
  table_strategies:
    order_events:
      strategy: rows          # relational / state tables
    sensor_readings:
      strategy: telemetry     # time-series tables
      ts_column: recorded_at

Omega installs its capture triggers on the named tables at startup and begins replicating.

Config reference

The full sqlite-replication: section:

Field	Type	Default	Meaning
`source_db_path`	string	—	Required. Path to the application SQLite database.
`source_db_path_env`	string	—	Env-var name to source the path from (overrides `source_db_path`).
`state_db_path`	string	`{data_dir}/sqlite-replication/state.db`	Where Omega keeps its replication cursors and pause state.
`state_db_path_env`	string	—	Env-var name for the state DB path.
`flush_interval`	duration	`5s`	How often the capture/flush loop runs.
`local_retention_bytes`	integer	`268435456` (256 MiB)	Cap on the local change journal.
`snapshot_on_first_run`	bool	`false`	Bootstrap a full snapshot of the tables on first run.
`table_strategies`	map	`{}`	Per-table capture config, keyed by table name (below).
`extra_sources`	list	`[]`	Additional source databases, each a full `sqlite-replication` config. One level deep — nested `extra_sources` are ignored.

`table_strategies.<table>`

Field	Type	Default	Meaning
`strategy`	string	`rows`	`rows` for relational/state tables; `telemetry` for time-series.
`ts_column`	string	—	For `telemetry`: the timestamp column used as the replication cursor.
`include_columns`	list	`[]` (all)	Restrict replication to these columns.

See Capture strategies for choosing between rows and telemetry.

Batching and large changes

Omega batches changes and publishes them on the sync topics (see Topics and connection). Two things worth knowing:

Payload size is bounded by security.max_payload_bytes, not a replication setting. A batch that would exceed the cap is spilled to a compressed (zstd) secondary object, uploaded out-of-band via a platform-granted URL, rather than being forced onto a single MQTT message.
Deduplication is handled on the platform. The device stamps each batch with the keys the platform needs to dedupe; there’s no device-side dedup knob.

A complete example

Per-device values pulled from the environment so one profile serves a fleet:

connection:
  transport: mqtt
  server_url_env: OMEGA_MQTT_BROKER_URL
  device_id_env: OMEGA_DEVICE_ID
  root_topic_env: OMEGA_ROOT_TOPIC
  cert_dir: /var/lib/omega/certs
  mqtt:
    keep_alive: 30s
    tls:
      ca_cert_path: /etc/omega/ca.crt
      client_cert_path: /var/lib/omega/certs/device.crt
      client_key_path: /var/lib/omega/certs/device.key

modules:
  required:
    - sqlite-replication

security:
  signed_control:
    enabled: true
    key_env: OMEGA_CONTROL_KEY
  capabilities:
    sqlite-replication: true

sqlite-replication:
  source_db_path_env: OMEGA_SOURCE_DB_PATH
  state_db_path: /var/lib/omega/sqlite-replication/state.db
  flush_interval: 5s
  table_strategies:
    order_events:
      strategy: rows
    sensor_readings:
      strategy: telemetry
      ts_column: recorded_at

Validate it, then run or install as a service:

omega-agent --validate --client config.yaml     # exit 0 = good
omega-agent install-service --client /etc/omega/config.yaml

First-batch schema review

The first batch for a new table lands as a queued schema review on the platform — approve it once and replication proceeds. See Schema review workflow.

SQLite sync configuration — deeper config notes.
Capture strategies — rows vs telemetry.
Topics and connection — the sync wire topics.
Provisioning checklist — end-to-end bring-up.
Configure Omega · Deploy Omega.

Omega edge runtime

Device RPC

Edge SQLite sync

Edge agent (Omega)

Operate & query

Wire protocol reference

Omega setup for SQLite sync

1. Build

2. Enable the module

3. Point it at the database

Config reference

`table_strategies.<table>`

Batching and large changes

A complete example

First-batch schema review

​1. Build

​2. Enable the module

​3. Point it at the database

​Config reference

​table_strategies.<table>

​Batching and large changes

​A complete example

​First-batch schema review

​Related

1. Build

2. Enable the module

3. Point it at the database

Config reference

`table_strategies.<table>`

Batching and large changes

A complete example

First-batch schema review

Related