{"id":14248427,"url":"https://github.com/charles-001/dolphie","last_synced_at":"2026-02-28T07:01:39.729Z","repository":{"id":58607765,"uuid":"532695496","full_name":"charles-001/dolphie","owner":"charles-001","description":"Your single pane of glass for real-time analytics into MySQL/MariaDB \u0026 ProxySQL","archived":false,"fork":false,"pushed_at":"2026-02-24T17:25:56.000Z","size":1127,"stargazers_count":1117,"open_issues_count":1,"forks_count":74,"subscribers_count":15,"default_branch":"main","last_synced_at":"2026-02-24T21:49:26.474Z","etag":null,"topics":["monitoring","mysql","python"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/dolphie/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/charles-001.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["charles-001"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2022-09-05T00:43:48.000Z","updated_at":"2026-02-24T17:26:00.000Z","dependencies_parsed_at":"2022-09-22T17:02:46.714Z","dependency_job_id":"12411317-3b9e-4a65-bf4e-013f14c55db7","html_url":"https://github.com/charles-001/dolphie","commit_stats":null,"previous_names":[],"tags_count":82,"template":false,"template_full_name":null,"purl":"pkg:github/charles-001/dolphie","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charles-001%2Fdolphie","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charles-001%2Fdolphie/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charles-001%2Fdolphie/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charles-001%2Fdolphie/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/charles-001","download_url":"https://codeload.github.com/charles-001/dolphie/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charles-001%2Fdolphie/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29927175,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-27T19:37:42.220Z","status":"online","status_checked_at":"2026-02-28T02:00:07.010Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["monitoring","mysql","python"],"created_at":"2024-08-22T00:00:44.914Z","updated_at":"2026-02-28T07:01:39.690Z","avatar_url":"https://github.com/charles-001.png","language":"Python","readme":"# Dolphie\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://user-images.githubusercontent.com/13244625/187600748-19d2ad15-42e8-4f9c-ada5-a153cdcf4070.png\" width=\"120\"\u003e\u003cbr\u003e\n  Your single pane of glass for real-time analytics into MySQL/MariaDB \u0026 ProxySQL\u003cbr\u003e\u003cbr\u003e\n  \u003cimg src=\"https://github.com/charles-001/dolphie/assets/13244625/88a41290-f52c-4b8e-97f8-3b7ef5096eae\" width=\"30\"\u003e\n  \u003cimg src=\"https://github.com/charles-001/dolphie/assets/13244625/1d94502a-9abf-4436-a7d0-cb2b08c105c1\" width=\"30\"\u003e\n  \u003cimg src=\"https://github.com/charles-001/dolphie/assets/13244625/9b1aadc8-cabb-4256-92f9-fe4d04451b83\" width=\"30\"\u003e\n\u003c/p\u003e\n\n![Untitled](https://github.com/user-attachments/assets/b23426ad-060e-4a3a-bb10-66cf0ac95bd0)\n\u003cp\u003e\u003c/p\u003e\n\u003cvideo src='https://github.com/user-attachments/assets/0818485e-f290-4ac4-95d4-8fdc25bb1124'\u003e\u003c/video\u003e\n\u003cp\u003e\u003c/p\u003e\n\u003cvideo src='https://github.com/user-attachments/assets/9eba7a32-1084-43de-9f62-268ad5f0f922'\u003e\u003c/video\u003e\n\n## Installation\n\nRequires Python 3.9+\n\n#### Using PyPi\n\n```shell\n$ pip install dolphie\n```\n\n#### Using Poetry\n\n```shell\n$ curl -sSL https://install.python-poetry.org | python3 -\n\n$ poetry install\n```\n\n#### Using Homebrew\n\nIf you are a [Homebrew](https://brew.sh/) user, you can install [dolphie](https://formulae.brew.sh/formula/dolphie) via\n\n```sh\n$ brew install dolphie\n```\n\n#### Using Docker\n\n```sh\n$ docker pull ghcr.io/charles-001/dolphie:latest\n$ docker run -dit --name dolphie ghcr.io/charles-001/dolphie:latest\n$ docker exec -it dolphie dolphie --tab-setup\n```\n\n## Usage\n\n```\npositional arguments:\n  uri                   Use a URI string for credentials (mysql/proxysql) - format: mysql://user:password@host:port (port is optional with default 3306, or 6032 for ProxySQL)\n\noptions:\n  --help                show this help message and exit\n  --tab-setup           Start Dolphie by showing the Tab Setup modal instead of automatically connecting with the specified options\n  -C , --cred-profile   Credential profile to use. See below for more information\n  -u , --user           Username\n  -p , --password       Password\n  -h , --host           Hostname/IP address\n  -P , --port           Port (socket has precedence)\n  -S , --socket         Socket file\n  -c , --config-file    Dolphie's config file to use. Options are read from these files in the given order: ['/etc/dolphie.cnf', '/etc/dolphie/dolphie.cnf', '~/.dolphie.cnf']\n  -m , --mycnf-file     MySQL config file path to use. This should use [client] section [default: ~/.my.cnf]\n  -l , --login-path     Specify login path to use with mysql_config_editor's file ~/.mylogin.cnf for encrypted login credentials [default: client]\n  -r , --refresh-interval\n                        The time, in seconds, between each data collection and processing cycle [default: 1]\n  --host-cache-file     Resolve IPs to hostnames when your DNS is unable to. Each IP/hostname pair should be on its own line using format ip=hostname [default: ~/dolphie_host_cache]\n  --tab-setup-file      Specify location of file that stores the available hosts to use in Tab Setup modal [default: ~/dolphie_hosts]\n  --heartbeat-table     (MySQL only) If your hosts use pt-heartbeat, specify table in format db.table to use the timestamp it has for replication lag instead of Seconds_Behind_Master from SHOW REPLICA STATUS\n  --ssl-mode            Desired security state of the connection to the host. Supports: REQUIRED/VERIFY_CA/VERIFY_IDENTITY [default: OFF]\n  --ssl-ca              Path to the file that contains a CA (certificate authority)\n  --ssl-cert            Path to the file that contains a certificate\n  --ssl-key             Path to the file that contains a private key for the certificate\n  --panels              What panels to display on startup separated by a comma. Supports: ['dashboard', 'processlist', 'graphs', 'replication', 'metadata_locks', 'ddl', 'pfs_metrics', 'statements_summary', 'proxysql_hostgroup_summary', 'proxysql_mysql_query_rules', 'proxysql_command_stats'], [default: ['dashboard', 'processlist']]\n  --graph-marker        What marker to use for graphs (available options: https://tinyurl.com/dolphie-markers) [default: braille]\n  --pypi-repo           What PyPi repository to use when checking for a new version default: [https://pypi.org/pypi/dolphie/json]\n  -H , --hostgroup      This is used for creating tabs and connecting to them for hosts you specify in Dolphie's config file under a hostgroup section. As an example, you'll have a section called [cluster1] then below it you will list each host on a new line in the format key=host (keys have no meaning). Hosts support optional port (default is whatever port parameter is) in the format host:port. You can also name the tabs by suffixing ~tab_name to the host (i.e. 1=host~tab_name)\n  -R, --record          Enables recording of Dolphie's data to a replay file. Note: This can use significant disk space. Monitor accordingly!\n  -D, --daemon          Starts Dolphie in daemon mode. This will not show the TUI and is designed be put into the background with whatever solution you decide to use. Automatically enables --record. This mode is solely used for recording data to a replay file\n  --daemon-log-file     Full path of the log file for daemon mode\n  --daemon-panels       Which panels to run queries for in daemon mode separated by a comma. This can control significant load if the queries are responsible. Dashboard/Replication panels cannot be turned off. Supports: ['processlist', 'metadata_locks', 'pfs_metrics', 'statements_summary', 'proxysql_hostgroup_summary'], [default: ['processlist', 'metadata_locks', 'pfs_metrics']]\n  --replay-file         Specify the full path of the replay file to load and enable replay mode\n  --replay-dir          Directory to store replay data files\n  --replay-retention-hours\n                        Number of hours to keep replay data. Data will be purged every hour [default: 48]\n  --exclude-notify-vars\n                        Dolphie will let you know when a global variable has been changed. If you have variables that change frequently and you don't want to see them, you can specify which ones with this option separated by a comma (i.e. --exclude-notify-vars=variable1,variable2)\n  --show-trxs-only      (MySQL only) Start with only showing threads that have an active transaction\n  --additional-columns  Start with additional columns in Processlist panel\n  --debug-options       Display options that are set and what they're set by (command-line, dolphie config, etc) then exit. WARNING: This will show passwords and other sensitive information in plain text\n  -V, --version         Display version and exit\n\nOrder of precedence for methods that pass options to Dolphie:\n\t1. Command-line\n\t2. Credential profile (set by --cred-profile)\n\t3. Environment variables\n\t4. Dolphie's config (set by --config-file)\n\t5. ~/.mylogin.cnf (mysql_config_editor)\n\t6. ~/.my.cnf (set by --mycnf-file)\n\nCredential profiles can be defined in Dolphie's config file as a way to store credentials for easy access.\nA profile can be created by adding a section in the config file with the format: [credential_profile_\u003cname\u003e]\nWhen using a credential profile, do not include the prefix 'credential_profile' (i.e. -C production)\nThe following options are supported in credential profiles:\n\tuser\n\tpassword\n\tsocket\n\tssl_mode REQUIRED/VERIFY_CA/VERIFY_IDENTITY\n\tssl_ca\n\tssl_cert\n\tssl_key\n\tmycnf_file\n\tlogin_path\n\nMySQL my.cnf file supports these options under [client] section:\n\thost\n\tuser\n\tpassword\n\tport\n\tsocket\n\tssl_mode REQUIRED/VERIFY_CA/VERIFY_IDENTITY\n\tssl_ca\n\tssl_cert\n\tssl_key\n\nLogin path file supports these options:\n\thost\n\tuser\n\tpassword\n\tport\n\tsocket\n\nEnvironment variables support these options:\n\tDOLPHIE_USER\n\tDOLPHIE_PASSWORD\n\tDOLPHIE_HOST\n\tDOLPHIE_PORT\n\tDOLPHIE_SOCKET\n\tDOLPHIE_SSL_MODE REQUIRED/VERIFY_CA/VERIFY_IDENTITY\n\tDOLPHIE_SSL_CA\n\tDOLPHIE_SSL_CERT\n\tDOLPHIE_SSL_KEY\n\nDolphie's config supports these options under [dolphie] section:\n\t(bool) tab_setup\n\t(str) credential_profile\n\t(str) user\n\t(str) password\n\t(str) host\n\t(int) port\n\t(str) socket\n\t(str) ssl_mode\n\t(str) ssl_ca\n\t(str) ssl_cert\n\t(str) ssl_key\n\t(str) mycnf_file\n\t(str) login_path\n\t(str) host_cache_file\n\t(str) tab_setup_file\n\t(int) refresh_interval\n\t(str) heartbeat_table\n\t(comma-separated str) startup_panels\n\t(str) graph_marker\n\t(str) pypi_repository\n\t(str) hostgroup\n\t(bool) show_trxs_only\n\t(bool) show_additional_query_columns\n\t(bool) record_for_replay\n\t(bool) daemon_mode\n\t(comma-separated str) daemon_mode_panels\n\t(str) daemon_mode_log_file\n\t(str) replay_file\n\t(str) replay_dir\n\t(int) replay_retention_hours\n\t(comma-separated str) exclude_notify_global_vars\n```\n\n## Supported MySQL versions\n\n- MySQL/Percona Server 5.6/5.7/8.x/9.x\n- AWS RDS/Aurora\n- Azure MySQL\n\n## Supported MariaDB versions\n\n- MariaDB 5.5/10.0/11.0+\n- AWS RDS\n- Azure MariaDB\n\n## Supported ProxySQL versions\n\n- ProxySQL 2.6+ (could work on previous versions but not tested)\n\nNote: Use `admin` user instead of `stats` user so you can use all features\n\n## MySQL Grants required\n\n#### Least privilege\n\n1. PROCESS (only if you switch to using processlist via `P` command)\n2. SELECT to `performance_schema` + `pt-heartbeat table` (if used)\n3. REPLICATION CLIENT/REPLICATION SLAVE\n\n#### Recommended\n\n1. PROCESS (only if you switch to using processlist via `P` command)\n2. Global SELECT access (good for explaining queries, listing all databases, etc)\n3. REPLICATION CLIENT/REPLICATION SLAVE\n4. SUPER (required if you want to kill queries)\n\n## Record \u0026 Replay\n\nDolphie is capable of recording your live session data that can be used in a future replay if needed. To begin recording, specify the `--record` option along with `--replay-dir` and you're good to go! The data will be saved in a SQLite database compressed with ZSTD for efficient storage management.\n\nTo view a replay from either a live session or daemon mode, specify the `--replay-file` option or bring up the `Tab Setup` modal. Replays enable you to navigate through the recorded data as if you were observing Dolphie in real-time at the exact time you need to investigate. The replay interface features intuitive controls for stepping backward, moving forward, playing/pausing, and jumping to specific timestamps. While some commands or features may be restricted in replay mode, all core functionalities for effective review and troubleshooting remain accessible.\n\n## Daemon Mode\n\nIf you need Dolphie running incognito while always recording data to capture those critical moments when a database stall causes an incident or a tricky performance issue slips past other monitoring tools, then look no further! Daemon mode is the solution. Purpose-built for nonstop recording, it ensures you never miss the insights that matter most.\n\nTo activate Daemon mode, specify the `--daemon` option, which will automatically enable `--record`. This will transform Dolphie into a resource-efficient, passive, always-on monitoring process that continuously records data. It removes Textual's TUI and creates a log file for messages while also printing them to the console.\n\nTo run Dolphie in the background using daemon mode, I recommend `systemctl` for its flexibility and management capabilities. To see how to set that up, refer to the [service configuration example](https://github.com/charles-001/dolphie/blob/main/examples/dolphie.service). While alternatives like `nohup` or `tmux` can be used, they are not advisable due to their limited management features. Additionally, check out the [config example](https://github.com/charles-001/dolphie/blob/main/examples/dolphie-daemon.cnf) as a helpful starting point for setting up this mode.\n\nIn Daemon mode, metrics are retained for the last 10 minutes to support graphing, with performance schema metric deltas automatically reset at 10-minute intervals. This approach keeps data fresh and relevant, providing an accurate view of recent activity.\n\n**Note**: Daemon mode's replay file can consume significant disk space, particularly on busy servers. To minimize disk usage, adjust the `--replay-retention-hours` and `--refresh-interval` options to control data retention and collection frequency.\n\nExample log messages in daemon mode:\n\n```\n[INFO] Starting Dolphie in daemon mode with a refresh interval of 1s\n[INFO] Log file: /var/log/dolphie/dolphie.log\n[INFO] Connected to MySQL with Process ID 324\n[INFO] Replay SQLite file: /var/lib/dolphie/replays/localhost/daemon.db (24 hours retention)\n[INFO] Connected to SQLite\n[INFO] Replay database metadata - Host: localhost, Port: 3306, Source: MySQL (Percona Server), Dolphie: 6.3.0\n[INFO] ZSTD compression dictionary trained with 10 samples (size: 52.56KB)\n[WARNING] Read-only mode changed: R/W -\u003e RO\n[INFO] Global variable innodb_io_capacity changed: 1000 -\u003e 2000\n```\n\n## System Utilization in the Dashboard Panel\n\nThe System Utilization section in the Dashboard panel will only display when Dolphie is running on the same host as the server you're connected to. It displays the following information:\n- Uptime\n- CPU Usage (Percentage, # of cores)\n- Load Averages (1, 5, and 15 minutes)\n- Memory Usage (Percentage, Used/Total)\n- Swap Usage (Used/Total)\n- Network Traffic (Down, Up)\n\nExample:\n\n\u003cimg width=\"235\" alt=\"Screenshot 2024-11-03 at 1 19 00 AM\" src=\"https://github.com/user-attachments/assets/664269bc-c303-4222-b0d2-fb1e65ce6202\"\u003e\n\n\n## Credential Profiles\n\nCredential profiles can be defined in Dolphie's config file as a way to store credentials for easy access. A profile can be created by adding a section in the config file with the format: `[credential_profile_\u003cname\u003e]`\n\nThe following options are supported in credential profiles:\n\n- host\n- port (default is 3306)\n- user\n- password\n- socket\n- ssl_mode REQUIRED/VERIFY_CA/VERIFY_IDENTITY\n- ssl_ca\n- ssl_cert\n- ssl_key\n- mycnf_file\n- login_path\n\nExample:\n\n```ini\n[credential_profile_dev]\nuser = dev_user\npassword = dev_password\n\n[credential_profile_prod]\nmycnf_file = /secure/path/to/prod.cnf\n```\n\nTo use a credential profile, you can specify it with `-C`/`--cred-profile` option without using the prefix `credential_profile` (i.e. `-C prod`) when starting Dolphie. Hostgroups can also use credential profiles (see below)\n\n## Hostgroups\n\nHostgroups are a way to easily connect to multiple hosts at once. To set this up, you will create a section in Dolphie's config file with the name you want the hostgroup to be and list each host on a new line in the format `key=\u003cjson\u003e` (keys have no meaning). Hosts support optional port (default is whatever `port` parameter is) in the format `host:port`. Once ready, you will use the parameter `hostgroup` or `Host Setup` modal to see it in action!\n\nNote: Colors can be used in the tab name by using the format `[color]text[/color]` (i.e. `[red]production[/red]`). You can also use emojis supported by Rich (can see them by running `python -m rich.emoji`) by using the format `:emoji:` (i.e. `:ghost:`). Rich supports the normal emoji shortcodes.\n\nExample:\n\n```ini\n[cluster1]\n1={\"host\": \"host1\", \"tab_title\": \"[yellow]host1[/yellow] :ghost:\", \"credential_profile\": \"dev\"}\n2={\"host\": \"host2\", \"tab_title\": \"[blue]host2[/blue] :ghost:\", \"credential_profile\": \"dev\"}\n3={\"host\": \"host3:3307\", \"tab_title\": \"[red]production[/red]\", \"credential_profile\": \"prod\"}\n4={\"host\": \"host4\"}\n```\n\n## Feedback\n\nI welcome all questions, bug reports, and requests. If you enjoy Dolphie, please let me know! I'd love to hear from you :dolphin:\n","funding_links":["https://github.com/sponsors/charles-001"],"categories":["服务端测试","Python","python","\u003ca name=\"data-management-tabular\"\u003e\u003c/a\u003eData management - Tabular data","Analysis","Table of Contents"],"sub_categories":["服务端监控"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharles-001%2Fdolphie","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcharles-001%2Fdolphie","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharles-001%2Fdolphie/lists"}