dbtrail

module

v0.128.0 Latest Latest Go to latest Published: Nov 8, 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 ¶

HTAP for MySQL and MariaDB. Transactions stay on your server; heavy queries come back in seconds from a columnar copy that follows your binlog, routed automatically on the same connection, with no ETL and nothing installed on your MySQL.

Website · Quick Start · Docs · Blog

mysql -h <dbtrail host> -P 3309 -u shop -p

SELECT c.tier, count(*) AS orders, round(sum(o.total), 2) AS revenue
FROM orders o JOIN customers c ON c.id = o.customer_id
GROUP BY c.tier ORDER BY revenue DESC;

The same SQL your application sends. DBTrail answered it from the copy, and your MySQL never ran it.

What you can do

Run heavy queries in seconds. Totals and rankings over whole tables, trends over years of data, page 5,000 of a listing. In our test, the heaviest of 14 real reports took 225 seconds on a MySQL replica and 7.9 with DBTrail; the 14 ran 6.5 times faster on average. The numbers
Keep one connection for your application. With routing on, DBTrail sends writes, transactions and lookups by key to your MySQL, and answers the heavy reads from the copy. Your application's SQL stays as it is. It also works behind ProxySQL. Connect your application
Point dashboards at it. Metabase, Grafana or any tool that speaks MySQL. Dashboards
Undo a wrong change. DBTrail keeps every change on your MySQL server, before and after, and writes the SQL that undoes the ones you didn't want. You review it and you run it. Undo a wrong change
See a table as it was yesterday at 14:30, or every version of one row, with AS OF from your mysql client. Restore tables to a moment
Ask Claude what changed. Connect Claude, or any MCP client, and ask in plain words: "what was deleted from orders in the last hour?", "how did customer 42 look on Monday?", "give me the SQL that puts it back". Its tools only read, and it never runs SQL on your MySQL. Connect Claude

Where it runs

DBTrail reads your binlog over the replication protocol, the way a replica does. Nothing is installed on your MySQL: no plugin, no agent, no triggers. You don't move to another database or another cloud. DBTrail runs on your own machines, next to MySQL, Percona Server, MariaDB, Amazon RDS or Aurora, and the copy is plain Parquet files on your disk or in your S3 bucket.

Install

You need Docker with Compose, and the mysql client.

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

It starts DBTrail and opens http://127.0.0.1:8090. Connect your MySQL in the form, take the first copy, turn on the MySQL port, and run a heavy query: the five steps are in the Quick Start.

For a server you keep running, the same setup as a compose file and a few API calls you can keep in your automation: In production. Linux packages and Amazon ECS too.

To try the time-travel SQL in 30 seconds, with nothing of yours connected: docker run --rm -p 6033:6033 ghcr.io/dbtrail/bintrail-demo (the demo image).

Limits

The copy is behind your MySQL. By seconds in fresh mode, by minutes otherwise. A query that must see a write made a second ago belongs on your MySQL, and routing keeps transactions there.
Lookups stay on your MySQL. A read by key takes a few milliseconds on MySQL and about 100 on the copy, so routing leaves it on your MySQL.
Not high availability, and not your backup. Writes always go to your MySQL and nothing fails over to DBTrail. History starts the day you install it. Keep your replicas and your backups.
Needs a ROW binlog with full row images (binlog_format=ROW, binlog_row_image=FULL), and a primary key on every InnoDB table. The connect form checks the binlog settings and shows the fix.
Some schema changes re-read a table. Adding or dropping a column, or a TRUNCATE, makes DBTrail read that table again, with a short lock.
Row history needs a bucket to last. Without S3 it keeps 48 hours. The copy itself stays.
The MySQL port has no TLS yet. Use it on a private network.
Yours to operate. DBTrail and its small index MySQL run on your machines. Disk, backups and upgrades are yours.

All of them: Limitations.

What it works with

Source	Analytical copy	Row history and undo
MySQL 8.0, 8.4	Yes	Yes
Percona Server for MySQL 8.0, 8.4	Yes	Yes
Amazon RDS for MySQL	Yes (verified)	Yes (verified)
Amazon Aurora MySQL	Yes (verified)	Yes (verified)
Google Cloud SQL for MySQL	Should work, please report issues	Should work
MariaDB 10.11+, including Amazon RDS for MariaDB	Yes	Yes. See MariaDB source
PostgreSQL 14+	One-time copy only, no scheduled update yet	Beta. See PostgreSQL source

DBTrail never needs the binlog files on disk, which is why managed cloud databases work.

Who builds it

DBTrail is built by Daniel Guzman-Burgos, former MySQL Technical Lead at Percona.

Documentation

The guides live at dbtrail.com/docs. This repository keeps the reference for the command line and for operators:

Use it	Operate it	Reference
Command-line quickstart	Install · Deployment	Time-Travel SQL
DBA guide	Capacity · Upgrading	Query & Recovery
Analytics with DuckDB	Docker · Upload to S3	MCP server
Iceberg export	Rotation & Status	MariaDB source · PostgreSQL source

Privacy

bintrail is DBTrail's command-line tool. It 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 turns off in one line:

bintrail telemetry off      # or: DO_NOT_TRACK=1, BINTRAIL_TELEMETRY=off
bintrail telemetry show     # prints what would be sent; sends nothing

