dbcli/mycli: A MySQL Terminal Client With Auto-Completion and Dataframes

The gap mycli fills between mysql and a GUI client

The stock mysql client gives you a prompt and a table. It does not know your schema while you type, it does not colour SQL, and it hands results back as text you then copy somewhere else to analyse. mycli targets that gap. It is a terminal client for MySQL and the servers that speak its protocol: the README lists MySQL, MariaDB, Percona, TiDB and Apache Doris as known-compatible, with pgcli named as the Postgres equivalent.

The audience is narrow and specific. If you write ad hoc SQL against a live database all day, the completion and highlighting change how the session feels. If you occasionally run one query a month, the extra install surface buys you little. The project also carries a data-science angle: Polars dataframe transforms and Parquet saves are documented features, which points at people who pull a result set and immediately want to reshape or plot it rather than export it to a notebook first.

How completion, highlighting and the /f favourites actually work

mycli is a Python package. The dependency list in pyproject.toml shows the mechanism: prompt_toolkit for the interactive line editor, Pygments for syntax highlighting, sqlparse and sqlglot for parsing, PyMySQL for the wire protocol, and rapidfuzz for fuzzy matching. Completion is not a static keyword list. The README states that smart-completion is context-sensitive: typing SELECT * FROM and pressing tab shows only table names, while SELECT * FROM users WHERE and tab shows only column names. That behaviour requires the parser to know where the cursor sits in the statement, which is what sqlparse and sqlglot are there for.

Favourite queries are a second layer. They are saved and run through slash commands, and the README documents Jinja templating with positional or named parameters. The example given is saving with /fs alias <query> and executing with /f alias --key=value. Output handling is a third layer: shell-style trailing redirects with $>, $>> and $| operators, Polars transforms with .|, Parquet saves with .>, and an output explorer bound to fzf through the \x special command. Some features exist only as key bindings, and the README points to a separate doc for those, which is worth knowing before you conclude a feature is missing.

Configuration lives in ~/.myclirc, created on first run. That file is where the features above are tuned, and it is the first place to look when behaviour differs from the README.

Installing mycli and running a first query

The README calls pip the always-up-to-date route. The extra installs pull in the optional pieces, so the bracket is part of the command:

pip install --upgrade 'mycli[all]'

On macOS, Homebrew is the documented alternative, with pygments marked optional:

brew update && brew install mycli pygments

On Debian or Ubuntu the distro package exists, with fzf and pygments optional but recommended. The README warns that OS packages can be considerably out of date, so check the version before filing a bug against old behaviour:

apt-get install mycli fzf python3-pygments

If you want to see the client before committing to an install, the README gives a uv one-liner that runs it straight from the index:

uv tool run 'mycli[all]' --help

There is also a container image. The README is explicit that the Dockerhub images are out of date and that the ghcr.io images are preferred, and it says a sample database is included:

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

The same image is documented as working with Apple's container tool. Once installed, the README points at mycli --help for usage, and shell completions for bash, zsh or fish are set up by evaluating the output of mycli --completions SHELL, with SHELL replaced by your shell. For a permanent setup the README suggests adding that command to ~/.bashrc, ~/.zshrc or ~/.config/fish/config.fish, or saving the output to a file and sourcing it to keep login time down.

Where mycli is the wrong tool

Windows is the clearest boundary. The README states that the libraries are Windows-compatible but that there are known limitations according to the test suite, that the basics work without modification, and that this configuration is not supported software at this time. It asks for pull requests to address the shortcomings. That is an honest statement, and it means a Windows team should treat native mycli as experimental. WSL is described as more compatible, though still not 100 percent perfect, and the README again invites pull requests to complete WSL support.

There is a second boundary the README raises itself: release 2.0.0 has breaking changes, linked from the changelog. Anyone upgrading across that line should read the changelog rather than assume the config file carries over unchanged. A third consideration is that mycli is a client, not a server-side tool. Pin a version if upgrade stability matters to you.

mycli against pgcli and against the plain mysql client

The README names pgcli as the Postgres equivalent, and the two share the dbcli organisation, so the real comparison is not mycli versus pgcli but which database you are on. If your fleet is Postgres, pgcli is the sibling project; mycli will not connect to it. That is the whole difference in approach, and it is a protocol boundary rather than a feature gap.

The more useful comparison is against the stock mysql client, which is always present and has no Python dependency. mycli adds a dependency tree that includes prompt_toolkit, PyMySQL, sqlglot, and keyring, and it needs Python 3.11 or newer per pyproject.toml. In exchange you get context-sensitive completion, Pygments highlighting, Jinja-templated favourites, redirect operators, and dataframe transforms. If your workflow is a shell script piping SQL into mysql, mycli offers nothing for that path. If your workflow is a human at a prompt, the trade is worth examining against your own schema size.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-10-31. Releases v2.30.0, v2.30.1 and v2.30.2 landed on 2026-10-17, 2026-10-24 and 2026-10-28, which suggests a fast patch cadence rather than a stable, slow-moving line. Frequent patch releases are good for fixes and bad for anyone who pins versions casually, so read the changelog before each bump.

The licence is BSD-3-Clause, declared both in the README badge and in pyproject.toml as license = "BSD-3-Clause". That is a permissive licence, which generally means you can use and redistribute it with the copyright notice and disclaimer intact. This is not legal advice; if you are embedding mycli in a product, have counsel read the actual LICENSE.txt in the repository.

Upgrade cost is mostly the Python floor and the dependency pins. pyproject.toml requires Python 3.11 or newer and pins ranges across roughly twenty packages, including click ~= 8.5.0 and prompt_toolkit ~= 3.0.53. Those ranges are tight enough that a major bump in any of them is a release event, not a silent update. The alternative install paths carry their own cost: the README says OS packages could be considerably out of date, so a distro upgrade and a mycli upgrade are two different clocks to track.

Editorial conclusion

Adopt mycli if you spend your day in an interactive MySQL, MariaDB, Percona, TiDB or Apache Doris session and want completion, highlighting and dataframe transforms in the same window. Skip it if you need a supported native Windows client, since the README states that configuration is not supported software, or if you only run scripted queries where a plain driver is enough. Verify first that your Python is 3.11 or newer, that fzf and pygments are present if you want fuzzy history and highlighting, and that you are pulling ghcr.io/dbcli/mycli rather than the Dockerhub image the README calls out of date.

Frequently asked questions

Official sources

1. dbcli/mycli on GitHub
2. License: BSD-3-Clause
3. Project website
4. README
5. Releases