MOLT Replicator Commands and Flags - CockroachDB

This page lists the MOLT Replicator commands and the flags that you can use to configure a MOLT Replicator command execution.

Commands

MOLT Replicator provides the following commands:

Command	Description
`pglogical`	Replicate from PostgreSQL source to CockroachDB target using logical replication.
`mylogical`	Replicate from MySQL source to CockroachDB target using GTID-based replication.
`oraclelogminer`	Replicate from Oracle source to CockroachDB target using Oracle LogMiner.
`start`	Replicate from CockroachDB source to PostgreSQL, MySQL, or Oracle target (failback mode). Requires a CockroachDB changefeed with rangefeeds enabled.
`make-jwt`	Generate JWT tokens for authorizing changefeed connections in failback scenarios. Supports signing tokens with RSA or EC keys, or generating claims for external JWT providers. For details, refer to JWT authentication.
`version`	Display version information and Go module dependencies with checksums. For details, refer to Supply chain security.

For command-specific flags and examples, refer to MOLT Replicator’s How it works and Common uses documentation.

Flags

This page lists all available flags for the MOLT Replicator commands: start, pglogical, mylogical, oraclelogminer, and make-jwt.

Flag	Commands	Type	Description
`-a`, `--allow`	`make-jwt`	`STRING`	One or more `database.schema` identifiers. Can be repeated for multiple schemas.
`--allowUnsupportedOracleVersion`	`oraclelogminer`	`BOOL`	Use at your own risk. Starts replication to CockroachDB from an Oracle major version outside of the supported list instead of failing at startup. Unsupported versions are not supported by Cockroach Labs and may cause silent data corruption or permanent data loss in the worst case. Only use this flag if you fully accept the risk and can validate data integrity yourself. Default: `false`
`--applyTimeout`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`DURATION`	The maximum amount of time to wait for an update to be applied. Default: `30s`
`--assumeIdempotent`	`start`	`BOOL`	Disable the extra staging table queries that debounce non-idempotent redelivery in changefeeds.
`--backfillFromSCN`	`oraclelogminer`	`INT`	The SCN of the earliest active transaction at the time of the initial snapshot. Ensures no transactions are skipped when starting replication from Oracle.
`--bestEffortOnly`	`start`	`BOOL`	Eventually-consistent mode; useful for high-throughput, skew-tolerant schemas with foreign keys.
`--bestEffortWindow`	`start`	`DURATION`	Use an eventually-consistent mode for initial backfill or when replication is behind; `0` to disable. Default: `1h0m0s`
`--bindAddr`	`start`	`STRING`	The network address to bind to. Default: `":26258"`
`--claim`	`make-jwt`	`BOOL`	If `true`, print a minimal JWT claim instead of signing.
`--collapseMutations`	`start`, `pglogical`, `mylogical`	`BOOL`	Combine multiple mutations on the same primary key within each batch into a single mutation. Default: `true`
`--defaultGTIDSet`	`mylogical`	`STRING`	Required the first time `replicator` is run. The default GTID set, in the format `source_uuid:min(interval_start)-max(interval_end)`, which provides a replication marker for streaming changes.
`--dataDir`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`STRING`	Base directory for replicator data (for example, metrics snapshots). Default: `"replicator-data"`
`--disableAuthentication`	`start`	`BOOL`	Disable authentication of incoming Replicator requests; not recommended for production.
`--disableFKAwareScheduling`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`BOOL`	Disable Replicator’s default foreign-key-aware scheduling, which serializes target transactions that touch foreign-key-related rows so that a parent and its child rows commit in order, preventing potential transient foreign-key violation errors. Default: `false`
`--disableOracleSequenceSync`	`start`	`BOOL`	Disable automatic advancement of Oracle sequences and identity columns during failback. By default, Replicator advances each affected sequence past the highest replicated primary key value so that inserts on Oracle after cutover do not fail with `ORA-00001` (unique constraint violated). If set to `true`, you must manually advance the affected sequences past the replicated values before cutover. Default: `false`
`--discard`	`start`	`BOOL`	Dangerous: Discard all incoming HTTP requests; useful for changefeed throughput testing. Not intended for production.
`--discardDelay`	`start`	`DURATION`	Adds additional delay in discard mode; useful for gauging the impact of changefeed round-trip time (RTT).
`--dlqTableName`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`IDENT`	The name of a table in the target schema for storing dead-letter entries. Default: `replicator_dlq`
`--enableCheckpointStream`	`start`	`BOOL`	Enable checkpoint streaming (use an internal changefeed from the staging table for real-time updates), rather than checkpoint polling (query the staging table for periodic updates), for failback replication. Default: `false` (use checkpoint polling)
`--enableParallelApplies`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`BOOL`	Enable parallel application of independent table groups during replication. By default, applies are synchronous. When enabled, this increases throughput at the cost of higher target pool usage and memory usage. Default: `false`
`--fetchMetadata`	`mylogical`	`BOOL`	Fetch column metadata explicitly, for older versions of MySQL that do not support `binlog_row_metadata`.
`--flushPeriod`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`DURATION`	Flush queued mutations after this duration. Default: `1s`
`--flushSize`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`INT`	Ideal batch size to determine when to flush mutations. Default: `1000`
`--gracePeriod`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`DURATION`	Allow background processes to exit. Default: `30s`
`--healthCheckTimeout`	`start`	`DURATION`	The timeout for the health check endpoint. Default: `5s`
`--httpResponseTimeout`	`start`	`DURATION`	The maximum amount of time to allow an HTTP handler to execute. Default: `2m0s`
`--ignoreDeletionsForTable`	`pglogical`	`STRING`	Drop `DELETE` mutations for the named tables before buffering, to avoid memory pressure from large batch deletions already handled by target-side TTLs.
`--immediate`	`start`	`BOOL`	Bypass staging tables and write directly to target; recommended only for KV-style workloads with no foreign keys.
`--includeSourceDatabases`	`mylogical`	`STRING`	Replicate only the named MySQL source databases; all other databases on the server are ignored. Without this flag, Replicator reads every database on the server and maps every table into the target by name, so two databases that each contain a table with the same name cause replication to fail (`unexpected number of columns`). Comma-separate multiple names or repeat the flag; names are case-sensitive. Startup fails if a listed database does not exist. Do not list two databases that share a table name.
`-k`, `--key`	`make-jwt`	`STRING`	The path to a PEM-encoded private key to sign the token with.
`--limitLookahead`	`start`	`INT`	Limit number of checkpoints to be considered when computing the resolving range; may cause replication to stall completely if older mutations cannot be applied.
`--logDestination`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`STRING`	Write logs to a file. If not specified, write logs to `stdout`.
`--logFormat`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`STRING`	Choose log output format: `"fluent"`, `"text"`. Default: `"text"`
`--maxRetries`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`INT`	Maximum number of times to retry a failed mutation on the target (for example, due to contention or a temporary unique constraint violation) before treating it as a hard failure. Default: `10`
`--metricsAddr`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`STRING`	A `:port` or `host:port` on which to serve metrics and diagnostics. The metrics endpoint is `http://{host}:{port}/_/varz`.
`--metricsSnapshotCompression`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`STRING`	Compression for snapshot files: `"gzip"` or `"none"`. Default: `"gzip"`
`--metricsSnapshotPeriod`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`DURATION`	How often to periodically store a metrics snaphot to files (for example, `15s`, `1m`). Set to `0` to disable. Default: `0`
`--metricsSnapshotRetentionSize`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`STRING`	Delete oldest snapshots when the total size of the `metrics-snapshots` directory in the `--dataDir` exceeds this (for example, `100MB`, `1GiB`). Either this flag or `--metricsSnapshotRetentionTime` (or both) must be enabled. Default: `""`
`--metricsSnapshotRetentionTime`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`DURATION`	Delete snapshots older than this duration (for example, `24h`, `168h`). `0` to disable. Either this flag or `--metricsSnapshotRetentionSize` (or both) must be enabled. Default: `168h`
`--multiSchemaFanout`	`start`	`BOOL`	Replicate a single CockroachDB changefeed into the matching schemas of one target database: each table keeps its schema, and the database is swapped (for example, `sourcedb.sales.orders` maps to `targetdb.sales.orders`). The webhook sink URL must end in just the target database name, with no schema, and the changefeed must be created `WITH full_table_name` so that each row carries its source schema, which selects the target schema. Supported for CockroachDB and PostgreSQL targets only. Default: `false`
`--ndjsonBufferSize`	`start`	`INT`	The maximum amount of data to buffer while reading a single line of `ndjson` input; increase when source cluster has large blob values. Default: `65536`
`--oracle-application-users`	`oraclelogminer`	`STRING`	List of Oracle usernames responsible for DML transactions in the PDB schema. Enables replication from the latest-possible starting point. Usernames are case-sensitive and must match the internal Oracle usernames (e.g., `PDB_USER`).
`-o`, `--out`	`make-jwt`	`STRING`	A file to write the token to.
`--parallelism`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`INT`	The number of concurrent database transactions to use. Default: `16`
`--publicationName`	`pglogical`	`STRING`	The publication within the source database to replicate.
`--quiescentPeriod`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`DURATION`	How often to retry deferred mutations. Default: `10s`
`--replicationProcessID`	`mylogical`	`UINT32`	The replication process ID to report to the source database. Default: `10`
`--retireOffset`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`DURATION`	How long to delay removal of applied mutations. Default: `24h0m0s`
`--retryInitialBackoff`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`DURATION`	Initial delay before the first retry attempt when applying a mutation to the target database fails due to a retryable error, such as contention or a temporary unique constraint violation. Default: `25ms`
`--retryMaxBackoff`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`DURATION`	Maximum delay between retry attempts when applying mutations to the target database fails due to retryable errors. Default: `2s`
`--retryMultiplier`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`INT`	Multiplier that controls how quickly the backoff interval increases between successive retries of failed applies to the target database. Default: `2`
`--scanSize`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`INT`	The number of rows to retrieve from the staging database used to store metadata for replication. Default: `10000`
`--schemaRefresh`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`DURATION`	How often a watcher will refresh its schema. If this value is zero or negative, refresh behavior will be disabled. Default: `1m0s`
`--scn`	`oraclelogminer`	`INT`	Required the first time `replicator` is run. The snapshot System Change Number (SCN) from the initial data load, which provides a replication marker for streaming changes.
`--scnWindowSize`	`oraclelogminer`	`INT`	The maximum size of SCN bounds per pull iteration from LogMiner. This helps prevent timeout errors when processing large SCN ranges. Set to `0` or a negative value to disable the cap. Default: `3250`
`--slotName`	`pglogical`	`STRING`	Required. PostgreSQL replication slot name. Must match the slot name specified with `--pglogical-replication-slot-name` in the MOLT Fetch command. Default: `"replicator"`
`--sourceConn`	`pglogical`, `mylogical`, `oraclelogminer`	`STRING`	The source database’s connection string. When replicating from Oracle, this is the connection string of the Oracle container database (CDB).
`--sourceOracleWalletLocation`	`oraclelogminer`	`STRING`	Path to a directory containing an Oracle auto-login wallet (`cwallet.sso`, `sqlnet.ora`, and `tnsnames.ora`) for TLS (TCPS) connections to the Oracle source. A single wallet location applies to both `--sourceConn` (CDB) and `--sourcePDBConn` (PDB). Refer to Connect to Oracle over TLS (TCPS).
`--sourcePDBConn`	`oraclelogminer`	`STRING`	Connection string for the Oracle pluggable database (PDB). Only required when using an Oracle multitenant configuration. `--sourceConn` must be included.
`--sourceSchema`	`oraclelogminer`	`STRING`	Required. Source schema name on Oracle where tables will be replicated from.
`--stageDisableCreateTableReaderIndex`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`BOOL`	Disable the creation of partial covering indexes to improve read performance on staging tables. Set to `true` if creating indexes on existing tables would cause a significant operational impact. Default: `false`
`--stageMarkAppliedLimit`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`INT`	Limit the number of mutations to be marked applied in a single statement. Default: `100000`
`--stageSanityCheckPeriod`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`DURATION`	How often to validate staging table apply order (`-1` to disable). Default: `10m0s`
`--stageSanityCheckWindow`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`DURATION`	How far back to look when validating staging table apply order. Default: `1h0m0s`
`--stageUnappliedPeriod`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`DURATION`	How often to report the number of unapplied mutations in staging tables (`-1` to disable). Default: `1m0s`
`--stagingConn`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`STRING`	The staging database’s connection string.
`--stagingCreateSchema`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`BOOL`	Automatically create the staging schema if it does not exist.
`--stagingIdleTime`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`DURATION`	Maximum lifetime of an idle connection. Default: `1m0s`
`--stagingJitterTime`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`DURATION`	The time over which to jitter database pool disconnections. Default: `15s`
`--stagingMaxLifetime`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`DURATION`	The maximum lifetime of a database connection. Default: `5m0s`
`--stagingMaxPoolSize`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`INT`	The maximum number of staging database connections. Default: `128`
`--stagingSchema`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`STRING`	Name of the CockroachDB schema that stores replication metadata. Required each time `replicator` is rerun after being interrupted, as the schema contains a checkpoint table that enables replication to resume from the correct transaction. Default: `_replicator.public`
`--standbyTimeout`	`pglogical`	`DURATION`	How often to report WAL progress to the source server. Default: `5s`
`--targetApplyQueueSize`	`pglogical`, `oraclelogminer`	`INT`	Size of the apply queue that buffers mutations before they are written to the target database. Larger values can improve throughput, but increase memory usage. This flag applies only to PostgreSQL and Oracle sources, and replaces the deprecated `--copierChannel` and `--stageCopierChannelSize` flags.
`--targetConn`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`STRING`	The target database’s connection string.
`--targetIdleTime`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`DURATION`	Maximum lifetime of an idle connection. Default: `1m0s`
`--targetJitterTime`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`DURATION`	The time over which to jitter database pool disconnections. Default: `15s`
`--targetMaxLifetime`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`DURATION`	The maximum lifetime of a database connection. Default: `5m0s`
`--targetMaxPoolSize`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`INT`	The maximum number of target database connections. Default: `128`
`--targetOracleWalletLocation`	`start`	`STRING`	Path to a directory containing an Oracle auto-login wallet (`cwallet.sso`, `sqlnet.ora`, and `tnsnames.ora`) for TLS (TCPS) connections to an Oracle failback target. Refer to Connect to Oracle over TLS (TCPS).
`--targetSchema`	`pglogical`, `mylogical`, `oraclelogminer`	`STRING`	Required. The SQL database schema in the target cluster to update. CockroachDB schema names must be fully qualified in the format `database.schema`.
`--targetStatementCacheSize`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`INT`	The maximum number of prepared statements to retain. Default: `128`
`--taskGracePeriod`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`DURATION`	How long to allow for task cleanup when recovering from errors. Default: `1m0s`
`--timestampLimit`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`INT`	The maximum number of source timestamps to coalesce into a target transaction. Default: `1000`
`--tlsCertificate`	`start`	`STRING`	A path to a PEM-encoded TLS certificate chain.
`--tlsPrivateKey`	`start`	`STRING`	A path to a PEM-encoded TLS private key.
`--tlsSelfSigned`	`start`	`BOOL`	If true, generate a self-signed TLS certificate valid for `localhost`.
`--userscript`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`STRING`	The path to a TypeScript configuration script. For example, `--userscript 'script.ts'`. For more information, refer to Userscript Overview.
`--userscriptQueueSize`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`INT`	The number of mutations that can be buffered in the queue between the userscript source acceptor and the core sequencer’s copier. Tune this value to avoid replication bottlenecks when using userscripts. Default: `1000`
`-v`, `--verbose`	`start`, `pglogical`, `mylogical`, `oraclelogminer`	`COUNT`	Increase logging verbosity. Use `-v` for `debug` logging or `-vv` for `trace` logging.