{"id":47735819,"url":"https://github.com/dbtrail/bintrail","last_synced_at":"2026-05-03T17:06:22.536Z","repository":{"id":346237413,"uuid":"1161864008","full_name":"dbtrail/bintrail","owner":"dbtrail","description":"Bintrail","archived":false,"fork":false,"pushed_at":"2026-05-02T00:17:17.000Z","size":1175,"stargazers_count":2,"open_issues_count":8,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-02T02:27:51.346Z","etag":null,"topics":["binlog","cli","database","dba-tools","disaster-recovery","golang","mcp","mysql","point-in-time-recovery","recovery"],"latest_commit_sha":null,"homepage":"https://www.dbtrail.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dbtrail.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":"CLA.md"}},"created_at":"2026-02-19T15:54:14.000Z","updated_at":"2026-04-21T21:40:31.000Z","dependencies_parsed_at":null,"dependency_job_id":"834f21b6-e7fd-4c34-9bad-23200623d0f4","html_url":"https://github.com/dbtrail/bintrail","commit_stats":null,"previous_names":["dbtrail/bintrail"],"tags_count":45,"template":false,"template_full_name":null,"purl":"pkg:github/dbtrail/bintrail","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbtrail%2Fbintrail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbtrail%2Fbintrail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbtrail%2Fbintrail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbtrail%2Fbintrail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dbtrail","download_url":"https://codeload.github.com/dbtrail/bintrail/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbtrail%2Fbintrail/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32577142,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["binlog","cli","database","dba-tools","disaster-recovery","golang","mcp","mysql","point-in-time-recovery","recovery"],"created_at":"2026-04-02T22:35:41.026Z","updated_at":"2026-05-03T17:06:22.529Z","avatar_url":"https://github.com/dbtrail.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bintrail\n\nA 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.\n\n## Requirements\n\n- Go 1.24+\n- MySQL 8.0+ (index database)\n- Source MySQL server with `binlog_format = ROW` and `binlog_row_image = FULL`\n\n## Install\n\n```sh\ngo install github.com/dbtrail/bintrail/cmd/bintrail@latest\n```\n\nOr build from source:\n\n```sh\ngit clone https://github.com/dbtrail/bintrail\ncd bintrail\ngo build ./cmd/bintrail\n```\n\n## Quick start\n\n```sh\n# 1. Create index tables (run once)\nbintrail init --index-dsn \"user:pass@tcp(127.0.0.1:3306)/binlog_index\"\n\n# 2. Snapshot schema metadata from the source server\nbintrail snapshot \\\n  --source-dsn \"user:pass@tcp(source:3306)/\" \\\n  --index-dsn  \"user:pass@tcp(127.0.0.1:3306)/binlog_index\"\n\n# 3. Index binlog files (requires access to /var/lib/mysql on the source host)\nbintrail index \\\n  --index-dsn  \"user:pass@tcp(127.0.0.1:3306)/binlog_index\" \\\n  --source-dsn \"user:pass@tcp(source:3306)/\" \\\n  --binlog-dir /var/lib/mysql \\\n  --all\n\n# 4. Query the index\nbintrail query \\\n  --index-dsn \"user:pass@tcp(127.0.0.1:3306)/binlog_index\" \\\n  --schema mydb --table orders --pk 12345\n\n# 5. Generate recovery SQL\nbintrail recover \\\n  --index-dsn \"user:pass@tcp(127.0.0.1:3306)/binlog_index\" \\\n  --schema mydb --table orders --event-type DELETE \\\n  --since \"2026-02-19 14:00:00\" --until \"2026-02-19 14:05:00\" \\\n  --output recovery.sql\n```\n\n\u003e **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](docs/streaming.md).\n\n\u003e **New to bintrail?** See the [Practical Guide for DBAs](docs/guide.md) for scenario-based walkthroughs and troubleshooting.\n\n## Commands\n\n| Command | Description |\n|---|---|\n| `init` | Create index tables in the target MySQL database |\n| `snapshot` | Capture table and column metadata from the source server |\n| `index` | Parse binlog files from disk and write row events to the index |\n| `stream` | Connect as a replica and index row events in real-time |\n| `query` | Search the index with flexible filters (schema, table, PK, time range, GTID) |\n| `recover` | Generate reversal SQL for matching events |\n| `reconstruct` | Rebuild row state at a point in time from baselines + binlog events |\n| `rotate` | Drop old partitions, add new ones, optionally archive to Parquet |\n| `status` | Show indexed files, partition sizes, and event counts |\n| `dump` | Invoke mydumper to create a logical dump of the source server |\n| `baseline` | Convert mydumper output to Parquet snapshots |\n| `upload` | Upload local Parquet files to S3 |\n| `config init` | Generate a `.bintrail.env` configuration file |\n| `init-shim` | Generate a `shim.yaml` for the BYOS time-travel SQL shim |\n| `proxysql-config` | Generate ProxySQL setup SQL for BYOS time-travel SQL routing |\n| `shim` | Run the in-process MySQL-protocol server for `_flashback`/`_diff`/`_snapshot` queries |\n| `profile` | Manage RBAC access profiles for query and recover |\n| `flag` | Label tables and columns (e.g. `pii`, `sensitive`) for access rules |\n| `access` | Link flags to profiles with allow/deny permissions |\n| `generate-key` | Generate an AES-256 encryption key for dump encryption |\n\nAll commands accept `--log-level` (default `info`) and `--log-format` (default `text`). See each command's `--help` for flags and usage.\n\n## MCP Server\n\nBintrail ships an [MCP](https://modelcontextprotocol.io) server that exposes query, recover, and status as read-only tools — letting Claude (or any MCP client) explore your binlog index conversationally.\n\n### Claude Connector\n\nThe easiest way to connect — works from claude.ai, Claude Desktop, and Claude mobile:\n\n1. Deploy the [MCP Gateway](docs/mcp-gateway.md) (handles OAuth + tenant routing)\n2. In Claude, go to **Settings \u003e Integrations \u003e Add custom integration**\n3. Enter your gateway URL (e.g. `https://mcp.dbtrail.com/mcp`)\n4. Authorize with your tenant ID — done\n\n### Claude Code (local)\n\nThe project ships `.mcp.json` which pre-registers the server using `go run`:\n\n```json\n{\n  \"mcpServers\": {\n    \"bintrail\": {\n      \"command\": \"go\",\n      \"args\": [\"run\", \"./cmd/bintrail-mcp\"],\n      \"env\": { \"BINTRAIL_INDEX_DSN\": \"user:pass@tcp(127.0.0.1:3306)/binlog_index\" }\n    }\n  }\n}\n```\n\nSet `BINTRAIL_INDEX_DSN` to your index database DSN, then enable with `claude mcp enable bintrail`.\n\nSee [MCP Server docs](docs/mcp-server.md) for HTTP mode, proxy setup, and tool details.\n\n## How it works\n\n```\nSource MySQL            Index MySQL\n(information_schema) ──snapshot──► schema_snapshots\n                                        │\nBinlog files on disk ──index──►   binlog_events (partitioned)\n                                  index_state\n                                        │\nReplication stream   ──stream──►  binlog_events (partitioned)\n                                  stream_state (checkpoint)\n                                        │\n                          query / recover ──► stdout / .sql file\n```\n\nThe index stores complete before and after row images for every event, so recovery never requires the original binlog files.\n\n**`bintrail index`** reads binlog files directly from disk — best for self-managed MySQL where the binlog directory is accessible.\n\n**`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.\n\n## Documentation\n\n| Guide | Description |\n|---|---|\n| [Quickstart](docs/quickstart.md) | Zero to recovery in 10 minutes |\n| [Practical Guide for DBAs](docs/guide.md) | Scenario-based walkthroughs and troubleshooting |\n| [Indexing](docs/indexing.md) | File-based indexing in depth |\n| [Streaming](docs/streaming.md) | Real-time replication indexing |\n| [Streaming 101](docs/streaming-101.md) | Getting started with stream |\n| [Query and Recovery](docs/query-and-recovery.md) | Filters, output formats, and recovery workflows |\n| [Rotation and Status](docs/rotation-and-status.md) | Partition management and monitoring |\n| [Dump and Baseline](docs/dump-and-baseline.md) | mydumper workflow and Parquet baselines |\n| [DDL Tracking](docs/ddl-tracking.md) | Schema change detection and handling |\n| [Server Identity](docs/server-identity.md) | Multi-server identity management |\n| [Upload](docs/upload.md) | Parquet archive uploads to S3 |\n| [MCP Server](docs/mcp-server.md) | MCP server setup, HTTP mode, and proxy |\n| [MCP Gateway](docs/mcp-gateway.md) | OAuth gateway for Claude Connector |\n| [Deployment](docs/deployment.md) | cron, systemd, Ansible, and production setup |\n| [Docker](docs/docker.md) | Container images and Docker Compose |\n| [Parquet Debugging](docs/parquet-debugging.md) | Inspecting and troubleshooting Parquet archives |\n| [BYOS Time-Travel SQL](docs/byos-time-travel-sql.md) | End-to-end setup for `_flashback` / `_diff` / `_snapshot` virtual schemas via ProxySQL + `bintrail shim` |\n\n## Agent exit codes\n\n`bintrail agent` uses distinct process exit codes so a supervisor (e.g. systemd) can distinguish permanent failures from transient ones:\n\n| Code | Meaning | Supervisor action |\n|---|---|---|\n| 0 | Clean shutdown (SIGTERM/SIGINT) | — |\n| 64 | Fatal auth/config error (missing, invalid, or revoked API key; wrong tenant mode) | Fix credentials, restart manually |\n| 65 | Rate-limited by the server | Contact support before restarting |\n| 1 | Transient/unknown error | Safe to respawn (default systemd behavior) |\n\nFor systemd, add `RestartPreventExitStatus=64 65` to the service unit so the agent is not respawned on permanent failures.\n\n## License\n\nThis project is licensed under the [Business Source License 1.1](LICENSE). 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.\n\nFor alternative licensing arrangements, contact daniel@dbtrail.com.\n\n## Contributing\n\nContributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. All contributors must agree to the [Contributor License Agreement](CLA.md) — first-time contributors will be prompted automatically via CLA Assistant.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdbtrail%2Fbintrail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdbtrail%2Fbintrail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdbtrail%2Fbintrail/lists"}