As AdminAPI evolves, some releases might require you to upgrade the metadata of existing 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.
Without upgrading the metadata you cannot use MySQL Shell
8.0.19 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()
,
and
Cluster
.describe()
.
Cluster
.options()
This dba.upgradeMetadata()
operation
compares the version of the metadata schema found on the
cluster MySQL Shell is currently connected to with the
version of the metadata schema supported by this MySQL Shell
version. If the installed metadata version is lower, an
upgrade process is started. The
dba.upgradeMetadata()
operation then
upgrades any automatically created MySQL Router users to have the
correct privileges. Manually created MySQL Router users with a
name not starting with mysql_router_
are
not automatically upgraded. This is an important step in
upgrading your cluster, only then can the MySQL Router application
be upgraded. To get information on which of the MySQL Router
instances registered with a cluster require the metadata
upgrade, 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"
}
}
}
A cluster which is using the new metadata cannot be administered by earlier MySQL Shell versions, for example once you upgrade to version 8.0.19 you can no longer use version 8.0.18 or earlier to administer the cluster.
To upgrade a cluster's metadata, connect MySQL Shell's global
session to your cluster and use the
dba.upgradeMetadata()
operation to upgrade
the cluster's metadata to the new metadata. For example:
mysql-js> \connect user@example.com:3306
mysql-js> dba.upgradeMetadata()
InnoDB Cluster Metadata Upgrade
The cluster you are connected to is using an outdated metadata schema version
1.0.1 and needs to be upgraded to 2.0.0.
Without doing this upgrade, no AdminAPI calls except read only operations will
be allowed.
The grants for the MySQL Router accounts that were created automatically when
bootstrapping need to be updated to match the new metadata version's
requirements.
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 you encounter an error related to the cluster
administration user missing privileges, use the
operation with the update option to grant the user the correct
privileges. See Configuring Users for AdminAPI.
Cluster
.setupAdminAccount()