Bintrail

A CLI tool that parses MySQL ROW-format binary logs, indexes every row event into MySQL with full before/after images, and generates reversal SQL for point-in-time recovery — without needing the original binlog files.

Requirements

• Go 1.24+
• MySQL 8.0+ (index database)
• Source MySQL server with binlog_format = ROW and binlog_row_image = FULL

Install

go install github.com/dbtrail/bintrail/cmd/bintrail@latest

Or build from source:

git clone https://github.com/dbtrail/bintrail
cd bintrail
go build ./cmd/bintrail

Quick start

# 1. Create index tables (run once)
bintrail init --index-dsn "user:pass@tcp(127.0.0.1:3306)/binlog_index"

# 2. Snapshot schema metadata from the source server
bintrail snapshot \
  --source-dsn "user:pass@tcp(source:3306)/" \
  --index-dsn  "user:pass@tcp(127.0.0.1:3306)/binlog_index"

# 3. Index binlog files (requires access to /var/lib/mysql on the source host)
bintrail index \
  --index-dsn  "user:pass@tcp(127.0.0.1:3306)/binlog_index" \
  --source-dsn "user:pass@tcp(source:3306)/" \
  --binlog-dir /var/lib/mysql \
  --all

# 4. Query the index
bintrail query \
  --index-dsn "user:pass@tcp(127.0.0.1:3306)/binlog_index" \
  --schema mydb --table orders --pk 12345

# 5. Generate recovery SQL
bintrail recover \
  --index-dsn "user:pass@tcp(127.0.0.1:3306)/binlog_index" \
  --schema mydb --table orders --event-type DELETE \
  --since "2026-02-19 14:00:00" --until "2026-02-19 14:05:00" \
  --output recovery.sql

Managed MySQL (RDS, Aurora, Cloud SQL)? Use bintrail stream instead of bintrail index — it connects over the replication protocol and requires no access to binlog files on disk. See Streaming.

New to bintrail? See the Practical Guide for DBAs for scenario-based walkthroughs and troubleshooting.

Commands

All commands accept --log-level (default info) and --log-format (default text). See each command's --help for flags and usage.

MCP Server

Bintrail ships an MCP server that exposes query, recover, and status as read-only tools — letting Claude (or any MCP client) explore your binlog index conversationally.

Claude Connector

The easiest way to connect — works from claude.ai, Claude Desktop, and Claude mobile:

1. Deploy the MCP Gateway (handles OAuth + tenant routing)
2. In Claude, go to Settings > Integrations > Add custom integration
3. Enter your gateway URL (e.g. https://mcp.dbtrail.com/mcp)
4. Authorize with your tenant ID — done

Claude Code (local)

The project ships .mcp.json which pre-registers the server using go run:

{
  "mcpServers": {
    "bintrail": {
      "command": "go",
      "args": ["run", "./cmd/bintrail-mcp"],
      "env": { "BINTRAIL_INDEX_DSN": "user:pass@tcp(127.0.0.1:3306)/binlog_index" }
    }
  }
}

Set BINTRAIL_INDEX_DSN to your index database DSN, then enable with claude mcp enable bintrail.

See MCP Server docs for HTTP mode, proxy setup, and tool details.

How it works

Source MySQL            Index MySQL
(information_schema) ──snapshot──► schema_snapshots
                                        │
Binlog files on disk ──index──►   binlog_events (partitioned)
                                  index_state
                                        │
Replication stream   ──stream──►  binlog_events (partitioned)
                                  stream_state (checkpoint)
                                        │
                          query / recover ──► stdout / .sql file

The index stores complete before and after row images for every event, so recovery never requires the original binlog files.

bintrail index reads binlog files directly from disk — best for self-managed MySQL where the binlog directory is accessible.

bintrail stream connects as a replica over the replication protocol — best for managed MySQL (RDS, Aurora, Cloud SQL) where binlog files are not directly accessible.

Documentation

Agent exit codes

bintrail agent uses distinct process exit codes so a supervisor (e.g. systemd) can distinguish permanent failures from transient ones:

For systemd, add RestartPreventExitStatus=64 65 to the service unit so the agent is not respawned on permanent failures.

License

This project is licensed under the Business Source License 1.1. You may use bintrail for any purpose, including production use, except offering it as part of a competing commercial hosted service or managed consulting service. Each version converts to Apache License 2.0 four years after its release.

For alternative licensing arrangements, contact daniel@dbtrail.com.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before opening a pull request. All contributors must agree to the Contributor License Agreement — first-time contributors will be prompted automatically via CLA Assistant.