Upgrade assistant

OceanBase Database V4.x delivers significant improvements in performance and analytical processing (AP). Many customers want to upgrade OceanBase Database cluster instances from earlier versions to V4.x to use the new features. To meet this need, OceanBase Cloud provides Upgrade Assistant, which thoroughly validates compatibility, performance, and feasibility and provides a safe rollback mechanism for a more convenient and efficient upgrade experience.

Upgrade process

Upgrade Assistant does not perform an in-place kernel version upgrade on the source cluster instance. Instead, it completes the upgrade through four phases: Environment assessment, Create tenant, Data migration, and Traffic switching:

1. Environment assessment: The system compares tenant parameters (and optionally instance parameters) between the source and target sides, listing parameters with discrepancies for your confirmation or modification to avoid business behavior changes after the upgrade due to parameter inconsistency.

2. Create tenant: The system creates a tenant with the same name as the source tenant on the prepared V4.x target cluster instance, copies the source tenant's databases and users, and enables the corresponding access addresses for the target tenant based on those enabled for the source tenant.

3. Data migration: A data migration task synchronizes the existing and incremental data from the source tenant to the target tenant.

4. Traffic switching: After source-side sessions are closed and the pre-switch checks are complete, tenant domain name switching begins. The target tenant takes over the source tenant's original access address, and a fixed prefix is added to the source tenant's access address. Applications therefore do not need changes to their database connection configurations. They only need to be restarted to connect to the upgraded tenant.

Limitations

• Upgrade Assistant is an allowlist feature. To use it, contact OceanBase Technical Support.

• Currently, only Alibaba Cloud is supported. Only tenant upgrades are supported; cluster upgrades are not supported.

• Only source tenants of versions 2.x or 3.x can be upgraded to target cluster instances of version 4.x.

• Only transactional tenants are supported. Both MySQL and Oracle compatibility modes are supported.

• Multiple upgrade tasks cannot be created in parallel for the same source tenant.

• The source cluster instance and the target cluster instance must be located in the same region and have the same deployment mode.

Prerequisites

• You have prepared the source cluster instance, source tenant, and target cluster instance.

  The target cluster instance must be version 4.x, with a compatibility mode that matches the source tenant's, and its specifications must be sufficient to host the source tenant's data volume and business workload. To create one, see Create an instance and Create a tenant.

• The allowlist of the target cluster instance already includes the IP addresses from the source cluster instance's allowlist.

  After traffic is switched, business applications will connect to the target tenant. If the target cluster instance's allowlist lacks the application's IP address, the application will be unable to connect. You can reuse the allowlist group configuration from the source cluster instance on the Security Settings page of the target cluster instance by using Import Allowlist Group, eliminating the need to manually enter each item. For details, see Set up allowlist groups.

• You have purchased a data migration instance, or confirmed that there are available data migration tasks under your account.

  Step 4 requires selecting a purchased migration task. If no available migration tasks exist, the process will be interrupted. For details on the purchase method, see Purchase a data migration instance. For recommended specification selection, see Data migration specifications. For billing information, see Data migration billing.

Procedure

An upgrade task progresses through four phases: Environment assessment, Create tenant, Data migration, and Traffic switching. The execution status of each phase is displayed in the upgrade process area of the upgrade task card.

On the Upgrade tasks page, you can view all upgrade tasks under the current project. Information includes the task name, source instance, source tenant, target instance, version upgrade, creation time, and completion time. A flowchart shows the execution status of the task at each phase: Environment assessment, Create tenant, Data migration, and Traffic switching (including Reverse traffic switching when reverse incremental synchronization is enabled).

You can filter tasks by Current stage or Current status in the upper-right corner of the page, or search by task name. The action buttons in the upper-right corner of a card change with the task status: View environment assessment results after environment assessment is complete, Restart task if a phase fails, and View traffic switching details or View reverse traffic switching details after traffic switching is complete.

If a phase fails during the upgrade, you can click Restart task in the upper-right corner of the card to re-execute the failed step without having to recreate the upgrade task.

Step 1: Create upgrade task

1. Log in to the OceanBase Cloud console.

2. In the left-side navigation pane, click Upgrade Assistant.

3. On the Upgrade Assistant page, click Create upgrade task in the upper-right corner of the Upgrade tasks section.

4. In the Create upgrade task panel, configure the following parameters and then click OK.

   Basic information

   Parameter	Description
   Task name	Enter the name of the upgrade task.
   Upgrade scope	Currently, only upgrades at the Tenant level are supported. This value is fixed as Tenant and does not require configuration.
   Source instance	Select the source cluster instance to be upgraded.
   Source tenant	Select the source tenant to be upgraded.
   Target instance	Select a target cluster instance from the drop-down list. Only cluster instances of version 4.x can be used as upgrade targets.

   Environment assessment

   Parameter	Description
   Assessment type	Tenant parameters is the default assessment item. It is selected by default and cannot be deselected. You can optionally select Instance parameters as needed.

Step 2: Perform environment assessment

1. After the environment assessment is complete, click View environment assessment results in the upper-right corner of the upgrade task card.

2. In the pop-up window, open the Confirm target tenant parameter values and Confirm target instance parameter values tabs. If modifications are needed, click the edit button on the corresponding tab.

   Note

   Parameters marked with a yellow icon indicate that the source parameter value has been modified, the source and target parameter values are inconsistent, or the parameter is specific to the target. We recommend that you pay special attention to these parameters.

