Sync Modes

ReflexDB maintains an in-memory snapshot of your database. Two sync strategies keep it current: CDC (change data capture) and poll (periodic full reload). CDC is recommended for production; poll works when CDC prerequisites aren’t met.

CDC mode

CDC streams change events from the source database in real time. Only tables that actually changed are reloaded — the rest stay untouched in memory.

Each database backend has its own CDC mechanism:

Sync mode	Backend	Mechanism	Source prerequisite
binlog	MySQL / MariaDB	Binary log replication	REPLICATION CLIENT + REPLICATION SLAVE grants
logical	PostgreSQL	Logical replication (pgoutput)	wal_level = logical, a publication, pg_read_all_data grant
cdc	SQL Server	CDC table polling	CDC enabled on the database (sys.sp_cdc_enable_db)

When you provision an instance, ReflexDB automatically selects CDC if the source supports it. The dashboard shows which mode is active on the instance card.

Batch window

In CDC mode, the batch window (sync.interval in YAML, “Batch window” on the dashboard) controls how long the engine accumulates changed table names before flushing. A burst of writes to the same table within one window triggers a single reload, not one per change.

Value	Effect
1–5s	Low latency, more frequent reloads. Recommended for production CDC.
30s (default)	Good for light write traffic.
Higher	Fewer reloads under heavy writes, but data lags behind by up to this value.

Note

The batch window only affects how often changed tables are reloaded — it does not affect tables with no changes. Idle tables cost zero I/O in CDC mode.

Reconnect behaviour

When the CDC stream disconnects (network issue, source database restart, connection timeout), the engine reconnects automatically using exponential backoff. The stream is always reopened first, so from that moment on no new change can be missed — events buffer while any follow-up reload runs.

Two reconnect modes control what happens after the stream is reopened:

Mode	YAML key	Behaviour
Full (default)	cdc_reconnect_mode: full	After reconnecting, reload all tables. Safe: guarantees no missed changes, including those committed while disconnected.
Resume	cdc_reconnect_mode: resume	Skip the reload. Changes the engine had already observed before the disconnect are kept and flushed. Changes committed during the disconnect depend on the backend: SQL Server recovers them (change-table retention lets the poller resume from the pre-disconnect LSN); MySQL and PostgreSQL accept the gap until the next safety net tick or the affected table’s next change.

Full is the safe default — use it unless reconnect traffic is a concern on large databases. Resume reduces reconnect traffic to near zero but accepts a data gap. Combine it with the freshness safety net (below) to bound the maximum staleness.

Restarts and deploys have no gap: the replication position is captured before the initial data load (on PostgreSQL the replication stream itself opens before the load and buffers through it), so changes committed while the initial load runs are replayed or streamed, not lost. On PostgreSQL the position file is ignored — temporary replication slots cannot replay a saved LSN, so resume there only skips the post-reconnect reload.

Caution

resume mode is an advanced setting available through YAML config only. It intentionally trades freshness for lower reconnect cost. The dashboard always defaults to full.

Freshness safety net

The safety net fires a full reload if no snapshot swap occurs within a configurable interval. It guards against silent CDC failures — for example, a misconfigured publication or a stuck WAL sender.

Setting	Dashboard	YAML
Enable	“Freshness guarantee” toggle on the instance card (CDC only)	sync.safety_net: 300
Disable	Uncheck the toggle	sync.safety_net: 0
Presets	1 min, 5 min, 15 min, 30 min	Any value 0–3600 seconds

The timer resets on every successful swap — from a CDC batch, a reconnect reload, or a previous safety net tick. Active databases with regular writes will never trigger it.

Recommended: 300 seconds (5 minutes) for production CDC instances. This means data is never more than 5 minutes stale, even if CDC silently stops delivering events.

CDC YAML reference

All CDC settings live under the sync: section of reflexdb.yaml:

version: 1
sync:
  mode: binlog                    # binlog | logical | cdc | poll
  interval: 5                    # batch window in seconds (CDC mode)
  safety_net: 300                # freshness safety net in seconds (0 = disabled)
  cdc_reconnect_mode: full       # full | resume
  cdc_reconnect_policy: backoff  # backoff | shutdown
  cdc_retry_base_ms: 1000        # first retry delay (doubles each attempt)
  cdc_max_retries: 5             # attempts per phase before policy kicks in
  binlog_server_id: 1001         # MySQL only — unique replica ID
  binlog_pos_file: ""            # persist binlog position across restarts

Tip

The dashboard exposes batch window and safety net. The reconnect mode, policy, and retry tuning are YAML-only — most users never need to change them.

---

Poll mode

In poll mode, the engine performs a full SELECT * of every tracked table on a fixed timer and swaps the entire snapshot atomically. No CDC prerequisites are required.

The sync interval (sync.interval in YAML, “Sync interval” on the dashboard) controls how often the full reload runs:

Plan	Minimum interval
Free	300s (5 min)
Pro	60s
Teams	30s
Business	15s
Enterprise	5s

Caution

Poll mode reads the entire dataset each cycle. For large databases, this generates significant NAT Gateway traffic that counts toward your plan’s data transfer budget. The dashboard shows a transfer projection when configuring poll intervals. Use CDC mode when possible.

---

Choosing a mode

Factor	CDC	Poll
Latency	Milliseconds to seconds (batch window)	Sync interval (seconds to minutes)
Source DB load	Reads only changed tables	Full read every cycle
Network cost	Low — proportional to write rate	High — proportional to database size × frequency
Prerequisites	Replication grants / WAL config	SELECT only
Failure mode	Reconnects automatically; safety net catches silent failures	Simple retry on next tick

Recommendation: Use CDC with a 5-second batch window and a 5-minute safety net for production. Fall back to poll only when CDC prerequisites can’t be met.