All Products
Search

This Product

    ApsaraDB RDS:[Discontinued] Convert the TokuDB engine to the InnoDB engine

    Document Center

    ApsaraDB RDS:[Discontinued] Convert the TokuDB engine to the InnoDB engine

    Last Updated:Jul 15, 2026

    As of August 1, 2019, ApsaraDB RDS for MySQL no longer supports the TokuDB storage engine. This topic describes how to convert tables from the TokuDB engine to the InnoDB engine.

    Background

    Percona has discontinued support for TokuDB. This means that known bugs cannot be fixed and may cause business disruptions. For this reason, Alibaba Cloud removed support for the TokuDB storage engine in ApsaraDB RDS for MySQL on August 1, 2019. Directly converting the storage engine blocks DML operations and can impact concurrency. Evaluate your business requirements and choose one of the following solutions to perform the conversion.

    TokuDB engine discontinuation date

    August 1, 2019

    Applicability

    Instances that use the TokuDB storage engine.

    Note

    You can run the show engines; command to view the default storage engine of the instance, or run the show create table <table_name>; command to view the storage engine of a specific table.

    Precautions

    • Converting the storage engine increases storage usage. You must reserve free space that is approximately twice the size of the TokuDB tables you are converting. Monitor your storage usage closely during the operation.

    • After the conversion, CPU utilization decreases, but IOPS increases. This is because the data pages are not compressed, so reading the same amount of data requires more I/O operations.

    • When you perform a full migration, you must switch the application endpoint. We recommend that you perform this operation during off-peak hours to minimize business impact.

    • If you change the database version during a full migration, we recommend that you perform a compatibility test in advance.

    Recommended solutions

    • Use Solution 1 if your tables are small (under 100 MB) and your application can tolerate a short period of downtime. This method has a brief table lock time and avoids complex tool configurations.

    • Use Solution 2 or Solution 3 if your tables are large (over 5 GB).

    • Use Solution 3 or Solution 4 if you need to convert all tables in the instance.

    • After you convert the engine, change the default_storage_engine instance parameter to InnoDB.

    Solution 1

    This solution converts the engine directly by using an ALTER TABLE statement. It is the simplest method but blocks DML operations on the table, which can be time-consuming for large tables.

    1. Log on to the ApsaraDB RDS database by using Data Management (DMS).

    2. In the top navigation bar, choose sql operations > sql window.

    3. Run the following command: 

      ALTER TABLE test.testfs ENGINE=innodb;
      【执行SQL：(1)】
