Documentation Home
MySQL Shell 9.5
Download this Manual
PDF (US Ltr) - 2.5Mb
PDF (A4) - 2.5Mb


MySQL Shell 9.5  / MySQL AdminAPI  /  Upgrade Metadata Schema

6.10 Upgrade Metadata Schema

As AdminAPI evolves, some releases might require you to upgrade the metadata of existing ClusterSets, ReplicaSets, and Clusters to ensure they are compatible with newer versions of MySQL Shell. For example, the addition of InnoDB ReplicaSet in version 8.0.19 means that the metadata schema has been upgraded to version 2.0. Regardless of whether you plan to use InnoDB ReplicaSet or not, to use MySQL Shell 8.0.19 or later with a cluster deployed using an earlier version of MySQL Shell, you must upgrade the metadata of your Cluster.

Warning

Without upgrading the metadata you cannot use MySQL Shell to change the configuration of a cluster created with earlier versions. For example, you can only perform read operations against the cluster such as:

  • Cluster.status()

  • Cluster.describe()

  • Cluster.options()

Thedba.upgradeMetadata() operation compares the version of the metadata schema found on the ClusterSet, ReplicaSet, or InnoDB Cluster that MySQL Shell is currently connected to, with the version of the metadata schema supported by this MySQL Shell version. If the metadata found version is lower, an upgrade process is started. Thedba.upgradeMetadata() function then updates any automatically created MySQL Router users to have the correct privileges. Manually created MySQL Router users with a name not starting withmysql_router_ are not automatically upgraded. This is an important step in upgrading your ClusterSet, ReplicaSet, or InnoDB Cluster, only then can the MySQL Router metadata be upgraded. To view information on which of the MySQL Router instances registered with a ClusterSet, ReplicaSet, or Cluster require the metadata upgrade, use the.listRouters() function. For example, to list the Router instances associated with a Cluster, using the assigned variablecluster issue:

cluster.listRouters({'onlyUpgradeRequired':'true'}){    "clusterName": "mycluster",    "routers": {        "example.com::": {            "hostname": "example.com",            "lastCheckIn": "2019-11-26 10:10:37",            "roPort": 6447,            "roXPort": 64470,            "rwPort": 6446,            "rwXPort": 64460,            "version": "8.0.18"        }    }}

In this example, theonlyUpgradeRequired options is included in thelistRouters() function. TheonlyUpgradeRequired is a Boolean value that enables filtering , so only router instances that support older versions of the Metadata Schema and require upgrading are included in the returned JSON object.

To upgrade a ClusterSet, ReplicaSet, or Cluster's metadata, connect MySQL Shell's global session to your ClusterSet, ReplicaSet, or Cluster and use thedba.upgradeMetadata() operation to upgrade the ClusterSet, ReplicaSet, or Cluster's metadata to the new metadata. For example:

mysql-js> shell.connect('user@example.com:3306')mysql-js> dba.upgradeMetadata()InnoDB Cluster Metadata UpgradeThe cluster you are connected to is using an outdated metadata schema version1.0.1 and needs to be upgraded to 2.0.0.Without doing this upgrade, no AdminAPI calls except read only operations willbe allowed.The grants for the MySQL Router accounts that were created automatically whenbootstrapping need to be updated to match the new metadata version'srequirements.Updating router accounts...NOTE: 2 router accounts have been updated.Upgrading metadata at 'example.com:3306' from version 1.0.1 to version 2.0.0.Creating backup of the metadata schema...Step 1 of 1: upgrading from 1.0.1 to 2.0.0...Removing metadata backup...Upgrade process successfully finished, metadata schema is now on version 2.0.0

If the installed metadata version is lower, an upgrade process is started.

Thedba.upgradeMetadata() function accepts the following options:

  • dryRun: is a Boolean value used to enable a dry run of the upgrade process. IfdryRun is used, thedba.upgradeMetadata() function determines whether a metadata upgrade or restore is required and informs you without actually executing the operation.

If you encounter an error related to the ClusterSet, ReplicaSet, or Cluster administration user missing privileges, use the relevant.setupAdminAccount() operation with the update option to grant the user the correct privileges:

  • Create or upgrade a MySQL user account with the necessary privileges to administer an InnoDB Cluster:<Cluster>.setupAdminAccount(user, options)

    SeeInnoDB Cluster administrator accounts.

  • Create or upgrade a MySQL user account with the necessary privileges to administer an InnoDB ReplicaSet:<ReplicaSet>.setupAdminAccount(user, options)