clarifications and corrections

Author: taroface

src/current/_includes/molt/fetch-data-load-output.md

@@ -1,6 +1,14 @@
 1. Check the output to observe `fetch` progress. 
 
 	{% if page.name == "migrate-load-replicate.md" %}
+	<section class="filter-content" markdown="1" data-scope="postgres">
+	If you included the `--pglogical-publication-and-slot-drop-and-recreate` flag, a publication named `molt_fetch` is automatically created:
+
+	~~~ json
+	{"level":"info","time":"2025-02-10T14:28:11-05:00","message":"dropping and recreating publication molt_fetch"}
+	~~~
+	</section>
+
 	<section class="filter-content" markdown="1" data-scope="oracle">
 	The following message shows the appropriate values for the `--backfillFromSCN` and `--scn` replication flags to use when [starting Replicator](#start-replicator):
 

src/current/_includes/molt/migration-prepare-database.md

@@ -165,7 +165,20 @@ Connect to the primary instance (PostgreSQL primary, MySQL primary/master, or Or
 {{site.data.alerts.end}}
 
 <section class="filter-content" markdown="1" data-scope="postgres">
-Verify that you are connected to the primary server by running `SELECT pg_is_in_recovery();` and getting a `false` result.
+Verify that you are connected to the primary server:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SELECT pg_is_in_recovery();
+~~~
+
+You should get a false result:
+
+~~~
+ pg_is_in_recovery
+-------------------
+ f
+~~~
 
 Enable logical replication by setting `wal_level` to `logical` in `postgresql.conf` or in the SQL shell. For example:
 

src/current/_includes/molt/migration-prepare-schema.md

@@ -2,13 +2,13 @@
 
 #### Schema Conversion Tool
 
-The [MOLT Schema Conversion Tool]({% link cockroachcloud/migrations-page.md %}) (SCT) automates target schema creation. It requires a free [CockroachDB {{ site.data.products.cloud }} account]({% link cockroachcloud/create-an-account.md %}).
+The [MOLT Schema Conversion Tool]({% link cockroachcloud/migrations-page.md %}) (SCT) converts source table definitions to CockroachDB-compatible syntax. It requires a free [CockroachDB {{ site.data.products.cloud }} account]({% link cockroachcloud/create-an-account.md %}).
 
-1. Upload a source `.sql` file to convert the syntax and identify [unimplemented features and syntax incompatibilities]({% link molt/migration-strategy.md %}#unimplemented-features-and-syntax-incompatibilities) in the schema.
+1. Upload a source `.sql` file to convert the syntax and identify [unimplemented features and syntax incompatibilities]({% link molt/migration-strategy.md %}#unimplemented-features-and-syntax-incompatibilities) in the table definitions.
 
-1. Import the converted schema to a CockroachDB cluster:
-	- When migrating to CockroachDB {{ site.data.products.cloud }}, the Schema Conversion Tool automatically [applies the converted schema to a new {{ site.data.products.cloud }} database]({% link cockroachcloud/migrations-page.md %}#migrate-the-schema).
-	- When migrating to a {{ site.data.products.core }} CockroachDB cluster, [export a converted schema file]({% link cockroachcloud/migrations-page.md %}#export-the-schema) and pipe the [data definition language (DDL)]({% link {{ site.current_cloud_version }}/sql-statements.md %}#data-definition-statements) directly into [`cockroach sql`]({% link {{ site.current_cloud_version }}/cockroach-sql.md %}).
+1. Import the converted table definitions to a CockroachDB cluster:
+	- When migrating to CockroachDB {{ site.data.products.cloud }}, the Schema Conversion Tool automatically [applies the converted table definitions to a new {{ site.data.products.cloud }} database]({% link cockroachcloud/migrations-page.md %}#migrate-the-schema).
+	- When migrating to a {{ site.data.products.core }} CockroachDB cluster, [export a converted DDL file]({% link cockroachcloud/migrations-page.md %}#export-the-schema) and pipe the [data definition language (DDL)]({% link {{ site.current_cloud_version }}/sql-statements.md %}#data-definition-statements) directly into [`cockroach sql`]({% link {{ site.current_cloud_version }}/cockroach-sql.md %}).
 
 <section class="filter-content" markdown="1" data-scope="mysql">
 Syntax that cannot automatically be converted will be displayed in the [**Summary Report**]({% link cockroachcloud/migrations-page.md %}?filters=mysql#summary-report). These may include the following:
@@ -28,7 +28,7 @@ Identifiers are case-sensitive in MySQL and [case-insensitive in CockroachDB]({%
 The MySQL [`AUTO_INCREMENT`](https://dev.mysql.com/doc/refman/8.0/en/example-auto-increment.html) attribute, which creates sequential column values, is not supported in CockroachDB. When [using the Schema Conversion Tool]({% link cockroachcloud/migrations-page.md %}?filters=mysql#convert-a-schema), columns with `AUTO_INCREMENT` can be converted to use [sequences]({% link {{ site.current_cloud_version }}/create-sequence.md %}), `UUID` values with [`gen_random_uuid()`]({% link {{ site.current_cloud_version }}/functions-and-operators.md %}#id-generation-functions), or unique `INT8` values using [`unique_rowid()`]({% link {{ site.current_cloud_version }}/functions-and-operators.md %}#id-generation-functions). Cockroach Labs does not recommend using a sequence to define a primary key column. For more information, refer to [Unique ID best practices]({% link {{ site.current_cloud_version }}/performance-best-practices-overview.md %}#unique-id-best-practices).
 
 {{site.data.alerts.callout_info}}
-Changing a column type during schema conversion will cause [MOLT Verify]({% link molt/molt-verify.md %}) to identify a type mismatch during data validation. This is expected behavior.
+Changing a column type during table definition conversion will cause [MOLT Verify]({% link molt/molt-verify.md %}) to identify a type mismatch during data validation. This is expected behavior.
 {{site.data.alerts.end}}
 
 ##### `ENUM` type

src/current/_includes/molt/molt-connection-strings.md

@@ -18,7 +18,7 @@ The source connection **must** point to the primary instance (PostgreSQL primary
 For example:
 
 ~~~
---source 'postgres://migration_user:password@localhost:5432/molt?sslmode=verify-full'
+--source 'postgres://migration_user:password@localhost:5432/source_database?sslmode=verify-full'
 ~~~
 </section>
 
@@ -30,7 +30,7 @@ For example:
 For example:
 
 ~~~
---source 'mysql://migration_user:password@localhost/molt?sslcert=.%2fsource_certs%2fclient.root.crt&sslkey=.%2fsource_certs%2fclient.root.key&sslmode=verify-full&sslrootcert=.%2fsource_certs%2fca.crt'
+--source 'mysql://migration_user:password@localhost/source_database?sslcert=.%2fsource_certs%2fclient.root.crt&sslkey=.%2fsource_certs%2fclient.root.key&sslmode=verify-full&sslrootcert=.%2fsource_certs%2fca.crt'
 ~~~
 </section>
 

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

@@ -67,12 +67,12 @@ When testing locally, specify the host as follows:
 
     {% if page.name == "molt-replicator.md" %}
     ~~~
-    --sourceConn 'postgres://postgres:[email protected]:5432/molt?sslmode=disable'
+    --sourceConn 'postgres://postgres:[email protected]:5432/source_database?sslmode=disable'
     --targetConn "postgres://[email protected]:26257/defaultdb?sslmode=disable"
     ~~~
     {% else %}
     ~~~
-    --source 'postgres://postgres:[email protected]:5432/molt?sslmode=disable'
+    --source 'postgres://postgres:[email protected]:5432/source_database?sslmode=disable'
     --target "postgres://[email protected]:26257/defaultdb?sslmode=disable"
     ~~~
     {% endif %}
@@ -81,12 +81,12 @@ When testing locally, specify the host as follows:
 
     {% if page.name == "molt-replicator.md" %}
     ~~~
-    --sourceConn 'postgres://postgres:[email protected]:5432/molt?sslmode=disable'
+    --sourceConn 'postgres://postgres:[email protected]:5432/source_database?sslmode=disable'
     --targetConn "postgres://[email protected]:26257/defaultdb?sslmode=disable"
     ~~~
     {% else %}
     ~~~
-    --source 'postgres://postgres:[email protected]:5432/molt?sslmode=disable'
+    --source 'postgres://postgres:[email protected]:5432/source_database?sslmode=disable'
     --target "postgres://[email protected]:26257/defaultdb?sslmode=disable"
     ~~~
     {% endif %}

src/current/_includes/molt/molt-secure-connection-strings.md

@@ -5,7 +5,7 @@
 	- Provide your connection strings as environment variables. For example:
 
 		~~~ shell
-		export SOURCE="postgres://migration_user:a%2452%26@localhost:5432/molt?sslmode=verify-full"
+		export SOURCE="postgres://migration_user:a%2452%26@localhost:5432/source_database?sslmode=verify-full"
 		export TARGET="postgres://root@localhost:26257/defaultdb?sslmode=verify-full"
 		~~~
 
@@ -31,7 +31,7 @@
 
 	{% include_cached copy-clipboard.html %}
 	~~~
-	postgresql://[email protected]:5432/appdb?sslmode=verify-full&sslrootcert=/etc/molt/certs/ca.pem&sslcert=/etc/molt/certs/client.crt&sslkey=/etc/molt/certs/client.key
+	postgresql://[email protected]:5432/appdb?sslmode=verify-full&sslrootcert=/etc/source_database/certs/ca.pem&sslcert=/etc/source_database/certs/client.crt&sslkey=/etc/source_database/certs/client.key
 	~~~
 
 - URL-encode connection strings for the source database and [CockroachDB]({% link {{site.current_cloud_version}}/connect-to-the-database.md %}) so special characters in passwords are handled correctly.
@@ -46,7 +46,7 @@
 		Use the encoded password in your connection string. For example:
 
 		~~~
-		postgres://migration_user:a%2452%26@localhost:5432/molt
+		postgres://migration_user:a%2452%26@localhost:5432/source_database
 		~~~
 
 - Remove `sslmode=disable` from production connection strings.

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

@@ -2,13 +2,14 @@ Configure the following [MOLT Replicator]({% link molt/replicator-flags.md %}) f
 
 {% if page.name == "migrate-load-replicate.md" %}
 <section class="filter-content" markdown="1" data-scope="postgres">
-|           Flag          |                                                                              Description                                                                               |
-|-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| [`--slotName`]({% link molt/replicator-flags.md %}#slot-name)            | **Required.** PostgreSQL replication slot name. Must match the slot name specified with `--pglogical-replication-slot-name` in the [MOLT Fetch command](#start-fetch). |
-| [`--targetSchema`]({% link molt/replicator-flags.md %}#target-schema)        | **Required.** Target schema name on CockroachDB where tables will be replicated. Schema name must be fully qualified in the format `database.schema`.                  |
-| [`--stagingSchema`]({% link molt/replicator-flags.md %}#staging-schema)       | **Required.** Staging schema name on CockroachDB for replication metadata and checkpoints. Schema name must be fully qualified in the format `database.schema`.        |
-| [`--stagingCreateSchema`]({% link molt/replicator-flags.md %}#staging-create-schema) | Automatically create the staging schema if it does not exist. Include this flag when starting replication for the first time.                                          |
-| [`--metricsAddr`]({% link molt/replicator-flags.md %}#metrics-addr)         | Enable Prometheus metrics at a specified `{host}:{port}`. Metrics are served at `http://{host}:{port}/_/varz`.                                                         |
+|                                         Flag                                         |                                                                                                       Description                                                                                                        |
+|--------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [`--slotName`]({% link molt/replicator-flags.md %}#slot-name)                        | **Required.** PostgreSQL replication slot name. Must match the slot name specified with `--pglogical-replication-slot-name` in the [MOLT Fetch command](#start-fetch).                                                   |
+| [`--publicationName`]({% link molt/replicator-flags.md %}#publication-name)          | **Required.** PostgreSQL publication name. Must match the publication name created either manually or automatically with `--pglogical-publication-and-slot-drop-and-recreate` in the [MOLT Fetch command](#start-fetch). |
+| [`--targetSchema`]({% link molt/replicator-flags.md %}#target-schema)                | **Required.** Target schema name on CockroachDB where tables will be replicated. Schema name must be fully qualified in the format `database.schema`.                                                                    |
+| [`--stagingSchema`]({% link molt/replicator-flags.md %}#staging-schema)              | **Required.** Staging schema name on CockroachDB for replication metadata and checkpoints. Schema name must be fully qualified in the format `database.schema`.                                                          |
+| [`--stagingCreateSchema`]({% link molt/replicator-flags.md %}#staging-create-schema) | Automatically create the staging schema if it does not exist. Include this flag when starting replication for the first time.                                                                                            |
+| [`--metricsAddr`]({% link molt/replicator-flags.md %}#metrics-addr)                  | 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">

src/current/_includes/molt/verify-output.md

@@ -48,7 +48,7 @@
 	{"level":"info","time":"2025-02-10T15:35:04-05:00","message":"starting verify on public.employees, shard 1/1"}
 	~~~
 
-	A `finished row verification` message containing a summary is written after each table is compared. For details on the summary fields, refer to the [MOLT Verify]({% link molt/molt-verify.md %}#usage) page.
+	A `finished row verification` message is written after each table is compared. If `num_success` equals `num_truth_rows` and the error counters (`num_missing`, `num_mismatch`, `num_extraneous`, and `num_column_mismatch`) are all `0`, the table verified successfully. Any non-zero values in the error counters indicate data discrepancies that need investigation. For details on each field, refer to the [MOLT Verify]({% link molt/molt-verify.md %}#usage) page.
 
 	~~~ json
 	{"level":"info","type":"summary","table_schema":"public","table_name":"employees","num_truth_rows":200004,"num_success":200004,"num_conditional_success":0,"num_missing":0,"num_mismatch":0,"num_extraneous":0,"num_live_retry":0,"num_column_mismatch":0,"time":"2025-02-10T15:35:05-05:00","message":"finished row verification on public.employees (shard 1/1)"}

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

@@ -148,7 +148,7 @@ MOLT Fetch captures a consistent point-in-time checkpoint at the start of the da
 {{site.data.alerts.end}}
 
 <section class="filter-content" markdown="1" data-scope="postgres">
-1. Run the `replicator` command, using the same slot name that you specified with `--pglogical-replication-slot-name` in the [Fetch command](#start-fetch). Use `--stagingSchema` to specify a unique name for the staging database, and include `--stagingCreateSchema` to have MOLT Replicator automatically create the staging database:
+1. Run the `replicator` command, using the same slot name that you specified with `--pglogical-replication-slot-name` and the publication name created by `--pglogical-publication-and-slot-drop-and-recreate` in the [Fetch command](#start-fetch). Use `--stagingSchema` to specify a unique name for the staging database, and include `--stagingCreateSchema` to have MOLT Replicator automatically create the staging database:
 
 	{% include_cached copy-clipboard.html %}
 	~~~ shell
@@ -157,6 +157,7 @@ MOLT Fetch captures a consistent point-in-time checkpoint at the start of the da
 	--targetConn $TARGET \
 	--targetSchema defaultdb.migration_schema \
 	--slotName molt_slot \
+	--publicationName molt_fetch \
 	--stagingSchema defaultdb._replicator \
 	--stagingCreateSchema \
 	--metricsAddr :30005 \