1.source.adoc

OpenLogReplicator.json - source element

Author: Adam Leszczyński <aleszczynski@bersler.com>, version: 1.9.0, date: 2026-01-23

This section documents the source element of the OpenLogReplicator JSON configuration. It explains each available field, constraints, defaults and operational notes.

Table 1. Source element

Parameter	Type / constraints	Description and notes
alias	string, max length: 256, mandatory, unique	Logical identifier for this source. Referenced by target elements and recorded in checkpoint files. TIP: Use short, descriptive names.
format	element — see format, mandatory	Configuration of the output message format and serialization options.
name	string, max length: 256, mandatory	Human-readable name used to identify the database connection in logs and checkpoints. WARNING: Do not change this value while using existing checkpoint files; mismatches will prevent proper restart.
reader	element — see reader, mandatory	Configuration for reading redo logs (online, offline, batch, etc.).
arch	string, allowed: online, online-keep, path, list, default: online	Method used to obtain archived redo log file lists. online — read archive list from the database (connection opened as needed). online-keep — keep the database connection open. path — read archive filenames from a filesystem path. list — use a user-provided file list (commonly used with batch reader). NOTE: Only valid for readers that support archived redo logs.
arch-read-sleep-us	integer, min: 0, default: 10000000	Microseconds to sleep between attempts to read archived redo log lists.
arch-read-tries	integer, min: 0, max: 1000000000, default: 10	Number of retries before failing to obtain an archived redo log list.
debug	element — see debug	Group of debugging options.
filter	element — see filter	Filter rules that determine which users, schemas and tables are processed. CAUTION: Filters apply only to data rows, not to DDL. On first run the schema is loaded only for tables selected by the filter; changing the filter later may require resetting checkpoints and reloading schema.
flags	integer, min: 0, max: 524287, default: 0	Bitmask of runtime options. Common flags: 0x0001 — Only read archived logs (do not read online redo). CAUTION: May delay replication until log switches occur. 0x0002 — Schemaless mode (operate without schema). 0x0004 — Adaptive schema (valid with schemaless). 0x0008 — Disable O_DIRECT (do not use direct IO). TIP: Disabling direct IO reduces guarantees; use only when necessary. 0x0010 — Ignore recoverable errors and continue (not recommended). 0x0020 — Include DDL text in output. 0x0040 — Show invisible (hidden) columns. 0x0080 — Show guard columns. 0x0100 — Show nested columns. 0x0200 — Show unused columns. 0x0400 — Include incomplete transactions in output. 0x0800 — Include system transactions. 0x1000 — Include checkpoint records in output. 0x2000 — Do not delete old checkpoint files. 0x8000 — Emit column data as raw (hex). 0x10000 — Decode binary XMLType (experimental). 0x20000 — Emit JSON values in binary format (experimental). 0x40000 — Support UPDATEs for NOT NULL columns with occasional NULLs (experimental). NOTE: Refer to the User Manual for details on schemaless and adaptive schema modes.
redo-read-sleep-us	integer, min: 0, default: 50000	Microseconds to sleep when the online redo log is exhausted and the process waits for new transactions. TIP: Default 50,000 μs (50 ms) provides a good latency/CPU trade-off. Lower values reduce latency at the cost of higher CPU usage.
redo-verify-delay-us	integer, min: 0, default: 0	When non-zero, read online redo log data again after this delay (μs) to verify consistency. IMPORTANT: This double-read is a workaround for filesystems that may present stale caches. Prefer direct IO instead of relying on double reads.
refresh-interval-us	integer, min: 0, default: 10000000	Microseconds between attempts to refresh the list of redo log groups while reading online redo logs.

Note

Validate alias, name and referenced sub-elements before deployment. Tune redo-read-sleep-us and refresh-interval-us for desired latency versus CPU usage. Changing format, name or alias while reusing existing checkpoint files can prevent restart; prefer creating fresh checkpoints after configuration changes.

Example source configuration (JSON)

{
  "source": {
    "alias": "db_primary",
    "name": "primary_db",
    "format": { "type": "json" },
    "reader": { "type": "online" },
    "arch": "online",
    "redo-read-sleep-us": 50000,
    "flags": 0,
    "metrics": {}
  }
}