Documentation Home
MySQL Shell Release Notes
Related Documentation Download these Release Notes
PDF (US Ltr) - 0.6Mb
PDF (A4) - 0.6Mb

MySQL Shell Release Notes  /  Changes in MySQL Shell 8.0.32 (2023-01-17, General Availability)

Changes in MySQL Shell 8.0.32 (2023-01-17, General Availability)


This version includes a change which enables MySQL Shell to read MySQL Server option files and login paths by default. As a result, if you connect to a MySQL Server which uses an option file, it will be used, by default. If you do not want to use the options file, you must add --no-defaults to your command line.

For more information, see WL#11206 in Functionality Added or Changed.

AdminAPI Added or Changed Functionality

  • A new attribute named hiddenFromRouter is added to the output of the following commands:

    • Cluster.status()

    • Cluster.describe()

    • ReplicaSet.status()

    This attribute is true for any member hidden from MySQL Router traffic using the _hidden metadata tag. (Bug #34680289)

  • A new option, use_replica_primary_as_rw is added to <ClusterSet>.setRoutingOption().

    This option is read by MySQL Router and enables it to open or close a read-write (R/W) port on a router targeting a specific Cluster (where target_cluster is not set to primary), enabling you to use a R/W port on a ReplicaCluster. The ReplicaCluster continues to only accept R/O traffic. In the event of a switchover or failover, the R/W port remains unchanged.

    See MySQL Router Status for InnoDB ClusterSet. (Bug #34544084)

  • It is now possible to set ipAllowList on a running cluster with Cluster.setOption and Cluster.setInstanceOption.


    This option can only be set if the communicationStack is set to XCOM.

    See Setting Options for InnoDB Cluster.

    This also corrects an issue in Cluster.setOption, where instances were not checked to confirm they were online, and if the specified options were supported on each instance. (Bug #34424385)

  • As of this release, ReplicaSet replication channels are created with SSL enabled by default.


    This change does not apply to replication groups adopted using this version; their replication channels remain unencrypted.

    (Bug #30472808, Bug #30473564)

AdminAPI Bugs Fixed

  • It was not possible to use dba.dropMetadataSchema() or cluster.dissolve() on a cluster which belonged to a ClusterSet. As of this release, these functions can be used on ClusterSet clusters if they are the only Cluster in the ClusterSet or they are invalidated. (Bug #34787737)

  • It was not possible to create a working Cluster using MySQL Server 8.0.22 and a more recent version of MySQL Shell. (Bug #34787542)

  • rebootClusterFromCompleteOutage() was unable to complete the reboot process if the rebooted cluster was a member of a ClusterSet and was missing purged transactions. There was no check for such purged transactions.

    As of this release, rebootClusterFromCompleteOutage() checks for purged transactions before attempting rejoinCluster.

    Additionally, replica clusters are now synchronized in two steps: the primary of the cluster is synchronized with the ClusterSet primary, then the rest of the cluster waits for those transactions to be applied.

    If there are both errant and unrecoverable transactions, an errant transaction error is thrown. (Bug #34692990)

  • Metadata changes in createCluster() were prematurely committed through implicit commit statements. As of this release, these statements are executed in a separate session. (Bug #34670761)

  • super_read_only was set on every rejoined cluster member, regardless of what mode the cluster was running, single- or multi-primary. (Bug #34647972)

  • If the primary was unreachable, Cluster.status() failed with an error instead of automatically connecting to a secondary member. (Bug #34615265)

  • If the primary was unreachable, dba.getCluster() failed instead of retrieving the cluster object from a secondary. (Bug #34579287)

  • During reboot or failover in a ClusterSet or ReplicaSet, MySQL Shell checks if the candidate primary has the most recent GTID_EXECUTED. However, if load is high, it is possible that the applier is still working and GTID_EXECUTED still incrementing, and the check returns a premature result.

    As of this release, a timeout option is added to ClusterSet.forcePrimaryCluster() which specifies a number of seconds to wait for the applier to finish and ensure GTID_EXECUTED has the most up to date GTID set. The default value of timeout uses the value of dba.gtidWaitTimeout.

    The existing timeout option of ClusterSet.setPrimaryCluster() is extended to enable the applier to finish. (Bug #34465675)

  • A fix in a previous version which prevented invalid endpoints being stored in the metadata did not take existing invalid values into account. As a result, attempting to add a member back to a cluster failed if the member's metadata contained an invalid endpoint. The following error was displayed:

            Debug: Cluster.addInstance: Invalid address format: ''(ArgumentError)

    As of this release, Cluster.status() scans for such invalid endpoints and generates a warning, and Cluster.rescan() corrects the invalid data. (Bug #34395705)

  • Under certain circumstances, Cluster recovery accounts are leftover and not used. This can occur if a recovery process is canceled, for example.

    As of this release cluster.status() reports the existence of such accounts in the instanceErrors field and cluster.rescan() removes any such leftover accounts. (Bug #33235502)

  • An instance being provisioned for a cluster by clone was reported as "mode": "R/W" while it was being provisioned. As of this release, any member with status other than ONLINE will be reported as "mode": "n/a". (Bug #30902267)

  • The dba.upgradeMetadata() error message contained a typo.

    Thanks to Nico Pay for the contribution. (Bug #108861, Bug #34733164)

  • Attempting to add an instance to a newly-created Replica Cluster, if the Primary Cluster was under high load, failed with several errors related to super_read_only.

    This issue was caused by an out-of-date topology view, leading to the newly created ReplicaCluster being considered a standalone cluster.

    As of this release, createReplicaCluster() synchronizes the metadata update transactions. thereby ensuring it has the correct topology view. (Bug #108426, Bug #34584939)

  • The error ReplicaSet.status: Failed to execute query on Metadata Illegal mix of collations was returned if the server was configured with character-set-client-handshake=OFF or --skip-character-set-client-handshake, and the client attempted to use a different collation. The server collation was used for the client sessions, instead of negotiating the collation used.

    As of this release, the collation is explicitly set by AdminAPI sessions. (Bug #108209, Bug #34530914)

Functionality Added or Changed

  • Important Change: The following options were added to the exportTable(), dumpInstance(), dumpSchemas(), and dumpTables() utilities:

    • where: enables you to export the data which satisfies a SQL condition.

    • partitions: enables you to export named partitions.

    As part of this development, the following options were added to the dumpInstance(), dumpSchemas(), and dumpTables() utilities:

    • fieldsTerminatedBy

    • fieldsEnclosedBy

    • fieldsEscapedBy

    • fieldsOptionallyEnclosed

    • linesTerminatedBy

    • dialect (json dialect is not supported) enabling you to dump your data as CSV or TSV file formats.

    For information on exportTable(), see Options

    For information on dumpInstance(), dumpSchemas(), and dumpTables(), see Options for Dump Output. (Bug #32669773, Bug #108504, Bug #34606598, WL #15311)

  • Important Change: As of this release, MySQL Shell supports MySQL login paths and option files by default.


    If you do not want MySQL Shell to read the option file, you must add --no-defaults to your command line.

    The following MySQL command line options are now supported at the start of the command line:

    MySQL Shell also reads a new section in the MySQL configuration file, [mysqlsh], in which you can define the MySQL Shell options.

    MySQL Shell also reads the [client] section of the MySQL Preconfiguration file.

    For more information, see Connecting using login-path and Options Files.


    Some [client] options are not supported by MySQL Shell, such as local-infile, and some options have the same name in both, but take different values, such as the [client] option --compress and the [mysqlsh] option compress=value.

    MySQL Shell returns a specific error for such options, specifying the name of the option and the error.

    This is something to be aware of during an upgrade to MySQL Shell 8.0.32. Your options files may require editing, or you may need to define an alternate options file for your MySQL Shell installation.

    (WL #11206)

  • As of MySQL 8.0.32, unquoted identifiers starting with a dollar sign ($) are deprecated. As of MySQL Shell 8.0.32, the Upgrade Checker utility checks for the existence of such identifiers and presents a list to the user. Stored routines are also checked. (Bug #34684193)

  • The following changes were made to the logSql option:

    • --log-sql=on no longer filters SELECT statements by default.

    • A new filtering option, logSql.ignorePatternUnsafe, is added. This option defines a colon-separated list of statement patterns to filter out. Default value is *IDENTIFIED*:*PASSWORD*.

    • The default value of the filtering option, logSql.ignorePattern, is changed from *SELECT*:*SHOW*:*IDENTIFIED*:*PASSWORD* to *SELECT*:*SHOW*.

    • logSql option parameters were updated:

      • on: logs all SQL statements except those defined in the logSql.ignorePatternUnsafe and logSql.ignorePattern options.

      • all: new parameter which logs all SQL statements except those defined in the logSql.ignorePatternUnsafe.

    See SQL Logging Options. (Bug #34249346)

  • In previous versions, chunking required a defined primary key or unique index on the table. As of this version, tables without primary key or unique index can be chunked based on the number of rows in the table, the average row length, and the bytesPerChunk value. (Bug #34195250)

  • It is now possible to configure MySQL Shell's AWS S3 support with AWS environment variables. For more information, see S3-compatible Storage.

    The command line option s3Region was added to the dump and load utilities. This option enables you to define the AWS region from the command line. For more information, see MySQL Shell Utilities. (Bug #108495, Bug #34604763)

  • MySQL Shell supports the Microsoft Azure Blob storage service for import, export, dump, and load operations.

    See Azure Blob Storage and MySQL Shell Utilities. (WL #15337)

Bugs Fixed

  • Under certain circumstances, HTTPS read operations could fail with a libcurl-related CURLE_PARTIAL_FILE error. As of this release, the read operation is retried. (Bug #34765385)

  • The following errors occurred if MySQL Shell was used to call a stored procedure that produces more than one result:

    • Using --column-type-info only displayed the column metadata for the first result.

    • Using JSON output, such as --json=raw, only displayed the first result.

    (Bug #34716739)

  • Under certain circumstances, calling util.importTable() with a wildcard, on a bucket in Oracle Cloud Infrastructure's Object Storage, failed with an error similar to the following:

            Util.importTable: Failed to list multipart uploads: ... (404) (MYSQLSH 54404)

    (Bug #34679579)

  • The authentication_oci_client plugin is now bundled with the MySQL Shell installation, in the lib/mysql/plugins directory of your MySQL Shell installation on Linux platforms, and lib\mysql\plugins on Windows platforms.

    As of this release, the default value of mysqlPluginDir is set to the MySQL plugins directory of your MySQL Shell installation. For example, on Linux platforms, this is lib/mysql/plugins. (Bug #34676464)

  • Under certain circumstances, util.debug.collectDiagnostics failed with the following error:

              TypeError: object of type 'NoneType' has no len()

    (Bug #34674675)

  • When started from the command line using options with incorrect values, MySQL Shell did not return useful information on which option was in error. As of this release, the error message contains helpful information on which option contains the error. (Bug #34624922)

  • Loading a dump using a Pre-Authenticated Request (PAR) failed if the filename contained URL-encoded characters. (Bug #34599319)

  • The extra consistency check for the dump utilities with consistent: true was too sensitive and reported errors even when no DDL changes were made.

    As of this release, the consistency check analyzes statements executed during the dump and fails only if DDL-related statements are detected.

    A new option is added to the dump utilities, skipConsistencyChecks: [true | false], which, if set to true, skips the additional consistency check and assumes the dump is consistent. (Bug #34556560)

  • If sql_mode was set to ANSI_QUOTES, the following occurred:

    • \status failed with the following error:

              Unknown column ' ' in 'field list'

    • USE schema failed with the following error if the schema's name contained consecutive quotation marks (sample""name, for example):

                  ERROR: Too many consecutive quote characters: 2

    (Bug #34538796, Bug #34709673)

  • Under certain circumstances, in SQL mode, splitting statements with commands such as \q could cause MySQL Shell to close unexpectedly. (Bug #34517691)

  • When parsing SQL script, MySQL Shell did not account for the sql_mode current session value NO_BACKSLASH_ESCAPES and escaped all backslashes. (Bug #34488296)

  • It was not possible to USE a schema with a single quote (') in its name. (Bug #34334556)

  • MySQL Shell now bundles Python 3.10.8 for platforms where Python 3 is not included or is not at the minimum supported version.


    This is true for all builds except Oracle Linux 7, which bundles Python 3.9.15

    (Bug #109240, Bug #34844958)

  • util.loadDump failed if a table in the dump had more than one FULLTEXT index. The following error was returned:

           InnoDB presently supports one FULLTEXT index creation at a time

    As of this release, if a table contains more than one FULLTEXT index, each additional index is created using separate ALTER TABLE statements. (Bug #108991, Bug #34787778)

  • loadDump failed when loading a view which referenced another view whose DEFINER did not yet exist.

    As of this release, users are loaded after objects and view placeholders are created, but before the placeholders are replaced by the views. (Bug #108975, Bug #34768224)

  • The util global object was not available from the command line if the persisted default mode was set to SQL. (Bug #108839, Bug #34734133)

  • When using util.exportTable() to export to an S3 bucket, the AWS-specific information, such as the S3 bucket name, was not written to the suggested util.importTable() call. (Bug #108497, Bug #34657730)

  • Attempting to add an instance to a newly-created Replica Cluster, when the Primary Cluster is under very high load, failed with errors related to super_read_only.

    (Bug #108426, Bug #34584939)

  • MySQL Shell Upgrade Checker did not check for orphaned stored routines. That is, stored routines which reference non-existent schemas. As a result, the upgrade procedure could fail.

    As of this release, the Upgrade Checker utility checks for such orphaned routines and returns an error if they are found. (Bug #108005, Bug #34433132)

  • Extra underscores were added to property names when querying MySQL 8.0 servers with the MySQL Shell Python API. In MySQL 8.0, the column names are uppercase, but Python naming conventions added an underscore before each uppercase letter, resulting in column names like row.c_o_l_u_m_n_n_a_m_e.

    As of this release, such fields are exposed as properties in both Python and JavaScript, and the column name takes precedence over the naming convention. (Bug #107853, Bug #34379393)

  • A package year verification check prevented compilation of MySQL Shell, with default options, when close to the end of year. As of this release, MySQL Shell compilation defaults to the current year as package year. (Bug #101905, Bug #32246288)