13.3 Customizing the Prompt

The MySQL Shell prompt can be customized using prompt theme files. To customize the prompt theme file, either set the MYSQLSH_PROMPT_THEME environment variable to a prompt theme file name, or copy a prompt theme file to the ~/.mysqlsh/ directory on Linux and macOS, or the %AppData%\Roaming\MySQL\mysqlsh\ directory on Windows. The file must be named prompt.json, and MySQL Shell must be restarted before changes take effect.

Figure 13.1 MySQL Shell prompt

There are six parts that can make up the prompt:

• Status: Whether it is a production system and whether the connection has been lost.

• MySQL: A reminder that you are working with a MySQL database.

• Connection: Which host you are connected to, and on which port that SSL is being used.

• Schema: The current default schema.

• Mode: The mode you are using: JS = JavaScript, PY = Python, and SQL = SQL.

• End: The prompt ends with >.

The user configuration path for the mysqlsh directory where the prompt.json is located can be overridden on all platforms by defining the environment variable MYSQLSH_USER_CONFIG_HOME. The value of this variable replaces %AppData%\Roaming\MySQL\mysqlsh\ on Microsoft Windows or ~/.mysqlsh/ on Unix.

On Microsoft Windows, find the prompt theme files in the following directory: %programfiles%\MySQL\MySQL Shell 8.0\share\mysqlsh\prompt\.

On macOS, find the prompt theme files in the following directory: /usr/local/mysql-shell/share/mysqlsh/prompt.

On Linux, find the prompt theme files in the following directory: /usr/share/mysqlsh/prompt/.

The format of the prompt theme file is described in the README.prompt file. Some sample prompt theme files are also included, for example, prompt_256.json:

In the sample prompt theme prompt_256.json, there is an object with the classes disconnected%host% and %is_production%. The variables are defined in this file or come from MySQL Shell itself, for example, %host and %port. In this example, the host is included in the environment variable PRODUCTION_SERVERS.

  "variables" : {
        "is_production": {
        "match" : {
        "pattern": "*;%host%;*",
        "value": ";%env:PRODUCTION_SERVERS%;"
        },

The background and foreground colors are defined using the bg and fg elements. These elements allow you to customize the colors used in the prompt. Specify the colors in one of the following ways:

• By Name: Use a color defined by name.

• By Index: Use a value between 0 and 255 (inclusive) where 0 is black, 63 light blue, 127 magenta, 193 yellow, and 255 is white.

• By RGB: Use a value in the #rrggbb format. The terminal must support TrueColor.

Named colors are used in this example, with a text PRODUCTION output if the Boolean is_production elements returns TRUE.

    "production" : {
    "text": " PRODUCTION ",
    "bg": "red",
    "fg": "white"
    }

These elements output the prompt in the following format:

Figure 13.2 MySQL Shell prompt

Color display depends on the support available from the terminal. Most terminals support 256 colors in Linux and Mac. In Windows, color support requires either a 3rd party terminal program with support for ANSI/VT100 escapes, or Windows 10. By default, MySQL Shell attempts to detect the terminal type and handle colors appropriately. If auto-detection does not work for your terminal type, or if you want to modify the color mode due to accessibility requirements or for other purposes, you can define the environment variable MYSQLSH_TERM_COLOR_MODE to force MySQL Shell to use a specific color mode. The possible values for this environment variable are rgb, 256, 16, and nocolor.

On startup, if an error is found in the prompt theme file, an error message is printed and a default prompt theme is used. Some of the sample prompt theme files require a special font (for example SourceCodePro+Powerline+Awesome+Regular.ttf). If you set the MYSQLSH_PROMPT_THEME environment variable to an empty value, MySQL Shell uses a minimal prompt with no color.