dbtrail

module

v0.42.0 Latest Latest Go to latest Published: Jul 22, 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 and PostgreSQL --- 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/Postgres. That's the experience dbtrail makes possible.

What you get

dbtrail tails the MySQL binary log or the Postgres WAL 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
Undo cascade deletes — reconstruct child rows an ON DELETE CASCADE wiped out (and restore FKs an ON DELETE SET NULL cleared) that InnoDB removes below the binlog and most tools can't see — see Query & Recovery
Time-travel — query any row (or table) as it was at any moment, from the web console or the reconstruct CLI; the live SQL AS OF interface additionally needs ProxySQL — see Time-Travel SQL
Who changed this? — session attribution (database user, host, and client program behind a change) is available in the commercial distribution (dbtrail EE)
Prove the safety net holds — bintrail verify checks (off-line, drift-free) that a recovery would actually reproduce the source, and bintrail status flags any gap in the captured stream — so you find out before you need it — see Verify
Web console — browse, recover, and add servers to monitor, all in the UI
Ask it in plain English — connect Claude Desktop to your console in one click (an .mcpb bundle and a copy-paste URL: 5-minute guide); any MCP client works — see the MCP server reference

Works with MySQL, Percona Server for MySQL, Amazon RDS for MySQL, and Amazon Aurora MySQL (verified); Google Cloud SQL for MySQL is expected to work — please report issues. 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, pick the source type (MySQL, MariaDB, or PostgreSQL), and paste the database you want to watch — host, user, password. dbtrail runs preflight checks, provisions an index, and starts streaming within the minute.

PostgreSQL (beta) & MariaDB (alpha) sources

The same one-line install — the console captures PostgreSQL and MariaDB sources too, not just MySQL. In + Add server, choose the source type; PostgreSQL reveals fields for the database, replication slot, and publication. PostgreSQL needs a one-time source-side setup first (wal_level = logical, REPLICA IDENTITY FULL, and a publication — dbtrail validates these and never runs DDL on your source). Full walkthrough, incl. managed RDS/Aurora/Cloud SQL: PostgreSQL source (beta) · MariaDB source (alpha).

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 · Verify recoveries	Docker
30-second demo	Streaming · Indexing	Upload to S3 · S3 IAM policy · Upgrading
	MariaDB source (alpha) · PostgreSQL source (beta)	Server identity
	Connect an AI assistant · MCP server	Parquet debugging
	Dump & Baseline · DDL tracking

Privacy

bintrail runs entirely in your infrastructure. Your database data never leaves it — not your rows, schemas, table names, queries, hostnames, DSNs, or file paths.

Official release builds do report metadata-only usage statistics: which command ran, whether it succeeded, a coarse error class, and your version and platform. It is on by default and off in one line:

bintrail telemetry off      # or: DO_NOT_TRACK=1, BINTRAIL_TELEMETRY=off
bintrail telemetry show     # see exactly what would be sent — sends nothing

No identifier of any kind is stored or transmitted, so there is nothing tying those statistics to you or your machine. A binary you build yourself has no reporting address compiled in and is incapable of sending anything. TELEMETRY.md documents every field, every control, and the CI tests that enforce both.

The privacy policy covers the Claude Desktop extension (.mcpb) — which reports nothing at all — and how data moves when an AI client queries your deployment.

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).

Want the index server operated for you — sized, backed up, upgraded, kept alive on-call — instead of running it yourself? That is the managed service at dbtrail.com. See SUPPORT.md for the ship-vs-operate boundary.

Directories ¶

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

