Commands
| Command | Usage |
|---|---|
fetch | Start the fetch task. This loads data from a source database to a target CockroachDB database. |
Subcommands
| Command | Usage |
|---|---|
tokens list | List active continuation tokens. |
Flags
Global flags
| Flag | Description |
|---|---|
--source | (Required) Connection string used to connect to the Oracle PDB (in a CDB/PDB architecture) or to a standalone database (non‑CDB). You can also set this with the MOLT_SOURCE environment variable. If both are set, the flag takes precedence. For details, refer to Source and target databases. |
--source-cdb | Connection string for the Oracle container database (CDB) when using a multitenant (CDB/PDB) architecture. Omit this flag on a non‑multitenant Oracle database. You can also set this with the MOLT_SOURCE_CDB environment variable. If both are set, the flag takes precedence. For details, refer to Source and target databases. |
--target | (Required) Connection string for the target database. You can also set this with the MOLT_TARGET environment variable. If both are set, the flag takes precedence. For details, refer to Source and target databases. |
--allow-tls-mode-disable | Allow insecure connections to databases. Secure SSL/TLS connections should be used by default. This should be enabled only if secure SSL/TLS connections to the source or target database are not possible. |
--assume-role | Service account or role to use for assume role authentication. --use-implicit-auth must be included. For example, --assume-role='user-test@cluster-ephemeral.iam.gserviceaccount.com' --use-implicit-auth. For Amazon S3, this flag accepts the CockroachDB ASSUME_ROLE syntax, including an external ID ('{role};external_id={id}') and a comma-separated chain of roles. To use a different role chain for IMPORT INTO, set --import-assume-role. For details, refer to Cloud Storage Authentication. |
--bucket-path | The path within the cloud storage bucket where intermediate files are written (e.g., 's3://bucket/path' or 'gs://bucket/path'). Only the URL path is used; query parameters (e.g., credentials) are ignored. To pass in query parameters, use the appropriate flags: --assume-role, --import-region, --use-implicit-auth. |
--case-sensitive | Toggle case sensitivity when comparing table and column names on the source and target. To disable case sensitivity, set --case-sensitive=false. If = is not included (e.g., --case-sensitive false), the flag is interpreted as --case-sensitive (i.e., --case-sensitive=true).Default: false |
--cleanup | Whether to delete intermediate files after moving data using cloud or local storage. Note: Cleanup does not occur on continuation. |
--compression | Compression method for data when using IMPORT INTO (gzip/none).Default: gzip |
--continuation-file-name | Restart fetch at the specified filename if the task encounters an error. --fetch-id must be specified. For details, see Fetch continuation. |
--continuation-token | Restart fetch at a specific table, using the specified continuation token, if the task encounters an error. --fetch-id must be specified. For details, see Fetch continuation. |
--crdb-pts-duration | The duration for which each timestamp used in data export from a CockroachDB source is protected from garbage collection. This ensures that the data snapshot remains consistent. For example, if set to 24h, each timestamp is protected for 24 hours from the initiation of the export job. This duration is extended at regular intervals specified in --crdb-pts-refresh-interval.Default: 24h0m0s |
--crdb-pts-refresh-interval | The frequency at which the protected timestamp’s validity is extended. This interval maintains protection of the data snapshot until data export from a CockroachDB source is completed. For example, if set to 10m, the protected timestamp’s expiration will be extended by the duration specified in --crdb-pts-duration (e.g., 24h) every 10 minutes while export is not complete. Default: 10m0s |
--direct-copy | Enables direct copy, which copies data directly from source to target without using an intermediate store. |
--dropped-constraints-file | Path of a SQL file to which MOLT Fetch writes ALTER TABLE ... ADD ... statements for the constraints other than primary keys (such as CHECK, UNIQUE, and FOREIGN KEY) that it dropped when it created the target tables. Run the file against the target after the data load completes to restore the constraints. Review the file first: it uses the source schema, table, and column names, so edit it if you renamed objects with --transformations-file, and some source syntax may need edits before CockroachDB accepts it. Requires --table-handling drop-on-target-and-recreate. Cannot be used with --fetch-id. See also --dropped-indexes-file. |
--dropped-indexes-file | Path of a SQL file to which MOLT Fetch writes CREATE INDEX statements for the secondary indexes that it dropped when it created the target tables. Run the file against the target after the data load completes to restore the indexes. Recreating indexes after the load keeps the data load fast. Review the file before you run it. Requires --table-handling drop-on-target-and-recreate. Cannot be used with --fetch-id. See also --dropped-constraints-file. |
--export-concurrency | Number of shards to export at a time per table, each on a dedicated thread. This flag controls shard-level parallelism. MOLT Fetch does not prioritize shards by size. This flag is distinct from --table-concurrency, which controls how many tables are processed simultaneously. The total number of concurrent threads is the product of --export-concurrency and --table-concurrency. Tables can be sharded with a range-based or stats-based mechanism. For details, refer to Table sharding.Default: 4 |
--export-retry-max-attempts | Maximum number of retry attempts for source export queries when connection failures occur. Only supported for PostgreSQL and CockroachDB sources. Default: 3 |
--export-retry-max-duration | Maximum total duration for retrying source export queries. If 0, no time limit is enforced. Only supported for PostgreSQL and CockroachDB sources.Default: 5m0s |
--fail-on-no-tables | Exit with an error when no tables are left to migrate, for example because --table-filter or --schema-filter matches no tables, or the tables are missing on the target. Without this flag, MOLT Fetch exits successfully without moving any data.Default: false |
--filter-path | Path to a JSON file defining row-level filters for the data import phase. Refer to Selective data movement. |
--fetch-id | Restart fetch task corresponding to the specified ID. If --continuation-file-name or --continuation-token are not specified, fetch restarts for all failed tables. |
--flatten-partitioned-tables | For PostgreSQL sources, load each declaratively partitioned table into one unpartitioned target table. With this flag, --table-filter matches only the name of the partitioned table, not the names of its partitions. To use this flag with logical replication setup (--pglogical-replication-slot-name), the source must be PostgreSQL 13 or later. With --pglogical-publication-and-slot-drop-and-recreate, MOLT Fetch creates the publication with publish_via_partition_root enabled. Otherwise, the existing publication must have publish_via_partition_root enabled and must include each partitioned table.Default: false |
--flush-rows | Number of rows before the source data is flushed to intermediate files. Note: If --flush-size is also specified, the fetch behavior is based on the flag whose criterion is met first. |
--flush-size | Size (in bytes) before the source data is flushed to intermediate files. Note: If --flush-rows is also specified, the fetch behavior is based on the flag whose criterion is met first. |
--ignore-replication-check | Skip querying for replication checkpoints such as pg_current_wal_insert_lsn() on PostgreSQL, gtid_executed on MySQL, and CURRENT_SCN on Oracle. This option is intended for use during bulk load migrations or when doing a one-time data export from a read replica. For Oracle sources, this flag also skips the check of redo log and archive log settings that MOLT Fetch runs before it exports data. |
--import-assume-role | Role chain that CockroachDB assumes to read the bucket during IMPORT INTO, in the CockroachDB ASSUME_ROLE syntax ('{role};external_id={id}', comma-separated for a chain of roles). Applies only to s3:// paths in --bucket-path. Requires --use-implicit-auth.Default: Value of --assume-role. |
--import-batch-size | The number of files to be imported at a time to the target database during the data import phase. This applies only when using IMPORT INTO for data movement. Note: Increasing this value can improve the performance of full-scan queries on the target database shortly after fetch completes, but very high values are not recommended. If any individual file in the import batch fails, you must retry the entire batch.Default: 1000 |
--import-region | The region of the cloud storage bucket. This applies only to Amazon S3 buckets. Set this flag only if you need to specify an AWS_REGION explicitly when using IMPORT INTO for data movement. For example, --import-region=ap-south-1. |
--local-path | The path within the local file server where intermediate files are written (e.g., data/migration/cockroach). --local-path-listen-addr must be specified. |
--local-path-crdb-access-addr | Address of a local file server that is publicly accessible. This flag is only necessary if CockroachDB cannot reach the local address specified with --local-path-listen-addr (e.g., when moving data to a CockroachDB Cloud deployment). --local-path and --local-path-listen-addr must be specified.Default: Value of --local-path-listen-addr. |
--local-path-listen-addr | Write intermediate files to a local file server at the specified address (e.g., 'localhost:3000'). --local-path must be specified. |
--log-file | Write messages to the specified log filename. If no filename is provided, messages write to fetch-{datetime}.log. If "stdout" is provided, messages write to stdout. Log files are readable only by the user who runs MOLT (permissions 0600), and log directories that MOLT creates have permissions 0700. To let a process that runs as another user read the logs, run it as the same user as MOLT or as root, or set --log-file stdout and capture the output. |
--logging | Level at which to log messages (trace/debug/info/warn/error/fatal/panic).Default: info |
--metrics-listen-addr | Address of the Prometheus metrics endpoint, which has the path {address}/metrics. For details on important metrics to monitor, refer to Monitoring.Default: '127.0.0.1:3030' |
--mode | Configure the MOLT Fetch behavior: data-load, export-only, or import-only. For details, refer to Fetch mode.Default: data-load |
--non-interactive | Run the fetch task without interactive prompts. This is recommended only when running molt fetch in an automated process (i.e., a job or continuous integration). |
--opt-out-telemetry | Turn off MOLT telemetry, which is on by default. MOLT telemetry writes run summary events to the MOLT log, and writes to a _molt_telemetry_runs table on the target database. MOLT does not send telemetry over the network. |
--oracle-application-users | Comma-separated list of Oracle users whose active transactions MOLT Fetch checks when it chooses the replication start point (SCN). For example, --oracle-application-users=user1,user2. Include every user that may have a transaction in progress at cutover. If this flag is not set, MOLT Fetch finds the application users automatically (users with ORACLE_MAINTAINED='N' in ALL_USERS). This requires Oracle 12.1 or later and SELECT on ALL_USERS. On Oracle 11g, or if the MOLT user cannot query ALL_USERS, you must set this flag. |
--oracle-narrow-snapshot-scn-by-table-touch | For Oracle sources, move the replication start point (SCN) later by checking only the active transactions that hold a lock on a table in the schemas being migrated. Requires SELECT on V$LOCK and ALL_OBJECTS. Do not use this flag with parallel DML workloads.Default: false |
--oracle-tablespace-filter | For Oracle sources, move only tables in tablespaces that match a specified POSIX regular expression. Ignored, with a warning, for other sources. Default: '.*' |
--pglogical-replication-slot-name | Name of a PostgreSQL replication slot that will be created before taking a snapshot of data. Must match the slot name specified with --slotName in the MOLT Replicator command. For details, refer to Initial bulk load (before replication). |
--pglogical-publication-and-slot-drop-and-recreate | Drop the PostgreSQL publication and replication slot if they exist, then recreate them. Creates a publication named molt_fetch and the replication slot specified with --pglogical-replication-slot-name. For details, refer to Initial bulk load (before replication).Default: false |
--pprof-listen-addr | Address of the pprof endpoint. Default: '127.0.0.1:3031' |
--require-empty-target | Before it moves any data, check that every target table in scope is empty, and stop if any table has rows. Cannot be used with --table-handling truncate-if-exists, --table-handling drop-on-target-and-recreate, --fetch-id, --continuation-token, or --mode export-only.Default: false |
--row-batch-size | Number of rows per shard to export at a time. For details on sharding, refer to Table sharding. See also Best practices. Default: 100000 |
--schema-filter | Move schemas that match a specified regular expression. Default: '.*' |
--skip-pk-check | Skip primary-key matching to allow data load when source or target tables have missing or mismatched primary keys. Disables sharding and bypasses --export-concurrency and --row-batch-size settings. Refer to Skip primary key matching.Default: false |
--skip-sequence-sync | Skip advancing target sequences after the data load. By default, MOLT Fetch advances each sequence that backs a loaded column past the largest value it loaded (the smallest value, for a descending sequence), so that the first insert after the migration does not conflict with a migrated row. Default: false |
--source-oracle-wallet-location | 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 --source and --source-cdb. Refer to Connect to Oracle over TLS (TCPS). |
--table-concurrency | Number of tables to export at a time. This flag controls table-level parallelism. MOLT Fetch does not prioritize tables by size, row count, or other criteria and processes tables in a randomized order for each run. The number of concurrent threads is the product of --export-concurrency and --table-concurrency.Default: 4 |
--table-exclusion-filter | Exclude tables that match a specified POSIX regular expression. This value cannot be set to '.*', which would cause every table to be excluded. Default: Empty string |
--table-filter | Move tables that match a specified POSIX regular expression. Default: '.*' |
--table-handling | How tables are initialized on the target database (none/drop-on-target-and-recreate/truncate-if-exists). For details, see Target table handling.Default: none |
--transformations-file | Path to a JSON file that defines transformations to be performed on the target schema during the fetch task. Refer to Transformations. |
--type-map-file | Path to a JSON file that contains explicit type mappings for automatic schema creation, when enabled with --table-handling drop-on-target-and-recreate. For details on the JSON format and valid type mappings, see type mapping. |
--use-console-writer | Use the console writer, which has cleaner log output but introduces more latency. Default: false (log as structured JSON) |
--use-copy | Use COPY FROM to move data. This makes tables queryable during data load, but is slower than using IMPORT INTO. For details, refer to Data movement. |
--use-implicit-auth | Use implicit authentication for cloud storage URIs. |
--use-stats-based-sharding | Enable statistics-based sharding for PostgreSQL sources. This allows sharding of tables with primary keys of any data type and can create more evenly distributed shards compared to numerical range sharding, which can place most rows in a single shard when the primary key is text or spans several columns. Statistics-based sharding is enabled by default for PostgreSQL 11+ sources (disabled for other sources) and requires access to pg_stats. For details, refer to Table sharding.Default: true for PostgreSQL 11+ sources; false otherwise |
tokens list flags
| Flag | Description |
|---|---|
--conn-string | (Required) Connection string for the target database. For details, see List active continuation tokens. |
-n, --num-results | Number of results to return. |