MySQL Shell 8.0 Release Notes

35 Changes in MySQL Shell 8.0.4 (2018-01-25, Release Candidate)

Deprecation and Removal Notes

  • The command line options --classic, --node, --sqln, and --ssl were stated as deprecated, but actually had been removed. MySQL Shell now handles the options again, but prints a warning message when they are used. The deprecated options are processed as their replacement options, as follows:

    (Bug #27012385)

AdminAPI Added or Changed Functionality

  • When you create clusters or add instances you can now override the default group name, local addresses, and group seeds. This makes it easier to customize your clusters. The following options were added to the dba.createCluster() and cluster.addInstance() commands:

    • use groupName with dba.createCluster() to set the name of the cluster

    • use localAddress to set the address which an instance provides to communicate with other instances

    • use groupSeeds to set the instances used as seeds when instances join the cluster

    For more information, see Customizing InnoDB Cluster Member Servers. (Bug #26485254, Bug #26838005, WL #11162)

  • Connections to an InnoDB cluster have been simplified. Now, when you issue dba.getCluster() and the active Shell session is not a connection to the primary, the cluster is queried for the primary information and a connection to the primary is automatically opened. This ensures that configuration changes can be written to the metadata. As part of this improvement you can now configure the type of MySQL Shell connection to an InnoDB Cluster with the following options which have been added:

    Additionally the following changes were made:

    • The dba.resetSession() method has been removed.

    • A new disconnect() method has been added to the cluster object, which closes all internal sessions opened by the cluster. InnoDB Cluster operations on a disconnected cluster object result in an error.

    • The output of the Cluster.status() method now includes the groupInformationSourceMember field, which shows the URI of the internal connection used by the cluster object to obtain information about the cluster.

    (WL #11251)

    References: See also: Bug #25091586.

AdminAPI Bugs Fixed

  • Account validation did not work correctly unless the session account existed. Now, validation is done using the account that was authenticated by the server. (Bug #26979375)

  • The AdminAPI in MySQL Shell for working with InnoDB cluster only supports TCP connections to server instances. The AdminAPI now checks that a TCP connection is in use before starting an operation that requires database access, instead of attempting the operation with another connection type and not succeeding. (Bug #26970629)

  • If you issued STOP GROUP REPLICATION on an instance that belonged to a cluster, attempting to rejoin the instance to the cluster failed because the wrong Group Replication seeds were being used. Now, Cluster.rejoinInstance() correctly sets group_replication_group_seeds based on the group_replication_local_address of all currently active instances in the cluster. (Bug #26861636)

  • Sometimes the dba.addInstance() command failed with an error indicating that the server was in RECOVERING state despite being ONLINE. The fix ensures the correct instance state is returned. (Bug #26834542)

  • If the user running MySQL Shell did not have write permissions to the option file configured by AdminAPI, no error was displayed. (Bug #26830224)

  • With the addition of WL#10470, the default value of server_id has changed to 1. As the server ID has to be unique for each instance, this caused issues with AdminAPI. Now, server instances with server_id=1 are correctly identified as incorrectly configured for InnoDB Cluster use. (Bug #26818744)

  • AdminAPI now supports Python 2.6 in addition to Python 2.7, removing the need to manually install on Oracle Linux 6. (Bug #26809748)

  • After removing an instance from a cluster using Cluster.removeInstance(), the instance silently rejoined the Group Replication group after it restarted. This happened because group_replication_start_on_boot was set to ON by default. Now, for instances running MySQL version 8.0.4 and later, the fix sets group_replication_start_on_boot to OFF in the option file. For instances running a MySQL version earlier than 8.0.4, a warning is issued to tell you to manually edit group_replication_start_on_boot in the instance's option file to avoid the issue. (Bug #26796118)

  • Using AdminAPI commands on Windows that required SSL resulted in an error due to the Python version being used. (Bug #26636911)

  • Creating an InnoDB Cluster from an existing Group Replication deployment, by using the adoptFromGR option with the dba.createCluster() command, would fail with an error stating that the instance was already part of a replication group. The issue was only present in the MySQL Shell default wizard mode. The fix ensures that the interactive layer of the dba.createCluster() command allows the use of the adoptFromGR option. (Bug #26485316)

  • The warnings generated when creating and adding sandbox instances have been improved. (Bug #26393614)

  • When working with instances that had require_secure_transport=ON, AdminAPI commands that required a connection to the instance failed. (Bug #26248116)

  • The Cluster.dissolve() command was trying to stop Group Replication on all of the instances registered in the metadata which lead to connection errors if any of those instances were not contactable, in other words with the state (MISSING). The fix ensures that only instances which can be contacted, in other words with the state ONLINE, are stopped. (Bug #26001653)

  • When adding instances to an InnoDB Cluster using the appropriate AdminAPI operations, checks are performed to verify the compatibility of any existing tables. If incompatible tables (for example using MyISAM) are detected then an error is issued. However the error message was referring to an option not available for the AdminAPI operations: --allow-non-compatible-tables. (Bug #25966731)

  • The cluster.rejoinInstance() command attempted to rejoin an instance even if was already part of the cluster. Now, only instances in the MISSING state are accepted by cluster.rejoinInstance(). Attempting to rejoin an instance in any other state fails with an error. (Bug #87873, Bug #26870329)

  • On Unix, if Python 3 was installed AdminAPI commands failed. (Bug #87731, Bug #26785584)

  • When using the dba.checkInstanceConfiguration() and dba.configurelocalinstance() commands, the account being used was not being checked if it had enough privileges to actually execute the command. The fix ensures that account has the required privileges before proceeding. This also required a change of the privileges given to clusterAdmin users. (Bug #87300, Bug #26609909)

Functionality Added or Changed

  • X DevAPI: A new patch() operation has been added to the modify() function which enables you to modify a document by merging in a set of changes. For more information see JSON_MERGE_PATCH(). (WL #10856)

  • X DevAPI: MySQL Shell performs automatic _id generation on collection add operations when no _id is specified on the documents being added. The autogenerated _id is created using the UUID() function. Now, the order of the tokens used has changed from aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee, where eeeeeeeeeeee is the MAC Address, to eeeeeeeeeeee-dddd-cccc-bbbb-aaaaaaaa. (WL #10005)

  • X DevAPI: Sessions created by X DevAPI using either mysql.getClassicSession(connection_data) or mysqlx.getSession(connection_data) now use ssl-mode=REQUIRED as the default if no ssl-mode is provided, and neither ssl-ca nor ssl-capath is provided. If no ssl-mode is provided and any of ssl-ca or ssl-capath is provided, all Sessions created by MySQL Shell now default to ssl-mode=VERIFY_CA. (WL #10706)

  • X DevAPI: In addition to the existing CRUD commands which work on documents in a collection by matching a filter, the following operations have been added to enable you to work with single documents:

    • Collection.replaceOne(string id, Document doc) updates (or replaces) the document identified by id with the provided one, if it exists.

    • Collection.addOrReplaceOne(string id, Document doc) add the given document. If the id or any other field that has a unique index on it already exists in the collection, the operations updates the matching document instead.

    • Document Collection.getOne(string id) returns the document with the given id. This is a shortcut for Collection.find("_id = :id").bind("id", id).execute().fetchOne().

    • Result Collection.removeOne(string id) removes the document with the given id. This is a shortcut for Collection.remove("_id = :id").bind("id", id).execute().

    Using these operations you can reference documents by ID, making operations on single documents simpler by following a load, modify and save pattern such as: 

    doc = collection.getOne(id);
doc["address"] = "123 Long Street";
collection.replaceOne(id, doc);

    (WL #10849)

  • X DevAPI: You can now use savepoints with MySQL Shell sessions. The following methods have been added to the Session object:

    • Use setSavepoint() to generate a savepoint. The server executes the SAVEPOINT SQL statement and returns the generated savepoint name.

    • Use setSavepoint(name) to specify the name used by the SAVEPOINT SQL statement.

    • Use releaseSavepoint(name) to execute the RELEASE SQL statement.

    • Use rollbackTo(name) to execute the ROLLBACK TO name SQL statement.

    Any names passed to these functions are checked to make sure that the name is not null or an empty string. Names such as '', "", ``, and so on are not allowed even though they are allowed by the server. For more information, see SAVEPOINT, ROLLBACK TO SAVEPOINT, and RELEASE SAVEPOINT Statements. (WL #10868, WL #10869)

  • X DevAPI: X DevAPI now supports row-locking for CRUD operations on tables and collections. Use the lockShared() method for write locks and the lockExclusive() method for read locks, which have been added to find() and select(). Either method can be called any number of times, including none, in any combination. But the locking type to be used is always the last one called. Once you call a lock method you can only then execute the operation, calling execute() or bind(). For more information, see InnoDB Locking. (WL #10850, WL #10641)

  • X DevAPI: The X DevAPI drop operations have been improved. Now, the drop() methods are at the same level as the create() methods and they all return nothing. There is now no need to use execute() after the drop method. If a drop method is called on an object which no longer exists in the database there is now no error.

    This modifies Session objects so that:

    • dropSchema() returns Nothing

    • dropTable(String schema, String name) is removed

    • dropCollection(String schema, String name) is removed

    • dropView(String schema, String name) is removed

    This modifies Schema objects so that:

    • Nothing dropCollection(String name) is added

    This modifies Collection objects so that:

    • dropIndex(String name) is a direct operation, meaning .execute() is no longer needed

    • dropIndex(String name) returns Nothing

    (WL #10712)

  • X DevAPI: The mysql module, used with classic sessions for SQL connections to instances, has been streamlined. This has resulted in the following changes:

    • The new getSession() function has been added to the mysql module to create a classic session. This function works in the same way as the existing mysql.getClassicSession() function.

    • The runSql() method of ClassicSession has been extended to take a list of arguments to replace with placeholders in the query. For example, now you can issue: 

      session.runSql("select * from tbl where name = ? and age > ?", ["Joe", "20"])

      Additionally a query() function has been added to ClassicSession as an alias to runSql(), making it consistent with Session.query().

    • The following functions have been removed from ClassicSession:

      • createSchema()

      • getSchema()

      • getDefaultSchema()

      • getCurrentSchema()

      • setCurrentSchema()

      • ClassicSchema()

    • The ClassicTable object has been removed.

    • The following Table and View DDL functions have been removed from Schema objects:

      • dropTable()

      • dropView()

    • The behavior of the global db variable has been modified. When a global connection is created and the connection data includes a default schema, the global db variable is set to the corresponding Schema object. Now, this is not done for connections through the classic MySQL protocol, such as those created by ClassicSession.

    (WL #11180)

  • MySQL Shell now supports autocompletion of text preceding the cursor by pressing the Tab key. Autocompletion is available for:

    • Built-in MySQL Shell commands, for example typing \con followed by the Tab key completes to \connect.

    • SQL, JavaScript and Python language keywords depending on the current MySQL Shell mode.

    • Table names, column names, and active schema names in SQL mode, based on the current default schema.

    Autocompletion can be configured using the following command options:

    (WL #10447)

  • You can now use Unix sockets for X Protocol connections. Socket file paths in URI type strings should be either percent encoded, such as root@/home%2Fuser%2Fmysql-sandboxes%2F3310%2Fsandboxdata%2Fmysqlx.sock, or surrounded by parenthesis such as root@(/home/user/mysql-sandboxes/3310/sandboxdata/mysqlx.sock). The --socket option cannot be combined with the --port option. See Connecting to the Server Using URI-Like Strings or Key-Value Pairs. (WL #10503)

  • Use util.checkForServerUpgrade([uri]) to check if a server can be upgraded from the version it is currently running to the next major series release. For example, you can verify that a server instance running MySQL 5.7 satisfies the upgrade prerequisites for MySQL 8.0, see Preparing Your Installation for Upgrade. To verify a server instance at a URI type string such as user@example.com:3306 issue: 

    util.checkForServerUpgrade(['user@example.com:3306'])

    MySQL Shell provides a report on anything in the table space which would cause a problem when upgrading the instance to MySQL 8.0. (WL #11051)

  • MySQL Shell builds against MySQL server version 8.0.4 and OpenSSL. (WL #11343)

  • MySQL 8.0.4 uses the caching_sha2_password authentication plugin and encrypted connections by default. This means any new accounts created in MySQL use these features. The new authentication method is completely transparent if the connection is made with encrypted connections enabled, which is the default, and the preferred mode of connection. If encrypted connections are explicitly disabled, the following limitations apply:

    • X Protocol sessions require encrypted connections.

    • If the caching_sha2_password plugin reports an error such as Authentication requires a secure connection, it is not possible to connect to the account with MySQL Shell, until either an encrypted connection is made or the mysql client is used to clear the error.

    See Using Encrypted Connections and Caching SHA-2 Pluggable Authentication. (WL #11513)

Bugs Fixed

  • Attempting a server connection without specifying the port or socket, when using an expired or temporary password, failed with an error requiring a password reset. The default connection data is now set at an appropriate point in connection processing, so the connection succeeds. (Bug #27266648)

  • MySQL Shell required the option name ssl-ciphers instead of the standard MySQL option name --ssl-cipher to specify the list of permitted ciphers for connection encryption. The standard option name --ssl-cipher is now required in MySQL Shell. (Bug #27185275)

  • The --show-warnings option was not working in MySQL Shell. (Bug #27036716)

  • The output of \status when using a Unix socket for connections was showing a relative path. Now the absolute path of the socket is shown. (Bug #26983193)

  • MySQL Shell now automatically pre-loads the built-in mysql and mysqlx API modules when it is invoked in batch mode, as well as when it is used in interactive mode. (Bug #26174373)

  • The user configuration path for MySQL Shell defaults to %AppData%\MySQL\mysqlsh\ on Windows, and ~/.mysqlsh/ on Unix. This directory is used for the MySQL Shell history file (history), log file (mysqlsh.log), and theme file (prompt.json). It is also the final location that MySQL Shell searches for startup scripts (mysqlshrc.js or mysqlshrc.py).

    You can now override the user configuration path by specifying an alternative path using the MYSQLSH_USER_CONFIG_HOME environment variable. A directory specified by that environment variable is used by MySQL Shell for the user configuration data in place of %AppData%\MySQL\mysqlsh\ on Windows, and ~/.mysqlsh/ on Unix. (Bug #26025157)

  • For file processing, MySQL Shell now expands a leading tilde in a file path to the appropriate home directory. MySQL Shell identifies the home directory using a relevant environment variable, or looks it up for the logged-in user. (Bug #25676405)

  • MySQL Shell now provides a program_name connection attribute to the server at connect time, with the value mysqlsh. Connection attributes are displayed in the Performance Schema connection attribute tables. (Bug #24735491, Bug #82771)

  • Running help() in MySQL Shell in Python mode caused an AttributeError. (Bug #24554329, Bug #82767)

  • Arrays and Objects now accept the IN operator. For example: 

    collection.find("'Fred' IN username")

    (WL #10848, WL #10610)

MySQL Documentation Library