Skip to content

Replicator: Clarify --immediate vs default consistency mode #23198

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bsanchez-the-roach wants to merge 2 commits into
base: main
Choose a base branch
from
+12 −4
Open

Replicator: Clarify --immediate vs default consistency mode #23198

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
13a26b4
Replicator: Clarify --immediate vs default consistency mode for non-C…
bsanchez-the-roach Apr 20, 2026
6bbf765
fixed consistent mode for non-crdb source
bsanchez-the-roach Apr 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 12 additions & 4 deletions src/current/molt/molt-replicator.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,17 +72,25 @@ MOLT Replicator supports forward replication from PostgreSQL, MySQL, and Oracle,

### Consistency modes

MOLT Replicator supports three consistency modes for balancing throughput and transactional guarantees:
*Consistency modes* control how MOLT Replicator balances throughput and transactional guarantees.

1. *Consistent* (failback mode only, default for CockroachDB sources): Preserves per-row order and source transaction atomicity. Concurrent transactions are controlled by [`--parallelism`]({% link molt/replicator-flags.md %}#parallelism).
#### Failback mode (CockroachDB source)

1. *BestEffort* (failback mode only): Relaxes atomicity across tables that do not have foreign key constraints between them (maintains coherence within FK-connected groups). Enable with [`--bestEffortOnly`]({% link molt/replicator-flags.md %}#best-effort-only) or allow auto-entry via [`--bestEffortWindow`]({% link molt/replicator-flags.md %}#best-effort-window) set to a positive duration (such as `1s`).
When using the `start` command to replicate from CockroachDB to another database, you can configure one of the following consistency modes:

1. *Consistent* (default): Preserves per-row order and source transaction atomicity. Mutations are buffered in memory and are flushed out to the target database when [`--flushSize`]({% link molt/replicator-flags.md %}#flush-size) is reached or once [`--flushPeriod`]({% link molt/replicator-flags.md %}#flush-period) has passed since the previous flush. Concurrent transactions are controlled by [`--parallelism`]({% link molt/replicator-flags.md %}#parallelism).

1. *BestEffort*: Relaxes atomicity across tables that do not have foreign key constraints between them (maintains coherence within FK-connected groups). Mutations are buffered in memory and are flushed out to the target database when [`--flushSize`]({% link molt/replicator-flags.md %}#flush-size) is reached or once [`--flushPeriod`]({% link molt/replicator-flags.md %}#flush-period) has passed since the previous flush. Enable with [`--bestEffortOnly`]({% link molt/replicator-flags.md %}#best-effort-only) or allow auto-entry via [`--bestEffortWindow`]({% link molt/replicator-flags.md %}#best-effort-window) set to a positive duration (such as `1s`).

{{site.data.alerts.callout_info}}
For independent tables (with no foreign key constraints), BestEffort mode applies changes immediately as they arrive, without waiting for the resolved timestamp. This provides higher throughput for tables that have no relationships with other tables.
{{site.data.alerts.end}}

1. *Immediate* (default for PostgreSQL, MySQL, and Oracle sources): Applies updates as they arrive to Replicator with no buffering or waiting for resolved timestamps. For CockroachDB sources, provides highest throughput but requires no foreign keys on the target schema.
1. *Immediate*: Applies updates as they arrive to Replicator with no buffering or waiting for resolved timestamps. Enable with [`--immediate`]({% link molt/replicator-flags.md %}#immediate). Provides highest throughput but requires no foreign keys on the target schema.

#### Forward replication (PostgreSQL, MySQL, Oracle sources)

When using `pglogical`, `mylogical`, or `oraclelogminer` commands to replicate from PostgreSQL, MySQL, or Oracle sources to CockroachDB, Replicator always preserves per-row order and source transaction atomicity for any changes. This behavior cannot be configured. The consistency mode flags ([`--immediate`]({% link molt/replicator-flags.md %}#immediate), [`--bestEffortOnly`]({% link molt/replicator-flags.md %}#best-effort-only), [`--bestEffortWindow`]({% link molt/replicator-flags.md %}#best-effort-window)) do not apply to these commands and will have no effect if specified.

## Commands

Expand Down
Loading