MySQL Shell 8.0  /  Customizing MySQL Shell  /  Configuring MySQL Shell

7.4 Configuring MySQL Shell

You can configure MySQL Shell to match your preferences, for example to start up to a certain programming language or to customize output and so on. Configuration options can be set for only the current session, 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 either MySQL Shell 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.

This section describes which options are available and how to configure them.

Valid Configuration Options

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

optionName DefaultValue Type
autocomplete.nameCache true boolean
batchContinueOnError false boolean (READ ONLY)
devapi.dbObjectHandles true boolean
dba.gtidWaitTimeout 60 integer greater than 0
history.autoSave false boolean
history.maxSize 1000 integer
history.sql.ignorePattern *IDENTIFIED* : *PASSWORD* string
interactive true boolean (READ ONLY)
logLevel 5 integer ranging from 1 to 8
outputFormat table string (table, vertical, json, json/raw, tabbed)
passwordsFromStdin false boolean
sandboxDir C:\Users\MyUser\MySQL\mysql-sandboxes or $HOME/mysql-sandboxes string
showWarnings true boolean
useWizards true boolean
defaultMode none string (sql, js or py)
Note

string values are case sensitive.

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.

Note

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 a data dictionary. Use the data dictionary as follows:

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

In addition to the dictionary-like 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 MYSQL_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.