Dolphie: a terminal dashboard for MySQL, MariaDB and ProxySQL

A TUI that replaces watching mysqladmin output scroll by

Dolphie describes itself as a single pane of glass for real-time analytics into MySQL, MariaDB and ProxySQL, and the README is mostly screenshots and short demonstration videos rather than prose, which is a reasonable choice for a terminal dashboard. The interface is built on the Textual library, and the dependency list in the packaging metadata names textual and textual-plotext alongside rich, which is the standard stack for a rich terminal application with plots. The tool connects to a server and refreshes on a cycle, with the refresh interval given in seconds and a default of 1, so what you see is a live picture rather than a snapshot. The audience is a database operator or developer during an incident, someone who already has a terminal open and wants the processlist, the replication state and the lock situation on screen at once instead of running three commands and reading three screens.

Eleven panels, and the query load behind them is yours to control

The --panels option names the panels that can be displayed at startup, and the list is long enough to be worth reading as a feature map: dashboard, processlist, graphs, replication, metadata_locks, ddl, pfs_metrics, statements_summary, proxysql_hostgroup_summary, proxysql_mysql_query_rules and proxysql_command_stats. The default is dashboard and processlist, which is a sensible starting point because the full set is a lot of queries against a live server. The daemon mode exposes a separate --daemon-panels option, and the help text is explicit that this can control significant load if the queries are responsible, naming dashboard and replication as the two panels that cannot be turned off. So the tool admits that a monitoring panel is a query against your production database, and gives you two separate sets of switches depending on whether a human or a daemon is driving it. The ProxySQL specific panels, hostgroup summary, MySQL query rules and command stats, are what make this more than a MySQL front end.

Credentials come from five different places, and precedence matters

Dolphie accepts credentials in more ways than most tools of this kind, and the order in which they are consulted is where mistakes happen. There is a positional URI argument in the format mysql://user:password@host:port, where the port is optional and defaults to 3306, or 6032 for ProxySQL. There are individual flags for user, password, host, port and socket, with the note that the socket has precedence over the port. There is a credential profile option, a MySQL config file option pointing at the [client] section, and a login path option for the encrypted credentials in mysql_config_editor's ~/.mylogin.cnf. Configuration files are read from a documented list of locations when neither the config file option nor the DOLPHIE_CONFIG environment variable is set, namely /etc/dolphie.cnf, /etc/dolphie/dolphie.cnf and ~/.dolphie.cnf. The packaging metadata shows the myloginpath library in the dependency list, which is the piece that reads those encrypted login paths.

pip install dolphie

uv tool install dolphie

brew install dolphie

Running it in Docker, and the tab setup modal for multi host fleets

The Docker path is a pull, a detached run, and one extra command, and that last command is the interesting one. The --tab-setup flag starts Dolphie by showing a Tab Setup modal instead of connecting automatically, which is how you work with a set of hosts rather than a single server. The --hostgroup option is the other half of that story: it reads hosts from a hostgroup section in the Dolphie config file, where a section such as [cluster1] lists one host per line as key=<json>, and the JSON carries a required host, an optional port, and optional tab_title and credential_profile fields. The keys themselves have no meaning, which is a small design choice that makes the file easy to generate from an inventory system. Combining the two is what turns a single connection tool into something you can point at a cluster and tab between.

docker pull ghcr.io/charles-001/dolphie:latest
docker run -dit --name dolphie ghcr.io/charles-001/dolphie:latest
docker exec -it dolphie dolphie --tab-setup

Recording and replay are the answer to the question a live TUI cannot answer

A refresh every second tells you what is happening now, and nothing about what happened at 3am. Dolphie addresses that with a record and replay mechanism, and the implementation choices are unusually well specified. The --record flag writes data to a replay file and the help text warns in capitals that this can use significant disk space and to monitor accordingly. The --daemon flag runs the tool without the TUI, in the background, and it automatically enables recording, because that mode exists solely for recording data to a replay file. Replay files are written into a replay directory, and --replay-retention-hours controls how long they are kept, defaulting to 48 hours with data purged every hour. There is also a --replay-summary option that stores a compact summary next to each row, holding the latest value of every metric, status values, lock states and replication state, so that timelines and graphs can be rebuilt without decoding whole rows, at a cost of roughly a kilobyte per row.

The panels reflect MySQL internals, down to the heartbeat table

The choice of what to display is where this tool shows its specialism. The metadata_locks panel and the ddl panel track the two things that cause the classic production incident where a long running query holds a lock and everything behind it piles up. The pfs_metrics and statements_summary panels come from the performance schema, which means the accuracy of what you see depends on the performance schema being configured to capture what you want, a point the tool cannot fix for you. The replication panel uses Seconds_Behind_Master from SHOW REPLICA STATUS, and the --heartbeat-table option lets you substitute the timestamp from a pt-heartbeat table in db.table format when your hosts run pt-heartbeat, which is the usual way to get a truer replication lag than the built-in counter. The --ssl-mode option covers the connection security with REQUIRED, VERIFY_CA and VERIFY_IDENTITY, defaulting to OFF, with separate flags for the CA file, the client certificate and the client key.

Small conveniences: filters, host cache, version check and notify suppression

A few smaller options show what a tool feels like after daily use. The --filters option starts with filters applied to threads, supporting user, host, db, hostgroup, time as a minimum query time, and query for partial query text, with a value prefixed by an exclamation mark excluding what it matches. Filters from the config, a credential profile and the command line are merged, and the more specific source wins for the filters it sets, which is a sensible conflict rule. The --host-cache-file option resolves IPs to hostnames when DNS cannot, with ip=hostname pairs on each line, and --tab-setup-file stores the list of available hosts for the Tab Setup modal. The --pypi-repo option points at the PyPI JSON endpoint used when checking for a new version, so you can redirect that check at an internal mirror or disable the outbound call. The --exclude-notify-vars option suppresses notifications about frequently changing global variables.

Versioning pace, packaging and the licence

Dolphie moves quickly. The listed releases are 6.16.0 on 2026-09-11, 6.17.1 on 2026-09-14 and 6.18.0 on 2026-09-15, and the last push to the repository was on 2026-09-15, so three point releases landed inside four days. The package requires Python 3.10 or newer and the project description is GPL-3.0-or-later, with the licence text in the LICENSE file, and the copyright held by Charles Thompson. The build backend is hatchling, and the console entry point is dolphie = 'dolphie.App:main'. The Dockerfile is a slim Python 3.12 image that installs the exact version parsed out of pyproject.toml, which means a container build pins to a version rather than tracking the latest release. The test setup is worth noting as well, with pytest, pytest-asyncio, pytest-textual-snapshot for interface snapshots, basedpyright for type checking, and markers for integration runs against Docker MySQL, MariaDB and ProxySQL servers and for multi-node topologies, which are excluded by default in the default pytest run.

Editorial conclusion

Dolphie suits an operator who wants a live view of a MySQL, MariaDB or ProxySQL fleet from a terminal, and who wants to keep the monitoring tool on the same machine as the client rather than in a collector stack. It is the wrong choice if you need long term storage, since the replay files are local and expire, and a poor fit for a fleet too large to watch from one screen, because there is no aggregation layer. Before adopting it, check the credential story for your environment, since the tool reads MySQL option files, login paths and a URI, and read the daemon mode example configuration because recording to a replay file is the only way to get history out of it, and the README warns it can consume significant disk space.

Frequently asked questions

Official sources

1. charles-001/dolphie on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases