DBTrail CLI
DBTrail reads the MySQL binlog, keeps a Parquet copy for DuckDB queries and gives Claude Desktop read-only MCP access
- 68 ★ on the repository
- Last commit
- Apache-2.0
Broad access
Why this level
- Reads the production MySQL binary log and copies every row change, personal data included, into Parquet
- A replication user is created for the connection, and installation runs through a curl and sh script
- Generates SQL that changes data when run, so it must be reviewed before execution
Install
- Works in
Manual install
curl -fsSL https://raw.githubusercontent.com/dbtrail/dbtrail/main/install.sh | shNeeds Docker with Compose and DuckDB for queries. The script starts the stack and prints next steps; the web interface sign-in is at 127.0.0.1:8090.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Reads the production MySQL binary log and copies every row change, personal data included, into Parquet
- A replication user is created for the connection, and installation runs through a curl and sh script
- Generates SQL that changes data when run, so it must be reviewed before execution
This is third-party code. Review the repository files before installing.
What it does
DBTrail connects to MySQL over the replication protocol like an ordinary replica and, from the binary log, lays tables into Parquet files in your folder or S3 bucket. The copy lags by minutes, and the refresh schedule is set from five minutes to a day. Queries go to DuckDB through a generated views.sql, so heavy reports do not load the production database. It works with MySQL 8.0 and 8.4, Percona, Amazon RDS and Aurora, and MariaDB; PostgreSQL gets a one-time copy. The same change stream keeps every version of every row. You can view a table as of a past moment in the web interface or with the reconstruct command and get SQL that undoes only the damaged rows: DBTrail writes the SQL and you review and run it yourself. The bintrail verify command checks without access to the source that a recovery would produce the expected result. The web interface adds servers, sets up snapshots and browses changes. DBTrail connects to Claude Desktop or any MCP client through an MCP server whose tools are all read-only.
Who it is for. MySQL administrators and analysts who need reports without loading the production database and a way to roll back damaged rows, and who want to hand data questions to an assistant.
Good fit when
- Reports on the production database push the working set out of the buffer pool and analytics needs a separate copy
- Someone deleted or damaged rows and you need rollback SQL for just those
- You need to know how a row or table looked a week ago and what changed between two moments
- The database sits in Amazon RDS or Aurora, with no access to binary log files
- You want to ask Claude Desktop questions about the data in plain language, read-only
Not a fit when
- You need high availability or a backup: DBTrail replaces neither, and history starts on the day you install it
- An application must read from the copy: it lags by minutes and accepts no writes
- You need seconds of delay by default: the fresh mode is switched on per server
- The machine has no Docker with Compose and no DuckDB for queries
Example request
Show through MCP how the order row with id 4217 looked yesterday at 18:00 and what has changed sinceLimitations
- A ROW binary log with full row images is required: binlog_format=ROW and binlog_row_image=FULL; bintrail doctor checks them and prints the fix.
- A table schema change, TRUNCATE, DROP or RENAME pauses updates until a full database read, at most once a day, with a short lock.
- Without an S3 bucket row history is kept for 48 hours, and the three newest snapshots of each table stay on disk.
- There is no MySQL server for reports: they run in DuckDB, and the optional MySQL port (beta, no TLS) answers only what a row looked like at a past moment.
How to disable. Stop the Docker Compose stack the install script set up and remove the replication user created for DBTrail in MySQL. The Parquet files in your folder or S3 bucket stay with you.
FAQ
How do I install DBTrail?
Run curl -fsSL https://raw.githubusercontent.com/dbtrail/dbtrail/main/install.sh | sh. Docker with Compose is required, and DuckDB is needed wherever you run queries. The script downloads the Docker Compose stack, starts it and prints the next steps. The web interface opens at http://127.0.0.1:8090.
Does DBTrail load the production database?
Little: after the first read of the tables DBTrail receives only the binary log over the replication protocol, with no plugins, agents or triggers on the database server. A full read repeats when a table schema changes, at most once a day.
Can an assistant change data through MCP?
No, every tool of the MCP server is read-only. DBTrail also only writes the SQL that undoes changes, and you review and run it. Connecting Claude Desktop is described in docs/connect-ai.md in the repository.
Which databases are supported?
MySQL 8.0 and 8.4, Percona Server, Amazon RDS and Aurora for MySQL, and MariaDB 10.11 and newer. Google Cloud SQL is stated to work in principle. PostgreSQL 14 and newer gets a one-time copy, and row history there is in beta.
Does DBTrail replace backups?
No. History starts on the day of installation, so keep physical backups. DBTrail does not provide high availability either: applications do not connect to the copy and there is no failover to it.
Discussion
No questions or reviews yet.
Related
CLI toolsA desktop SQL workspace with a built-in MCP server: the agent reads the schema and runs queries in the same client you already use
DuckDB / MotherDuck MCP Server
DuckDB / MotherDuck Local MCP Server
An MCP server for SQL analytics on DuckDB: local files, in-memory databases, S3-hosted databases and MotherDuck
A token-lean MCP server for PostgreSQL, MySQL, MariaDB, SQL Server and SQLite with a read-only mode
A temporary DuckDB sandbox: an agent loads a CSV and queries the data over MCP or REST without touching the production database
A lightweight database workspace with an MCP server: the agent reads the schema, runs queries and explores data in PostgreSQL, MySQL and more
DuckDB plugin for Claude Code: SQL over CSV, Parquet and databases, S3 file reading, and search across docs and session logs
README in short
The README shows a query on the copy in DuckDB, explains why the copy is needed and describes how it works in four steps: first read, binary log, scheduled update and queries. It gives measurements on a TPC-C dataset, features of the copy and row history, limits, a table of supported databases, installation with a first run and documentation links.