dbtrail

module

v0.12.0 Latest Latest Go to latest Published: Jun 10, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/dbtrail/dbtrail

Links

Open Source Insights

README ¶

Point-in-time recovery for MySQL — no locks, no schema changes, no waiting for a restore.

SELECT * FROM orders WHERE id = 123 AS OF '2026-05-20 14:00:00'

— against production MySQL. That's the experience dbtrail makes possible.

dbtrail tails the binary log, keeps every row change with full before/after images in a searchable index, and turns "someone ran the wrong UPDATE" from a restore-from-backup incident into a two-minute fix:

See every change — what changed and when, for every row, with before → after diffs
Undo precisely — generate exact reversal SQL for just the damaged rows
Time-travel — query any row (or table) as it was at any moment
From a web console — browse, recover, and add servers to monitor, all in the UI

It also ships an MCP server, so Claude (or any MCP client) can search your change history and draft recoveries.

Works with MySQL, Percona Server for MySQL, Amazon RDS for MySQL, Amazon Aurora MySQL, and Google Cloud SQL for MySQL — dbtrail connects over the replication protocol, so it never needs access to the binlog files on disk (that's what makes managed cloud databases work). Requires MySQL 8.0+ with binlog_format=ROW and binlog_row_image=FULL — bintrail doctor checks both and prints the exact fix for anything missing.

Get started

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. That's your login from now on.

Then click + Add server: paste the MySQL you want to watch — host, user, password — and dbtrail runs the preflight checks (failures come back as fix-this cards), provisions an index for it, and starts streaming. Watching events within the minute, and the terminal is already behind you.

The console binds to your machine only (127.0.0.1); your password persists in the stack's volume, so every later visit is a normal sign-in.

Forgot the password? Reset it from the host shell — re-running this overwrites it, no data lost:

docker compose exec -it bintrail bintrail-console user set-password

To reach the console from another machine, set the password from the shell first — until one exists, exposing the port would expose the create-password screen — then publish the port, ideally behind TLS. The console guide has the full auth, TLS, and reverse-proxy options (plus an opt-in API token for automation).

The compose stack ships a pinned MySQL 8.4 container as the index store. That index holds the forensic record — it is your system of record, so back up its volumes (lose them and you re-index from scratch). dbtrail ships that MySQL but does not operate it: disk, backups, and upgrades are yours. Prefer your own? Set INDEX_DSN in .env to a MySQL 8.0+ you run and remove the bundled index services — dbtrail installs only its tables there, never operating the server. Either way, what's supported on each side is spelled out in SUPPORT.md; for an index that's operated for you, there's the managed service at dbtrail.com.

Other ways to install — plain Docker, .deb/.rpm, go install, source builds, and the binary quickstart: see docs/install.md.

Just curious? One container, zero setup, time-travel SQL in 30 seconds: docker run --rm -p 6033:6033 ghcr.io/dbtrail/bintrail-demo — see the demo image.

How it works

The index is self-contained: recovery never needs the original binlog files, and old partitions rotate out to Parquet files — on local disk or in any S3-compatible bucket (S3, MinIO, …); no cloud account needed. Queries read them transparently either way. Time-travel SQL (AS OF) is served by a MySQL-protocol shim behind ProxySQL — your clients keep speaking plain MySQL.

Documentation

Start here	Reference	Operations
Install	Query & Recovery	Deployment · Capacity
Quickstart	Web console	Rotation & Status
DBA guide	Time-Travel SQL	Docker
30-second demo	Streaming · 101 · Indexing	Upload to S3
	MCP server · MCP gateway	Server identity
	Dump & Baseline · DDL tracking	Parquet debugging

License

Apache-2.0 — free for any use, including commercial and production. Contributions welcome: see CONTRIBUTING.md (CLA required, prompted automatically on your first PR).

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
bintrail command
bintrail-console command Command bintrail-console serves the read-only Bintrail web console as a standalone binary, decoupled from the core `bintrail` CLI.	Command bintrail-console serves the read-only Bintrail web console as a standalone binary, decoupled from the core `bintrail` CLI.
bintrail-mcp command bintrail-mcp is an MCP (Model Context Protocol) server that exposes read-only Bintrail operations as tools: query, recover, and status.	bintrail-mcp is an MCP (Model Context Protocol) server that exposes read-only Bintrail operations as tools: query, recover, and status.
mcp-gateway command mcp-gateway is an authentication and routing gateway for bintrail-mcp.	mcp-gateway is an authentication and routing gateway for bintrail-mcp.
e2e
shim Package shim_e2e holds the docker-compose-driven end-to-end test for `bintrail shim`.	Package shim_e2e holds the docker-compose-driven end-to-end test for `bintrail shim`.
internal
agent Package agent implements the outbound communication channel between the bintrail agent (running in customer infrastructure) and the dbtrail service.	Package agent implements the outbound communication channel between the bintrail agent (running in customer infrastructure) and the dbtrail service.
archive Package archive writes a binlog_events partition to a Parquet file before it is dropped.	Package archive writes a binlog_events partition to a Parquet file before it is dropped.
baseline Package baseline converts mydumper output into Parquet files, enabling full audit reconstruction when combined with binlog change events.	Package baseline converts mydumper output into Parquet files, enabling full audit reconstruction when combined with binlog change events.
buffer Package buffer provides an in-memory event buffer for BYOS mode.	Package buffer provides an in-memory event buffer for BYOS mode.
byos Package byos implements the Bring Your Own Storage (BYOS) data separation layer.	Package byos implements the Bring Your Own Storage (BYOS) data separation layer.
cliutil Package cliutil provides shared filter-parsing and output helpers used by both cmd/bintrail/ commands and cmd/bintrail-mcp/.	Package cliutil provides shared filter-parsing and output helpers used by both cmd/bintrail/ commands and cmd/bintrail-mcp/.
config
console Package console serves an embedded, read-only, single-operator web UI over a bintrail index.	Package console serves an embedded, read-only, single-operator web UI over a bintrail index.
doctor
indexer Package indexer consumes parsed binlog events and batch-inserts them into the binlog_events table in the index MySQL database.	Package indexer consumes parsed binlog events and batch-inserts them into the binlog_events table in the index MySQL database.
metadata
observe Package observe provides shared observability setup for Bintrail: structured logging via log/slog and Prometheus metrics for the stream command.	Package observe provides shared observability setup for Bintrail: structured logging via log/slog and Prometheus metrics for the stream command.
parquetquery Package parquetquery implements a DuckDB-backed query engine for Parquet archive files.	Package parquetquery implements a DuckDB-backed query engine for Parquet archive files.
parser Package parser reads MySQL ROW-format binlog files and emits typed events.	Package parser reads MySQL ROW-format binlog files and emits typed events.
query Package query implements the binlog_events query engine — dynamic SQL construction from filter options and multi-format result rendering.	Package query implements the binlog_events query engine — dynamic SQL construction from filter options and multi-format result rendering.
reconstruct Package reconstruct implements row state reconstruction by combining baseline Parquet snapshots with indexed binlog change events.	Package reconstruct implements row state reconstruction by combining baseline Parquet snapshots with indexed binlog change events.
recovery Package recovery generates reversal SQL from indexed binlog events.	Package recovery generates reversal SQL from indexed binlog events.
rotation
serverid Package serverid manages persistent server identities for bintrail.	Package serverid manages persistent server identities for bintrail.
shim Package shim implements an in-process MySQL-protocol server that answers time-travel queries by translating them into bintrail's existing query engine.	Package shim implements an in-process MySQL-protocol server that answers time-travel queries by translating them into bintrail's existing query engine.
status Package status provides shared types and display helpers for the binlog index status.	Package status provides shared types and display helpers for the binlog index status.
storage Package storage defines an abstract storage backend interface for managing Parquet files and other binary objects.	Package storage defines an abstract storage backend interface for managing Parquet files and other binary objects.
streamdeps Package streamdeps wires the production helper functions into a streamrun.Deps — the host side of streamrun's dependency-injection seam.	Package streamdeps wires the production helper functions into a streamrun.Deps — the host side of streamrun's dependency-injection seam.
streamrun
testutil Package testutil provides shared helpers for integration tests that require a live MySQL connection.	Package testutil provides shared helpers for integration tests that require a live MySQL connection.