Merge pull request #476 from percona/ps-9701

[DOCS] - Add Clone limitations 8.0

Author: patrickbirch

docs/clone-plugin-limitations.md

@@ -0,0 +1,23 @@
+# Clone plugin limitations
+
+The clone plugin clones instances within the same series only. It clones from version 8.0.37 to 8.0.42, but not from 8.0 to 8.4. Before the 8.0.37 version, it requires matching point release numbers.
+
+Before version 8.0.27, the clone plugin blocks DDL on the donor and recipient during cloning. This block includes `TRUNCATE TABLE`. Use dedicated donor instances to work around this limitation. DML continues during cloning.
+
+From the 8.0.27 version, the clone plugin allows concurrent DDL on the donor by default. The `clone_block_ddl` variable controls this limit.
+
+The clone plugin clones from a donor to a hotfix instance of the same version from 8.0.26 version onward.
+
+The clone plugin clones one MySQL instance at a time. It does not clone multiple instances in one operation.
+
+The clone plugin does not support the X Protocol port (mysqlx_port) for remote cloning.
+
+The clone plugin does not clone MySQL server configurations. The recipient keeps its own settings.
+
+The clone plugin does not clone binary logs.
+
+The clone plugin clones InnoDB data only. It clones other storage engine tables, like MyISAM and CSV, as empty tables.
+
+The clone plugin does not support connections to the donor through MySQL Router.
+
+Local cloning does not clone general tablespaces created with absolute paths. This prevents file path conflicts.

docs/clone-plugin-overview.md

@@ -0,0 +1,36 @@
+# Clone plugin overview
+
+The Clone plugin lets you clone data from either a local server or from a remote server. The plugin creates a physical snapshot of the data stored in InnoDB, which includes schemas, tables, tablespaces, and data dictionary metadata. The cloned data is a functional data directory and can be used for provisioning a server.
+
+The following table lists the cloning operation types:
+
+| Cloning operation type | Description |
+|---|---|
+| Local | Clones the data from the server where the operation is initiated to either a directory on the same server or a server node. |
+| Remote | Clones the data from the donor to the joiner over the network. |
+
+When replicating a large number of transactions, the Clone plugin may be a more efficient solution. 
+
+## Install the Clone plugin
+
+The Clone plugin must be installed on both the donor and the joiner servers at either server startup or at runtime. To install the plugin at runtime, run the following command:
+
+```{.bash data-prompt="mysql>"}
+mysql> INSTALL PLUGIN clone SONAME 'mysql_clone.so';
+```
+
+Review the INFORMATION_SCHEMA.PLUGINS table or run the `SHOW PLUGINS` command to verify the installation. The following is an example of querying the PLUGINS table.
+
+```{.bash data-prompt="mysql>"}
+mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS FROM INFORMATION_SCHEMA.PLUGINS WHERE PLUGIN_NAME='clone';
+```
+
+The result lists the Clone plugin and the status.
+
+For more information about the Clone plugin, see:
+
+* [Load the Clone plugin](load-clone-plugin.md)
+
+* [Use the Clone plugin](clone-plugin-usage.md)
+
+* [Clone plugin limitations](clone-plugin-limitations.md)

docs/clone-plugin-usage.md

