add Replicator security content; refine includes

Author: taroface

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

@@ -72,4 +72,4 @@ For details, refer to [Connect using a URL]({% link {{site.current_cloud_version
 
 #### Secure connections
 
-{% include molt/fetch-secure-connection-strings.md %}
+{% include molt/molt-secure-connection-strings.md %}

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

@@ -0,0 +1,52 @@
+- To keep your database credentials out of shell history and logs, follow these best practices when specifying your source and target connection strings:
+
+	- Avoid plaintext connection strings.
+
+	- 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 TARGET="postgres://root@localhost:26257/molt?sslmode=verify-full"
+		~~~
+
+		Afterward, reference the environment variables in MOLT commands:
+
+		{% if page.name == "molt-replicator.md" %}
+		~~~
+		--sourceConn $SOURCE
+		--targetConn $TARGET
+		~~~
+		{% else %}
+		~~~
+		--source $SOURCE
+		--target $TARGET
+		~~~
+		{% endif %}
+
+	- If possible, use an external secrets manager to load the environment variables from stored secrets.
+
+- Use TLS-enabled connection strings to encrypt data in transit from MOLT to the database. When using TLS certificates, ensure certificate files are accessible to the MOLT binary on the same machine.
+
+	For example, a PostgreSQL connection string with TLS certificates:
+
+	{% 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
+	~~~
+
+- 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.
+
+	- Given a password `a$52&`, pass it to the `molt escape-password` command with single quotes:
+
+		{% include_cached copy-clipboard.html %}
+		~~~ shell
+		molt escape-password --password 'a$52&'
+		~~~
+
+		Use the encoded password in your connection string. For example:
+
+		~~~
+		postgres://migration_user:a%2452%26@localhost:5432/replicationload
+		~~~
+
+- Remove `sslmode=disable` from production connection strings.

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

@@ -0,0 +1,61 @@
+### Failback issues
+
+If the changefeed shows connection errors in `SHOW CHANGEFEED JOB`:
+
+##### Connection refused
+
+~~~
+transient error: Post "https://replicator-host:30004/molt/public": dial tcp [::1]:30004: connect: connection refused
+~~~
+
+This indicates that Replicator is down, the webhook URL is incorrect, or the port is misconfigured.
+
+**Resolution:** Verify that MOLT Replicator is running on the port specified in the changefeed `INTO` configuration. Confirm the host and port are correct.
+
+##### Unknown schema error
+
+~~~
+transient error: 400 Bad Request: unknown schema:
+~~~
+
+This indicates the webhook URL path is incorrectly formatted. Common causes include using the wrong path format for your target database type or incorrect database names.
+
+**Resolution:** Check the webhook URL path mapping:
+
+- **PostgreSQL targets:** Use `/database/schema` format (for example, `/molt_db/public`).
+- **MySQL/Oracle targets:** Use `/SCHEMA` format (for example, `/MOLT_DB`). Use only the schema name (for example, `molt` instead of `molt/public`).
+
+Verify that the target database and schema names match the webhook URL.
+
+##### GC threshold error
+
+~~~
+batch timestamp * must be after replica GC threshold
+~~~
+
+This indicates starting from an invalid cursor that has been garbage collected.
+
+**Resolution:** Double-check the cursor to ensure it represents a valid range that has not been garbage collected, or extend the GC TTL on the source CockroachDB cluster:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+ALTER DATABASE defaultdb CONFIGURE ZONE USING gc.ttlseconds = {gc_ttl_in_seconds};
+~~~
+
+##### Duplicated data re-application
+
+This occurs when resuming a changefeed from a cursor causes excessive data duplication.
+
+**Resolution:** Clear the staging database to prevent duplication. **This deletes all checkpoints and buffered data**, so use with caution:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+DROP DATABASE _replicator;
+~~~
+
+For more targeted cleanup, delete mutations from specific staging tables:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+DELETE FROM _replicator.employees WHERE true;
+~~~

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

@@ -0,0 +1,64 @@
+### Fetch issues
+
+##### Fetch exits early due to mismatches
+
+`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 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.
+- A source column is nullable, but the corresponding target column is not nullable (i.e., the constraint is more strict on the target).
+
+`molt fetch` can continue in the following cases, and will output a log with a corresponding `mismatch_tag` and `failable_mismatch` set to `false`:
+
+- A target table has a column that is not in the corresponding source table.
+- A source column has a `NOT NULL` constraint, and the corresponding target column is nullable (i.e., the constraint is less strict on the target).
+- A [`DEFAULT`]({% link {{site.current_cloud_version}}/default-value.md %}), [`CHECK`]({% link {{site.current_cloud_version}}/check.md %}), [`FOREIGN KEY`]({% link {{site.current_cloud_version}}/foreign-key.md %}), or [`UNIQUE`]({% link {{site.current_cloud_version}}/unique.md %}) constraint is specified on a target column and not on the source column.
+
+<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'`, 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
+ALTER USER migration_schema QUOTA UNLIMITED ON USERS;
+~~~
+
+##### No tables to drop and recreate on target
+
+When expecting a bulk load but seeing `no tables to drop and recreate on the target`, ensure the migration user has `SELECT` and `FLASHBACK` privileges on each table to be migrated. For example:
+
+~~~ sql
+GRANT SELECT, FLASHBACK ON migration_schema.employees TO C##MIGRATION_USER;
+GRANT SELECT, FLASHBACK ON migration_schema.payments TO C##MIGRATION_USER;
+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 {% if page.name != "migrate-load-replicate.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-load-replicate.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 %}.
+
+##### Oracle sessions remain open after forcefully stopping `molt` or `replicator`
+
+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.
+- 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##MIGRATION_USER';
+    ~~~
+
+    Wait until any remaining sessions display an `INACTIVE` status, then terminate them using:
+
+    ~~~ sql
+    ALTER SYSTEM KILL SESSION 'sid,serial#' IMMEDIATE;
+    ~~~
+
+    Replace `sid` and `serial#` in the preceding statement with the values returned by the `SELECT` query.
+</section>