9.memory.adoc

OpenLogReplicator.json - memory element

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

This section describes the memory element in the OpenLogReplicator JSON configuration. It explains each parameter, constraints, defaults and operational notes related to memory allocation and buffering.

Table 1. Memory element

Parameter	Type / constraints	Description and notes
max-mb	integer, min: 32, default: 2048	Maximum total memory (megabytes) the process may allocate for internal data structures and buffers. NOTE: Does not include memory allocated on-demand for sending large JSON messages to outputs (e.g., Kafka) or separate LOB processing buffers.
min-mb	integer, min: 16, max: max-mb, default: 32	Amount of memory (megabytes) reserved at startup and the target minimal allocation during operation. The allocator may grow above this value up to max-mb and release memory when necessary.
read-buffer-max-mb	integer, min: read-buffer-min-mb, max: max-mb, default: min(max-mb / 8, 128)	Maximum size of the read buffer used for disk I/O (megabytes). IMPORTANT: Larger read buffers can improve throughput but consume addressable memory. This buffer is resident (not swappable) and counts toward max-mb. Do not allocate more than ~25% of total memory to disk buffers.
read-buffer-min-mb	integer, min: 4, min(max-mb - unswap-min-mb - write-buffer-min-mb - 4, read-buffer-max-mb), default: 4	Minimum size reserved for read buffers (megabytes). The runtime may expand buffers up to read-buffer-max-mb when needed.
swap-mb	integer, min: 0, max: max-mb, default: floor(max-mb * 3 / 4)	Threshold (megabytes) of resident memory usage that triggers swapping of transaction data to disk. IMPORTANT: Set to 0 to disable swapping. When enabled, transactions may be written to per-transaction swap files under swap-path.
swap-path	string, max length: 256, default: ./tmp	Directory used for swap files created when swap-mb is exceeded. NOTE: Swap files are created per transaction with the pattern <swap-path>/<database>-<xid>.swap. CAUTION: Directory must be writable by the process. Only applicable when swap-mb > 0.
unswap-buffer-min-mb	integer, min: 4, max: max-mb - write-buffer-min-mb - read-buffer-min-mb - 4, default: 4 (only when swapping enabled)	Memory reserved for reading swapped transaction data back into memory during commit processing (megabytes). NOTE: Only applicable when swap-mb > 0.
write-buffer-max-mb	integer, min: write-buffer-min-mb, max: max-mb, default: min(max-mb, 2048)	Maximum size of the output/write buffer used to assemble messages for sinks (megabytes). IMPORTANT: This buffer is resident (not swappable) and counts toward max-mb. Must be large enough to hold the largest expected LOB plus ~10% overhead; otherwise large fields may cause the process to fail to allocate required memory.
write-buffer-min-mb	integer, min: 4, max: max-mb - unswap-min-mb - read-buffer-min-mb - 4, default: 4	Minimum reserved memory for the output/write buffer (megabytes). The buffer may grow up to write-buffer-max-mb.

Note

All sizes are in megabytes. Ensure the sum of all minimum buffers plus expected dynamic allocations remains below max-mb. Prefer enabling swap only when sufficient fast storage is available; swapping increases I/O and may affect latency. Do not set resident buffers (read-buffer-, write-buffer-, unswap-buffer-min-mb) so large that normal processing cannot allocate additional needed memory. When changing memory settings in production, test under representative workloads to avoid OOM or excessive swapping.

Example memory configuration (JSON)

{
  "memory": {
    "max-mb": 2048,
    "min-mb": 64,
    "read-buffer-min-mb": 8,
    "read-buffer-max-mb": 128,
    "swap-mb": 1536,
    "swap-path": "./tmp",
    "unswap-buffer-min-mb": 8,
    "write-buffer-min-mb": 16,
    "write-buffer-max-mb": 512
  }
}