[opensourcedex]

mycli is a free, open source databases project written in Python and released under BSD-3-Clause. It has 11,976 GitHub stars, 699 forks and 0 open issues, and was last pushed 11 hours ago. On this registry it ranks #69 of 143 tracked projects in Databases, with 5 head-to-head comparisons available.

What is mycli?

mycli is a rich terminal client for MySQL-compatible databases, aimed at developers, data scientists, and operators who want auto-completion, syntax highlighting, and dataframe tooling inside an interactive SQL shell.

What it is

mycli is a Python command-line client for MySQL and its compatible relatives. It lives in the MySQL tooling ecosystem and stands in for the stock mysql shell, keeping the same connect-and-query workflow while layering on interactive editing features: completion as you type, colourised SQL, multiline query support, pretty-printed result tables, and dataframe transforms. Configuration lives in ~/.myclirc, which mycli creates on first run, and the project homepage is http://mycli.net with documentation at http://mycli.net/docs.

The concrete problem it solves is the friction of working against a database from a terminal. The plain mysql client offers no completion beyond the shell's own, no highlighting, and no convenient way to reshape a result set without exporting it. mycli addresses that with context-sensitive completion, so SELECT * FROM followed by tab lists only table names while SELECT * FROM users WHERE followed by tab lists only column names; with fuzzy history search and an output explorer using fzf; and with a Pipelines-style workflow for the result data itself. It is known to be compatible with MySQL, MariaDB, Percona, TiDB, and Apache Doris.

Key capabilities

  • Auto-completion for SQL keywords plus tables, views, columns, enums, and other schema objects, with context-sensitive suggestions keyed to the position in the statement.
  • Syntax highlighting via Pygments, listed as optional but recommended in the macOS and Debian/Ubuntu install paths.
  • Favorite queries with positional or named parameters using Jinja, saved with /fs alias and run with /f alias --key=value.
  • Shell-style trailing redirects using $>, $>>, and $| operators for sending output to files or pipes.
  • Polars dataframe transforms and plots with the .| operator, and Parquet saves with .>.
  • Querying LLMs with schema-derived context through the /llm command.
  • Password storage in the system keyring, plus logging of every query and its results to a file when enabled, off by default.

Who uses it and how

  • Developers exploring an unfamiliar schema interactively, relying on tab completion to discover table and column names without leaving the terminal.
  • Data analysts pulling result sets and reshaping them in place with Polars transforms or writing them out as Parquet rather than exporting to another tool.
  • Operators connecting through SSH, Kubernetes, Vault, or HashiCorp Boundary integrations, which let the client reach databases behind those access layers.
  • Teams standardising on a shared query workflow, since favorite queries with Jinja parameters can be saved once and re-run with different named values.
  • Users running the LLM path who want natural-language queries grounded in their own schema context.

Getting started

Install with pip install --upgrade 'mycli[all]', or use Homebrew with brew update && brew install mycli pygments on macOS, or sudo apt-get install mycli fzf python3-pygments on Debian and Ubuntu. Shell completion is enabled with eval "$(mycli --completions SHELL)" for bash, zsh, or fish.

How it compares

The README names pgcli as the Postgres equivalent, so mycli occupies the MySQL side of the same family of Python terminal clients: same interaction model, different server backend. Both are BSD-3-Clause licensed, self-hosted command-line tools rather than hosted services, so cost is whatever the underlying database already costs.

When to use it — and when not to

A self-hoster runs a local Python package and manages ~/.myclirc, optional dependencies such as fzf and Pygments, and keyring-backed credentials; the /llm feature also means schema context leaves the machine for whichever model provider is configured. Anyone who needs a GUI, a shared browser-based console, or a supported commercial product should look elsewhere. Note that release 2.0.0 carries breaking changes, so the upgrade path from 1.x deserves a check against the changelog before rolling it out broadly.

project readme (upstream, from github) — read inline

mycli

Build Status License

Rich MySQL terminal client with auto-completion, syntax highlighting, and dataframes.

Homepage: https://mycli.net

Documentation: https://mycli.net/docs

Completion
CompletionGif

Mycli is known to be compatible with

Postgres equivalent

Release 2.x

Release 2.0.0 has breaking changes!

Quick Start

If you already know how to install Python packages, then you can install mycli via pip. This package is always up to date.

You might need sudo on Linux.

pip install --upgrade 'mycli[all]'

or, on macOS (pygments is optional but recommended):

brew update && brew install mycli pygments

or, on Debian or Ubuntu (fzf and pygments are optional but recommended):

sudo apt-get install mycli fzf python3-pygments

Usage

See

mycli --help

