If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/github/gh-ost shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1w ago
• 33+ active contributors
• Distributed ownership (top contributor 27% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live github/gh-ost repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/github/gh-ost.

What it runs against: a local clone of github/gh-ost — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in github/gh-ost | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 38 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of github/gh-ost. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/github/gh-ost.git
#   cd gh-ost
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of github/gh-ost and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "github/gh-ost(\\.git)?\\b" \\
  && ok "origin remote is github/gh-ost" \\
  || miss "origin remote is not github/gh-ost (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "go/cmd/gh-ost/main.go" \\
  && ok "go/cmd/gh-ost/main.go" \\
  || miss "missing critical file: go/cmd/gh-ost/main.go"
test -f "go/logic/migrator.go" \\
  && ok "go/logic/migrator.go" \\
  || miss "missing critical file: go/logic/migrator.go"
test -f "go/logic/streamer.go" \\
  && ok "go/logic/streamer.go" \\
  || miss "missing critical file: go/logic/streamer.go"
test -f "go/logic/applier.go" \\
  && ok "go/logic/applier.go" \\
  || miss "missing critical file: go/logic/applier.go"
test -f "go/mysql/connection.go" \\
  && ok "go/mysql/connection.go" \\
  || miss "missing critical file: go/mysql/connection.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 38 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~8d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/github/gh-ost"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

gh-ost is GitHub's triggerless online schema migration tool for MySQL that performs live table alterations without blocking reads or writes. It uses binary log streaming to capture and replay changes to a ghost table instead of relying on database triggers, enabling true pause capability and decoupled write load on the master during migrations. Monolithic Go binary. Core logic lives in /go directory (base utilities, context, load maps in /go/base). CLI and orchestration logic would be in main packages. Documentation-heavy with /doc containing operational guides, command-line reference, troubleshooting, and design rationale. Docker builds for testing and packaging via Dockerfile.test and Dockerfile.packaging.

MySQL database operators and DevOps engineers managing schema changes on production systems who need zero-downtime migrations with pausability, audit trails, and the ability to test migrations on replicas before applying to the master.

Production-ready and actively maintained by GitHub. The project has comprehensive test coverage (replica-tests, golangci-lint, CodeQL workflows), extensive documentation in /doc, and appears to be regularly developed (though exact commit dates not visible in data). This is battle-tested at GitHub's scale.

Relatively low risk due to GitHub backing and Go's strong ecosystem. Main risks: dependency on go-mysql binary log parsing (github.com/go-mysql-org/go-mysql v1.11.0) and MySQL-specific complexity that could have edge cases. Single maintainer concern typical of infrastructure tools, but GitHub's sponsorship mitigates abandonment risk. Requires careful testing on replicas before master application (intentional design, not a flaw).

Unable to determine from file list alone (no recent commits, PRs, or CHANGELOG visible), but CI/CD pipelines are active: .github/workflows/ includes ci.yml, replica-tests.yml, golangci-lint.yml, and codeql.yml, suggesting continuous integration and security scanning are enforced on new changes.

git clone https://github.com/github/gh-ost.git
cd gh-ost
go build ./...
# Or use the provided build script:
./build.sh

Daily commands: The tool runs as a command-line utility (no dev server). Execute the binary with appropriate MySQL connection flags. See /doc/command-line-flags.md for all options. For testing: docker-compose.yml is present for local test environment setup. Local tests documented in /doc/local-tests.md.

• go/cmd/gh-ost/main.go — Entry point for the gh-ost application; all command-line execution begins here and initializes the migration orchestrator.
• go/logic/migrator.go — Core orchestrator that drives the entire schema migration lifecycle; coordinates inspectors, streamers, appliers, and throttlers.
• go/logic/streamer.go — Binlog event consumer and processor; handles real-time replication of DML changes to the ghost table during migration.
• go/logic/applier.go — Executes SQL statements against the database; manages ghost table creation, row copying, and final cutover.
• go/mysql/connection.go — Low-level MySQL protocol handler; abstracts all database connectivity and query execution for the tool.
• go/binlog/binlog_reader.go — Parses and reads MySQL binary log events; provides the event stream that streamer.go consumes.
• go/logic/inspect.go — Analyzes the source table schema, constraints, and replication topology; validates migration feasibility.

Add a new MySQL operation to the migration workflow

1. Define the operation as a method on the Applier or Inspector struct (go/logic/applier.go)
2. Call the new operation from the appropriate phase in Migrator.Migrate() (go/logic/migrator.go)
3. Add error handling and logging for the operation (go/logic/migrator.go)

Add a new HTTP API endpoint for control or monitoring

1. Add a handler function in the Server struct (go/logic/server.go)
2. Register the route in the server's HTTP router initialization (go/logic/server.go)
3. Implement JSON marshaling for the response using existing context or state structs (go/base/context.go)

Add support for a new SQL constraint type

1. Extend the parser's constraint-parsing logic (go/sql/parser.go)
2. Add the constraint type definition to the types module (go/sql/types.go)
3. Update the SQL builder to generate CREATE/ALTER statements for the new constraint (go/sql/builder.go)

Add a new throttling heuristic or metric

1. Add a metric field to the LoadMap or context structure (go/base/load_map.go)
2. Populate the metric in Migrator or Streamer during migration (go/logic/migrator.go)
3. Implement the throttling decision logic in Throttler.ShouldThrottle() (go/logic/throttler.go)

• Go 1.25+ — Compiled, statically-linked binary enables portability across MySQL environments without runtime dependencies; concurrency primitives (goroutines, channels) suit binlog streaming and parallel chunk copying.
• go-mysql (go-mysql-org/go-mysql) — Handles MySQL binlog protocol parsing, GTID management, and replication stream decoding; eliminates need to re-implement MySQL wire protocol.
• HTTP JSON API (go/logic/server.go) — Enables interactive control, pausability, and external monitoring without stopping the migrator; decouples CLI from core engine.
• Triggerless design (no stored procedures) — Avoids overhead and complexity of trigger-based solutions; achieves real-time replication via binlog reading instead.

• Binlog-based replication instead of trigger-based row capture

  • Why: Triggers add CPU overhead to the source table's DML; binlog reading is asynchronous and decoupled from application workload.
  • Consequence: Requires binary log to be enabled and row-based format (RBR); slightly more complex binlog parsing logic.

• Chunk-based row copying with pausability

  • Why: Allows migration to adapt to real-time load; can pause during peak hours without losing progress.
  • Consequence: Requires checkpointing state; adds complexity to resume logic; lock contention during chunk creation.

• Ghost table approach (copy table schema, swap at cutover)

  • Why: Minimizes lock time during cutover (atomic rename); allows long-running copy phase without blocking reads.
  • Consequence: Requires temporary disk space for ghost table; no in-place mutation; cannot be used if table space is extremely limited.

• No custom trigger logic on the source table

  • Why: Simplifies operations and avoids trigger compilation errors or missing stored procedures.
  • Consequence: Must stream binlog in parallel; requires continuous connection to binary log position.

• Does not migrate data across different MySQL versions or major schema incompatibilities
• Does not provide built-in rollback to the original table (manual cleanup or hooks required)
• Not designed for non-MySQL databases (PostgreSQL, SQLite, etc.)
• Does not handle cross-database or cross-server table merges
• Not a real-time replication tool; designed for one-time schema changes, not continuous sync
• Does not support instant DDL (MySQL 8.0.12+) as a primary mechanism, though may attempt it

MySQL binlog format: Must be set to ROW binlog format (not STATEMENT) for gh-ost to work correctly; this is documented but easy to miss. Replica lag: The tool monitors and throttles on replica lag (doc/subsecond-lag.md), so having a healthy replica is not optional. Binary log position tracking: The tool reads from the binlog at the position of the ghost table creation; if binlog is rotated or purged, migration fails. Dry-run on replicas: Testing on a replica does not actually swap tables (by design), but requires a second table comparison step. Go version constraint: go 1.25.9 in go.mod; older Go versions may not build. No ALTER TABLE support: Some MySQL versions have restrictions on which ALTER TABLE statements gh-ost can apply; check /doc/requirements-and-limitations.md.

• Binary Log (Binlog) Streaming — gh-ost's entire design centers on reading the MySQL binary log to capture row changes asynchronously instead of using triggers; understanding binlog format (ROW vs STATEMENT) is essential to troubleshooting change propagation.
• Ghost Table Pattern — gh-ost creates a shadow copy of the table being altered and swaps it at the end; understanding the multi-stage lifecycle (create ghost → copy data → replay changes → cut-over) is key to following the tool's flow.
• Replication Lag Detection and Throttling — The tool monitors replica lag and pauses writes to the ghost table if replicas fall behind; this is a critical safety feature documented in /doc/throttle.md and /doc/subsecond-lag.md.
• Online Schema Change (OSC) — gh-ost solves the classical OSC problem of altering table schemas without downtime; knowing the history of triggers-based solutions (pt-osc, Facebook's OSC) helps appreciate gh-ost's innovations.
• Row-based Binlog Format — gh-ost requires MySQL binlog format to be set to ROW (not STATEMENT or MIXED); this determines what information is available in the binlog for change replay.
• Cut-over and Atomic Table Swap — The final step of gh-ost involves swapping the original table with the ghost table using a brief RENAME/lock; understanding the cut-over phase (/doc/cut-over.md) is critical for minimizing downtime during that window.
• Triggerless Change Propagation — Unlike traditional OSC tools, gh-ost does not use database triggers to replicate changes; instead it reads the binlog asynchronously. This is the core architectural innovation enabling true pause and decoupled workload.

• percona/pt-online-schema-change — Direct predecessor and competitor: Percona's trigger-based online schema change tool that gh-ost was designed to improve upon
• github/vitess — GitHub's MySQL sharding middleware that includes online schema migration as a core feature; complementary approach to gh-ost for horizontally scaled MySQL
• openark/orchestrator — GitHub-affiliated MySQL replication orchestrator that integrates with gh-ost for replica health monitoring and master failover safety during migrations
• go-mysql-org/go-mysql — The underlying Go library gh-ost depends on for MySQL binlog streaming and replication; critical for understanding change propagation
• mysql/mysql-server — The upstream MySQL database; gh-ost is tightly coupled to MySQL's binlog format and replication semantics

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for go/logic/applier.go

The applier.go file is critical for applying schema changes to the ghost table, but there's only an applier_test.go stub. Given gh-ost's role in production MySQL migrations, thorough unit tests for applier logic (statement execution, error handling, retry logic) are essential. This directly reduces production risk.

• [ ] Review go/logic/applier.go to identify untested code paths (statement building, error cases, transaction handling)
• [ ] Expand go/logic/applier_test.go with table-driven tests for various ALTER statements
• [ ] Add mock MySQL connection tests to verify applier behavior on connection failures and deadlocks
• [ ] Ensure test coverage reaches >80% for applier.go using 'go test -cover'

Add integration tests for binlog reader edge cases (go/binlog/gomysql_reader.go)

The binlog module is foundational for gh-ost's ability to capture and apply changes. Currently, testdata exists (rbr-sample-*.txt) but there are no visible test files for gomysql_reader.go. Adding tests for malformed binlog entries, position tracking, and replication lag detection would improve reliability.

• [ ] Create go/binlog/gomysql_reader_test.go with tests for parsing the existing testdata files
• [ ] Add tests for edge cases: corrupted binlog markers, missing GTID info, large transactions
• [ ] Verify that binlog position tracking is accurate across transaction boundaries
• [ ] Run tests against the existing testdata binlog files (mysql-bin.000066, mysql-bin.000070)

Document and add tests for go/logic/hooks.go callback behavior

The hooks.go file enables lifecycle callbacks (e.g., on-before-cut-over, on-complete), which are documented in doc/hooks.md. However, hooks_test.go appears minimal. Production users need confidence that hooks execute correctly at each stage. Adding test coverage with examples will improve adoption.

• [ ] Review doc/hooks.md and go/logic/hooks.go to map all hook trigger points
• [ ] Expand go/logic/hooks_test.go with tests for hook execution order, timeout handling, and failure scenarios
• [ ] Add tests verifying that hook failures at critical stages (e.g., on-before-cut-over) properly halt migration
• [ ] Document hook callback examples in doc/hooks.md with code snippets from the test cases

• Add test coverage for go/base/load_map.go — the file exists but no corresponding load_map_test.go is visible in the file list; write unit tests for the load map data structure used in row copying.
• Expand doc/command-line-flags.md with runnable examples — add 3-5 concrete CLI invocation examples for common scenarios (e.g., 'add a column with a default value', 'rename a column'), each with expected output and estimated runtime.
• Document the interactive command protocol — doc/interactive-commands.md exists but there is no visible reference to the actual implementation; map commands to code locations in /go main packages and add examples of piping commands to gh-ost for CI/CD automation.

• High · Outdated Go Version — go.mod. The project specifies 'go 1.25.9' in go.mod, which appears to be a future or invalid Go version. The latest stable Go version as of early 2024 is 1.21.x. This suggests either a configuration error or use of an unstable/unreleased version that may lack security patches. Fix: Update to a stable, currently maintained Go version (1.21 or later, within the current LTS track). Verify the Go version against official Go releases at golang.org.
• High · Potential SQL Injection in Schema Migration Logic — go/logic/applier.go, go/logic/inspect.go, go/logic/streamer.go, go/binlog/binlog_dml_event.go. The codebase contains multiple SQL-related files (applier.go, inspect.go, streamer.go) that handle schema migrations and DML events. Without reviewing the actual code, schema migration tools are high-risk for SQL injection if user inputs or table/column names are not properly parameterized. The presence of raw SQL handling in applier.go and binlog processing suggests potential injection vectors. Fix: Conduct thorough code review of SQL query construction. Ensure all dynamic SQL uses prepared statements with parameterized queries. Implement input validation and sanitization for table names, column names, and values. Use the database/sql package's parameter binding features consistently.
• High · Insecure Dependency: github.com/go-mysql-org/go-mysql v1.11.0 — go.mod - github.com/go-mysql-org/go-mysql v1.11.0. The go-mysql library (v1.11.0) is a community-maintained MySQL driver. While functional, it may have known security vulnerabilities or lag behind security updates compared to the official go-sql-driver/mysql. Check CVE databases for disclosed vulnerabilities in this specific version. Fix: Verify if v1.11.0 has any known CVEs. Consider migrating primary MySQL operations to the official go-sql-driver/mysql (already included) or database/sql with mysql driver. If go-mysql is necessary, upgrade to the latest version and monitor for security advisories.
• Medium · Outdated Indirect Dependencies — go.mod - indirect dependencies (docker/docker, containerd, moby packages). Several indirect dependencies have outdated versions: github.com/docker/docker v28.0.1+incompatible (released ~2024, but marked incompatible), github.com/containerd/log v0.1.0, and others. Incompatible versions and older releases may contain known CVEs. The '+incompatible' suffix indicates version compatibility issues. Fix: Run 'go mod tidy' and 'go get -u ./...' to update dependencies. Address any reported security vulnerabilities using 'go list -u -m all'. Remove the +incompatible suffix by upgrading to a compatible version of docker/docker. Pin versions in go.mod to stable, patched releases.
• Medium · Unencrypted MySQL Credentials in Configuration — go/logic/my.cnf.test, potential runtime config files. The project references 'my.cnf.test' (go/logic/my.cnf.test), which is a MySQL configuration file. If similar patterns exist in production configurations or if credentials are stored in plaintext config files, this poses a credential exposure risk. No environment-based secret management is evident. Fix: Never store MySQL credentials in plaintext configuration files. Use environment variables, secure vaults (HashiCorp Vault, AWS Secrets Manager), or Go's database/sql.DB with secure connection strings. Ensure all .cnf files are in .gitignore and never committed. Implement credential rotation policies.
• Medium · Missing Security Headers and Input Validation in HTTP Server — go/logic/server.go, go/logic/hooks.go. The presence of go/logic/server.go indicates an HTTP server component. Without reviewing the code, web-facing components require explicit security headers (CORS, CSP, X-Frame-Options, etc.) and robust input validation. Interactive commands via HTTP (doc/interactive-commands.md) suggest potential attack vectors. Fix: Implement security headers middleware for all HTTP responses. Validate and sanitize all inputs from interactive commands. Use rate limiting and authentication for HTTP endpoints. Implement HTTPS enforcement and certificate validation. Review CORS policies to restrict to trusted origins only

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.