No identifier of any kind is stored or transmitted, so nothing ties those statistics to you or your machine. A binary you build yourself has no reporting address compiled in and cannot send 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 are welcome; see CONTRIBUTING.md. Each commit carries a Signed-off-by line (DCO); git commit -s adds it.

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. SUPPORT.md draws the ship-vs-operate line.

Directories ¶

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

Path	Synopsis
assurance Package assurance exposes read-only access to the backup-assurance signals — restore coverage, the capture-continuity verdict, baseline staleness, and the scheduled-verify run history — for tooling and embedding distributions that import the core as a module.	Package assurance exposes read-only access to the backup-assurance signals — restore coverage, the capture-continuity verdict, baseline staleness, and the scheduled-verify run history — for tooling and embedding distributions that import the core as a module.
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.
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.
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.
mcpext Package mcpext is the extension seam for MCP tools: an embedding distribution registers a provider here and its tools appear on every MCP server the core builds — the standalone bintrail-mcp binary and the web console's /mcp endpoint alike.	Package mcpext is the extension seam for MCP tools: an embedding distribution registers a provider here and its tools appear on every MCP server the core builds — the standalone bintrail-mcp binary and the web console's /mcp endpoint alike.
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
accessprofiles Package accessprofiles is the ONE implementation of authoring access profiles: the flags on tables and columns (table_flags), the named profiles (profiles) and the allow/deny rules that join them (access_rules).	Package accessprofiles is the ONE implementation of authoring access profiles: the flags on tables and columns (table_flags), the named profiles (profiles) and the allow/deny rules that join them (access_rules).
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.
audittest Package audittest holds the canonical list of audit emissions the core must produce, plus the recording sink the contract tests drive it with.	Package audittest holds the canonical list of audit emissions the core must produce, plus the recording sink the contract tests drive it with.
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: a CRC-32C _MANIFEST sidecar written next to the _SUCCESS marker, validated on every baseline read path — local (#636) and S3 (#698).	Package baselineintegrity provides at-rest integrity for baseline Parquet files: a CRC-32C _MANIFEST sidecar written next to the _SUCCESS marker, validated on every baseline read path — local (#636) and S3 (#698).
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 cascade that InnoDB applied but never wrote to the binary log — ON DELETE CASCADE (deleted child rows), ON DELETE SET NULL (nulled child FKs), and their ON UPDATE siblings (child FKs rewritten to the parent's new key, or nulled, when the parent's referenced key is UPDATEd; #1002).	Package cascade reconstructs the side effects of an InnoDB foreign-key cascade that InnoDB applied but never wrote to the binary log — ON DELETE CASCADE (deleted child rows), ON DELETE SET NULL (nulled child FKs), and their ON UPDATE siblings (child FKs rewritten to the parent's new key, or nulled, when the parent's referenced key is UPDATEd; #1002).
cascadebaseline Package cascadebaseline implements cascade.BaselineProvider over internal/reconstruct — the Phase-2 fallback that lets cascade recovery recover a child row that has no binlog event in the lookback window by reading it out of a `bintrail baseline` Parquet snapshot.	Package cascadebaseline implements cascade.BaselineProvider over internal/reconstruct — the Phase-2 fallback that lets cascade recovery recover a child row that has no binlog event in the lookback window by reading it out of a `bintrail baseline` Parquet snapshot.
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.
copymirror Package copymirror keeps a LOCAL mirror of the snapshots a server publishes to S3, so SQL on the copy can read them (#2302).	Package copymirror keeps a LOCAL mirror of the snapshots a server publishes to S3, so SQL on the copy can read them (#2302).
ddltext Package ddltext reads the text of a table DDL statement: its verb, the tables it names and, for an ALTER TABLE that only adds columns, the columns.	Package ddltext reads the text of a table DDL statement: its verb, the tables it names and, for an ALTER TABLE that only adds columns, the columns.
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).
hiderules Package hiderules holds the per-server rules that hide tables and columns on the analytical surfaces (#2529): SQL on the copy, the MySQL-protocol port and the MCP sql tool.	Package hiderules holds the per-server rules that hide tables and columns on the analytical surfaces (#2529): SQL on the copy, the MySQL-protocol port and the MCP sql tool.
icebergexport Package icebergexport writes the current state of indexed tables to Apache Iceberg tables, incrementally (#1466).	Package icebergexport writes the current state of indexed tables to Apache Iceberg tables, incrementally (#1466).
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.
installid Package installid derives the replication server-id capture uses: the source's own triple (internal/serverid) and what tells this installation apart from another one capturing the same source.	Package installid derives the replication server-id capture uses: the source's own triple (internal/serverid) and what tells this installation apart from another one capturing the same source.
keyidx Package keyidx writes the key index that sits beside a snapshot table's Parquet file (#2496): every row's integer key with the row's number in the file, sorted by key, in a flat fixed-width file a refresh can search without reading it whole.	Package keyidx writes the key index that sits beside a snapshot table's Parquet file (#2496): every row's integer key with the row's number in the file, sorted by key, in a flat fixed-width file a refresh can search without reading it whole.
mcptools Package mcptools implements the read-only Bintrail MCP tools — query, recover, status, list_schema_changes, and the opt-in reconstruct (#953) and recover_cascade (#1128) — decoupled from how the index connection is obtained.	Package mcptools implements the read-only Bintrail MCP tools — query, recover, status, list_schema_changes, and the opt-in reconstruct (#953) and recover_cascade (#1128) — decoupled from how the index connection is obtained.