3. After confirmation, click the cross in the upper-left corner of the pop-up window to close it.

Step 3: Create tenant

1. In the upgrade process section, click Next: Create tenant.

2. In the dialog box that appears, click OK.

3. Wait for the tenant to be created.

Step 4: Data migration

1. In the upgrade process section, click Next step: data migration to create a data migration task.

Step 5: Traffic switching

1. In the upgrade process section, click Next: Traffic switching.

2. In the Load monitoring section at the top of the Traffic switching panel, compare the load data of the source and target tenants to determine when to switch.

   This section displays the following metrics for both the Source tenant and the target tenant (for example, 4.3.5 target tenant):

   • QPS

   • Average SQL Statement Processing Time

   • CPU Percent

3. At the bottom of the panel, complete the following sub-steps in order:

   1. Close the source sessions. Expand the list to view Current active session(s) and Current session(s) in the Source tenant active sessions section. After confirming that the business application is no longer writing data, click Close source sessions. In the confirmation dialog box, click Close.

      Notice

      Closing source sessions will lock all source users. Confirm that the business application is no longer writing data.

   2. Migrate complex objects. Click Start migration. This step migrates the remaining complex objects from the tenant creation step and applies the remaining user privileges to the target.

   3. Pre-switch check. Click Start check. After the check is complete, confirm the check result and decide whether to enable reverse incremental synchronization.

      Notice

      • If reverse incremental synchronization is not enabled, incremental data from the target will not be synchronized to the source database, and reverse traffic switching cannot be performed.
      • This step will disable triggers and foreign keys on the source side, as follows:
        • MySQL-compatible mode: Triggers are dropped, and foreign key checking is disabled.
        • Oracle-compatible mode: Triggers and foreign key constraints are disabled.

   4. Switch application-layer connection(s).

      1. Click Confirm that tenant domain name switching will be enabled. After the switch, the target tenant takes over the source tenant's original access address, and a fixed prefix is added to the source tenant's access address.

      2. Wait for the switching to complete, then restart the application so that it connects to the new tenant without changing the database configuration.

   5. Performance observation. Wait for 30 minutes, and then compare the key performance metrics for the 30-minute periods before and after traffic switching.

      Note

      You can click View more target-side monitoring in the upper-right corner of the Performance observation section to go to the Performance monitoring page and view more monitoring metrics.

4. Click the cross in the upper-left corner of the panel to close it.

5. Evaluate the upgrade effect.

   • If the performance data meets expectations, you can select ... > Disable reverse incremental synchronization in the upgrade process area to end the upgrade process.

     Notice

     After disabling reverse incremental synchronization, incremental data from the target will no longer be synchronized to the source database, and you will no longer be able to perform reverse traffic switching. Please perform this operation only after confirming that business operations are normal.

   • If the performance data does not meet expectations, you can select ... > Reverse traffic switching in the upgrade process area to proceed to the next step.

Step 6 (optional): Perform reverse traffic switching

1. In the upgrade process area, choose ... > Reverse traffic switching.

   Notice

   We recommend that you perform the switching during off-peak hours.

2. In the confirmation dialog box that appears, enter switch and click Switch.

3. In the Load monitoring section at the top of the Reverse traffic switching panel, compare the load data of the source and target tenants to determine when to switch.

   This section displays the QPS, Average SQL Statement Processing Time, and CPU Percent metrics for the source and target tenants.

4. At the bottom of the panel, complete the following substeps in order:

   1. Close target sessions. Expand the list to view the Current active session(s) count in the Target tenant active session(s) section. After confirming that no active sessions remain, click Close target sessions. In the confirmation dialog box, click Close.

      Notice

      All target users will be locked, and all existing database connections will be terminated.

   2. Unlock source users and objects. Click Unlock source objects.

      Note

      This step unlocks the users and restores the triggers and foreign keys that were disabled or dropped during forward traffic switching.

   3. Switch application-layer connection(s). First, click Confirm that tenant domain name switching will be enabled, and then restart the application.

      Note

      After the switch, the access addresses for the source and target tenants revert to their pre-upgrade states.

5. Click the cross in the upper-left corner of the panel to close it.

6. If the Reverse traffic switching node shows a check mark, the rollback to the earlier version is complete. The View reverse traffic switching details option will then appear in the upper-right corner of the task card, allowing you to review the entire reverse switching process.

What to do next

1. Confirm that workloads on the target tenant are running normally and determine whether any O&M configurations on the target need to be reconfigured.

   Step 3 only automatically replicates the databases, users, and access addresses of the source tenant. You need to manually verify configurations such as backup policies, alert rules, and tenant parameters.

2. Check other systems connected to the source tenant.

   After the traffic is switched, the access address of the source tenant will be prefixed with a fixed string. If systems such as data migration, data subscription, Binlog services, or SQL diagnostic tools are connected to the source tenant, update their connection configurations accordingly.

3. Stop or release the data migration tasks used for this upgrade to avoid further charges. For more information, see Stop and release a data migration task.

4. After confirming that rollback is no longer required, release the source cluster instance as needed to avoid charges for both the source and target cluster instances. For more information, see Release an instance.

   Notice

   After releasing the source cluster instance, you cannot roll back to the source tenant. Perform this operation only after your business has been running stably for a period of time and you have confirmed the data is correct.