Release Notes for MariaDB Shell 23.01.1

Overview

MariaDB Shell is a command-line tool that unifies troubleshooting and administration for MariaDB database products.

MariaDB Shell 23.01.1 was released on 2023-01-26. This release is a Technical Preview and should not be used in production environments.

Notable Changes

  • When MariaDB Shell raises an error to the user, the error message contains a URL that can be visited in a web browser to find error codes and other product details in the MariaDB Documentation. (TENT-265)

  • For each sys sub-command that contains the legacy term slave, MariaDB Shell implements a replacement sub-command that replaces the legacy term slave with the replacement term replica: (TENT-181)

    Old Sub-command

    New Sub-command

    start-all-slaves

    start-all-replicas

    start-slave

    start-replica

    stop-all-slaves

    stop-all-replicas

    stop-slave

    stop-replica

  • For consistency, MariaDB Shell also implements aliases for some other replication-related sys sub-commands that do not contain the legacy term slave:

    Old Sub-command

    New Sub-command

    all-replication-status

    all-replica-status

    replication-status

    replica-status

  • When the grants dump sub-command encounters errors, the error messages are output as SQL comments using the -- prefix, so that the sub-command output is valid SQL that can be executed. (TENT-192)

  • MariaDB Shell adds support for connecting to database servers using a remote SSH tunnel. (TENT-59)

    • When the --ssh-user and --ssh-host command-line options are specified, a remote SSH tunnel is created between the client and the remote host.

    • On the client, the tunnel uses a random ephemeral TCP port. The client initiates the tunnel by connecting to the remote server on the standard SSH port. If the remote server uses a non-standard SSH port, it can be specified using the --ssh-port command-line option.

    • On the remote server, the traffic at the end of the tunnel is forwarded to the IP address 127.0.0.1 on the database port. The database port is specified in the normal way using the --port command-line option. Since the traffic is forwarded to 127.0.0.1, the SSH tunnel must terminate at the database server itself. Jump hosts are not currently supported.

    • MariaDB Shell supports password authentication and public key authentication for SSH tunnels:

      • The --ssh-pass command-line option can be used to enable password authentication. If an argument is provided, the argument is interpreted as the password. If no argument is provided, the user is prompted for the password.

      • The --ssh-key command-line option can be used to enable public key authentication. The argument must be the absolute path to the private key file. If the private key file is encrypted, the --ssh-key-pass command-line option can be used to specify the encryption password.

    • For example, to use a remote SSH tunnel with password authentication:

      $ mariadb-shell \
         --ssh-host HOSTNAME --ssh-port SSH_PORT \
         --ssh-user SSH_USER --ssh-password SSH_PASSWORD \
         --port TCP_PORT \
         --user DATABASE_USER --password DATABASE_PASSWORD
      
    • Or to use a remote SSH tunnel with public key authentication:

      $ mariadb-shell \
         --ssh-host HOSTNAME --ssh-port SSH_PORT \
         --ssh-user SSH_USER --ssh-key /home/MY_USER/.ssh/id_rsa --ssh-key-pass SSH_KEY_PASSWORD \
         --port TCP_PORT \
         --user DATABASE_USER --password DATABASE_PASSWORD
      

Issues Fixed

Can result in a hang or crash

  • When the --database command-line option is specified without an argument, MariaDB Shell can crash after trying to connect, even though the argument should be optional. (TENT-268)

    • In previous releases, MariaDB Shell can crash with the following errors:

      Traceback (most recent call last):
        File "/root/.pyenv/versions/3.10.7/lib/python3.10/site-packages/cx_Freeze/initscripts/__startup__.py", line 131, in run
        File "/root/.pyenv/versions/3.10.7/lib/python3.10/site-packages/cx_Freeze/initscripts/console.py", line 16, in run
        File "/sealion/sealion/__main__.py", line 23, in <module>
        File "/sealion/sealion/app.py", line 288, in main
        File "/sealion/sealion/shell.py", line 70, in __init__
        File "/sealion/sealion/shell.py", line 213, in connect
        File "/sealion/sealion/db.py", line 170, in __init__
        File "/sealion/sealion/db.py", line 176, in connect_mariadb
        File "/root/.pyenv/versions/3.10.7/lib/python3.10/site-packages/mariadb/__init__.py", line 128, in connect
        File "/root/.pyenv/versions/3.10.7/lib/python3.10/site-packages/mariadb/connections.py", line 79, in __init__
      TypeError: connect() argument 5 must be str or None, not bool
      SL00 (9999) - MariaDB Shell has crashed!
      For more information see: https://r.mariadb.com/shell/SL009999
      
    • Starting with this release, the argument for the --database command-line option is optional. When no argument is specified, no database is selected after connecting.

