MySQL Shell 8.0 Release Notes

11 Changes in MySQL Shell 8.0.33 (2023-04-18, General Availability)

AdminAPI Added or Changed Functionality

  • Important Change: It is now possible to configure Clusters, ClusterSets, and ReplicaSets to use SSL for:

    • Encrypting Group Replication and asynchronous replication channels.

    • Enabling replicas to verify the identity of the source.

    • Enabling replicas to use client SSL certificates for authentication.

    The following changes were made:

    • dba.createCluster() was extended with the following options:

      • memberAuthType

      • certIssuer

      • certSubject

    • dba.createReplicaSet() was extended with the following options:

      • memberAuthType

      • certIssuer

      • certSubject

      • replicationSslMode

    • cluster.addInstance() was extended with the following option:

      • certSubject

    • clusterSet.createReplicaCluster() was extended with the following option:

      • certSubject

    • The cluster.createClusterSet() option clusterSetReplicationSslMode was extended with the following values:

      • VERIFY_CA

      • VERIFY_IDENTITY

    • A new MySQL Shell option is added, dba.connectivityChecks: true | false. This option defines if connectivity checks are performed for cluster.addInstance(), clusterSet.createReplicaCluster(), and replicaSet.addInstance(), using the defined SSL configuration.

      If an SSL error occurs, the command stops and an error is returned.

    • cluster.options() and replicaSet.options() were extended to show relevant information on memberAuthType and certIssuer in the globalOptions section, and certSubject for each instance in the topology section. cluster.options() is also updated to list clusterSetReplicationSslMode in the globalOptions section.

    • replicaSet.status is extended with a new field, replicationSsl, to show the SSL information for each replication channel.

    Note

    If the cluster's memberAuthMode is set to any value other than password, cluster.rescan() will fail if used with addInstances

    For more information on these options, see the MySQL Shell 8.0 JavaScript API Reference or MySQL Shell 8.0 Python API Reference available from MySQL Documentation. (Bug #34256928, WL #13688)

  • Important Change: Cluster and ReplicaSet operations setupAdminAccount() and setupRouterAccount() are extended to enable authentication with client SSL certificates. The following changes were made:

    • The following options were added to setupAdminAccount() and setupRouterAccount():

      • requireCertIssuer: Optional SSL certificate issuer for the account.

      • requireCertSubject: Optional SSL certificate subject for the account.

      • passwordExpiration: numberOfDays | Never | Default: Password expiration setting for the account.

    • setupAdminAccount() and setupRouterAccount() were also added to the ClusterSet object.

    • The following options were added to dba.configureInstance() and dba.configureReplicaSetInstance():

      • clusterAdminCertIssuer: Optional SSL certificate issuer for the account.

      • clusterAdminCertSubject: Optional SSL certificate subject for the account.

      • clusterAdminPasswordExpiration: NumberOfDays | NULL | DEFAULT | NEVER: Password expiration setting for the account.

    For more information on these options, see the MySQL Shell 8.0 JavaScript API Reference or MySQL Shell 8.0 Python API Reference available from MySQL Documentation. (WL #15438)

  • It is now possible to set group_replication_paxos_single_leader using MySQL Shell.

    Note

    This can only be set by MySQL Shell on MySQL Server 8.0.31, or higher, because MySQL Shell requires the information provided by WRITE_CONSENSUS_SINGLE_LEADER_CAPABLE in the replication_group_communication_information table, which was introduced in MySQL 8.0.31.

    The following changes were made:

    (Bug #33930873)

  • The locking functionality introduced in MySQL Shell 8.0.20 to prevent conflicting ReplicaSet operations running concurrently has been extended to include Cluster and ClusterSet resources.

    For information on locking types and the operations which require them, see MySQL AdminAPI.

    Note

    The existing documentation on ReplicaSet locking has been moved to MySQL AdminAPI.

    (Bug #25803949, Bug #33250135, WL #11969)

AdminAPI Bugs Fixed

  • After an upgrade, Cluster.status displayed the following error, under instanceErrors:

    "WARNING: Incorrect recovery account (mysql_innodb_cluster_rServer_ID) being used. Use Cluster.rescan() to repair."

    This warning was displayed in error, as a result of a previous bug fix which introduced a check on recovery account formats. The recovery account format was expected to be of the form mysql_innodb_cluster_server_id but, for an upgrade, the recovery account format is mysql_innodb_cluster_rserver_id.

    As of this release, the recovery account format check has been updated to recognize older formats. (Bug #35046654)

    References: See also: Bug #33235502.

  • Python commands, such as Cluster.add_instance() did not check the Cluster was connected before proceeding. This could result in MySQL Shell closing unexpectedly.

    As of this release, Python commands check the cluster is connected before proceeding. (Bug #35046432)

  • Cluster.status() and Cluster.rescan() did not detect a mismatch of values between the group_replication_view_change_uuid stored in the metadata and the current runtime value. This could lead to errors during operations such as ClusterSet.setPrimaryCluster because the reconciliation of transaction sets cannot be done if the current UUID does not match the value stored in the ClusterSet metadata.

    As of this release, Cluster.status() raises a warning if the group_replication_view_change_uuid values do not match and Cluster.rescan() also detects the mismatch and updates the metadata accordingly. (Bug #35000998)

  • createReplicaCluster() failed with the error, ERROR: Error creating Replica Cluster: MySQL Error 1772 (HY000): Malformed GTID set. This was caused by the sql_mode including NO_BACKSLASH_ESCAPES. (Bug #34837601)

  • removeCluster() failed when attempting to remove an offline cluster from a ClusterSet, if group replication was attempting to bring the cluster back online, even if the force option was used. This issue could leave the Cluster metadata in a changed state.

    As of this release, removeCluster() stops group replication and ignores errors if the force option is used. The rollback process was improved and no longer depends on group replication being online. Instead, snapshots are taken of server data and are reapplied when necessary. (Bug #34693099)

  • dba.checkInstanceConfiguration() did not properly take into account value-less variables, such as disable_log_bin, and listed them as requiring changes although they were correctly configured. (Bug #34569971)

  • It is not possible to create sandboxes using older versions of MySQL 5.7, such as 5.7.21, due to incompatibilities between the supported versions of TLS. Newer versions of MySQL Shell do not support TLS v1.1 and older.

    As of this release, sandbox management commands which open local connections to the sandboxes, fall back to unencrypted connections if an SSL connection fails. (Bug #34548702)

  • A replica's globalStatus value, returned by ClusterSet.status(), was incorrectly reported as NOT_OK if the ClusterSet's primary cluster was unreachable, but the replica was functioning normally.

    As of this release, the globalStatus value OK_NOT_REPLICATING is returned if the replica is functioning normally but not replicating because the primary is offline or otherwise unreachable. (Bug #34324165)

  • It was not possible to upgrade the metadata schema of a cluster created by MySQL Shell 1.0.x with adoptFromGR: true. The following error was returned: 

          "ERROR: Truncated incorrect INTEGER value: 'true'"

    (Bug #31711835)

  • MySQL Shell disabled and persisted offline_mode when an instance was added or rejoined to a Cluster, or when rebooted. If this variable was enabled explicitly by the user, it was overwritten by MySQL Shell.

    As of this release, offline_mode is disabled globally, not persisted, and a new warning is added to Cluster.status to inform the user of the risks of enabling this variable. (Bug #108905, Bug #34778797)

  • When adding a member to a cluster, the values of auto_increment_increment and auto_increment_offset were miscalculated and were off by 1. As a result, when adding or rejoining an eighth member to a cluster, the new member was configured with the correct values, while the other seven members continued with the configuration of a seven-member cluster. (Bug #108759, Bug #34711038)

Functionality Added or Changed

  • If an AWS request fails with a HTTP 400 error and the reported error is ExpiredToken or TokenRefreshRequired, the request is silently retried if the authentication can be refreshed. (Bug #35027093)

  • It is now possible to use a non-default location for the OCI CLI config file used by the authentication_oci_client authentication plugin, using shell.options[oci.configFile] to define the alternate location. (Bug #34858763)

  • MySQL Shell now bundles the following client authentication plugins:

    • authentication_fido_client

    • authentication_kerberos_client

    • authentication_ldap_sasl_client

    These plugins are located in the /lib/mysql/plugins directory of your MySQL Shell installation. (Bug #34857426)

  • MySQL Shell now supports AWS credential_process external credential provider.

    For more information, see S3-compatible Storage. (Bug #34840953)

  • The Dump Loading utility (loadDump()) progress file now includes information on index creation status. (Bug #34840760)

Bugs Fixed

  • MySQL Shell could not connect if both port and socket file were defined in the configuration file. As of this release, the last value defined takes precedence. (Bug #35023480)

  • The --user/-u and --password/-p options were not recognized if they were specified before the URI in the connection string.

    They were recognized if they were specified after the URI. (Bug #35020175)

  • It was not possible to run the load or dump utilities over an SSH connection. The operation failed with an error similar to the following: 

            Util.dumpSchemas: The option ssh-remote-port '33060' is 
        already defined.(ArgumentError)

    (Bug #35018617)

  • The import table utility ignored the skipRows parameter when importing a single compressed file or multiple files.

    In addition, the documentation of skipRows was updated to clarify that it skips the defined number of lines from each file imported. (Bug #35018278)

  • If two different plugins defined an object.function with the same name for both the object and function, the MySQL Shell help displayed the same help data for both, even if the functions had different signatures and description. (Bug #34979347)

  • The dumpInstance() utility incorrectly commented out database-level GRANT statements referring to schema names with wildcard characters.

    As of this release, GRANT statement filtering has been removed for both dump and load utilities. Dump utilities print a warning if a GRANT on an excluded object is detected.

    The following additional, supporting changes were made:

    • Dumping with ocimds: true, all database level grants containing wildcards, are reported as errors. DB Systems use partial_revokes=ON which treats wildcard characters literally. These errors must be corrected manually.

    • A new compatibility option was added to the dump utilities, ignore_wildcard_grants. If enabled, ignores errors from grants on schemas with wildcards, which are interpreted differently in systems where the partial_revokes system variable is enabled.

    • A new option, handleGrantErrors, was added to util.loadDump(). This option defines the action taken in the event of errors related to GRANT or REVOKE errors.

      • abort: (default) stops the load process and displays an error.

      • drop_account: deletes the account and continues the load process.

      • ignore: ignores the error and continues the load process.

    (Bug #34952027)

  • The defaultValue option of shell.prompt did not return the defined value. (Bug #34889112)

  • The Upgrade Checker utility did not raise a warning for indexes which were too large. Tables with the compact or redundant row formats are not permitted to have indexes larger than 767 bytes in MySQL 8.0. As a result, such tables were inaccessible after upgrading to MySQL 8.0.

    As of this release, the Upgrade Checker checks for such index sizes on specific row formats and raises a warning if the can cause tables to be inaccessible after upgrade. (Bug #34826890)

  • MySQL Shell running on Oracle Cloud Infrastructure Cloud Shell closed unexpectedly when attempting to load a dump from an Object Storage bucket while FIPS mode was enabled. The following error was displayed: 

            md5_dgst.c(82): OpenSSL internal error, assertion failed: 
        Digest MD5 forbidden in FIPS mode!

    (Bug #34787908)

  • It was not possible to export a view with the Export Table utility (exportTable(). (Bug #34663934)

  • If the Dump Loading utility was run with "deferTableIndexes": "all" and "ignoreExistingObjects": true, the load could fail as the utility tried to add indexes which already existed.

    As of this release, if "ignoreExistingObjects": true, existing tables are checked for indexes and only missing indexes are added. (Bug #34566034)

  • The following issues occurred in the import table utility:

    • The reported progress exceeded 100% when importing compressed files.

    • The utility reported multiple threads in use when importing a single compressed file, although only one thread was used.

    • The utility reported an incorrect number of chunks and imported files.

    (Bug #33970577)

  • The dictionary used as the Python wrapper for a map did not pass the isinstance() test.

    As of this release, the implementation of the map wrapper used by MySQL Shell in Python mode has been updated and now inherits from Python's dict.To avoid duplication of data and ensure synchronization between Python's context and internal representation of data, data is not stored in the base class, but in the map wrapper. Due to this, and the fact that data is shared between Python and JavaScript modes, it is only safe to store basic types such as numbers, strings, arrays, and dictionaries, and native Shell objects such as Cluster and Session. As the base class is not used to store the data, all methods of the list class have been reimplemented.

    Be aware of the following limitations:

    • Order of insertion is not maintained; keys are always ordered alphabetically.

    • Only string types keys are supported; non-string keys are handled as follows:

      • converted to a string using str() when inserting multiple values.

      • treated as missing when accessing an element.

      • treated as an error, with an exception raised, when setting a value.

    (Bug #33517575)

  • The MySQL Shell source compilation documentation, INSTALL, did not include the antlr4 runtime, which is a mandatory dependency.

    Thanks to Evgeniy Patlan for this contribution. (Bug #109909, Bug #35045019)

  • The Dump Loading utility failed to load a dump using "deferTableIndexes": "all" if one of the tables being loaded contained multiple indexes and one, or more, index specified for an AUTO_INCREMENT column. (Bug #109313, Bug #34876423)

  • The dumpInstance() utility incorrectly commented out GRANT statements referring to existing views, routines, and non-existing schemas and objects instead of only commenting out GRANT statements which referred to objects not included in the dump.

    As of this release, GRANT statement filtering has been removed for both dump and load utilities. Dump utilities now detect invalid grants and print a warning if they are detected.

    A new compatibility option is introduced, strip_invalid_grants, which removes invalid GRANT statements from the dump. (Bug #108974, Bug #34764157)

MySQL Documentation Library