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.
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.
Set to true by adding
--force on the command line. See
Appendix A, MySQL Shell Command Reference. |
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. |
|
true |
boolean |
Defines if connectivity checks are performed for
If an SSL error occurs, the command stops and an error is returned. |
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”). |
logFile |
Path to the MySQL Shell log file. | string | Displays the path to the MySQL Shell log file. (Read-only) This value
can only be changed from the command line, using the
--log-file=path/to/logfile.log option.
See Appendix A, MySQL Shell Command Reference. |
dba.logSql |
0 | integer ranging from 0 to 2 | (Deprecated in MySQL Shell 8.0.30. Use logSql
instead.) 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.7, “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 |
*SELECT*:SHOW* | 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 User SQL Statements”). |
logLevel |
info | integer ranging from 1 to 8 or any of none, internal, error, warning, info, debug, debug2, debug3, respectively | Set a logging level for the application log (see Chapter 12, MySQL Shell Logging and Debug). |
logSql |
error | string (off, error, on, all) | Log SQL statements that are executed by MySQL Shell operations (see
Section 12.4, “MySQL Shell SQL Logging”). This log option
does not log user SQL statements executed interactively
from the SQL mode, only SQL statements executed by
MySQL Shell operations. Logs all SQL statements except
those defined in the
logSql.ignorePatternUnsafe and
logSql.ignorePattern options.
|
logSql.ignorePattern |
*SELECT*:*SHOW* |
string | Specify colon-separated list of glob pattern to filter out of SQL
statements logged by logSql (see
Section 12.4, “MySQL Shell SQL Logging”). |
logSql.ignorePatternUnsafe |
*IDENTIFIED*:*PASSWORD* |
string | Specify defines a colon-separated list of statement patterns to filter
out of SQL statements logged by logSql
(see Section 12.4, “MySQL Shell SQL Logging”). |
mysqlPluginDir |
MySQL Shell's MySQL plugin directory. That is, the
lib/mysql/plugins directory of your
MySQL Shell installation on Linux platforms, and
lib\mysql\plugins on Windows
platforms. |
string | Set a persistent path to a plugin directory. |
oci.configFile |
The default location for your platform. | string | Set a persistent path to an OCI CLI config file. |
oci.profile |
DEFAULT | string | Specify which profile to use in the OCI CLI config file. |
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”). |
|
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.6, “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.6, “Using an SSH Tunnel”). |
useWizards |
true | boolean | Enable wizard mode. |
verbose |
0 | 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.
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 [
- print help for options matchingfilter
]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
- print the current value of the option.option_name
\option [--persist]
- set the value of the option and ifoption_name
value
orname=value
--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
.
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[optionName]
: lists the current value of the option.shell.options.set(
: sets theoptionName
,value
)optionName
tovalue
for this session, the change is not saved to the configuration file.shell.options.setPersist(
: sets theoptionName
,value
)optionName
tovalue
for this session, and saves the change to the configuration file. In Python mode, the method isshell.options.set_persist
.shell.options.unset(
: resets theoptionName
)optionName
to the default value for this session, the change is not saved to the configuration file.shell.options.unsetPersist(
: resets theoptionName
)optionName
to the default value for this session, and saves the change to the configuration file. In Python mode, the method isshell.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')
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.