Quick Start

dbtrail is an open-source (Apache-2.0) change-tracking and point-in-time recovery system for MySQL. It tails the binary log and keeps every row-level change — with full before/after images — in a searchable index, so you can query your entire history, generate precise undo SQL, and time-travel any row to any moment. Full base snapshots (mydumper) plus continuous binlog streaming give you recovery down to the individual row. It works with MySQL and Percona Server 8.0 and 8.4, including Amazon RDS, Aurora, and Google Cloud SQL.

You can run dbtrail yourself from the open-source repository, or let dbtrail Cloud run it for you — same engine, managed control plane.

Prerequisites

Before connecting a server, make sure your MySQL instance is ready:

Self-hosted dbtrail requires MySQL 8.0 or later; dbtrail Cloud additionally supports MySQL 5.7.

SHOW VARIABLES LIKE 'log_bin';           -- Must be ON
SHOW VARIABLES LIKE 'binlog_format';     -- Must be ROW
SHOW VARIABLES LIKE 'binlog_row_image';  -- Must be FULL

[mysqld]
binlog_row_image = FULL

Create a dedicated MySQL user

Create a user with the minimum privileges dbtrail needs — replication access for binlog streaming and SELECT for schema snapshots:

CREATE USER 'bintrail'@'%' IDENTIFIED BY 'strong_password_here';
GRANT REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'bintrail'@'%';
GRANT SELECT ON *.* TO 'bintrail'@'%';

On Amazon RDS and Aurora, grant the rds_replication role instead of REPLICATION SLAVE:

GRANT rds_replication TO 'bintrail'@'%';

Choose your edition

Open Source

Two commands stand up the full stack — the streaming daemon, a bundled index MySQL, and the web console:

curl -fsSLO https://raw.githubusercontent.com/dbtrail/dbtrail/main/docker-compose.yml
docker compose up -d

Open http://127.0.0.1:8090 — on first run the console asks you to create a username and password. Then click + Add server and paste the MySQL you want to watch (host, port, and the dedicated user you created above). dbtrail runs the preflight checks, provisions an index for the server, and starts streaming — you'll see events within the minute.

The compose stack bundles a MySQL 8.4 container as the index store; that index holds your forensic record, so back up its volumes. For binary installs, bringing your own index MySQL, baselines for time-travel, and production deployment, see the dbtrail repository.

dbtrail Cloud

dbtrail Cloud runs the same engine as a managed service: register your server and dbtrail provisions and operates the infrastructure — fully hosted, or with the agent inside your VPC so your data never leaves your network. Self-serve signup is closed; existing Cloud customers can follow the Cloud Quick Start.

Verify it works

Make a test change to confirm dbtrail is capturing events:

CREATE DATABASE IF NOT EXISTS dbtrail_test;
CREATE TABLE IF NOT EXISTS dbtrail_test.ping (
  id INT PRIMARY KEY,
  ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
INSERT INTO dbtrail_test.ping (id) VALUES (1);

Wait 30 seconds for the change to be indexed, then verify:

Open Sourcedbtrail Cloud

Open the console at http://127.0.0.1:8090 — the INSERT appears in the recent-changes list on the Overview, and the Events screen lets you filter by schema and table.

Running the binaries directly instead of the compose stack? The CLI does the same from the terminal:

bintrail query --index-dsn "$IDX" --schema dbtrail_test --table ping

Go to Dashboard → Query, filter by schema and table, and you should see your INSERT events.

Or hit the REST API with an API key:

curl -s https://api.dbtrail.com/api/v1/query \
  -H "Authorization: Bearer bt_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"server": "production-main", "schema": "dbtrail_test", "limit": 5}'

Clean up the test table when you're done:

DROP DATABASE dbtrail_test;

Connect Claude

Both editions expose your change history to Claude (or any MCP client) through the same three read-only tools: query, recover (always dry-run — the AI never executes SQL), and status.

• Open Source — run the bundled bintrail-mcp server alongside your index, or self-host the MCP gateway for remote clients.
• dbtrail Cloud — connect to the hosted endpoint https://api.dbtrail.com/mcp with a bt_live_ API key; included on all plans, including Free.

See Connect Claude for setup in Claude Code, claude.ai, Claude Desktop, and Cursor.

Once connected, ask Claude anything about your database changes:

"Show me recent changes in dbtrail_test"

Next steps

• Recovery guide — generate point-in-time recovery SQL from change history
• Point-in-time recovery — full base snapshots plus binlog replay
• Configure streams — schema and table filtering, checkpoint intervals, SSL
• ProxySQL time-travel SQL (Beta) — query historical row state from any MySQL client via _flashback / _diff / _snapshot virtual schemas
• Connect Claude — MCP setup for every Claude surface
• Troubleshooting — common issues and fixes
• Cloud Quick Start — the managed-service path