Alter table test.testfs engine innodb
执行成功, 耗时: [18185ms.]

    Solution 2

    This solution uses a third-party online schema change tool to perform the conversion with minimal downtime. Many tools support online DDL, such as Percona's pt-osc and GitHub's gh-ost. This section uses gh-ost as an example. For detailed information, see the official gh-ost documentation.

    How it works

    gh-ost operates by creating a temporary "ghost" table with the same schema as the original table. It copies all data from the original table and then, by simulating replication, reads the binary log to synchronize incremental changes to the ghost table in real time. Finally, during off-peak hours, it performs a cutover by renaming the tables. The main performance impact is the I/O load during the initial data copy, which can be throttled by using parameters.

    • Advantages: Flexible and controllable, allowing you to schedule the cutover.

    • Disadvantages: Requires running a command for each table, which can be cumbersome if you have many tables.

    Parameters

    Parameter

    Description

    --initially-drop-old-table

    Checks for and deletes the leftover table from a previous failed migration.

    --initially-drop-ghost-table

    Checks for and deletes the existing ghost table.

    --aliyun-rds

    Specifies that the operation is performed on an Alibaba Cloud ApsaraDB RDS for MySQL instance.

    --assume-rbr

    Specifies that the binary log format is row-based replication (RBR).

    --allow-on-master

    Allows gh-ost to run on a primary database.

    --assume-master-host

    The endpoint of the primary database.

    --user

    The database account name.

    --password

    The database password.

    --host

    The endpoint of the database. This must be the same as the primary database endpoint.

    --database

    The database name.

    --table

    The table name.

    --alter

    The DDL statement to run.

    --chunk-size

    The number of rows to copy in each batch.

    --postpone-cut-over-flag-file

    A file that indicates the cutover is postponed. Delete this file to immediately initiate the table cutover.

    --panic-flag-file

    If this file is created, the gh-ost process stops immediately.

    --serve-socket-file

    The socket file for receiving interactive commands.

    --execute

    Runs the operation.

    Prerequisites

    • gh-ost is installed on your on-premises host or Elastic Compute Service (ECS) instance.

    • The IP address of the on-premises host or ECS instance is added to the IP address whitelist of the ApsaraDB RDS instance.

    Procedure

    1. On your on-premises host or ECS instance, run the following command to start the conversion and wait for the process to complete. 

      gh-ost --user="test01" --password="Test123456" --host="rm-bpxxxxx.mysql.rds.aliyuncs.com"  --database="test" --table="testfs"  --alter="engine=innodb" --initially-drop-old-table --initially-drop-ghost-table --aliyun-rds --assume-rbr --allow-on-master --assume-master-host="rm-bpxxxxx.mysql.rds.aliyuncs.com" --chunk-size=500 --postpone-cut-over-flag-file="/tmp/ghostpost.postpone" --panic-flag-file="/tmp/stop.flag" --serve-socket-file="/tmp/ghost.sock" --execute
      2019/06/13 17:22:51 binlogsyncer.go:79: [info] create BinlogSyncer with config {999
2019/06/13 17:22:51 binlogsyncer.go:246: [info] begin to sync binlog from position
2019/06/13 17:22:51 binlogsyncer.go:139: [info] register slave for master server rm
2019/06/13 17:22:51 binlogsyncer.go:573: [info] rotate to (mysql-bin.000014, 241268
# Migrating `test`.`testfs`; Ghost table is `test`.`_testfs_gho`
# Migrating `xxx`.`xxx`; xxx xxx rds.aliyuncs.com:3306; inspecting xxx
# Migration started at Thu Jun 13 17:22:50 +0800 2019
# chunk-size: 500; max-lag-millis: 1500ms; dml-batch-size: 10; max-load: ; critical
# throttle-additional-flag-file: /tmp/gh-ost.throttle
# postpone-cut-over-flag-file: /tmp/ghostpost.postpone [set]
# panic-flag-file: /tmp/stop.flag
# Serving on unix socket: /tmp/ghost.sock
Copy: 0/100000 0.0%; Applied: 0; Backlog: 0/1000; Time: 0s(total), 0s(copy); stream
Copy: 0/100000 0.0%; Applied: 0; Backlog: 0/1000; Time: 1s(total), 1s(copy); stream
Copy: 1500/100000 1.5%; Applied: 0; Backlog: 0/1000; Time: 2s(total), 2s(copy); str
Copy: 3000/100000 3.0%; Applied: 0; Backlog: 0/1000; Time: 3s(total), 3s(copy); str
Copy: 5500/100000 5.5%; Applied: 0; Backlog: 0/1000; Time: 4s(total), 4s(copy); str
Copy: 7500/100000 7.5%; Applied: 0; Backlog: 0/1000; Time: 5s(total), 5s(copy); str
Copy: 9000/100000 9.0%; Applied: 0; Backlog: 0/1000; Time: 6s(total), 6s(copy); str
Copy: 10500/100000 10.5%; Applied: 0; Backlog: 0/1000; Time: 7s(total), 7s(copy); s
Copy: 13500/100000 13.5%; Applied: 0; Backlog: 0/1000; Time: 8s(total), 8s(copy); s
Copy: 15500/100000 15.5%; Applied: 0; Backlog: 0/1000; Time: 9s(total), 9s(copy); s
Copy: 17500/100000 17.5%; Applied: 0; Backlog: 0/1000; Time: 10s(total), 10s(copy);

    2. Log on to the ApsaraDB RDS database by using Data Management (DMS).

    3. In the left-side navigation pane, view the tables. You will see temporary tables that end with _gho and _ghc. After logging on, in the table list of the test database, you can see the temporary tables _testfs_ghc and _testfs_gho created by gh-ost, indicating that the conversion is in progress.

    4. Run the rm /tmp/ghostpost.postpone command to initiate the table cutover. The following output is displayed.

      Copy: 100000/100000 100.0%; Applied: 0; Backlog: 0/1000; Time: 9m0s(total), 56s(copy); streamer: mysql-bin.000015:520562237;
Copy: 100000/100000 100.0%; Applied: 0; Backlog: 0/1000; Time: 9m30s(total), 56s(copy); streamer: mysql-bin.000015:520674422;
# Migrating `test`.`testfs`; Ghost table is `test`.`_testfs_gho`
# Migrating xxx xxx xxx mysql.rds.aliyuncs.com:3306; inspecting xxx xxx xxx xxx mysql.rds.aliyuncs.com:3306
# Migration started at Thu Jun 13 17:22:50 +0800 2019
# chunk-size: 500; max-lag-millis: 1500ms; dml-batch-size: 10; max-load: ; critical-load: ; nice-ratio: 0.000000
# throttle-additional-flag-file: /tmp/gh-ost.throttle
# postpone-cut-over-flag-file: /tmp/ghostpost.postpone
# panic-flag-file: /tmp/stop.flag
# Serving on unix socket: /tmp/ghost.sock
Copy: 100000/100000 100.0%; Applied: 0; Backlog: 0/1000; Time: 9m31s(total), 56s(copy); streamer: mysql-bin.000015:520681377;
2019/06/13 17:32:23 binlogsyncer.go:107: [info] syncer is closing...
2019/06/13 17:32:23 binlogstreamer.go:47: [error] close sync with err: sync is been closing...
2019/06/13 17:32:23 binlogsyncer.go:122: [info] syncer is closed
      Note

      You can ignore the error message in the output. The cutover is complete.

    5. Check the table schema and verify the data.

      Note

      After you confirm that the data is correct, you can delete the _del table.

      Run show create table `testfs`; to view the table schema and confirm that the AUTO_INCREMENT value is 100001, which indicates that all data has been retained.

    Solution 3

    This solution uses Alibaba Cloud Data Transmission Service (DTS) to synchronize data from the original table to a temporary table that uses the InnoDB engine. You then perform a table rename during off-peak hours. This solution is suitable for converting a large number of tables simultaneously.

    1. Log on to the ApsaraDB RDS database by using Data Management (DMS).

    2. In the top navigation bar, choose sql operations > sql window.

    3. Run the following command to create a temporary table that uses the InnoDB engine: 

      CREATE TABLE `testfs_tmp` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `vc` varchar(8000) DEFAULT NULL,
  PRIMARY KEY (`id`)
) ENGINE=innodb  DEFAULT CHARSET=utf8;

    4. Purchase a data synchronization instancePurchase a data synchronization instance.

      Note

      Data synchronization instances are a paid service. For more information, see Data Transmission Service Pricing.

    5. In the left-side navigation pane of the DTS console, click Data Synchronization.

    6. Find the data synchronization instance that you purchased and click Configure synchronization channel in the Actions column.

    7. Configure the source and destination instances.

      Section

      Parameter

      Description

      Source instance details

      Instance type

      Select RDS Instance.

      Instance ID

      Select the RDS instance that contains the TokuDB tables you want to convert.

      Encryption

      Select Non-encrypted or SSL-encrypted. If you select SSL-encrypted, you must first enable SSL encryption. This option significantly increases CPU utilization.

      Destination instance details

      Instance type

      Select RDS Instance.

      Instance ID

      Select the RDS instance that contains the TokuDB tables you want to convert.

      Encryption

      Select Non-encrypted or SSL-encrypted. If you select SSL-encrypted, you must first enable SSL encryption. This option significantly increases CPU utilization.

      The page also includes a Synchronization job name field and an Instance region drop-down list (for example, China (Hangzhou)). After the configuration, click Set whitelist and next.

    8. Click Set whitelist and next.

    9. Wait for the synchronization account to be created, and then click Next.

    10. Configure the synchronization objects: Set Synchronization type to One-way synchronization (DML+DDL), and set the Processing mode for existing destination tables to Pre-check and report errors. In the Source objects pane on the left, select the testfs table in the test002 database, move it to the Selected objects pane on the right, hover over the object, and then click Edit.

    11. Change the Database Name to the previously created testfs_tmp, and click OK.

    12. Click Next.

    13. Select only initial full data synchronization (do not select Schema migration) and click Precheck.

    14. Wait for the precheck to complete, and then click Close.

    15. Wait until the data synchronization latency is 0 ms. The synchronization task status changes to Synchronizing, indicating that data synchronization has started.

    16. In the DMS SQL window, run the following command to switch the table names: 

      RENAME TABLE `testfs` TO `testfs_del`, `testfs_tmp` TO `testfs`;
      Note

      • After the tables are switched, the DTS task reports an error. This is expected.

      • After you verify the data, release the data synchronization instance as soon as possible to avoid further charges.

    Solution 4

    This solution uses DTS to perform a full migration of the database to a new instance. This approach is suitable if you also plan to upgrade the instance or if your application can tolerate a longer downtime for the cutover.

    1. Export the schema as CREATE TABLE statements from the source instance. In the script, modify the ENGINE clause for each table.

      Note

      For example, change create table t1(id int,name varchar(10)) engine=tokudb; to create table t1(id int,name varchar(10)) engine=innodb;.

    2. Create an ApsaraDB RDS for MySQL instance, and then run the modified script to create the database and tables with the InnoDB engine.

    3. Use DTS to synchronize data from the source instance to the new instancesynchronize data from the source instance to the new instance.

      Note

      When you configure the DTS task, select only initial full data synchronization.

    4. After you confirm that the synchronization latency is zero, switch your application's endpoint to the new instance.