DBTrail Documentation

Install DBTrail, connect your MySQL and run your first query on the copy in DuckDB.

At the end you will have your MySQL tables as Parquet files, open in DuckDB on your machine.

Before you begin

Docker with Compose on the machine that will run DBTrail.
A MySQL login that can create users. You use it once, to create the user DBTrail connects with.
DuckDB on your machine, for the last step.
Your MySQL keeps full row changes in its binary log. Check it with SHOW VARIABLES WHERE Variable_name IN ('log_bin', 'binlog_format', 'binlog_row_image'); You want ON, ROW and FULL. Only log_bin needs a MySQL restart to change. binlog_format and binlog_row_image change on a running server with SET PERSIST, and apply to connections opened after that.
Every table has a primary key and uses InnoDB. One table without a primary key stops the first connect for the whole server.

MySQL and Percona Server 8.0 and 8.4, including RDS and Aurora. On RDS or Aurora, read this first.

Install

curl -fsSL https://raw.githubusercontent.com/dbtrail/dbtrail/main/install.sh | sh

It starts DBTrail and opens http://127.0.0.1:8090 in your browser. Your history lives in the Docker volumes of this stack: from the dbtrail folder, docker compose down stops DBTrail and keeps it, docker compose down -v deletes it. Other ports and options: installation guide. Without Docker: Install from Linux packages. The installer also gives the index MySQL a quarter of the machine's memory (INDEX_BUFFER_POOL in .env); on a busy source that is the setting that keeps capture up to date: Give the index MySQL memory.

Pick a username and password, then press Create & sign in.

Connect

The form to add your server opens by itself. Fill in the Host and Port of your MySQL; if it runs on this same machine, use host host.docker.internal. Copy the SQL the form shows, run it on your MySQL with your login, then press Check and connect.

Take the first copy

Click Snapshots in the sidebar, press Read database now and confirm. DBTrail reads every table once, and takes a lock on your tables to read them at one moment, so pick a quiet time. When it finishes, the copy is listed under Versions.

Query it in DuckDB

On Snapshots, press Download, then Download the data. Unpack the file and open DuckDB inside the folder it creates:

tar xzf dbtrail-backup-*.tar.gz
cd <the folder it created>
duckdb -init views.sql

Each table is a view with the table's own name, in a schema named like its database: demo.orders. A real run on demo data:

D SELECT c.tier, count(*) AS orders, round(sum(o.total), 2) AS revenue
  FROM demo.orders o
  JOIN demo.customers c ON c.id = o.customer_id
  GROUP BY c.tier ORDER BY revenue DESC;
┌──────────┬────────┬───────────────┐
│   tier   │ orders │    revenue    │
│ varchar  │ int64  │ decimal(38,2) │
├──────────┼────────┼───────────────┤
│ platinum │ 539848 │   59426197.40 │
│ gold     │ 539752 │   59353658.54 │
│ silver   │ 539056 │   59295443.48 │
│ bronze   │ 538385 │   59242795.95 │
└──────────┴────────┴───────────────┘

Keep the copy current

What you downloaded is the copy at one moment. To have DBTrail update it by itself: Snapshots, tab Settings, card Update the copy, pick how often, then Turn on. It opens on once a day. To read the copy that keeps updating: Query with DuckDB.

If a check fails

Check and connect lists each problem with its fix. Fix it and press Check and connect again. The common ones, with the SQL: Troubleshooting.

Next steps

Row history and undo: see a row before and after a change, and get the SQL that puts it back
Snapshots settings: keep the copy in S3 too
Dashboards: put Metabase in front of the copy
Connect Claude: ask about your changes in plain English
Command-line quickstart, for scripts and automation

Quick Start