Apply suggestions from code review

taroface · florence-crl · web-flow · commit e52ffdacf0c3 · 2025-07-16T16:00:14.000-04:00
Co-authored-by: Florence Morris &lt;58752716+florence-crl@users.noreply.github.com&gt;
diff --git a/src/current/_includes/molt/fetch-data-load-output.md b/src/current/_includes/molt/fetch-data-load-output.md
@@ -68,7 +68,7 @@
 	~~~
 
 	{% if page.name != "migrate-bulk-load.md" %}
-	This message includes a `cdc_cursor` value. You must set `--defaultGTIDSet` to this value when starting [`replication-only` mode](#replicate-changes-to-cockroachdb):
+	This message includes a `cdc_cursor` value. You must set the `--defaultGTIDSet` replication flag to this value when starting [`replication-only` mode](#replicate-changes-to-cockroachdb):
 
 	{% include_cached copy-clipboard.html %}
 	~~~ 
@@ -85,7 +85,7 @@
 
 	{% if page.name == "migrate-data-load-replicate-only.md" %}
 	<section class="filter-content" markdown="1" data-scope="oracle">
-	The following message contains the appropriate `--backfillFromSCN` and `--scn` values to set when [starting`replication-only` mode](#replicate-changes-to-cockroachdb):
+	The following message shows the appropriate values for the `--backfillFromSCN` and `--scn` replication flags to use when [starting`replication-only` mode](#replicate-changes-to-cockroachdb):
 
 	{% include_cached copy-clipboard.html %}
 	~~~ 
diff --git a/src/current/_includes/molt/fetch-intermediate-file-storage.md b/src/current/_includes/molt/fetch-intermediate-file-storage.md
@@ -6,7 +6,7 @@ MOLT Fetch can write intermediate files to either a cloud storage bucket or a lo
 | Local file server | `--local-path`<br>`--local-path-listen-addr`<br>`--local-path-crdb-access-addr` | Write to `--local-path` on a local file server at `--local-path-listen-addr`; if the target CockroachDB cluster cannot reach this address, specify a publicly accessible address with `--local-path-crdb-access-addr`. No additional authentication is required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 
 {{site.data.alerts.callout_success}}
-Cloud storage is often preferable to a local file server, which can require considerable disk space.
+Cloud storage is often preferred over a local file server, which may require significant disk space.
 {{site.data.alerts.end}}
 
 #### Cloud storage authentication
diff --git a/src/current/_includes/molt/fetch-replicator-flags.md b/src/current/_includes/molt/fetch-replicator-flags.md
@@ -34,10 +34,10 @@ Replication from Oracle requires `--scn` and `--backfillFromSCN`, which specify
 | `--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-data-load-replicate-only.md %}#replicate-changes-to-cockroachdb) when it starts replication:
+Resuming replication requires `--stagingSchema`, which specifies the staging schema name used as a checkpoint. MOLT Fetch [logs the staging schema name]({% link molt/migrate-data-load-replicate-only.md %}#replicate-changes-to-cockroachdb) as the `staging database name` when it starts replication. For example:
 
-~~~ shell
-staging database name: _replicator_1749699789613149000
+~~~ 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">
diff --git a/src/current/_includes/molt/fetch-schema-table-filtering.md b/src/current/_includes/molt/fetch-schema-table-filtering.md
@@ -1,4 +1,4 @@
-MOLT Fetch can restrict which schemas (or users) and tables are migrated by using the `--schema-filter`, `--table-filter`, and `--table-exclusion-filter` flags:
+MOLT Fetch can restrict which schemas (or users) and tables are migrated by using the following filter flags:
 
 |      Filter type       |            Flag            |                                                                   Description                                                                   |
 |------------------------|----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
diff --git a/src/current/_includes/molt/migration-create-sql-user.md b/src/current/_includes/molt/migration-create-sql-user.md
@@ -4,10 +4,10 @@ To create a user `crdb_user` in the default database (you will pass this usernam
 
 {% include_cached copy-clipboard.html %}
 ~~~ sql
-CREATE USER crdb_user WITH PASSWORD '{password}';
+CREATE USER crdb_user WITH PASSWORD 'password';
 ~~~
 
-Grant the necessary permissions to run either [`IMPORT INTO`]({% link {{site.current_cloud_version}}/import-into.md %}#required-privileges) or [`COPY FROM`]({% link {{site.current_cloud_version}}/copy.md %}#required-privileges) on the target tables, depending on the MOLT Fetch [data load mode](#data-load-mode)) you will use.
+Grant the necessary privileges to run either [`IMPORT INTO`]({% link {{site.current_cloud_version}}/import-into.md %}#required-privileges) or [`COPY FROM`]({% link {{site.current_cloud_version}}/copy.md %}#required-privileges) on the target tables, depending on the MOLT Fetch [data load mode](#data-load-mode) you will use.
 
 #### `IMPORT INTO` privileges
 
diff --git a/src/current/_includes/molt/migration-prepare-database.md b/src/current/_includes/molt/migration-prepare-database.md
@@ -1,6 +1,6 @@
 #### Create migration user on source database
 
-Create a dedicated migration user (e.g., `MIGRATION_USER`) on the source database. This user is responsible for reading data from source tables during the migration.
+Create a dedicated migration user (e.g., `MIGRATION_USER`) on the source database. This user is responsible for reading data from source tables during the migration. You will pass this username in the [source connection string](#source-connection-string).
 
 <section class="filter-content" markdown="1" data-scope="postgres">
 {% include_cached copy-clipboard.html %}
@@ -12,7 +12,7 @@ Grant the user privileges to connect, view schema objects, and select the tables
 
 {% include_cached copy-clipboard.html %}
 ~~~ sql
-GRANT CONNECT, RESOURCE ON DATABASE source_database TO MIGRATION_USER;
+GRANT CONNECT ON DATABASE source_database TO MIGRATION_USER;
 GRANT USAGE ON SCHEMA migration_schema TO MIGRATION_USER;
 GRANT SELECT ON ALL TABLES IN SCHEMA migration_schema TO MIGRATION_USER;
 ALTER DEFAULT PRIVILEGES IN SCHEMA migration_schema GRANT SELECT ON TABLES TO MIGRATION_USER;
@@ -37,7 +37,7 @@ FLUSH PRIVILEGES;
 <section class="filter-content" markdown="1" data-scope="oracle">
 {% include_cached copy-clipboard.html %}
 ~~~ sql
-CREATE USER MIGRATION_USER IDENTIFIED BY '{password}';
+CREATE USER MIGRATION_USER IDENTIFIED BY 'password';
 ~~~
 
 {{site.data.alerts.callout_info}}
@@ -164,7 +164,7 @@ CREATE TABLE migration_schema."_replicator_sentinel" (
 );
 ~~~
 
-Grant permissions to modify the checkpoint table. In Oracle Multitenant, grant the permissions on the PDB:
+Grant privileges to modify the checkpoint table. In Oracle Multitenant, grant the privileges on the PDB:
 
 {% include_cached copy-clipboard.html %}
 ~~~ sql
diff --git a/src/current/_includes/molt/molt-setup.md b/src/current/_includes/molt/molt-setup.md
@@ -45,7 +45,7 @@ When you run `molt fetch`, you can configure the following options for data load
 - [Intermediate file storage](#intermediate-file-storage): Export data to cloud storage or a local file server.
 - [Table handling mode](#table-handling-mode): Determine how existing target tables are initialized before load.
 - [Schema and table filtering](#schema-and-table-filtering): Specify schema and table names to migrate.
-- [Data load mode](#data-load-mode): Choose between `IMPORT INTO` or `COPY FROM`.
+- [Data load mode](#data-load-mode): Choose between `IMPORT INTO` and `COPY FROM`.
 - [Metrics](#metrics): Configure metrics collection during the load.
 {% if page.name != "migrate-bulk-load.md" %}
 - [Replication flags](#replication-flags): Configure the `replicator` process.
diff --git a/src/current/_includes/molt/molt-troubleshooting.md b/src/current/_includes/molt/molt-troubleshooting.md
@@ -5,7 +5,7 @@
 `molt fetch` exits early in the following cases, and will output a log with a corresponding `mismatch_tag` and `failable_mismatch` set to `true`:
 
 - A source table is missing a primary key.
-- A source and table primary key have mismatching types.
+- A source primary key and target primary key have mismatching types.
 - A [`STRING`]({% link {{site.current_cloud_version}}/string.md %}) primary key has a different [collation]({% link {{site.current_cloud_version}}/collate.md %}) on the source and target.
 - A source and target column have mismatching types that are not [allowable mappings]({% link molt/molt-fetch.md %}#type-mapping).
 - A target table is missing a column that is in the corresponding source table.
@@ -20,7 +20,7 @@
 <section class="filter-content" markdown="1" data-scope="oracle">
 ##### ORA-01950: no privileges on tablespace
 
-If you receive `ORA-01950: no privileges on tablespace 'USERS'`, the Oracle migration user does not have sufficient quota on the tablespace used to store its values (by default, this is `USERS`, but can vary). Grant a quota to the schema. For example:
+If you receive `ORA-01950: no privileges on tablespace 'USERS'`, it means the Oracle table owner (`migration_schema` in the preceding examples) does not have sufficient quota on the tablespace used to store its data. By default, this tablespace is `USERS`, but it can vary. To resolve this issue, grant a quota to the table owner. For example:
 
 ~~~ sql
 -- change UNLIMITED to a suitable limit for the table owner
@@ -62,15 +62,15 @@ If the `replicator` process is lagging significantly behind the current Oracle S
 If you shut down `molt` or `replicator` unexpectedly (e.g., with `kill -9` or a system crash), Oracle sessions opened by these tools may remain active.
 
 - Check your operating system for any running `molt` or `replicator` processes and terminate them manually.
-- Once both processes are confirmed stopped, ask a DBA to check for lingering Oracle sessions with:
+- After confirming that both processes have stopped, ask a DBA to check for active Oracle sessions using:
 
     ~~~ sql
     SELECT sid, serial#, username, status, osuser, machine, program
     FROM v$session
-    WHERE username = 'C##CDB_USER';
+    WHERE username = 'C##MIGRATION_USER';
     ~~~
 
-    Wait for any remaining sessions to show an `INACTIVE` status, then terminate them using:
+    Wait until any remaining sessions display an `INACTIVE` status, then terminate them using:
 
     ~~~ sql
     ALTER SYSTEM KILL SESSION 'sid,serial#' IMMEDIATE;
diff --git a/src/current/_includes/molt/verify-output.md b/src/current/_includes/molt/verify-output.md
@@ -1,4 +1,4 @@
-1. Issue the [MOLT Verify]({% link molt/molt-verify.md %}) command, specifying the source and target [connection strings](#connection-strings) and the tables to validate.
+1. Run the [MOLT Verify]({% link molt/molt-verify.md %}) command, specifying the source and target [connection strings](#connection-strings) and the tables to validate.
 
 	<section class="filter-content" markdown="1" data-scope="postgres">
 	{% include_cached copy-clipboard.html %}
@@ -30,7 +30,7 @@
 	~~~
 
 	{{site.data.alerts.callout_info}}
-	With Oracle Multitenant deployments, `--source-cdb` is **not** necessary for `verify`.
+	With Oracle Multitenant deployments, while `--source-cdb` is required for `fetch`, it  is **not** necessary for `verify`.
 	{{site.data.alerts.end}}
 	</section>
 
diff --git a/src/current/molt/migrate-bulk-load.md b/src/current/molt/migrate-bulk-load.md
@@ -1,6 +1,6 @@
 ---
 title: Bulk Load Migration
-summary: Learn how to migrate data from a PostgreSQL or MySQL database into a CockroachDB cluster.
+summary: Learn how to migrate data from a source database (such as PostgreSQL, MySQL, or Oracle) into a CockroachDB cluster.
 toc: true
 docs_area: migrate
 ---
@@ -13,7 +13,7 @@ Use `data-load` mode to perform a one-time bulk load of source data into Cockroa
 
 Perform the bulk load of the source data.
 
-1. Issue the [MOLT Fetch]({% link molt/molt-fetch.md %}) command to move the source data to CockroachDB, specifying [`--mode data-load`]({% link molt/molt-fetch.md %}#fetch-mode) to perform a one-time data load. This example command passes the source and target connection strings [as environment variables](#secure-connections), writes [intermediate files](#intermediate-file-storage) to S3 storage, and uses the `truncate-if-exists` [table handling mode](#table-handling-mode) to truncate the target tables before loading data. It also limits the migration to a single schema and filters three specific tables to migrate. The [data load mode](#data-load-mode) defaults to `IMPORT INTO`.
+1. Run the [MOLT Fetch]({% link molt/molt-fetch.md %}) command to move the source data into CockroachDB, specifying [`--mode data-load`]({% link molt/molt-fetch.md %}#fetch-mode) to perform a one-time data load. This example command passes the source and target connection strings [as environment variables](#secure-connections), writes [intermediate files](#intermediate-file-storage) to S3 storage, and uses the `truncate-if-exists` [table handling mode](#table-handling-mode) to truncate the target tables before loading data. It limits the migration to a single schema and filters for three specific tables. The [data load mode](#data-load-mode) defaults to `IMPORT INTO`.
 
 	<section class="filter-content" markdown="1" data-scope="postgres">
 	{% include_cached copy-clipboard.html %}
diff --git a/src/current/molt/migrate-data-load-and-replication.md b/src/current/molt/migrate-data-load-and-replication.md
@@ -1,6 +1,6 @@
 ---
 title: Load and Replicate
-summary: Learn how to migrate data from a PostgreSQL or MySQL database into a CockroachDB cluster.
+summary: Learn how to migrate data from a source database (such as PostgreSQL, MySQL, or Oracle) into a CockroachDB cluster.
 toc: true
 docs_area: migrate
 ---
diff --git a/src/current/molt/migrate-data-load-replicate-only.md b/src/current/molt/migrate-data-load-replicate-only.md
@@ -1,6 +1,6 @@
 ---
 title: Load and Replicate Separately
-summary: Learn how to migrate data from a PostgreSQL or MySQL database into a CockroachDB cluster.
+summary: Learn how to migrate data from a source database (such as PostgreSQL, MySQL, or Oracle) into a CockroachDB cluster.
 toc: true
 docs_area: migrate
 ---
@@ -87,7 +87,7 @@ With initial load complete, start replication of ongoing changes on the source t
 <a id="replication-flags"></a>
 {% include molt/fetch-replicator-flags.md %}
 
-1. Issue the [MOLT Fetch]({% link molt/molt-fetch.md %}) command to start replication on CockroachDB, specifying [`--mode replication-only`]({% link molt/molt-fetch.md %}#fetch-mode). For details on `--replicator-flags`, refer to [Replication flags](#replication-flags). In this example, the `--metricsAddr :30005` replication flag enables a Prometheus endpoint at `http://localhost:30005/_/varz` where replication metrics will be served. You can use these metrics to [verify that replication has drained](#stop-replication-and-verify-data) in a later step.
+1. Run the [MOLT Fetch]({% link molt/molt-fetch.md %}) command to start replication on CockroachDB, specifying [`--mode replication-only`]({% link molt/molt-fetch.md %}#fetch-mode). In this example, the `--metricsAddr :30005` replication flag enables a Prometheus endpoint at `http://localhost:30005/_/varz` where replication metrics will be served. You can use these metrics to [verify that replication has drained](#stop-replication-and-verify-data) in a later step.
 
 	<section class="filter-content" markdown="1" data-scope="postgres">
 	Be sure to specify the same `--pglogical-replication-slot-name` value that you provided in [Load data into CockroachDB](#load-data-into-cockroachdb).
diff --git a/src/current/molt/migration-overview.md b/src/current/molt/migration-overview.md
@@ -34,7 +34,7 @@ A migration to CockroachDB generally follows this sequence:
 1. Verify consistency before cutover: Use [MOLT Verify]({% link molt/molt-verify.md %}) to confirm that the CockroachDB data is consistent with the source.
 1. Cut over to CockroachDB: Redirect application traffic to the CockroachDB cluster.
 
-Refer to [Migration flows](#migration-flows).
+For more details, refer to [Migration flows](#migration-flows).
 
 ## MOLT tools
 
@@ -115,17 +115,17 @@ For migrations that tolerate downtime, use `data-load` mode to perform a one-tim
 
 ### Migrations with minimal downtime
 
-To minimize downtime during migration, MOLT Fetch supports replication streams that sync ongoing changes from the source database to CockroachDB. Instead of performing the entire data load during a planned downtime window, you can perform an initial load followed by continuous replication. Writes are only briefly paused to allow replication to drain before final cutover. The length of the pause depends on the volume of write traffic and the amount of replication lag between the source and CockroachDB.
+To minimize downtime during migration, MOLT Fetch supports replication streams that continuously synchronize changes from the source database to CockroachDB. Instead of loading all data during a planned downtime window, you can run an initial load followed by continuous replication. Writes are paused only briefly to allow replication to drain before the final cutover. The duration of this pause depends on the volume of write traffic and the replication lag between the source and CockroachDB.
 
 - Use `data-load-and-replication` mode to perform both steps in one task. Refer to [Load and Replicate]({% link molt/migrate-data-load-and-replication.md %}).
 - Use `data-load` followed by `replication-only` to perform the steps separately. Refer to [Load and Replicate Separately]({% link molt/migrate-data-load-replicate-only.md %}).
 
 ### Recovery and rollback strategies
 
-If the migration is interrupted or you need to abort cutover, MOLT Fetch supports safe recovery flows:
+If the migration is interrupted or cutover must be aborted, MOLT Fetch provides safe recovery options:
 
 - Use `replication-only` to resume a previously interrupted replication stream. Refer to [Resume Replication]({% link molt/migrate-replicate-only.md %}).
-- Use `failback` to reverse the migration, syncing changes from CockroachDB back to the original source. This ensures data consistency on the source so that you can retry later. Refer to [Migration Failback]({% link molt/migrate-failback.md %}).
+- Use `failback` to reverse the migration, synchronizing changes from CockroachDB back to the original source. This ensures data consistency on the source so that you can retry the migration later. Refer to [Migration Failback]({% link molt/migrate-failback.md %}).
 
 ## See also
 
diff --git a/src/current/molt/molt-fetch.md b/src/current/molt/molt-fetch.md
@@ -75,7 +75,7 @@ Complete the following items before using MOLT Fetch:
 ## Best practices
 
 {{site.data.alerts.callout_success}}
-To verify that your connections and configuration work properly, run MOLT Fetch in a staging environment before moving any data in production. Use a test or development environment that is as similar as possible to production.
+To verify that your connections and configuration work properly, run MOLT Fetch in a staging environment before migrating any data in production. Use a test or development environment that closely resembles production.
 {{site.data.alerts.end}}
 
 - To prevent connections from terminating prematurely during data export, set the following to high values on the source database:

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		-MOLT Fetch can restrict which schemas (or users) and tables are migrated by using the `--schema-filter`, `--table-filter`, and `--table-exclusion-filter` flags:
	`1`	`+MOLT Fetch can restrict which schemas (or users) and tables are migrated by using the following filter flags:`
`2`	`2`
`3`	`3`	`\| Filter type \| Flag \| Description \|`
`4`	`4`	`\|------------------------\|----------------------------\|-------------------------------------------------------------------------------------------------------------------------------------------------\|`