@@ -0,0 +1,66 @@
+# Use the Clone plugin
+
+The Clone plugin in the server enables you to create a physical copy of a server instance. This feature simplifies server provisioning and replication setup. Using the Clone plugin, you can quickly copy data from one server instance (donor) to another (recipient).
+
+## Common scenarios
+
+The following are common scenarios for using the Clone plugin:
+
+| **Scenario**                                     | **Description**                                                      |
+|--------------------------------------------------|----------------------------------------------------------------------|
+| Set up new replicas quickly                      | Without manual data copying                                          |
+| Bootstrap new Group Replication members          | Efficiently add new members to the group                             |
+| Create physical backups                          | With minimal performance impact                                      |
+| Build test environments                          | Mirror production data for accurate testing                          |
+| Provision new MySQL server instances             | Quickly set up new servers with existing data                        |
+| Perform local cloning                            | Clone data within the same server for testing or backup purposes     |
+| Clone encrypted and compressed data              | Support for cloning encrypted and page-compressed data               |
+
+The Clone Plugin significantly reduces the time needed to create full server instance copies compared to traditional backup and restore methods.
+
+## Local clone on the same server
+
+To clone data to a different directory on the same server:
+
+```{.bash data-prompt="mysql>"}
+mysql> CLONE LOCAL DATA DIRECTORY = '/path/to/destination/directory';
+```
+
+This command creates a full copy of all databases in the source directory.
+
+## Remote cloning to copy data between servers
+
+On the source server, create a user with the necessary privileges:
+
+```{.bash data-prompt="mysql>"}
+mysql> CLONECREATE USER clone_user@'%' IDENTIFIED BY 'password';
+mysql> GRANT CLONE_ADMIN ON *.* TO clone_user@'%';
+```
+
+On the target server, run the clone command:
+
+```{.bash data-prompt="mysql>"}
+mysql> CLONE INSTANCE FROM 'clone_user'@'donor_host':3306 
+IDENTIFIED BY 'password';
+```
+
+The destination server will shut down, replace its data, and restart automatically.
+
+## Monitor clone operations
+
+Check the status of ongoing and completed clone operations:
+
+```{.bash data-prompt="mysql>"}
+mysql> SELECT * FROM performance_schema.clone_status;
+mysql> SELECT * FROM performance_schema.clone_progress;
+```
+
+Additional details are recorded in the server error log.
+
+For more information about the Clone plugin, see:
+
+* [Clone plugin overview](clone-plugin-overview.md)
+
+* [Load the Clone plugin](load-clone-plugin.md)
+
+* [Clone plugin limitations](clone-plugin-limitations.md)

docs/load-clone-plugin.md

@@ -0,0 +1,51 @@
+# Load the Clone plugin
+    
+You cannot use the `--plugin-load-add` option to load the clone plugin during an upgrade from a previous MySQL version. Attempting to do so will raise an error. Upgrade the server first, then start it with `plugin-load-add=mysql_clone.so`.
+
+## Load the plugin
+
+Locate the Plugin Library File: Ensure the plugin library file (`mysql_clone.so`) is in the MySQL plugin directory (`plugin_dir` system variable). Set `plugin_dir` at server startup if necessary.
+
+=== "At server startup"
+
+    Load the Plugin at Server Startup: Use the `--plugin-load-add` option to name the library file. Add the following lines to your `my.cnf` file:
+    
+      ```ini
+      [mysqld]
+      plugin-load-add=mysql_clone.so
+      ```
+      Restart the server to apply the new settings.
+      
+  
+=== "At runtime"
+
+    Load the Plugin at Runtime: Alternatively, you can load the plugin at runtime with the following SQL statement:
+    
+      ```sql
+      INSTALL PLUGIN clone SONAME 'mysql_clone.so';
+      ```
+      
+      This command loads the plugin and registers it in the `mysql.plugins` table, ensuring it loads automatically at subsequent server startups without `--plugin-load-add`.
+
+## Verify Plugin installation
+
+Check the `INFORMATION_SCHEMA.PLUGINS` table or use the `SHOW PLUGINS` statement to verify the plugin installation:
+
+```sql
+SELECT PLUGIN_NAME, PLUGIN_STATUS
+FROM INFORMATION_SCHEMA.PLUGINS
+WHERE PLUGIN_NAME = 'clone';
+```
+If the plugin fails to initialize, check the server error log for diagnostic messages.
+
+## Control plugin activation state
+
+If the plugin is registered with `INSTALL PLUGIN` or loaded with `--plugin-load-add`, use the `--clone` option at server startup to control its activation state. To load the plugin at startup and prevent it from being removed at runtime, add these options:
+
+```ini
+[mysqld]
+plugin-load-add=mysql_clone.so
+clone=FORCE_PLUS_PERMANENT
+```
+   
+To prevent the server from running without the clone plugin, use `--clone` with `FORCE` or `FORCE_PLUS_PERMANENT`. These options ensure the server startup fails if the plugin does not initialize successfully.

mkdocs-base.yml

@@ -292,6 +292,12 @@ nav:
   - Manage:
       - extended-show-grants.md
       - uninstall-component.md
+      - Plugins:
+        - MySQL Clone plugin:
+          - clone-plugin-overview.md
+          - load-clone-plugin.md
+          - clone-plugin-usage.md
+          - clone-plugin-limitations.md
   - Back up and restore:
       - backup-restore-overview.md
       - backup-locks.md