MySQL Shell 8.0  /  Customizing MySQL Shell  /  Configuring MySQL Shell Options

13.4 Configuring MySQL Shell Options

You can configure MySQL Shell to match your preferences, for example to start up to a certain programming language or to provide output in a particular format. Configuration options can be set for the current session only, or options can be set permanently by persisting changes to the MySQL Shell configuration file. Online help for all options is provided. You can configure options using the MySQL Shell \option command, which is available in all MySQL Shell modes for querying and changing configuration options. Alternatively in JavaScript and Python modes, use the shell.options object.

Valid Configuration Options

The following configuration options can be set using either the \option command or shell.options scripting interface:

optionName DefaultValue Type Effect
autocomplete.nameCache true boolean Enable database name caching for autocompletion.
batchContinueOnError false boolean (READ ONLY) In SQL batch mode, force processing to continue if an error is found.
connectTimeout 10 float greater than 0 The time in seconds to wait before the connection of any session not using AdminAPI times out.
credentialStore.excludeFilters empty array An array of URLs for which automatic password storage is disabled, supports glob characters * and ?.
credentialStore.helper Depends on platform string Name of the credential helper used to fetch or store passwords. A special value default is supported to use the platform's default helper. The special value disabled disables the credential store.
credentialStore.savePasswords prompt string Controls automatic password storage, supported values: always, prompt or never.
dba.connectTimeout 5 float greater than 0 The time in seconds to wait before the connection of any session using AdminAPI times out.
dba.gtidWaitTimeout 60 integer greater than 0 The time in seconds to wait for GTID transactions to be applied, when required by AdminAPI operations (see Section 7.9, “Modifying or Dissolving an InnoDB Cluster”).
dba.logSql 0 integer ranging from 0 to 2 Log SQL statements that are executed by AdminAPI operations (see Chapter 12, MySQL Shell Logging and Debug).
dba.restartWaitTimeout 60 integer greater than 0 The time in seconds to wait for transactions to be applied during a recovery operation. Use to configure a longer timeout when a joining instance has to recover a large amount of data. See Section 7.4.6, “Using MySQL Clone with InnoDB Cluster”).
defaultCompress false boolean Request compression for information sent between the client and the server in every global session. Affects classic MySQL protocol connections only (see Section 4.3.6, “Using Compressed Connections”).
defaultMode None string (sql, js or py) The mode to use when MySQL Shell is started (SQL, JavaScript or Python).
devapi.dbObjectHandles true boolean Enable table and collection name handles for the X DevAPI db object.
history.autoSave false boolean Save (true) or clear (false) entries in the MySQL Shell code history when you exit the application (see Section 5.5, “Code History”).
history.maxSize 1000 integer The maximum number of entries to store in the MySQL Shell code history.
history.sql.ignorePattern *IDENTIFIED* : *PASSWORD* string Strings that match these patterns are not added to the MySQL Shell code history.
history.sql.syslog false boolean Send interactive SQL statements to the operating system’s system logging facility (see Section 12.3, “System Logging for SQL Statements”).
interactive true boolean (READ ONLY) Enable interactive mode.
logLevel Requires a value integer ranging from 1 to 8 Set a logging level for the application log (see Chapter 12, MySQL Shell Logging and Debug).
mysqlPluginDir None string Set a persistent path to the MySQL server's plugin directory. The path is specified when client-side plugins that ship with the server are used for authentication.
pager None string Use the specified external pager tool to display text and results. Command-line arguments for the tool can be added (see Section 4.6, “Using a Pager”).
passwordsFromStdin false boolean Read passwords from stdin instead of terminal.
resultFormat table string (table, tabbed, vertical, json | json/pretty, ndjson | json/raw, json/array) The default output format for printing result sets (see Section 5.7, “Output Formats”).
sandboxDir Depends on platform string The sandbox directory. On Windows, the default is C:\Users\MyUser\MySQL\mysql-sandboxes, and on Unix systems, the default is $HOME/mysql-sandboxes.
showColumnTypeInfo false boolean In SQL mode, display column metadata for result sets.
showWarnings true boolean In SQL mode, automatically display SQL warnings if any.
ssh.bufferSize 10240 integer greater than 0 The buffer size in bytes for data transfer through an SSH tunnel (see Section 4.3.5, “Using an SSH Tunnel”).
ssh.configFile empty string The path to a custom SSH configuration file that replaces the standard SSH configuration file ~/.ssh/config as the default for SSH tunneling (see Section 4.3.5, “Using an SSH Tunnel”).
useWizards true boolean Enable wizard mode.
verbose 1 integer ranging from 0 to 4 Enable verbose output to the console and set a level of detail (see Chapter 12, MySQL Shell Logging and Debug).

