Important Change; Microsoft Windows: Before installing MySQL Shell, make sure you have the Visual C++ Redistributable for Visual Studio 2015 (available at the Microsoft Download Center) installed on your Windows system. This now applies for both Community and Commercial versions of MySQL Shell.
Important Change: The way which document IDs are generated has been changed. Now document IDs are generated by the server, rather than by the client. As a result the
getDocumentIDs()methods have been removed. To get a list of the document IDs automatically generated by an 8.0.11 and later server, use
Result.getGeneratedIDs(). The type of column generated for the document ID in a collection has changed from
VARBINARY(32). The generated document ID can be overridden manually by including an ID but you must respect the server generated IDs to avoid conflicts. If you are using InnoDB cluster, use the
mysqlx_document_id_unique_prefixvariable to ensure your documents can be moved between replicasets.
Now, if you are adding documents to a collection on a server running a version of MySQL earlier than 8.0.11, you must manually include a document ID as these versions do not add the ID automatically.
The indexing of collections has been improved to make large collections of documents more efficient to navigate. Now, you can create an index based on one or more fields found in the documents in the collection, using a JSON document which maps fields from the collection's documents to MySQL types. The majority of MySQL types are supported, in addition to spatial indexes and GeoJSON data.
Support for the
InnoDBlocking modes has been added to the lock operations. Now you can use these locking modes with the
lockExclusive()methods, for example:
LockContentioncan be one of:
DEFAULT- if the function encounters a row lock it waits until there is no lock
NOWAIT- if the function encounters a row lock it aborts and generates an
SKIP_LOCKED- if the function encounters a row lock it skips the row and continues
For more information see Locking Read Concurrency with NOWAIT and SKIP LOCKED.
MySQL Shell can now connect to a MySQL server with an account that uses the
caching_sha2_passwordauthentication plugin. Assuming the server is configured for encrypted connections, you can use such accounts over both X Protocol and the classic MySQL protocol. See Using Encrypted Connections.Important
If you are not using encrypted connections, to connect over X Protocol with an account that uses the
caching_sha2_passwordauthentication plugin, the user's password must be stored in the cache. Currently there is no way to store the password over X Protocol if not using encrypted connections.
When using the classic MySQL protocol for connections with such an account and unencrypted connections, you can configure MySQL for password exchange using an RSA key pair. MySQL Shell supports such connections and the following command options have been added:
For more information, see Caching SHA-2 Pluggable Authentication.
InnoDB cluster instances running MySQL 8.0.11 and higher can now be configured for InnoDB cluster usage remotely, without the need to log in to the instance and run
dba.configureLocalInstance()locally. Use the new
dba.configureInstance()operation, which enables remote automatic configuration of compatible instances for InnoDB cluster usage and if necessary also supports remote restart of compatible instances after configuration.
Similarly, compatible instances support having any changes to their settings automatically persisted by AdminAPI after any cluster topology changes. Now, when working with remote instances if you create a cluster, add an instance to a cluster, or remove an instance from a cluster supporting this functionality, there is no need to log in to the instance and run
dba.configureLocalInstance()to persist the changes to the instance's option file. This makes working with production clusters, which are built on networked instances, much easier. This also ensures that instances automatically rejoin a cluster in the case of a restart.
As part of this feature the following improvements were made:
Improved display of messages.
Improved detection of loopback hostnames on Debian and Ubuntu, and local instances based on the hostname.
Improved display of required configuration changes.
Replaced automatic configuration of instances after issuing
dba.addInstancewith the configuration check
dba.checkInstance(), aborting the command if the check fails.
When specifying an account in interactive mode, if the user's hostname is local, for example localhost, you are given the option to recreate the account configured for remote usage by using the hostname
%, or to create a new InnoDB cluster administrator account.
References: See also: Bug #27608299, Bug #27112727, Bug #27629803.
MySQL Shell now has a configuration file which stores configuration changes across sessions. Use the new
\optionMySQL Shell command for querying and changing configuration options. Alternatively use the following methods with the
shell.options.set_persist(optionName, value) shell.options.unset_persist(optionName, value)
In addition the new
defaultModeoption has been added, which enables you to configure the programming language which MySQL Shell starts up in. You can override the default mode using the command options.
util.checkForServerUpgrade([uri])operation has been extended to check for the following incompatible features:
partitioned tables in shared tablespaces
\quitcommand was used to exit MySQL Shell, this event could be noted in the error log as an aborted connection. The issue has now been fixed. (Bug #27821045, Bug #90281)
When the MySQL Shell command-line option
--json=rawwas used, the output was actually provided in pretty-printed format, and an empty string was displayed in place of error messages. These issues have now been corrected. (Bug #27733996, Bug #26737357)
When MySQL Shell commands were executed from a script, interactive prompting for passwords and confirmations was not available. Now, interactive prompting is enabled by default when the commands are used in a script, as it is when they are used on the command line. The
--no-wizardcommand line option disables interactive prompting for MySQL Shell commands used in both ways. (Bug #27702250)
After creating a cluster administrative user using
dba.createCluster(), MySQL Shell attempted to reconnect using the new user but still using localhost, which failed causing the whole configuration to fail. Now MySQL Shell no longer switches accounts between administrative account creation and instance configuration. (Bug #27673816)
The changes introduced by Bug#27545850 mean that now it is not possible to modify Group Replication related options while the plugin is starting or stopping. The AdminAPI operations have been modified to ensure that they respect this change, and attempting to issue a statement which would change a Group Replication operation while the plugin is starting results in an error. There is no check for when the plugin is stopping and so you should ensure you do not attempt to configure an instance if there is a chance the plugin is stopping. (Bug #27545850)
util.checkForServerUpgrade()operation now prompts the user for a password interactively if the required password is not provided along with the command. If the
--no-wizardoption has been used to disable the connection wizard, missing credentials instead result in an error and the function is not executed. (Bug #27514395)
util.checkForServerUpgrade()operation was requiring the wrong privileges for the user passed to the function. The user now requires
ALLprivileges, and does not require the
GRANT OPTIONprivilege. (Bug #27506702)
util.checkForServerUpgrade()operation was rejecting host names that included the % (percent) symbol or were specified as a numeric IP address. (Bug #27506079, Bug #27513260)
When rejoining an instance to a cluster the displayed output has been improved. (Bug #27437389)
dba.createCluster()function fails if used on an instance with
innodb_page_size=4k, because the
instance_namecolumn of the instances table in the InnoDB Cluster metadata uses a
VARCHARof size 256, which is too large for the
innodb_page_size=4k. However, the size of this column cannot be changed because it is used to hold hostnames of the cluster members which can have a length up to 255 bytes. This limitation is now validated when using
dba.configureLocalInstance(). (Bug #27329079)
The AdminAPI commands which manage sandboxes failed with an error when using a sandbox directory with non-ASCII characters in the path. This occurred when the user name had a non-ASCII character because the default sandbox directory is a subdirectory of the
%userprofile%path, which is usually based on the current user name. The fix adds Unicode support to the internal provision tool used by AdminAPI. (Bug #27181177)
MySQL Shell now sets the value of
portby calculating the result of
((port * 10) + 1). The
portvariable defaults to 3306, in which case MySQL Shell sets
((3306 * 10) +1), resulting in port 33061 instead of the previous default of 13306. (Bug #27146799)
The online help for all AdminAPI commands which require a connection displayed detailed information on connection data, which cluttered up the details of each command. Now, the help displays an overview of connection details and information about where else to get more help. (Bug #27146290)
When creating a cluster on a Debian type platform with the default system configuration, the`
cluster.addInstance()command failed with an error if the instance hostname was used in the connection parameter. This happened because on these platforms the hostname is resolved to the IP address 127.0.1.1 by default, but this IP address is not supported by the Group Replication Group Communication Service (GCS). The fix adds a validation to the
cluster.addInstance()functions to verify if the connection hostname resolves to 127.0.1.1 and issue an error in that case. (Bug #27095984)
Cluster.forceQuorumUsingPartitionOf()operation was not working with a non-root user, even if that user had all the required privileges. The fix ensures that the specified user is used to connect to all instances, instead of the root user. (Bug #27089930)
dba.createCluster()in interactive mode as a user which did not have all the required privileges resulted in an unexpected halt. The error message generated when issuing
dba.checkInstanceConfiguration()if the account being used did not have the required privileges has also been improved. (Bug #27076753, Bug #27324699)
adoptFromGRto convert a Group Replication group into an InnoDB cluster, the output recommended adding instances. This message has now been improved to show that the instances were already added. (Bug #27061615)
By default, MySQL Shell connections are assumed to require a password, which is requested at the login prompt. A new MySQL Shell command-line option
--no-passwordis provided to explicitly specify that no password is used, and to disable the password prompt. The
--no-passwordoption can be used if socket peer-credential authentication is in use (for Unix socket connections), or for any authentication method where the user has a password-less account (though note that this situation is insecure and not recommended).
The methods previously provided by MySQL Shell for specifying that no password is used for the connection are still valid, and can be used instead of the
--no-passwordoption. These methods are as follows:
If you are connecting using a URI type string, place a
:after the user name in the URI type string but do not specify a password after it.
If you are connecting using individual parameters, specify the
--password=option with an empty value.
In interactive mode the
cluster.removeInstance()AdminAPI function was not accepting the second parameter with the options dictionary. This prevented use of the
forceoption, which failed with an error. (Bug #26986141)
References: See also: Bug #27572618.
cluster.addInstance()function was not checking the validity of the
server_uuidbeing added to the cluster. Now, the
server_uuidof an instance joining the cluster is checked to be unique, and if it is not an error is generated and the instance is prevented from joining the cluster. (Bug #26962715)
When setting up a cluster a replication user is created to enable distributed recovery. If MySQL Shell logging was enabled, the
CREATE USERstatements were not being correctly added to the log. (Bug #26938488)
When an error occurred while returning a result set, the fetch operation was interrupted but the associated error was not reported. The error is now reported correctly. (Bug #26906527)
dba.configureLocalInstance()operations were not correctly reporting any errors related to incorrect configuration of the instance's
server_id. Now, when an error is reported it is displayed in the list of variables not meeting the InnoDB cluster requirements.
In addition, the X Plugin load has been removed from the
my.cnfcreated by AdminAPI for sandbox instances running MySQL version 8.0.11 and later because X Plugin is installed by default for those versions. (Bug #26836230)
clusterAdminoption to create a user which can administer the cluster, the created account had too many privileges. (Bug #26737608)
Support for microseconds has been added to the
mysqlx.dateValue()function and the
Dateobject. (Bug #26429497)
Argument validation and error messages were improved for the
mysqlx.dateValue()function. (Bug #26429426, Bug #26429377)
dbglobal object is not available for connections in SQL mode. This reference has been removed from the message returned by the
\connectcommand in that situation. (Bug #26428665)
When you create a cluster and add instances to it internal users are created, which are required by Group Replication for distributed recovery when instances join the cluster. These automatically generated replication users were not being removed from instances after removing them from the cluster or after dissolving the cluster. (Bug #26395608)
The handling of SQL wildcard characters was corrected for the X DevAPI
Session.getSchema()functions. (Bug #26392984)
A shortcut to uninstall MySQL Shell is no longer provided in Microsoft Windows menus in the group of installed MySQL programs. Uninstallation of MySQL Shell should be handled through MySQL Installer. (Bug #26317449)
If an instance contained InnoDB cluster metadata but was stand alone, in other words it did not belong to a cluster, it was not possible to use
dba.dropMetadataSchema(). (Bug #26315635)
The runtime timer for MySQL Shell, which reports the time taken for each query execution, has been refactored to provide increased precision of 4 digits for fractional seconds. (Bug #25976636, Bug #86135)
In the event of a disconnection, MySQL Shell did not reconnect to the schema that was in use before the connection was lost. The last active schema set by the user is now restored during the automatic reconnection process, and during a manually triggered reconnection using the
\reconnectcommand. (Bug #25974003, Bug #86115)
If you issued
dba.configureLocalInstance()against an instance which was already valid for InnoDB cluster usage and specified the
myCnfoption, but the
my.cnffile was not readable, the operation would print that there are issues that need to be fixed. Now when you set the
myCnfoption, using either
dba.configureLocalInstance(), the operations only use it if necessary. In other words, if the target instance is not valid for InnoDB cluster usage and settings must be changed. (Bug #25702994)
cluster.status()AdminAPI methods return JSON objects containing the same information but some fields were identified by different tags. To make the tags consistent, the object returned from
cluster.describe()has changed so that
instanceshas been replaced with
address. (Bug #25247515)
MySQL Shell no longer attempts to reconnect automatically when the connection to the server is lost. A new MySQL Shell command
\reconnectis provided, which makes MySQL Shell try several reconnection attempts for the current global session with the existing connection parameters. If those attempts are unsuccessful, you can make a fresh connection using the
\connectcommand and specifying the connection parameters. (Bug #25105307)
Creating a cluster from an existing Group Replication group by using the
adoptFromGR:trueoption on an instance which already belonged to cluster was not being correctly detected. Now such a situation is detected and generates an error. (Bug #25061891, Bug #25664766)
MySQL Shell is able to create a session to an IPv6 address, but it failed to create an InnoDB cluster using such connections, reporting an URI-related error. This was related to the encoding of the URI containing an IPv6 address, which has been fixed. The core issue, IPv6 support for AdminAPI is a known issue as Group replication requires an IPv4 network, see Group Replication Requirements. The implementation of InnoDB cluster related operations has been modified in order to check if operations are executed using an IPv4 based session and IPv4 connection data. An exception is generated if these conditions are not met. (Bug #25042407)
A memory leak was fixed that occurred if MySQL Shell was started and a connection was made to the MySQL server, then the user exited MySQL Shell without executing any commands. (Bug #24794589)
Attempting to add two different instances with the same label to an InnoDB cluster correctly resulted in an error, however the instance with the duplicated label was being left with a partially initialized configuration. (Bug #24761416)