From 13a26b433c240e8ec4c1ba32259e75e159e796cb Mon Sep 17 00:00:00 2001 From: Brandon Sanchez Date: Mon, 20 Apr 2026 13:08:00 -0400 Subject: [PATCH 1/2] Replicator: Clarify --immediate vs default consistency mode for non-CRDB sources --- src/current/molt/molt-replicator.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/src/current/molt/molt-replicator.md b/src/current/molt/molt-replicator.md index 319ed1c2bcb..d122b3b6d45 100644 --- a/src/current/molt/molt-replicator.md +++ b/src/current/molt/molt-replicator.md @@ -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). +#### Forward replication (PostgreSQL, MySQL, Oracle sources) -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 `pglogical`, `mylogical`, or `oraclelogminer` commands to replicate from PostgreSQL, MySQL, or Oracle sources to CockroachDB, changes are always applied immediately as they arrive to Replicator. 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. + +#### Failback mode (CockroachDB source) + +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. 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). 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. ## Commands From 6bbf765e98318bba26544e09b7c33651a29f9927 Mon Sep 17 00:00:00 2001 From: Brandon Sanchez Date: Mon, 20 Apr 2026 15:04:38 -0400 Subject: [PATCH 2/2] fixed consistent mode for non-crdb source --- src/current/molt/molt-replicator.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/current/molt/molt-replicator.md b/src/current/molt/molt-replicator.md index d122b3b6d45..0729c224453 100644 --- a/src/current/molt/molt-replicator.md +++ b/src/current/molt/molt-replicator.md @@ -74,17 +74,13 @@ MOLT Replicator supports forward replication from PostgreSQL, MySQL, and Oracle, *Consistency modes* control how MOLT Replicator balances throughput and transactional guarantees. -#### Forward replication (PostgreSQL, MySQL, Oracle sources) - -When using `pglogical`, `mylogical`, or `oraclelogminer` commands to replicate from PostgreSQL, MySQL, or Oracle sources to CockroachDB, changes are always applied immediately as they arrive to Replicator. 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. - #### Failback mode (CockroachDB source) 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. Concurrent transactions are controlled by [`--parallelism`]({% link molt/replicator-flags.md %}#parallelism). +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). 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`). +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. @@ -92,6 +88,10 @@ When using the `start` command to replicate from CockroachDB to another database 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 MOLT Replicator provides the following commands: