dbtrail

module

v0.17.0-rc1 Latest Latest Go to latest Published: Jun 21, 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.

What you get

dbtrail tails the MySQL binary log and keeps every row change with full before/after images in a searchable index:

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 (requires ProxySQL — see Time-Travel SQL)
Web console — browse, recover, and add servers to monitor, all in the UI
MCP server — Claude or any MCP client can search 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 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.

Install

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

This downloads the Compose stack, brings it up, waits for the console, and prints what to do next. Then:

Open http://127.0.0.1:8090 — on first run, create a username and password (that's your login from now on).
Click + Add server and paste the MySQL you want to watch — host, user, password. dbtrail runs preflight checks, provisions an index, and starts streaming within the minute.

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.

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 · Indexing	Upload to S3
	MariaDB source (alpha)	Server identity
	MCP server	Parquet debugging
	Dump & Baseline · DDL tracking

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, status, and list_schema_changes.	bintrail-mcp is an MCP (Model Context Protocol) server that exposes read-only Bintrail operations as tools: query, recover, status, and list_schema_changes.
bintrail-pg command Command bintrail-pg is the PostgreSQL-source sibling of the core bintrail binary.	Command bintrail-pg is the PostgreSQL-source sibling of the core bintrail binary.
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.
cli Package cli holds command-layer building blocks intended to be shared across bintrail binaries.	Package cli holds command-layer building blocks intended to be shared across bintrail binaries.
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
duckdbutil Package duckdbutil holds small helpers shared by the DuckDB sessions bintrail opens (baseline reads, snapshot queries, S3 footer probes).	Package duckdbutil holds small helpers shared by the DuckDB sessions bintrail opens (baseline reads, snapshot queries, S3 footer probes).
event Package event holds the source-agnostic row-event type that flows from a capture backend into the indexer and the whole downstream value stack (query, recover, reconstruct, shim, console).	Package event holds the source-agnostic row-event type that flows from a capture backend into the indexer and the whole downstream value stack (query, recover, reconstruct, shim, console).
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.
pgcapture Package pgcapture decodes a PostgreSQL logical-replication (pgoutput) stream into the source-neutral event.Event consumed by the indexer and the rest of bintrail's value stack — the PostgreSQL analog of the go-mysql binlog parser in internal/parser.	Package pgcapture decodes a PostgreSQL logical-replication (pgoutput) stream into the source-neutral event.Event consumed by the indexer and the rest of bintrail's value stack — the PostgreSQL analog of the go-mysql binlog parser in internal/parser.
pgstreamrun Package pgstreamrun is the PostgreSQL streaming CONSUMER: it drives the internal/pgcapture capturer (the producer) into the shared indexer, persisting a durable LSN checkpoint to stream_state.	Package pgstreamrun is the PostgreSQL streaming CONSUMER: it drives the internal/pgcapture capturer (the producer) into the shared indexer, persisting a durable LSN checkpoint to stream_state.
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.