MySQL Blog Archive
For the latest blogs go to blogs.oracle.com/mysql
MySQL Shell AdminAPI – What’s new in 8.0.21?
Posted on Jul 16, 2020 by Miguel Araújo
Category: Shell
Tags: devops, high-availability, shell

The MySQL Development Team is happy to announce a new 8.0 Maintenance Release of MySQL Shell AdminAPI – 8.0.21!

As always, we have listened to the growing community of users and introduced a very useful feature for any production deployment of MySQL InnoDB Cluster or ReplicaSet.

Also, since we’re talking about a patch release, quality has been improved with several bugs fixed!

MySQL Shell AdminAPI

This release focused on introducing a tagging framework for the AdminAPI, which ultimately allowed us to introduce a very demanded feature:

As usual, we would like to summarize what’s new so you get familiarized and eager to update MySQL Shell to the new version!

Tagging the Metadata

It is certainly convenient to categorize your servers in a Cluster or ReplicaSet according to different characteristics, for example: region, OS, owner, etc.

Up to now this was virtually impossible, and there were no means to tag a Cluster or a ReplicaSet member with specific attributes that could be visualized with the AdminAPI.

In this release, we have introduced a tagging framework that allows users to associate custom key-value pairs to a Cluster, a ReplicaSet, or instance members of those. By introducing a new namespace called tag to the option handling commands, this becomes very easy and straightforward:

  • <Cluster>.setOption()
  • <ReplicaSet>.setOption() ⇒ NEW!
  • <Cluster>.setInstanceOption()
  • <ReplicaSet>.setInstanceOption() ⇒ NEW!
  • <Cluster>.options()
  • <ReplicaSet>.options() ⇒ NEW!

NOTE: We have extended ReplicaSet to support the same set of commands related to option management as in InnoDB Cluster: .options(), .setOption(), .setInstanceOption().

A practical example

A DBA operating with several InnoDB Clusters, spread out in different regions, would most definitely benefit from having a tag to identify the region of the Cluster being managed at each moment. That can now be simply accomplished setting a tag to the Cluster:

1
2
3
mysql-js> // Set a tag to identify the cluster's region
mysql-js> cluster.setOption("tag:region", "EMEA")
 

Tags are included in the output of <Cluster>.options() and <ReplicaSet>.options(), so they can be consulted at any time.

There’s a wide range of options and scenarios on which tagging instances is also useful. For example, the DBA may want to tag the instances that should be upgraded to the latest MySQL version.

1
2
3
mysql-js> // Set a tag on a cluster member
mysql-js> cluster.setInstanceOption("localhost:3310", "tag:needs_upgrade", "true")
 

Requirements

Tags are formed by key-value pairs of <name>:<value> and there are no constraints about the values chosen for the tags as long as it is a valid MySQL ASCII identifier.

Any name and value for a tag can be used, as long as it follows the following syntax rules: _ or letters followed by alphanumeric and _ characters, i.e. ^[a-zA-Z_][0-9a-zA-Z_]*.

NOTE: Only built-in tags are allowed to start with the underscore _ character.

Finally, there are no restrictions regarding tagging instances that are not ONLINE or even tagging Clusters or ReplicaSets that don’t have all instances ONLINE. The only requirement is that the Cluster (or ReplicaSet) is writable, i.e. it was quorum.

How to remove a tag?

Simple, set it to null !

1
2
3
4
5
mysql-js> // Remove a global tag from a ReplicaSet
mysql-js> replicaset.setOption("tag:region", null)
mysql-js> // Remove a tag from a ReplicaSet member
mysql-js> replicaset.setInstanceOption("localhost:3310", "tag:owner", null);
 

Built-in tags?

Built-in tags allowed us to introduce on-demand behavior changes to MySQL Router, such as support for hiding instances on MySQL InnoDB Cluster/ReplicaSet.

In this release we have introduced two built-in tags to enable that:

  • _hidden
  • _disconnect_existing_sessions_when_hidden

Please read the follow-up post describing and detailing this exciting new feature.

Notable Bugs fixed

BUG#31329024 – BINLOG CHECKSUMS NOT ALLOWED IN ADMINAPI FOR SERVERS WITH VERSION >= 8.0.21

A known and old limitation of MySQL Group Replication was the lack of support for using binary log checksums. However, in this release, Group Replication has lifted that limitation, and therefore, users can now rely on the MySQL default which is to have binary log checksums enabled.

Up to the previous release, the AdminAPI ensured that binary log checksums were disabled as it was an InnoDB Cluster requirement. In this release, that check has been removed for target instances running MySQL 8.0.21.