Can result in unexpected behavior

  • When some fish sub-commands are executed, MariaDB Shell can raise errors and restart. (TENT-173, TENT-175)

  • When the --pager command-line option is specified, the pager program is not used. (TENT-271)

  • When the fish dump sub-command is executed, it tries to connect as the user mariadb without a password to the host localhost, even if other connection details are specified. (TENT-229)

  • When the fish collect sub-command is executed, the terminal raises errors related to cursor position requests (CPR). (TENT-174)

    • In previous releases, the following error could be raised:

      WARNING: your terminal doesn't support cursor position requests (CPR).
      
  • When MariaDB Shell is executed with the --generate-defaults command-line option and the configuration initialization operation is canceled, MariaDB Shell raises an error. (TENT-280)

    • In previous releases, the following error could be raised:

      This will overwrite /home/geoff/.msh.cnf with defaults. Continue? [y]|n: n
      Traceback (most recent call last):
        File "/root/.pyenv/versions/3.10.7/lib/python3.10/site-packages/cx_Freeze/initscripts/__startup__.py", line 131, in run
        File "/root/.pyenv/versions/3.10.7/lib/python3.10/site-packages/cx_Freeze/initscripts/console.py", line 16, in run
        File "/sealion/sealion/__main__.py", line 23, in <module>
        File "/sealion/sealion/app.py", line 157, in main
      NameError: name 'exit' is not defined. Did you mean: 'atexit'?
      

Known Issues

  • This release of MariaDB Shell fails during execution if the installed MariaDB Connector/C package is the package bundled with MariaDB Enterprise Server. (CONPY-243)

    • The following error message can occur upon execution:

        File "/root/.pyenv/versions/3.10.7/lib/python3.10/site-packages/mariadb/__init__.py", line 136, in <module>
        File "/root/.pyenv/versions/3.10.7/lib/python3.10/site-packages/mariadb/__init__.py", line 136, in <genexpr>
      ValueError: invalid literal for int() with base 10: '17-12'
      
    • To use this release of MariaDB Shell, ensure that your MariaDB Connector/C package is the package bundled with MariaDB Community Server, which can be installed from the MariaDB Community Repository.

    • On CentOS, RHEL, and Rocky Linux, the MariaDB Connector/C package is called MariaDB-shared.

    • On Debian and Ubuntu, the MariaDB Connector/C package is called libmariadb3.

  • This release of MariaDB Shell fails during execution if the MariaDB Connector/C package is not installed. (CONPY-243)

    • The following error message can occur upon execution:

        File "/root/.pyenv/versions/3.10.7/lib/python3.10/site-packages/mariadb/__init__.py", line 7, in <module>
      ImportError: libmariadb.so.3: cannot open shared object file: No such file or directory
      
    • To use this release of MariaDB Shell, ensure that the MariaDB Connector/C package is installed.

  • When a file is piped to MariaDB Shell, the output still contains headers and prompts, as if an interactive shell were being used. (TENT-132)

    • This issue can impact users who want to use MariaDB Shell for non-interactive use cases.

  • When a stored procedure is called and the database can't be determined, because no default database is currently selected and the procedure name is not fully qualified, MariaDB Shell raises an error with an unclear error message. (TENT-130)

    • In this release, the following error can be raised:

      MariaDB (No Database) » CALL example_sp();
      SLHE (21243) - Unknown prepared statement handler (4294967295) given to mysqld_stmt_execute
      For more information see: https://docs.mariadb.com/mariadb-shell/SLHE21243
      
  • When a connection profile is used that defines a default database, MariaDB Shell does not select the database. (TENT-196)

  • When MariaDB Shell is installed on WSL2 for Ubuntu, it does not install the libffi7 and OpenSSL 1.1.1 dependencies. (TENT-263)

Platforms

MariaDB Shell 23.01.1 is provided for:

  • Apple macOS (x86_64, M1)

  • CentOS 7 (x86_64)

  • Debian 10 (x86_64)

  • Debian 11 (x86_64)

  • Microsoft Windows (x86_64)

  • Red Hat Enterprise Linux 7 (x86_64)

  • Red Hat Enterprise Linux 8 (x86_64)

  • Red Hat Enterprise Linux 9 (x86_64)

  • Rocky Linux 8 (x86_64)

  • Rocky Linux 9 (x86_64)

  • Ubuntu 18.04 (x86_64)

  • Ubuntu 20.04 (x86_64)

  • Ubuntu 22.04 (x86_64)

Installation