7 Changes in MySQL Shell 8.4.0 (2024-04-30, LTS Release)

Important

AdminAPI no longer supports MySQL 5.7. Any AdminAPI command run against that version returns an error.

Deprecation and Removal Notes

The helper command, --dba=enableXProtocol, is deprecated and subject to removal in a future release. (Bug #36380502)
AdminAPI no longer uses the deprecated Group Replication system variable, group_replication_allow_local_lower_version_join. (Bug #36187059)
The following functionality, deprecated in previous releases, was removed in this release:
- The following command line arguments:
  - --ssl
  - --node
  - --classic
  - --sqln
  - --import
  - --recreate-schema
  - --dbuser. The corresponding API attribute, dbUser was also removed.
  - --dbpassword. The corresponding API attribute, dbPassword was also removed.
  - -n and -c were removed from the \connect command.
  - --fido-register-factor. The plugins authentication_fido and authentication_fido_client are no longer packaged with MySQL Shell.
- The following functions:
  - arrayDelete() and merge() were removed from CollectionModify.
  - skip() was removed from CollectionFind.
  - getWarningCount() was removed from BaseResult.
  - getAffectedItemCount() was removed from Result.
  - getAffectedRowCount() and nextDataSet() were removed from SqlResult .
  - query() was removed from ClassicSession.
The ociParManifest and ociParExpireTime options were removed from the Dump utilities. (WL #11816, WL #15955)
The following, deprecated in previous releases, have been removed from AdminAPI:
- Commands:
  - dba.configureLocalInstance()
  - cluster.checkInstanceState()
- Options:
  - ipWhitelist was removed from all commands which contained it.
  - connectToPrimary was removed from dba.getCluster().
  - clearReadOnly was removed from all commands which contained it.
  - failoverConsistency was removed from all commands which contained it.
  - multiMaster was removed from dba.createCluster().
  - groupSeeds was removed from all commands which contained it.
  - memberSslMode was removed from cluster.addInstance() and cluster.rejoinInstance().
  - queryMembers was removed from cluster.status().
  - user and password were removed from all commands which contained them.
  - interactive was removed from all commands which contained it.
  - waitRecovery was removed from all commands which contained it.
  - updateTopologyMode was removed from cluster.rescan().
(WL #15870)

AdminAPI Added or Changed Functionality

As of MySQL 8.4.0, the default value of group_replication_consistency is changed from EVENTUAL to BEFORE_ON_PRIMARY_FAILOVER. As a result, the corresponding option in the AdminAPI, consistency was updated for MySQL 8.4.0 or higher. For previous versions, the default remains EVENTUAL. (Bug #36057775)
Cloning version compatibility checks for donor and recipient instances are relaxed. As of this release, with certain conditions, only the major and minor version numbers need to match, the patch number is now disregarded.
The following conditions apply:
- Only version 8.0.17, or higher, can perform cloning.
- If both versions are 8.0.37, or higher, only the major and minor versions are required to match.
- If the version is 8.0.17, or higher, and less than 8.0.37, major, minor, and patch numbers must match.
(Bug #36054489)
InnoDB Cluster Read Replicas now support certificate-based authentication.
The following changes were made to the cluster.addReplicaInstance() method:
- The option certSubject was added. This option specifies the certificate subject of the instance, used if the Cluster's memberAuthType is CERT_SUBJECT or CERT_SUBJECT_PASSWORD.
- The method now uses the Cluster's memberSslMode value to configure the authentication type of the Read Replica's replication channel.
- The method performs a connectivity check, using the configured memberSslMode before updating the topology.
- If the Cluster's memberAuthType is CERT_SUBJECT or CERT_SUBJECT_PASSWORD, the method verifies the server's certificate.
cluster.options() was updated to return certSubject in the topology array. (WL #16123)
As of this release, MySQL Router exposes its configuration in the Cluster metadata for all routers bootstrapped against it. This information is stored as JSON in the Cluster metadata schema and can be accessed by the MySQL Shell operation, object.routerOptions() for Cluster, ClusterSet, and ReplicaSets.
See Working with a Cluster's Routers.
The operation object.routingOptions() is deprecated and scheduled for removal in a future release. (WL #15954)

AdminAPI Bugs Fixed

The documentation for Rescanning a Cluster did not make clear that while group_replication_transaction_size_limit is set to the maximum value in Replica Clusters, the original value is stored in the metadata schema and is restored by Cluster.rescan() in the event of a switchover or failover. This overwrites any user-defined value set on the Replica Cluster.
The documentation is updated with this information. (Bug #36494958)

If the primary instance of a Replica Cluster was changed, attempting to remove that Cluster from the Cluster set failed with the following error:

        ERROR: Error enabling automatic super_read_only management at secondary:port: 
        MySQL Error 3910 (HY000): The function 'group_replication_enable_member_action' failed. 
        Member must be the primary or OFFLINE.

(Bug #36400360)

If AdminAPI operations were run against an unsupported version of MySQL, an error was returned. The error did not contain sufficient information.
As of this release, the error returned contains information on the minimum and maximum versions of MySQL supported by the current version of AdminAPI. (Bug #36338711)
clusterSet.setPrimaryCluster and replicaSet.setPrimaryCluster invoked FLUSH TABLES WITH READ LOCK when dryRun was enabled. These operations no longer invoke that statement for dry runs. (Bug #36314520)
cluster.setRoutingOption() accepted the address as the router name instead of the properly qualified router identifier, address::router_name.
As of this release, the router identifier is properly validated. (Bug #36267549)
When adding a Read Replica to a cluster which belonged to a ClusterSet, it was possible to specify a replication source which was an instance of the primary or Replica Cluster. This could be done using the replicationSources parameter.
As of this release, a check is added which prohibits replication sources which do not belong to the Cluster where the command was run to be used as a Read Replica's replication sources.
This check was also added for the cloneDonor parameter of rejoinInstance(), createReplicaCluster(), and addReplicaInstance().
Also, when calling setInstanceOption() with the replicationSources parameter, the source is checked to ensure it is not a Read Replica, the same instance, has a valid state, is reachable, and belongs to the correct Cluster. (Bug #36229274)
It was possible to remove a Cluster member, in a ClusterSet, which belonged to another Cluster. This could result in an unrecoverable ClusterSet.
As of this release, the instance targeted for removal is checked to ensure it is a member of the Cluster from which the command is run. (Bug #36229123)
Attempting to use dba.rebootClusterFromCompleteOutage() with a Read Replica as seed, resulted in an error similar to the following:
```
        Dba.rebootClusterFromCompleteOutage: Group replication does not seem to be active in instance 'db3.mysql.cluster:3306' (RuntimeError)
      
```
As of this release, the error message provides useful information on what has happened and how to fix it. (Bug #36225607)
dba.createReplicaSet with adoptFromAR:true could fail if the host and port values returned were not properly configured on the target instance. The error returned did not provide useful information.
As of this release, if the target instance does not have properly configured host and port values, it is ignored and the user is informed. (Bug #36201015)
The system variable binlog_transaction_dependency_tracking was deprecated in MySQL 8.0.35 and 8.2.0 and was removed in MySQL 8.4.0. As of MySQL 8.4.0, the server uses the WRITESET behavior by default and it is no longer verified or set by the AdminAPI for MySQL 8.4.0.
The behavior is unchanged for previous versions of MySQL. (Bug #36057800)
An error should have been returned when certIssuer, certSubject, replicationSslMode, and any value of certIssuer other than PASSWORD were used when adopting a Cluster or ReplicaSet using adoptFromGR=true. Instead, the invalid options were ignored.
As of this release, dba.createCluster() and dba.createReplicaSet() validate these options and return an error if they are used with adoptFromGR=true. (Bug #36029413)
Running Cluster.rejoinInstance() on an instance in ERROR state, resulted in errors stating that Group Replication settings cannot be changed while Group Replication is running.
As of this release, running Cluster.rejoinInstance() on an instance in ERROR state, automatically stops Group Replication before proceeding with the rejoin process. (Bug #35387205)
AdminAPI no longer retrieves information from the following tables on MySQL 8.4, or higher:
- mysql.slave_master_info
- mysql.slave_relay_log_info
The information which was retrieved from those tables is now retrieved from the Performance Schema.
Note
Behavior is unchanged on instances older than MySQL 8.4.
(Bug #32091724)

Utilities Added or Changed Functionality

A new entry, dbObjectType, is added to the Upgrade Checker utility's JSON output. It contains the type of dbObject which caused the check failure.
See JSON Output from the Upgrade Checker Utility. (Bug #36394895)
The Upgrade Checker now recommends an upgrade path for older versions. For example, if run against MySQL 5.7, it recommends upgrading to MySQL 8.0 before attempting an upgrade to MySQL 8.4. (Bug #36359408)
It is now possible to skip the default upgrade check when running a dump utility with ocimds:true, using the skipUpgradeChecks option.
See Options for Dump Control. (Bug #36227750)
The util.loadDump() summary is enhanced to show the time required for each stage, and throughput progress now includes rows per second. (Bug #36197620)
It is now possible to specify the level of compression for gzip and zstd on the exportTables and dump utilities.
- gzip: Compression level can be set from 0 to 9. Default compression level is 1. For example:
```
"compression": "gzip;level=4"
                
```
- zstd: Compression level can be set from 1 to 22. Default compression level is 1. For example:
```
"compression": "zstd;level=15"
                
```
(Bug #36050770)
A new check is added to the upgrade checker utility, deprecatedRouterAuthMethod. This checks for deprecated or invalid authentication methods in use by MySQL Router internal accounts. (Bug #36004507)
The Upgrade Checker check, orphanedRoutines, is renamed orphanedObjects and includes support for orphaned events. (Bug #31335863)
The following options were added to the upgrade checker utility.
- include: comma-separated list of checks to perform.
- exclude: comma-separated list of checks to ignore.
- list: returns a list of all checks which apply to the current configuration.
See Utility Checks. (WL #15974)
The upgrade check, partitionsWithPrefixKeys, is added to the Upgrade Checker utility. This checks for columns with index prefixes as part of a table's partitioning key. This was deprecated in MySQL 8.0.21 and removed in MySQL 8.4. The check is enabled by default for any upgrade from a version prior to MySQL 8.4.0 to MySQL 8.4.0 or higher. (WL #16159)
The following checks were added to the Upgrade Checker utility:
- removedSysVars: Checks for system variables which are in use in the source but were removed in the target version. Meaning the system variables are set on the source with non-default values.
- sysVarsNewDefaults: Checks for system variables with different default values in the target version.
- sysvarAllowedValues: Checks system variables for valid values.
- invalidPrivileges: Checks for user privileges that will be removed.
- pluginUsage: Checks for deprecated or removed plugins.
(WL #16135)

Utilities Bugs Fixed

Under certain circumstances, util.loadDump() could fail while executing the final stage, the postamble SQL file. The connection to the server was lost.
As of this release, if the connection was lost, it is retried. However, statements which are not idempotent are not retried, nor are statements which load data. (Bug #36381849)
Under certain circumstances, MySQL Shell could close unexpectedly while computing checksum values. (Bug #36323625)
Improved the performance of the upgrade checker utility on MySQL 5.7 instances containing thousands of schemas and tables. (Bug #36223266)
Under certain circumstances, a copy operation could stop responding while scanning the target instance for metadata. (Bug #36221818)
The dump utilities included the MySQL HeatWave Service-reserved username oracle-cloud-agent resulting in the following error:
```
        User 'oracle-cloud-agent'@'localhost' is using an unsupported 
        authentication plugin 'auth_socket' (fix this with 'skip_invalid_accounts' compatibility option)
      
```
The following users are now excluded when loading to, or dumping from, an MySQL HeatWave Service instance:
- ocidbm
- oracle-cloud-agent
- rrhhuser
(Bug #36159820)
Loading a dump on Windows platforms failed if sql_mode was set to STRICT_ALL_TABLES. The following error was returned:
```
        ERROR 1231 (42000): Variable 'wait_timeout' can't be set to the value of '31536000'
      
```
The load utility attempted to set a maximum value for wait_timeout which is not permitted on Windows platforms. (Bug #36119568)
Under certain circumstances dump and load operations could fail with CURL errors Connection reset by peer.
As of this release, the operations are retried in the event of CURL errors CURLE_SSL_CONNECT_ERROR (35) and CURLE_SEND_ERROR (55). (Bug #36022084, Bug #36201255)
When util.dumpInstance() was run with ocimds:true, the upgrade checker utility ran on the entire instance even if schema or table filtering was enabled on the util.dumpInstance() operation.
As of this release, the upgrade checker utility only runs on the schemas or tables being dumped. (Bug #35891996)
The upgrade checker utility did not check for the presence of columns partitioned with temporal types which used non-standard temporal delimiters. As a result, the upgrade could fail or tables could be inaccessible after the upgrade. Non-standard delimiters were deprecated in MySQL 8.0.29.
As of this release, the upgrade checker checks for such delimiters. (Bug #113050, Bug #36004848)
The upgrade checker utility did not check for all old temporal types. Under certain circumstances, this could result in an upgrade failure. (Bug #112991, Bug #36029331)

Functionality Added or Changed

MySQL Shell's default mode is changed from js (JavaScript) to sql in this release.
Note
As of this release, to execute JavaScript code from the command line, you must add the --js option to your command. For example:
```
        mysqlsh user@host:3306 --js -e "println(session)"
      
```
(Bug #36348763)
MySQL Shell's help command (\help or \?) now supports autocomplete. (Bug #36340752)
Output for the thread --locks report now includes information on metadata locks. Also, information on table handles, mutexes, data locks, and RWlocks was added to the thread --raw-locks report. (Bug #36055675)
The V8 JavaScript engine used by MySQL Shell was updated to version 12.0.267.8. (WL #15948)

Bugs Fixed

MySQL Shell returned a socket-specific connection message to the localhost although the connection was TCP and to a remote host. This occurred if a socket path was specified either in the configuration file or on the command line.
As of this release, the transport to use is determined by the right-most parameter on the command line. (Bug #112115, Bug #35751281)