review feedback and improvements

Author: taroface

src/current/_includes/molt/crdb-to-crdb-migration.md

@@ -1,3 +1,3 @@
 {{site.data.alerts.callout_info}}
-For CockroachDB-to-CockroachDB migrations, use [backup and restore]({% link {{ site.current_cloud_version }}/backup.md %}) with MOLT Replicator. Contact your account team for guidance.
+For CockroachDB-to-CockroachDB migrations, contact your account team for guidance.
 {{site.data.alerts.end}}

src/current/_includes/molt/molt-docker.md

@@ -67,14 +67,28 @@ When testing locally, specify the host as follows:
 
 - For macOS, use `host.docker.internal`. For example:
 
+    {% if page.name == "molt-replicator.md" %}
+    ~~~
+    --sourceConn 'postgres://postgres:[email protected]:5432/molt?sslmode=disable'
+    --targetConn "postgres://[email protected]:26257/molt?sslmode=disable"
+    ~~~
+    {% else %}
     ~~~
     --source 'postgres://postgres:[email protected]:5432/molt?sslmode=disable'
     --target "postgres://[email protected]:26257/molt?sslmode=disable"
     ~~~
+    {% endif %}
 
 - For Linux and Windows, use `172.17.0.1`. For example:
 
+    {% if page.name == "molt-replicator.md" %}
+    ~~~
+    --sourceConn 'postgres://postgres:[email protected]:5432/molt?sslmode=disable'
+    --targetConn "postgres://[email protected]:26257/molt?sslmode=disable"
+    ~~~
+    {% else %}
     ~~~
     --source 'postgres://postgres:[email protected]:5432/molt?sslmode=disable'
     --target "postgres://[email protected]:26257/molt?sslmode=disable"
-    ~~~
+    ~~~
+    {% endif %}

src/current/_includes/molt/molt-troubleshooting.md

@@ -1,5 +1,6 @@
 ## Troubleshooting
 
+{% if page.name != "migrate-resume-replication.md" %}
 ### Fetch issues
 
 ##### Fetch exits early due to mismatches
@@ -41,7 +42,7 @@ GRANT SELECT, FLASHBACK ON migration_schema.orders TO C##MIGRATION_USER;
 
 ##### Table or view does not exist
 
