Changes in MySQL Shell 8.0.13 (2018-10-22, General Availability)

• Deprecation and Removal Notes

• AdminAPI Added or Changed Functionality

• AdminAPI Bugs Fixed

• Functionality Added or Changed

• Bugs Fixed

Deprecation and Removal Notes

• If you do not specify a protocol with the \connect command or when starting MySQL Shell, MySQL Shell automatically attempts to use X Protocol for the session's connection, and falls back to classic MySQL protocol if X Protocol is unavailable. The connection type option -ma, which specified that behavior explicitly, is now deprecated.

  The use of a single dash with the connection type options -mx and -mc, for an X Protocol and classic MySQL protocol connection respectively, is also deprecated. These options must now be specified with a double dash (that is, --mx and --mc) with the \connect command or when starting MySQL Shell. They are now defined as aliases of the long form --mysql (--mc) and --mysqlx (--mx) connection type options. (Bug #27363459)

• The mysqlsh command-line options --dbpassword[=password] and --dbuser=user_name are now deprecated. Use the options --password (-p) and --user (-u) instead. (Bug #26049681)

AdminAPI Added or Changed Functionality

• The behavior of Cluster.dissolve() has been updated to make it more consistent with other AdminAPI commands. Now you do not have to pass in the force option to start the command, and there is an interactive prompt available. When all instances belonging to the cluster are online, if MySQL Shell is running in interactive mode then you are prompted to confirm the operation of dissolving the cluster. If MySQL Shell is running in noninteractive mode, when all instances are reachable, or online, then the command removes the instances from the cluster. In the case that instances are not reachable an error is thrown. Pass in the force option to remove instances which are not reachable. (WL #11889)

  References: See also: Bug #27833605, Bug #27837231.

• A new optional parameter exitStateAction can be used with the dba.createCluster() and cluster.addInstance() commands, which enables you to configure the group_replication_exit_state_action variable of an InnoDB Cluster member. The group_replication_exit_state_action variable enables you to specify what action is taken if a member involuntarily leaves the group. When group_replication_exit_state_action is set to ABORT_SERVER (the default value), the instance shuts itself down, and when group_replication_exit_state_action is set to READ_ONLY the instance switches itself to super read only mode instead and goes into the Group Replication ERROR state. (WL #12049)

• The new optional memberWeight option can be used with the dba.createCluster() and Cluster.addInstance() functions to enable you to set the group_replication_member_weight system variable of an InnoDB Cluster server instances in a single-primary cluster. The default value is 50, in other words the system variable default. Set the memberWeight option to an integer between 0 and 100 to configure a member's weight in the failover election process. The value determines the chance of the instance being elected as the primary in the event of a failover. See Single-Primary Mode for more information. (WL #11032)

AdminAPI Bugs Fixed

• The dba.deploySandboxInstance() function in version 8.0.12 deploys the sandbox and includes log_syslog=OFF in the instance's configuration file. This variable was deprecated in MySQL 8.0.12 and was removed in MySQL 8.0.13. Now, the variable has been updated to include the loose_ prefix which makes the server ignore it for a MySQL 8.0.13 sandbox, while maintaining compatibility with earlier version sandboxes. (Bug #28543536)

• Occasionally, when adding an instance to an existing cluster the instance got stuck in the distributed recovery phase resulting in an immutable reported status of RECOVERING. This issue was related to the automatically generated password for the internal replication users created by InnoDB Cluster. (Bug #28219398, Bug #91348)

• In the default interactive mode, whenever using the function dba.rebootClusterFromCompleteOutage() without any parameter, the function failed with an error specifying the cluster name does not exist. Now the default cluster is assumed when the function is issued without a parameter. (Bug #28207565)

• The handling of metadata server changes related to the Cluster.addInstance() has been improved, resulting in the following changes:

  • the correct session is now used for metadata and group operations

  • the Cluster.addInstance() operation aborts and recommends the use of Cluster.rescan() if the instance is in the group but not the InnoDB Cluster metadata

  • the unnecessary parameter super_user_password has been removed

  (Bug #28200661)

• The Windows scripts generated by dba.deploySandboxInstance() incorrectly displayed user output messages in quotes. Additionally, the scripts have been improved and they no longer display executed commands. (Bug #28199954)

• The dba.createCluster() AdminAPI operation always created replication users, even when the adoptFromGR option was used. However, when adopting an already existing Group Replication group no additional users need to be created. (Bug #28054500)

• Error messages issued by the AdminAPI relating to an invalid number of arguments for a function did not include the relevant object and method prior to the message text. These messages have now been standardized. (Bug #27832594)

• When using dba.createCluster() or Cluster.addInstance(), the AdminAPI was setting the values of auto_increment_offset and auto_increment_increment incorrectly. Now the variables are set according to the following logic:

  • for a cluster running in single-primary mode:

    • auto_increment_offset=2

    • auto_increment_increment=1

  • for a cluster running in multi-primary mode:

    • auto_increment_offset=1 and server_id % 7

    • auto_increment_increment=7

  (Bug #27084767)

• AdminAPI was using the incorrect terms for Group Replication. Now clusters are described as single-primary and multi-primary, the multiMasterp option has been deprecated, and the multiPrimary option has been added. (Bug #25926603)

• The result of calling dba.get_cluster().status() when quorum was lost could not be converted to a JSON object, because the string representation of the resultant object contained escape sequences. This issue was not limited to the Cluster.status() method, but affected all arrays and dictionaries returned by the Shell API in Python mode. The internal representation of arrays and dictionaries has been fixed. (Bug #91304, Bug #28200499)

Functionality Added or Changed

• X DevAPI: The connect-timeout connection path parameter (see Connecting to the Server Using URI-Like Strings or Key-Value Pairs) has been added to the X DevAPI, which enables you to specify the number of seconds clients such as MySQL Shell wait until the client stops trying to connect to an unresponsive MySQL server. The value of connect-timeout must be a non-negative integer that defines a time frame in milliseconds. The timeout default value is 10000 milliseconds, or 10 seconds. For example:

  // Decrease the timeout to 2 seconds.
  mysqlx.getSession('[e-mail]?connect-timeout=2000');
  
  // Increase the timeout to 20 seconds
  mysqlx.getSession('[e-mail]?connect-timeout=20000');

  To disable the timeout set the value to 0, meaning that the client waits until the underlying socket times out, which is platform dependent. (WL #12015, WL #12210)

• The upgrade checker utility provided by MySQL Shell, which is the checkForServerUpgrade() function of the util global object, has several enhancements:

  • You can now use the upgrade checker utility to check servers at earlier MySQL 8.0.x releases, as well as MySQL 5.7 servers, for compatibility errors and issues for upgrading.

  • You can now specify a target MySQL Server version to which you plan to upgrade. In MySQL Shell 8.0.13, you can specify release 8.0.11 (the MySQL Server 8.0 GA release), 8.0.12, or 8.0.13. The upgrade checker utility carries out the checks that are relevant for the specified target release. If you specify the short form version number 8.0, or omit the targetVersion option, the utility checks for upgrade to the MySQL Server release number that matches the current MySQL Shell release number, currently 8.0.13.

  • A check has been added for the removed syntax GROUP BY ASC/DESC, returning an error message if this syntax is found in a trigger, event, view, stored procedure, or function.

  • A check has been added for columns defined as ENUM or SET that contain elements longer than 255 characters, returning an error message if any such columns are found.

  • The upgrade checker utility no longer returns a value, making its output easier to parse and process when automation is used.

  You can access the upgrade checker utility from within MySQL Shell or start it from the command line. For instructions and further information, see MySQL Shell Utilities. (WL #12173)

• MySQL Shell onscreen output can now be displayed using a pager such as less or more. You can configure the pager you want to use with the shell.options[pager] option, the \pager command, or the --pager command option. This improves how you work with longer text output in MySQL Shell, specifically the online help and the results of SQL operations. See Using a Pager. (WL #10775)

• The integration of MySQL Shell into command-line environments has been improved. Use the mysqlsh [options] -- shell_object object_method [method_arguments] syntax to pass operations directly to MySQL Shell global objects, bypassing the REPL interface. For example:

  mysqlsh -- util check-for-server-upgrade user@example --output-format=JSON

  which executes the equivalent util.checkForServerUpgrade(user@example, {"outputFormat": "JSON"}) with MySQL Shell and returns the output in JSON format. This makes it easy to integrate MySQL Shell into your automation scripts. To get help for this interface, use the MySQL Shell command \help cmdline. See API Command Line Integration. (WL #10607)

• MySQL Shell has a new JSON import utility that enables you to import JSON documents from a file or standard input to a MySQL Server collection or relational table. The utility parses and validates the supplied JSON documents automatically and inserts them into the target database, removing the need to use multiple INSERT statements or write scripts to achieve this task. The utility can be started in a MySQL Shell session with the util.importJson() method in JavaScript or the util.import_json() method in Python. From the command line, you can use the -- util importJson syntax or the --import command to invoke the utility. (WL #10606)

Bugs Fixed

• The upgrade checker utility provided by MySQL Shell (the util.checkForServerUpgrade() operation) did not report removed functions if they were used in views or events. (Bug #28642534)

• MySQL Shell incorrectly labeled warning messages as error messages in JSON output. (Bug #28546510)

• When MySQL Shell server connection passwords are persisted using a Secret Store, if a classic MySQL protocol connection was made without specifying a port or socket, the saved password could not be retrieved for a subsequent connection. The password storage and retrieval process now ensures that the server URL used to store the password matches subsequent queries with user-provided connection options, even if defaults were used for the original connection. (Bug #28544628)

• A number of improvements have been made to the MySQL Shell prompt, including handling of overlength text, statement splitting, and support for multiple-line prompts. New sample prompt theme files are provided for double-line prompts that use one line for information display and a new line for the input prompt itself, so that additional information can be shown without detracting from the space available for text entry. (Bug #28515394, Bug #92048)

• The --table command line option did not produce the appropriate output format in noninteractive mode. (Bug #28511408)

• Extra spaces before or after the parameter used with the \help command are now trimmed. Previously, the presence of extra spaces made MySQL Shell unable to find the relevant help topic. (Bug #28508724, Bug #92030)

• Some native MySQL Shell objects were not properly wrapped into JavaScript objects, causing memory leaks. The memory-handling mechanism has been corrected. (Bug #28473341)

• If an empty string was provided as the argument for a MySQL Shell command-line option that expects a non-null argument and has no default defined, MySQL Shell did not return an appropriate error. The error handling for command-line arguments has now been improved so that a suitable error is issued in this situation and execution of the command terminates. (Bug #28378553)

• If a session was explicitly closed by the user without closing MySQL Shell, the prompt continued to display the details of the closed session. (Bug #28314383)

• User credentials stored by MySQL Shell could not be automatically retrieved for hosts identified by IPv6 addresses. (Bug #28261301)

• MySQL Shell now displays the build type (commercial or Community Edition) as part of the product version information displayed at startup and when the --help argument is used. (Bug #28242573)

• If a MySQL Shell session was disconnected without closing MySQL Shell (for example, using the session.close() method), a subsequent query in SQL mode did not return a "Not connected" error. MySQL Shell now checks not only that the global session object exists, but also that it has a valid connection to the MySQL server instance. (Bug #28240437)

• On the Windows platform, the background color was not reset in the MySQL Shell window when the terminal was cleared using Ctrl+L. (Bug #28235701, Bug #91102)

• The commercial MySQL Shell package could not be installed on Debian or Ubuntu if the equivalent Community Edition package had already been installed. (Bug #28223781)

• MySQL Shell was using some deprecated functions and properties internally, which caused warning messages to appear in the MySQL Shell log file, although the functions were not executed by users. The deprecated functions and properties have now been removed from the internal code. (Bug #28216558)

• If an invalid value was specified for the MySQL Shell option credentialStore.helper, the resulting error message at MySQL Shell startup was displayed incorrectly. (Bug #28216485)

• The upgrade checker utility provided by MySQL Shell (the util.checkForServerUpgrade() operation) now correctly handles account names with spaces and other blank characters, and skips the permissions check when the server was started with the --skip-grants option. (Bug #28212899, Bug #91326)

• When deleting history entries using the \history command in MySQL Shell, you can now specify a number of history entries to be deleted from the tail of the history, using the format \history delete -number. The handling of history entry numbers for deleted entries has been improved so that when the tail of the history is deleted, those history entry numbers are reused for new entries, and there is no gap. If a \history delete command empties the history, the numbering of history entries now resets as it does when the \history clear command is used. Also, the error message issued if you specify an invalid range of history entries to be deleted (using the format \history delete firstnumber-lastnumber ) has been improved. (Bug #28199513)

• On the Windows platform, using the Ctrl+C key combination in MySQL Shell caused MySQL Shell to close, even if a command was in progress. (Bug #27894642)

• The MySQL Shell code for identifying whether a given IP address is a loopback address did not account for additional IP addresses (besides the 127.0.0.0/8 address block) that had been added by the user to the loopback interface. All IP addresses assigned to the loopback interface are now checked. (Bug #27703779)

• When running MySQL Shell in batch mode, tab separated format is the default for output. In some situations, table format was used for output instead. This issue has now been fixed. A command line option --tabbed has also been added to switch to the tab separated format for output when MySQL Shell is in interactive mode, where the default is table format. (Bug #27546082, Bug #89514)

• Zone IDs in IPv6 addresses are now supported for MySQL Shell connections. A zone identifier is suffixed to the IPv6 address with a percent character (%) as a separator. For example:

  2001:0db8:3c4d:0015::1a2f:1a2b%14

  If an IPv6 address with a zone ID is provided as a URI type string, URL encoding (percent-encoding) must be used for the percent character. For example:

  mysqlsh --uri=user@[2001:0db8:3c4d:0015::1a2f:1a2b%2514]:33060
      shell.connect("user@[2001:0db8:3c4d:0015::1a2f:1a2b%2514]:33060")

  If an IPv6 address with a zone ID is provided using individual parameters or a data dictionary, URL encoding does not need to be used for the percent character, and the IPv6 address can be supplied as seen. For example:

  mysqlsh --user=user --host=2001:0db8:3c4d:0015::1a2f:1a2b%14 --port=33060

  See Connecting to the Server Using URI-Like Strings or Key-Value Pairs. (Bug #27539702)

• When MySQL Shell log entries were output to stderr by prepending @ (at sign) to the value of the --log-level option, and the JSON output format was selected for MySQL Shell, some log entries were not being output in JSON format. The logger now checks and uses the current value of the MySQL Shell outputFormat configuration option as the output format when writing log entries to stderr. (Bug #27480887)

• In SQL mode, MySQL Shell erroneously entered multi-line mode if an unknown command was executed, or if multiple consecutive SQL statement delimiters were used. Now, an appropriate error is returned in these situations. (Bug #27411526)

• On the Windows platform, when a long command was accessed from the MySQL Shell command history and edited at the right edge of the console window, a cursor positioning error caused the command to move up one line and overwrite the output of previous commands. The issue has now been fixed. (Bug #27068352)

• The result printer in MySQL Shell was refactored to improve handling of binary data based on the output format, handling of multi-byte characters, and alignment of table formatting when multi-line characters are present. (Bug #24912154, Bug #24967872)