MySQL Shell 8.0.12 introduces a new feature which allows users to store and automatically retrieve their MySQL account credentials. This enables them to seamlessly work with various servers without explicitly providing the password for each new connection and create secure unattended scripts which do not need to include plain text passwords.

Shell is going to automatically retrieve and store credentials in the following scenarios:

• if mysqlsh is invoked with any connection option at the command line, when establishing the first session,
• in case of built-in \connect command,
• in case of shell.connect() method,
• in case of all AdminAPI methods.

Automatic retrieval and storage of credentials is going to be performed only if user does not explicitly specify the password. Credentials are going to be stored after a successful connection to the MySQL server is made.

Here is an example:

From now on the user is able to connect to MySQL server without providing the password:

Choosing where to store the passwords

MySQL Shell does not store the credentials on its own. Instead, it uses a helper executable to persist and fetch secrets from an external storage. Users can choose which helper to use via Shell option:

shell.options["credentialStore.helper"]

Helper can also be chosen using:

• MYSQLSH_CREDENTIAL_STORE_HELPER environment variable,
• --credential-store-helper command line option.

In order to check which helpers are available on your platform, use the new Shell method:

There are two additional special values which can be used to set the "credentialStore.helper" option:

• "<disabled>" – disables the automatic storage/retrieval of credentials,
• "default" – selects the default helper on the current platform.

The default helpers are currently:

• "windows-credential" – on Windows platform,
• "keychain" – on macOS platform,
• "login-path" – on all remaining platforms.

The login-path helper uses mysql_config_editor utility and is able to work in compatibility mode with existing entries, for instance, the password stored using:

will be automatically retrieved by Shell:

Controlling the automatic storage

The credentials are stored whenever user provides a valid password at the prompt and a successful connection to the MySQL server is established.

The automatic storage of credentials is controlled using the following Shell options:

shell.options["credentialStore.excludeFilters"]

A list of strings, a credential for an URL matching one of the elements in this list is not going to be automatically stored. An element in this list may contain ‘*’ and ‘?’ wildcard characters.

shell.options["credentialStore.savePasswords"]

A string, allowed values are:

• "always" – passwords are always stored, unless the server URL matches one of the elements in "credentialStore.excludeFilters" list,
• "never" – passwords are not stored,
• "prompt" – in wizards mode, if the server URL does not match one of the elements in "credentialStore.excludeFilters" list, user is prompted if the password should be stored. The possible answers are:
  • yes – save this password,
  • no – don’t save this password,
  • never – don’t save this password and add the server URL to "credentialStore.excludeFilters" list (please note that the modified value is not persisted, meaning it will be in effect only until the Shell is restarted).

  If Shell is running in --no-wizard mode, this option is equivalent to "never".

This option can also be set using:

• MYSQLSH_CREDENTIAL_STORE_SAVE_PASSWORDS environment variable,
• --save-passwords command line option.

Working with credentials

MySQL Shell 8.0.12 provides four new Shell API methods, which allow users to create, list, update and delete credentials in the secret store handled by the current credential helper.

You can store or update a credential using:

If password is not provided, Shell will prompt for one:

In order to list all available credentials run:

Deleting a single credential can be accomplished by:

Finally, you can delete all credentials stored by the current helper:

Custom credential helpers

It is possible to create and use a custom credential helper in order to persist credentials in a secret store of your choice. Custom credential helper must fulfill the following conditions:

• Name of the executable must start with mysql-secret-store-.
• Executable must be placed in the same folder as Shell binary.
• Executable must accept a single command line argument and implement the interface defined by Shell, as summarized below.
• Helper must be able to differentiate secrets stored by MySQL Shell from other secrets available in a secret store.