String values are case-sensitive.

Options listed as READ ONLY cannot be modified.

The outputFormat option is now deprecated. Use resultFormat instead.

Using the \option Command

The MySQL Shell \option command enables you to query and change configuration options in all modes, enabling configuration from SQL mode in addition to JavaScript and Python modes.

The command is used as follows:

  • \option -h, --help [filter] - print help for options matching filter.

  • \option -l, --list [--show-origin] - list all the options. --show-origin augments the list with information about how the value was last changed, possible values are:

    • Command line

    • Compiled default

    • Configuration file

    • Environment variable

    • User defined

  • \option option_name - print the current value of the option.

  • \option [--persist] option_name value or name=value - set the value of the option and if --persist is specified save it to the configuration file.

  • \option --unset [--persist] <option_name> - reset option's value to default and if --persist is specified, removes the option from the MySQL Shell configuration file.


The value of option_name and filter are case-sensitive.

See Valid Configuration Options for a list of possible values for option_name.

Using the shell.options Configuration Interface

The shell.options object is available in JavaScript and Python mode to change MySQL Shell option values. You can use specific methods to configure the options, or key-value pairs as follows:

MySQL JS > shell.options['history.autoSave']=1

In addition to the key-value pair interface, the following methods are available:

  • shell.options.set(optionName, value) - sets the optionName to value for this session, the change is not saved to the configuration file.

  • shell.options.setPersist(optionName, value) - sets the optionName to value for this session, and saves the change to the configuration file. In Python mode, the method is shell.options.set_persist.

  • shell.options.unset(optionName) - resets the optionName to the default value for this session, the change is not saved to the configuration file.

  • shell.options.unsetPersist(optionName) - resets the optionName to the default value for this session, and saves the change to the configuration file. In Python mode, the method is shell.options.unset_persist.

Option names are treated as strings, and as such should be surrounded by ' characters. See Valid Configuration Options for a list of possible values for optionName.

Use the commands to configure MySQL Shell options as follows:

MySQL JS > shell.options.set('history.maxSize', 5000)
MySQL JS > shell.options.setPersist('useWizards', 'true')
MySQL JS > shell.options.setPersist('history.autoSave', 1)

Return options to their default values as follows:

MySQL JS > shell.options.unset('history.maxSize')
MySQL JS > shell.options.unsetPersist('useWizards')

Configuration File

The MySQL Shell configuration file stores the values of the option to ensure they are persisted across sessions. Values are read at startup and when you use the persist feature, settings are saved to the configuration file.

The location of the configuration file is the user configuration path and the file is named options.json. Assuming that the default user configuration path has not been overridden by defining the environment variable MYSQLSH_USER_CONFIG_HOME, the path to the configuration file is:

  • on Windows %APPDATA%\MySQL\mysqlsh

  • on Unix ~/.mysqlsh where ~ represents the user's home directory.

The configuration file is created the first time you customize a configuration option. This file is internally maintained by MySQL Shell and should not be edited manually. If an unrecognized option or an option with an incorrect value is found in the configuration file on startup, MySQL Shell exits with an error.