BUG#30884590 – ADDING AN INSTANCE WITH COMPATIBLE GTID SET SHOULDN’T PROMPT FOR CLONE

There are some scenarios on which adding an instance with a compatible GTID set to a Cluster/ReplicaSet requires provisioning. For example, if the missing transactions are not available in any of the Cluster’s binary logs (were purged).

Up to now, the AdminAPI prompted the user to select if clone should be used or the operation should be aborted. Considering that in such scenario clone is the only possible way to provision and add the instance to the Cluster/ReplicaSet, we can assume that clone is safe to be used and we can proceed with it automatically. So it’s completely unnecessary to prompt the user.

NOTE: instances with empty GTID-set are not considered to have a compatible GTID-set. Such scenarios are considered to be unsafe/unknown
thus the user is prompted on what action shall be taken.

This behavior has been changed in this released to ensure that no prompt is presented when clone is the only way to provision and instance and determined to be
safely usable.

BUG#29908657 – PROTOCOL MISMATCH ERROR WHEN RUNNING ADMINAPI COMMANDS USING X PROTOCOL

Using X-protocol URIs on the AdminAPI resulted in an unclear error very confusing to the end-user.

Since X-protocol is not supported for any AdminAPI operations, this has been fixed in this release as follows:

  • If the X-protocol scheme mysqlx::// is used in the URI, an error is thrown indicating that X-protocol is not supported.
  • If the scheme is not specified, but the X-protocol port is used, an error is thrown indicating that X-protocol is not supported.
  • If the Shell global session is established using the X-protocol, any AdminAPI operation that does not require a URI will automatically do a protocol-switch to the classic one. For example: dba.createCluster().
BUG#31238233 – ADOPTING A CLUSTER (ADOPTFROMGR) VIA A SECONDARY MEMBER DISABLES SUPER_READ_ONLY

It’s possible to adopt a Group Replication setup into an InnoDB Cluster to benefit from the full capabilities of InnoDB Cluster and the AdminAPI. That can be easily done using the adoptFromGR option of dba.createCluster().

This operation can be done whilst connected to any member of the Group, regardless of whether it’s a primary or a secondary. However, when a secondary member was used super_read_onlywas being incorrectly disabled.

This has been fixed in this release by ensuring that all operations performed during a
Cluster adoption are done using the primary member of the group. This ensures that no GTID inconsistencies occur and that super_read_only is not incorrectly disabled on secondary members.

BUG#31018091 – INNODB CLUSTER – ‘CLUSTERADMIN’ WITH NETMASK IN HOST IS NOT RECOGNIZED

Using the clusterAdmin option to create a user which had a netmask as part of
the host resulted in an error when this user was passed to the
dba.createCluster() operation. Now, accounts that have a netmask are treated
as accounts with wildcards, meaning that further checks to verify if the
account accepts remote connections from all instances are skipped.

BUG#30768504 – REBOOTCLUSTER PARTIAL FAILURE IF MYSQL 5.7 IF GR PLUGIN UNINSTALLED

If a complete outage of a Cluster happened and for some reason, the Group Replication plugin was uninstalled, the Group Replication configurations were not loaded after rebooting the Cluster from complete outage using dba.rebootClusterFromCompleteOutage().

The root cause of this issue is that Group Replication system variables do not exist if the plugin has not been loaded when the server starts even if those variables are persisted in the instance’s configuration file. In such scenarios, the user configurations would be lost and the default values would be used. Instances running MySQL 8.0 didn’t suffer from this issue because SET PERSISTis used and the sysvar loading process behaves differently.

In this release that has been fixed by making dba.configureInstance()persist the Group Replication system variables with the loose_ prefix. As a result, once
the Group Replication plugin is installed, on instances running 5.7 the
persisted values are used instead of the default values.

Try it now and send us your feedback

MySQL Shell 8.0.21 GA is available for download from the following links:

And as always, we are eager to listen to the community feedback! So please let us know your thoughts here in the comments, via a bug report, or a support ticket.

You can also reach us at #shell and #mysql_innodb_cluster in Slack: https://mysqlcommunity.slack.com/

The documentation of MySQL Shell can be found in https://dev.mysql.com/doc/mysql-shell/8.0/en/ and the official documentation of InnoDB Cluster and InnoDB ReplicaSet can be found in the User Guide.

The full list of changes and bug fixes can be found in the 8.0.21 Shell Release Notes.

Enjoy, and Thank you for using MySQL!

 Search
Categories