-If the Oracle migration user lacks privileges on certain tables, you may receive errors stating that the table or view does not exist. Either use `--table-filter` to [limit the tables to be migrated](#schema-and-table-filtering), or grant the migration user `SELECT` privileges on all objects in the schema. Refer to [Create migration user on source database](#create-migration-user-on-source-database).
+If the Oracle migration user lacks privileges on certain tables, you may receive errors stating that the table or view does not exist. Either use `--table-filter` to {% if page.name == "migrate-resume-replication.md" %}[limit the tables to be migrated]({% link molt/migrate-load-replicate.md %}#schema-and-table-filtering){% else %}[limit the tables to be migrated](#schema-and-table-filtering){% endif %}, or grant the migration user `SELECT` privileges on all objects in the schema. Refer to {% if page.name == "migrate-resume-replication.md" %}[Create migration user on source database]({% link molt/migrate-load-replicate.md %}#create-migration-user-on-source-database){% else %}[Create migration user on source database](#create-migration-user-on-source-database){% endif %}.
 
 {% if page.name != "migrate-bulk-load.md" %}
 ##### Missing redo logs or unavailable SCN
@@ -80,6 +81,7 @@ If you shut down `molt` or `replicator` unexpectedly (e.g., with `kill -9` or a
 
     Replace `sid` and `serial#` in the preceding statement with the values returned by the `SELECT` query.
 </section>
+{% endif %}
 
 {% if page.name != "migrate-bulk-load.md" %}
 ### Replicator issues
@@ -128,7 +130,7 @@ Dropping a replication slot can be destructive and delete data that is not yet r
 run CREATE PUBLICATION molt_fetch FOR ALL TABLES;
 ~~~
 
-**Resolution:** [Create the publication](#configure-source-database-for-replication) on the source database. Ensure you also create the replication slot:
+**Resolution:** {% if page.name == "migrate-resume-replication.md" %}[Create the publication]({% link molt/migrate-load-replicate.md %}#configure-source-database-for-replication){% else %}[Create the publication](#configure-source-database-for-replication){% endif %} on the source database. Ensure you also create the replication slot:
 
 {% include_cached copy-clipboard.html %}
 ~~~ sql
@@ -150,7 +152,7 @@ could not connect to source database: failed to connect to `user=migration_user
 run SELECT pg_create_logical_replication_slot('molt_slot', 'pgoutput'); in source database
 ~~~
 
-**Resolution:** [Create the replication slot](#configure-source-database-for-replication) or verify the correct slot name:
+**Resolution:** {% if page.name == "migrate-resume-replication.md" %}[Create the replication slot]({% link molt/migrate-load-replicate.md %}#configure-source-database-for-replication){% else %}[Create the replication slot](#configure-source-database-for-replication){% endif %} or verify the correct slot name:
 
 {% include_cached copy-clipboard.html %}
 ~~~ sql

src/current/_includes/molt/replicator-flags-usage.md

@@ -2,33 +2,40 @@ The following [MOLT Replicator]({% link molt/molt-replicator.md %}) flags are **
 
 {% if page.name == "migrate-load-replicate.md" %}
 <section class="filter-content" markdown="1" data-scope="postgres">
-|       Flag       |                                                  Description                                                   |
-|------------------|----------------------------------------------------------------------------------------------------------------|
-| `--targetSchema` | **Required.** Target schema name on CockroachDB where tables will be replicated.                               |
-| `--metricsAddr`  | Enable Prometheus metrics at a specified `{host}:{port}`. Metrics are served at `http://{host}:{port}/_/varz`. |
+|           Flag          |                                                                              Description                                                                               |
+|-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `--slotName`            | **Required.** PostgreSQL replication slot name. Must match the slot name specified with `--pglogical-replication-slot-name` in the [MOLT Fetch command](#start-fetch). |
+| `--targetSchema`        | **Required.** Target schema name on CockroachDB where tables will be replicated.                                                                                       |
+| `--stagingSchema`       | **Required.** Staging schema name for replication metadata and checkpoints.                                                                                            |
+| `--stagingCreateSchema` | Automatically create the staging schema if it does not exist. Include this flag when starting replication for the first time.                                          |
+| `--metricsAddr`         | Enable Prometheus metrics at a specified `{host}:{port}`. Metrics are served at `http://{host}:{port}/_/varz`.                                                         |
 </section>
 
 <section class="filter-content" markdown="1" data-scope="mysql">
-|        Flag        |                                                                                 Description                                                                                  |
-|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `--targetSchema`   | **Required.** Target schema name on CockroachDB where tables will be replicated.                                                                                             |
-| `--defaultGTIDSet` | **Required.** Default GTID set for changefeed.                                                                                                                               |
-| `--fetchMetadata`  | Explicitly fetch column metadata for MySQL versions that do not support `binlog_row_metadata`. Requires `SELECT` permissions on the source database or `PROCESS` privileges. |
-| `--metricsAddr`    | Enable Prometheus metrics at a specified `{host}:{port}`. Metrics are served at `http://{host}:{port}/_/varz`.                                                               |
-| `--userscript`     | Path to a userscript that enables table filtering from MySQL sources. Refer to [Table filter userscript](#table-filter-userscript).                                          |
+|           Flag          |                                                                                 Description                                                                                  |
+|-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `--targetSchema`        | **Required.** Target schema name on CockroachDB where tables will be replicated.                                                                                             |
+| `--defaultGTIDSet`      | **Required.** Default GTID set for changefeed.                                                                                                                               |
+| `--stagingSchema`       | **Required.** Staging schema name for replication metadata and checkpoints.                                                                                                  |
+| `--stagingCreateSchema` | Automatically create the staging schema if it does not exist. Include this flag when starting replication for the first time.                                                |
+| `--fetchMetadata`       | Explicitly fetch column metadata for MySQL versions that do not support `binlog_row_metadata`. Requires `SELECT` permissions on the source database or `PROCESS` privileges. |
+| `--metricsAddr`         | Enable Prometheus metrics at a specified `{host}:{port}`. Metrics are served at `http://{host}:{port}/_/varz`.                                                               |
+| `--userscript`          | Path to a userscript that enables table filtering from MySQL sources. Refer to [Table filter userscript](#table-filter-userscript).                                          |
 
 Replication from MySQL requires `--defaultGTIDSet`, which sets the starting GTID for replication. You can find this value in the `cdc_cursor` field of the `fetch complete` message after the [initial data load](#start-fetch) completes.
 </section>
 
 <section class="filter-content" markdown="1" data-scope="oracle">
-|         Flag        |                                                             Description                                                              |
-|---------------------|--------------------------------------------------------------------------------------------------------------------------------------|
-| `--targetSchema`    | **Required.** Target schema name on CockroachDB where tables will be replicated.                                                     |
-| `--sourceSchema`    | **Required.** Source schema name on Oracle where tables will be replicated from.                                                     |
-| `--scn`             | **Required.** Snapshot System Change Number (SCN) for the initial changefeed starting point.                                         |
-| `--backfillFromSCN` | **Required.** SCN of the earliest active transaction at the time of the snapshot. Ensures no transactions are skipped.               |
-| `--metricsAddr`     | Enable Prometheus metrics at a specified `{host}:{port}`. Metrics are served at `http://{host}:{port}/_/varz`.                       |
-| `--userscript`      | Path to a userscript that enables table filtering from Oracle sources. Refer to [Table filter userscript](#table-filter-userscript). |
+|           Flag          |                                                             Description                                                              |
+|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
+| `--sourceSchema`        | **Required.** Source schema name on Oracle where tables will be replicated from.                                                     |
+| `--targetSchema`        | **Required.** Target schema name on CockroachDB where tables will be replicated.                                                     |
+| `--scn`                 | **Required.** Snapshot System Change Number (SCN) for the initial changefeed starting point.                                         |
+| `--backfillFromSCN`     | **Required.** SCN of the earliest active transaction at the time of the snapshot. Ensures no transactions are skipped.               |
+| `--stagingSchema`       | **Required.** Staging schema name for replication metadata and checkpoints.                                                          |
+| `--stagingCreateSchema` | Automatically create the staging schema if it does not exist. Include this flag when starting replication for the first time.        |
+| `--metricsAddr`         | Enable Prometheus metrics at a specified `{host}:{port}`. Metrics are served at `http://{host}:{port}/_/varz`.                       |
+| `--userscript`          | Path to a userscript that enables table filtering from Oracle sources. Refer to [Table filter userscript](#table-filter-userscript). |
 
 Replication from Oracle requires `--sourceSchema`, `--scn`, and `--backfillFromSCN`. The `--sourceSchema` specifies the Oracle schema to replicate from, while `--scn` and `--backfillFromSCN` specify the snapshot SCN and the earliest active transaction SCN, respectively. You can find the SCN values in the message `replication-only mode should include the following replicator flags` after the [initial data load](#start-fetch) completes.
 </section>
@@ -39,38 +46,11 @@ Replication from Oracle requires `--sourceSchema`, `--scn`, and `--backfillFromS
 | `--stagingSchema` | **Required.** Staging schema name for the changefeed checkpoint table.                                         |
 | `--metricsAddr`   | Enable Prometheus metrics at a specified `{host}:{port}`. Metrics are served at `http://{host}:{port}/_/varz`. |
 
-Resuming replication requires `--stagingSchema`, which specifies the staging schema name used as a checkpoint. MOLT Fetch [logs the staging schema name]({% link molt/migrate-load-replicate.md %}#start-replicator) as the `staging database name` when it starts replication. For example:
+Resuming replication requires `--stagingSchema`, which specifies the staging schema name used as a checkpoint. The staging schema was created during [initial replication setup]({% link molt/migrate-load-replicate.md %}#start-replicator) with `--stagingCreateSchema`.
 
-~~~ json
-	{"level":"info","time":"2025-02-10T14:28:13-05:00","message":"staging database name: _replicator_1749699789613149000"}
-~~~
-
-<section class="filter-content" markdown="1" data-scope="mysql">
-{{site.data.alerts.callout_info}}
-When using `--table-filter`, you must also include `--userscript`. Refer to [Table filter userscript]({% link molt/migrate-load-replicate.md %}?filters=mysql#table-filter-userscript).
-{{site.data.alerts.end}}
-</section>
-
-<section class="filter-content" markdown="1" data-scope="oracle">
-{{site.data.alerts.callout_info}}
-When using `--table-filter`, you must also include `--userscript`. Refer to [Table filter userscript]({% link molt/migrate-load-replicate.md %}?filters=oracle#table-filter-userscript).
-{{site.data.alerts.end}}
-</section>
-
-{% elsif page.name == "migrate-data-load-and-replication.md" %}
-|       Flag      |                                                  Description                                                   |
-|-----------------|----------------------------------------------------------------------------------------------------------------|
-| `--metricsAddr` | Enable Prometheus metrics at a specified `{host}:{port}`. Metrics are served at `http://{host}:{port}/_/varz`. |
-
-<section class="filter-content" markdown="1" data-scope="mysql">
-{{site.data.alerts.callout_info}}
-When using `--table-filter`, you must also include `--userscript`. Refer to [Table filter userscript](#table-filter-userscript).
-{{site.data.alerts.end}}
-</section>
-
-<section class="filter-content" markdown="1" data-scope="oracle">
+<section class="filter-content" markdown="1" data-scope="mysql oracle">
 {{site.data.alerts.callout_info}}
-When using `--table-filter`, you must also include `--userscript`. Refer to [Table filter userscript](#table-filter-userscript).
+When using `--table-filter`, you must also include `--userscript`. Refer to [Table filter userscript]({% link molt/migrate-load-replicate.md %}#table-filter-userscript).
 {{site.data.alerts.end}}
 </section>
 

src/current/molt/migrate-load-replicate.md

@@ -73,6 +73,46 @@ Use [MOLT Verify]({% link molt/molt-verify.md %}) to confirm that the source and
 
 ## Configure Replicator
 
+### Replication connection strings
+
+MOLT Replicator uses `--sourceConn` and `--targetConn` to specify the source and target database connections.
+
+`--sourceConn` specifies the connection string of the source database:
+
+<section class="filter-content" markdown="1" data-scope="postgres">
+~~~
+--sourceConn 'postgresql://{username}:{password}@{host}:{port}/{database}'
+~~~
+</section>
+
+<section class="filter-content" markdown="1" data-scope="mysql">
+~~~
+--sourceConn 'mysql://{username}:{password}@{protocol}({host}:{port})/{database}'
+~~~
+</section>
+
+<section class="filter-content" markdown="1" data-scope="oracle">
+~~~
+--sourceConn 'oracle://{username}:{password}@{host}:{port}/{service_name}'
+~~~
+
+For Oracle Multitenant databases, also specify `--sourcePDBConn` with the PDB connection string:
+
+~~~
+--sourcePDBConn 'oracle://{username}:{password}@{host}:{port}/{pdb_service_name}'
+~~~
+</section>
+
+`--targetConn` specifies the target CockroachDB connection string:
+
+~~~
+--targetConn 'postgresql://{username}:{password}@{host}:{port}/{database}'
+~~~
+
+{{site.data.alerts.callout_success}}
+Follow best practices for securing connection strings. Refer to [Secure connections](#secure-connections).
+{{site.data.alerts.end}}
+
 ### Replication flags
 
 {% include molt/replicator-flags-usage.md %}