Path	Synopsis
cliapp
cmd
bintrail command Command bintrail is the OSS binary.	Command bintrail is the OSS binary.
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 Bridge mode (--connect): a stdio ↔ Streamable-HTTP proxy.	Bridge mode (--connect): a stdio ↔ Streamable-HTTP proxy.
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.
consoleapp Package consoleapp is the importable command layer of the bintrail-console binary — the console sibling of the cliapp seam.	Package consoleapp is the importable command layer of the bintrail-console binary — the console sibling of the cliapp seam.
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`.
ext Package ext exposes the extension points that embedding distributions — builds that import cliapp and wrap the OSS core — use to inject behavior: an audit sink recording data-access operations, extra doctor checks, agent WebSocket commands, and daemon source jobs.	Package ext exposes the extension points that embedding distributions — builds that import cliapp and wrap the OSS core — use to inject behavior: an audit sink recording data-access operations, extra doctor checks, agent WebSocket commands, and daemon source jobs.
indexquery Package indexquery exposes read-only programmatic access to the bintrail index — live MySQL partitions and Parquet archives merged — for tooling and embedding distributions that import the core as a module.	Package indexquery exposes read-only programmatic access to the bintrail index — live MySQL partitions and Parquet archives merged — for tooling and embedding distributions that import the core as a module.
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.
baselineintegrity Package baselineintegrity provides at-rest integrity for baseline Parquet files (#636): a CRC-32C _MANIFEST sidecar written next to the _SUCCESS marker, validated on every local read path.	Package baselineintegrity provides at-rest integrity for baseline Parquet files (#636): a CRC-32C _MANIFEST sidecar written next to the _SUCCESS marker, validated on every local read path.
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.
cascade Package cascade reconstructs the side effects of an InnoDB foreign-key ON DELETE CASCADE (deleted child rows) or ON DELETE SET NULL (nulled child FKs) that InnoDB applied but never wrote to the binary log.	Package cascade reconstructs the side effects of an InnoDB foreign-key ON DELETE CASCADE (deleted child rows) or ON DELETE SET NULL (nulled child FKs) that InnoDB applied but never wrote to the binary log.
cascaderecover Package cascaderecover assembles the cascade-recovery SQL script (the documented preamble, the SET FOREIGN_KEY_CHECKS=0/1 wrapper, the CASCADE re-INSERTs, and the idempotent SET NULL restorations) from a synthesized cascade result.	Package cascaderecover assembles the cascade-recovery SQL script (the documented preamble, the SET FOREIGN_KEY_CHECKS=0/1 wrapper, the CASCADE re-INSERTs, and the idempotent SET NULL restorations) from a synthesized cascade result.
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
consistency Package consistency provides primitives that detect, with overwhelming probability, whether a Parquet snapshot diverges from the MySQL table it was taken from.	Package consistency provides primitives that detect, with overwhelming probability, whether a Parquet snapshot diverges from the MySQL table it was taken from.
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
duckdbtuning Package duckdbtuning holds the shared DuckDB resource-tuning flags used by the offline query/recover/reconstruct/verify commands (#510/#511): the --ultrafast / --duckdb-threads / --duckdb-memory-limit flag set, the precedence resolution into a duckdbutil.Tuning, and the archive-fetcher adapter that carries that budget into parquetquery.	Package duckdbtuning holds the shared DuckDB resource-tuning flags used by the offline query/recover/reconstruct/verify commands (#510/#511): the --ultrafast / --duckdb-threads / --duckdb-memory-limit flag set, the precedence resolution into a duckdbutil.Tuning, and the archive-fetcher adapter that carries that budget into parquetquery.
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.
mcptools Package mcptools implements the four read-only Bintrail MCP tools — query, recover, status, and list_schema_changes — decoupled from how the index connection is obtained.	Package mcptools implements the four read-only Bintrail MCP tools — query, recover, status, and list_schema_changes — decoupled from how the index connection is obtained.
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.
pgbaseline Package pgbaseline produces Parquet baseline snapshots directly from a live PostgreSQL source (#593 slice C) — the PG sibling of the mydumper→Parquet converter in internal/baseline, with no dump step: it COPYs each published table inside one REPEATABLE READ snapshot and streams the rows into internal/baseline.Writer.	Package pgbaseline produces Parquet baseline snapshots directly from a live PostgreSQL source (#593 slice C) — the PG sibling of the mydumper→Parquet converter in internal/baseline, with no dump step: it COPYs each published table inside one REPEATABLE READ snapshot and streams the rows into internal/baseline.Writer.
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.
pgshim Package pgshim is the PostgreSQL wire-protocol front-end for bintrail's time-travel engine (#1008).	Package pgshim is the PostgreSQL wire-protocol front-end for bintrail's time-travel engine (#1008).
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
telemetry Package telemetry implements bintrail's usage telemetry: a metadata-only, spool-based reporter for command mix and error classes.	Package telemetry implements bintrail's usage telemetry: a metadata-only, spool-based reporter for command mix and error classes.
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.
verify Package verify reconstructs each table's state from baseline + binlog and compares its content fingerprint against the live source, proving that a recovery would reproduce the source.	Package verify reconstructs each table's state from baseline + binlog and compares its content fingerprint against the live source, proving that a recovery would reproduce the source.