Documentation Home
MySQL Shell Release Notes
Related Documentation
MySQL Shell 8.0 User Guide
Download these Release Notes
PDF (US Ltr) - 0.6Mb
PDF (A4) - 0.6Mb
MySQL Shell Release Notes  /  Changes in MySQL Shell 8.0.19 (2020-01-13, General Availability)

Changes in MySQL Shell 8.0.19 (2020-01-13, General Availability)

AdminAPI Added or Changed Functionality

  • Incompatible Change: The AdminAPI now includes InnoDB ReplicaSets, that enables you to administer asynchronous replication set ups in a similar way to InnoDB Cluster. The addition of InnoDB ReplicaSet means that the InnoDB Cluster metadata schema has been upgraded to version 2.0. Regardless of whether you plan to use InnoDB ReplicaSet or not, to use MySQL Shell 8.0.19 and AdminAPI you must upgrade the metadata of your clusters. Connect MySQL Shell's global session to your cluster and use the new dba.upgradeMetadata() operation to upgrade the cluster's metadata to use the new metadata.

    Warning

    Without upgrading the metadata you cannot use MySQL Shell 8.0.19 to change the configuration of a cluster created with earlier versions. You can only read the configuration of the cluster, for example using Cluster.status().

    The dba.upgradeMetadata() operation upgrades any automatically created MySQL Router users to have the correct privileges. Manually created MySQL Router users with a name not starting with mysql_router_ are not automatically upgraded. This is an important step in upgrading your cluster, only then can the MySQL Router application be upgraded. See Upgrade InnoDB Cluster.

    Warning

    A cluster which is using the new metadata cannot be administered by earlier MySQL Shell versions, for example once you upgrade to version 8.0.19 you can no longer use version 8.0.18 or earlier to administer the cluster.

    To get information on which of the MySQL Router instances registered with a cluster require the metadata upgrade, issue cluster.listRouters({'onlyUpgradeRequired':'true'}). (WL #11033, WL #13386)

  • AdminAPI now supports socket connections to be used for cluster and replica set operations. (Bug #26265826)

  • You can now get information about the MySQL Router instances registered with an InnoDB Cluster, and unregister a Router from a cluster, for example when you stop using it. Use the Cluster.listRouters() operation to show a list of all Routers registered with the cluster. The results provides information such as the hostname, ports, and so on.

    To filter the list to only show Router instances that do not support the latest metadata version use the onlyUpgradeRequired option, for example by issuing Cluster.listRouters({'onlyUpgradeRequired':'true'}). The returned information shows whether the Router instance is compatible or not with the Metadata version supported by the version of MySQL Shell you are using, which you can use when upgrading a cluster.

    To remove a registered Router from a cluster, use the Cluster.removeRouterMetadata(router) operation. (WL #13466, WL #13462)

  • The AdminAPI includes support for InnoDB ReplicaSet, that enables you to administer asynchronous replication sets in a similar way to InnoDB Cluster. InnoDB ReplicaSet enables you to deploy an asynchronous replication set consisting of a single primary and multiple secondaries (traditionally referred to as the MySQL replication master and slaves). You administer a ReplicaSet using AdminAPI operations, for example to check the status of the InnoDB ReplicaSet, and manually failover to a new primary in the event of a failure. Similar to InnoDB Cluster, MySQL Router supports bootstrapping against InnoDB ReplicaSet, which means you can automatically configure MySQL Router to use your InnoDB ReplicaSet without having to manually configure files. This makes InnoDB ReplicaSet a quick and easy way to get MySQL replication and MySQL Router up and running, making it well suited to scaling out reads, development environments, and applications that do not require the high availability offered by InnoDB Cluster. See Upgrade InnoDB Cluster. (WL #13235)

AdminAPI Bugs Fixed

  • The dba.configureLocalInstance() operation could fail with a key not found (LogicError) error when executed on a non-sandbox instance where it did not have access to the my.cnf option file and the operation requested an output configuration file to be specified. (Bug #30657204)

  • The extended status information now displays the version of metadata found on an InnoDB Cluster or InnoDB ReplicaSet. For example issue: 

    mysql-js> Cluster.status({extended=1})
mysql-js> ReplicaSet.status({extended=1})

    (Bug #30624615)

  • If a cluster had been deployed with MySQL Shell version 8.0.14 or earlier, the metadata contained an invalid port number for X Protocol connections. The metadata upgrade catches such ports and removes the invalid number. To avoid problems with routing due to this incorrect port, upgrade your cluster's metadata. See Upgrade InnoDB Cluster. (Bug #30618264)

  • When a replication replica was configured to read from an InnoDB Cluster primary, even with the appropriate replication filtering to ignore the metadata replication was failing when an instance was added to the cluster using MySQL Clone as the recovery method. This was because the recovery process was granting a privilege on an account, which failed and broke replication. (Bug #30609075)

  • The Cluster.removeInstance() operation was issuing a misleading error message when the instance was unreachable, indicating that it did not belong to the cluster when an alternative valid host or IP was used. Now, the error indicates that the instance is unreachable. (Bug #30580393)

  • Although MySQL Shell version 8.0.18 added support for IPv6 in WL#12758, using an InnoDB Cluster which consisted of MySQL Shell version 8.0.18 and MySQL Router 8.0.18 with IPv6 addresses was not possible. With the release of version 8.0.19 of both MySQL Shell and MySQL Router, be aware that:

    • combining MySQL Shell version 8.0.18 with MySQL Router 8.0.18 causes Router to fail, due to no IPv6 support. (Bug#30354273)

    • combining MySQL Shell version 8.0.18 with Router 8.0.19 in a cluster which uses X Protocol connections, results in AdminAPI storing mysqlX IPv6 values incorrectly in the metadata, causing Router to fail. (Bug#30548843) However, combining MySQL Shell version 8.0.18 with Router 8.0.19 in a cluster which uses MySQL classic protocol connections, is possible.

    Therefore, to use InnoDB Cluster with IPv6 addresses, regardless of the protocol used, the recommended deployment is MySQL Shell 8.0.19 and MySQL Router 8.0.19. (Bug #30548843)

    References: See also: Bug #30354273.

  • When using automatic rejoin, if a target instance was rejoining the cluster, operations such as dba.rebootClusterFromCompleteOutage(), Cluster.status(), and so on were failing. Now, clusters consider automatic rejoin as an instance state instead of a check that always aborts the operation. This ensures that Cluster.status() is reported even for instances which are rejoining the cluster, and that dba.rebootClusterFromCompleteOutage() can detect instances which are rejoining the cluster and override the rejoin operation so that the cluster can be properly rebooted. (Bug #30501590)

  • SSL client certificate options for the clusterAdmin user were not being copied when setting up connection options, which made them fail when connecting. (Bug #30494198)

  • When the automatically calculated localAddress is not valid, for example when it exceeds the valid range, the error message has now been improved. See Configuring InnoDB Cluster Ports. (Bug #30405569)

  • The AdminAPI ensures that all members of a cluster have the same consistency level as configured at cluster creation time. However, when high and non-default consistency levels were chosen for the cluster, adding instances to it resulted in an error 3796 which indicates that group_replication_consistency cannot be used on the target instance. This happened because the consistency values of BEFORE, AFTER and BEFORE_AND_AFTER cannot be used on instances that are RECOVERING and several transactions happen while the instance is in the RECOVERING phase. Other AdminAPI commands result in the same error for the same scenario (high global consistency levels) whenever at least one member of the cluster is RECOVERING. For example, dba.getCluster(). The fix ensures that all sessions used by the AdminAPI use the consistency level of EVENTUAL when the cluster's consistency level is BEFORE, AFTER or BEFORE_AND_AFTER. (Bug #30394258, Bug #30401048)

  • Some privileges required for persisting configuration changes on MySQL 8.0 servers were missing for the clusterAdmin users created by AdminAPI. In particular, an Access Denied error was being issued indicating the SYSTEM_VARIABLES_ADMIN and PERSIST_RO_VARIABLES_ADMIN privileges were required. Now these privileges are added for the clusterAdmin user on MySQL 8.0 servers. (Bug #30339460)

  • When using MySQL Clone as the recovery method, trying to add an instance that did not support RESTART to a cluster caused MySQL Shell to stop unexpectedly. Now, in such a situation a message explains that Cluster.rescan() must be used to ensure the instance is added to the metadata. (Bug #30281908)

  • The autocommit and sql_mode system variables are session settings, but they can be set globally to different values. AdminAPI was failing if these variables had non-default values in several different ways, for example DML was failing, system variables could not be set and so on. (Bug #30202883, Bug #30324461)

  • Attempting to bootstrap MySQL Router against an InnoDB Cluster which had the cluster administration user modified or removed was failing. This was caused by the privileges granted on the InnoDB Cluster metadata table. The recommended solution is to upgrade to metadata 2.0, which changes the privileges on the metadata to ensure this issue does not occur. See Upgrade InnoDB Cluster. (Bug #29868432)

  • When you created a multi-primary cluster, the group_replication_enforce_update_everywhere_checks system variable was not being set automatically. However, switching to multi-primary mode automatically enables group_replication_enforce_update_everywhere_checks and switching to single-primary disables it. Now, the dba.createCluster() operation sets the group_replication_enforce_update_everywhere_checks variable as appropriate for single-primary or multi-primary clusters. (Bug #29794779)

  • In version 8.0.16, the autoRejoinTries option was added to define the number of times an instance attempts to rejoin the cluster after being expelled. The option is a valid cluster setting, configurable through the AdminAPI like many other options. However, the autoRejoinTries option was not being listed by Cluster.options(). (Bug #29654346)

  • The InnoDB Cluster metadata now supports host names up to 265 characters long, where 255 characters can be the host part and the remaining characters can be the port number. (Bug #29507913)

  • dba.createCluster() could fail if the instance had been started with innodb_default_row_format=COMPACT or innodb_default_row_format=REDUNDANT. This was because no ROW_FORMAT was specified on the InnoDB Cluster metadata tables, which caused them to use the one defined in innodb_default_row_format. The metadata schema has been updated to use ROW_FORMAT = DYNAMIC. (Bug #28531271)

  • When an instance restarted, for example after a complete outage, it could have super_read_only disabled. This meant that instances which were not the primary could be written to, resulting in the instances no longer being in synchrony. This could result in dba.rebootClusterFromCompleteOutage() failing with a Conflicting transaction sets error. The fix ensures that all instances have super_read_only=1 persisted while they belong to the cluster, either through SET PERSIST_ONLY, or through dba.configureLocalInstance() for instances which do not support persisting. (Bug #97279, Bug #30545872)

  • The Cluster.status() operation could report an error get_uint(24): field value out of the allowed range because it was always expecting a positive value for some fields that could in fact have negative values. For example, this could happen when the clocks of different instances were offset. (Bug #95191, Bug #29705983)

  • If you changed the name of the clusterAdmin user once a cluster had been created, you could encounter an error such as The user specified as a definer does not exist. This was because the clusterAdmin user was used as the DEFINER of the views required by InnoDB Cluster, and if this user is renamed then the definer is in effect missing. In version 8.0.19 the InnoDB Cluster metadata has been changed to avoid this problem, use dba.upgradeMetadata() to upgrade the cluster. See Upgrade InnoDB Cluster. Clusters deployed with 8.0.19 and later do not suffer from this issue. (Bug #92128, Bug #28541069)

  • It was not possible to create a multi-primary cluster due to cascading constraints on the InnoDB Cluster metadata tables. This has been fixed in version 8.0.19 and so to solve this issue upgrade your cluster using dba.upgradeMetadata(). See Upgrade InnoDB Cluster. (Bug #91972, Bug #29137199)

Functionality Added or Changed

  • The JavaScript function require() has been improved in MySQL Shell to support loading of local modules, in addition to built-in modules and modules that are on module search paths already known to MySQL Shell. If you specify the module name or path prefixed with ./ or ../, MySQL Shell now searches for the specified module in the folder that contains the JavaScript file or module currently being executed, or in interactive mode, searches in the current working directory. If the module is not found in that folder, MySQL Shell proceeds to check the well-known module search paths specified by the sys.path variable. (WL #13119)

  • MySQL Shell's upgrade checker utility (the util.checkForServerUpgrade() operation) includes the following new and extended checks:

    • The utility now flags all date, datetime, and timestamp columns that have a default value of zero, and states if the SQL mode (either global or for the current session) allows the insertion of zero values for these column types. By default, these are no longer permitted in MySQL, and it is strongly advised to replace zero values with valid ones, as they might not work correctly in the future.

    • The check for usage of removed functions now includes the PASSWORD() function.

    • The utility now checks for any orphaned tables which are recognized by InnoDB, but the SQL layer thinks they are handled by a different storage engine. This situation can happen if manual updates are made in the data directory. Orphaned tables can stall the upgrade process if they are present.

    (WL #13526)

  • In MySQL Shell's interactive mode, for JavaScript, Python, or SQL, the \source command or its alias \. can be used to execute code from a script file at a given path. For compatibility with the mysql client, in SQL mode only, you can now execute code from a script file using the source command with no backslash and an optional SQL delimiter. source can be used both in MySQL Shell's interactive mode for SQL, to execute a script directly, and in a file of SQL code processed in batch mode, to execute a further script from within the file. In SQL mode only, you can also now use the \source command's alias \. (which does not use a SQL delimiter) in a file of SQL code processed in batch mode. So with MySQL Shell in SQL mode, you could now execute the script in the /tmp/mydata.sql file from either interactive mode or batch mode using any of these three commands: 

            source /tmp/mydata.sql; 
        source /tmp/mydata.sql 
        \. /tmp/mydata.sql  

    The command \source /tmp/mydata.sql is also valid, but in interactive mode only. (WL #13320)

Bugs Fixed

  • When searching for startup scripts in the platform's standard global configuration path (in the folder %PROGRAMDATA%\MySQL\mysqlsh on Windows, or /etc/mysql/mysqlsh/ on Unix), MySQL Shell checked for the incorrect script name shellrc, rather than the correct name mysqlshrc. (Bug #30656548)

  • On Windows, MySQL Shell passed UTF-8 encoded strings to the NTFS file system, which stores file names in UTF-16 encoding. The mismatch caused files and folders to be incorrectly named or located when non-ASCII characters were used. MySQL Shell now converts all strings used in operations on NTFS from UTF-8 to UTF-16, and converts back to UTF-8 all strings received from Unicode function versions of Windows API calls. (Bug #30538516)

  • Some host names were not parsed correctly in the connection data provided when running MySQL Shell's upgrade checker utility checkForServerUpgrade(), including where the user account's host name had been set up by specifying an IP address and subnet mask. (Bug #30536355, Bug #30696901, Bug #98056)

  • If the MySQL Server environment variable MYSQL_UNIX_PORT (which specifies the default Unix socket file) was updated by the same process that was then used to create a MySQL Shell connection to a MySQL server using a socket file, MySQL Shell cached and connected using the socket file path that had previously been set, but reported that a connection had been made using the updated socket file path. The correct socket file used for the connection is now displayed. (Bug #30533318)

  • If a prompt theme file used to customize the MySQL Shell prompt contained an ill-formed UTF-8 sequence, on startup an error message was displayed in place of the prompt text. MySQL Shell now validates the prompt theme file before loading it, and if there is a problem, uses a default prompt instead and issues an error message. (Bug #30406283)

  • If MySQL Shell was installed on Microsoft Windows at a non-default location, and subsequently uninstalled, files created after installation by the Python library used by MySQL Shell were not removed. These files are now removed when MySQL Shell is uninstalled from any location. (Bug #30333801)

  • Previously, most MySQL Shell options that expected an integer value could be set with an empty value, in which case the value 1 was applied. The exception was the logLevel option, which required a value. The behavior has now been standardized so all MySQL Shell options that expect a non-string value must be specified with a value, with the exception of options set on the command line. The affected options are dba.gtidWaitTimeout, dba.logSql, history.maxSize, and verbose. (Bug #30320839)

  • When using MySQL Shell in interactive mode, using a template literal in a multiple-line JavaScript statement resulted in an error. The issue has now been fixed. (Bug #30248651)

  • In Python mode, when multiple statements were input to MySQL Shell at the same time for execution in interactive mode, only the first statement was executed correctly. (Bug #30029568)

  • The Debian control file for MySQL Shell has been corrected to remove packaging errors that occurred when certain variables were not defined. Thanks to Evgeniy Patlan for the fix. (Bug #29802600, Bug #95158)

  • In MySQL Shell's parser for URI-like connection strings, handling of path separators was previously platform dependent. Unified parsing has now been introduced so that Windows named pipes can be parsed correctly on Unix platforms, and Unix socket files can be parsed correctly on Windows platforms. (Bug #29456981)

  • MySQL Shell now looks up host names by obtaining the fully qualified domain name of the provided address and using the absolute form of this name (with a trailing dot). This method avoids potential issues caused by some network configurations that resolve host names as loopback addresses when they are actually addressable externally. (Bug #27704559)


PREV   HOME   UP   NEXT
Related Documentation
MySQL Shell 8.0 User Guide
Download these Release Notes
PDF (US Ltr) - 0.6Mb
PDF (A4) - 0.6Mb