Features

  • Auto-completion as you type for SQL keywords as well as tables, views, columns, enums, and more!
  • Fuzzy history search using fzf.
  • Output explorer using fzf or other tools.
  • Syntax highlighting using Pygments.
  • Smart-completion suggests context-sensitive completion:
    • SELECT * FROM tab will only show table names.
    • SELECT * FROM users WHERE tab will only show column names.
  • Multiline queries.
  • Favorite queries with positional or named parameters using Jinja. Save a query using
    /fs alias
    and execute it with
    /f alias --key=value
  • Timing of SQL statements and table rendering.
  • Logging of every query and its results to a file (off by default).
  • Pretty printing of tabular data.
  • Shell-style trailing redirects with $>, $>> and $| operators.
  • Polars dataframe transforms and plots with .|, and Parquet saves with .>.
  • Querying LLMs with context derived from your schema using /llm.
  • Storing passwords in the system keyring.
  • Modern defaults such as UTF-8 connection type and SSL.
  • Integrations with: SSH, Kubernetes, Vault, and Boundary.

Mycli creates a config file ~/.myclirc on the first run; you can use the options in that file to configure the above features, and more.

Some features are only exposed as key bindings.

Contributions

If you're interested in contributing to this project, first of all we would like to extend our heartfelt gratitude. We've written a small doc to describe how to get mycli running in a development setup.

https://github.com/dbcli/mycli/blob/main/CONTRIBUTING.md

Additional Install Instructions

Shell Completions

If installed via Homebrew, shell completions may already be configured.

Otherwise, to configure shell completions for the current session, execute a command like this:

eval "$(mycli --completions SHELL)"

replacing SHELL with bash, zsh, or fish, depending on your choice of shell.

To permanently install shell completions, the above command may be added to your ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish. To speed up login time, the output of mycli --completions SHELL may be saved to a file and loaded with source.

Alternative Install Methods

These are some alternative ways to install mycli that are not managed by our team but provided by OS package maintainers. OS packages could be considerably out of date.

If present, the fzf package can be used for fuzzy history search, and as an output "explorer" with the \x special command. pygmentize can be used for syntax highlighting within the fuzzy history search. The less package is also expected, but almost always already installed.

Arch, Manjaro

You can install the mycli package available in the AUR. fzf and python-pygments are optional but recommended:

yay -S mycli fzf python-pygments

Debian, Ubuntu

On Debian and Ubuntu distributions, you can easily install the mycli package using apt. The fzf and python3-pygments packages are optional but recommended:

sudo apt-get install mycli fzf python3-pygments

Fedora

Fedora has a package available for mycli; install it using dnf. The fzf and python-pygments packages are optional but recommended:

sudo dnf install mycli fzf python-pygments

Docker

The images on Dockerhub are out of date. ghcr.io is preferred. Example:

docker run --pull=always -it ghcr.io/dbcli/mycli:latest

Windows

Option 1: Native Windows

Install the less pager, for example by scoop install less.

Install the fzf fuzzy finder, for example by scoop install fzf.

Follow the instructions on this blog post: https://web.archive.org/web/20221006045208/https://www.codewall.co.uk/installing-using-mycli-on-windows/

The libraries used in mycli are Windows-compatible, but there are known limitations according to the test suite. The basics work without any modifications, but this configuration isn't supported software at this time.

PRs to address shortcomings on Windows would be welcome!

Option 2: WSL

Mycli is more compatible with WSL than with native Windows, though still not 100% perfect. This is a good option for using mycli on Windows.

With WSL, you are probably using an Ubuntu distribution, in which case recommended dependencies can be installed by

sudo apt-get install fzf python3-pygments

and mycli can be installed by apt-get or by pip (recommended):

pip install --upgrade 'mycli[all]'

PRs to complete WSL support would be welcome!

Thanks

This project was funded through Kickstarter. Our thanks to the backers who supported the project.

A special thanks to Jonathan Slenders for creating Python Prompt Toolkit, which is quite literally the backbone library, that made this app possible. Jonathan has also provided valuable feedback and support during the development of this app.

Click is used for command line option parsing and printing error messages.

Thanks to PyMysql for a pure Python adapter to MySQL databases.

Compatibility

Mycli is tested on macOS (full), Linux (full), Windows (partial), and WSL (partial), and requires Python 3.10 or better.

To connect to MySQL versions earlier than 5.5, you may need to set the following in ~/.myclirc:

[connection]
# character set for connections without --charset being set at the CLI
default_character_set = utf8

or use --charset=utf8 when invoking mycli.

Configuration and Usage

For more information on using and configuring mycli, check out our documentation.

Common topics include:

Frequently asked questions

Is mycli free to use?

mycli is open source under the BSD-3-Clause licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does mycli do?

Rich MySQL Terminal Client with AutoCompletion, Syntax Highlighting, and Dataframes

What is mycli written in?

mycli is primarily written in Python. Its source is publicly available at https://github.com/dbcli/mycli, and it has 11,976 GitHub stars.