# github/gh-ost architecture

> Architecture diagram of the GitHub repository github/gh-ost, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/github/gh-ost
- Repository: https://github.com/github/gh-ost

## Overview

##### Project type and purpose
- This is `gh-ost`, a Go-based command-line tool (an open-source utility) whose sole purpose is triggerless online schema migrations for MySQL.
- It reads the MySQL binary log, streams change events, applies them to a “ghost” table, and ultimately swaps tables, all without using triggers.

##### File structure
- Top-level directories
- go/cmd: entrypoint for the CLI (`main.go`)
- go/base: support code for context, logging, configuration
- go/binlog: parsing and reading MySQL binlog files/streams
- go/mysql: connection management and MySQL-specific utilities
- go/logic: the core migration engine (streamer, applier, migrator, throttler, hooks)
- go/sql: SQL statement builder, parser, encodings
- doc: end-user and developer documentation, images
- resources/hooks-sample: sample external hook scripts
- script: build, test, CI, bootstrap scripts
- Config/build/deployment
- go.mod / go.sum: Go modules
- Dockerfile.* and docker-compose.yml: containerized testing and packaging
- .github/workflows: CI, linting, replica-tests

##### README for additional insights
- Emphasis on:
- binlog-based incremental copy
- pause-and-resume (throttling)
- interactive control over a UNIX socket or TCP
- external hooks for custom behavior

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI & Config"
        CLI["CLI Parser & Flag Loader"]:::cli
        Config["Configuration & Context Manager"]:::config
    end

    subgraph "MySQL Connection"
        ConnMgr["MySQL Connection Manager"]:::mysql
    end

    subgraph "Binlog Reader"
        BLReader["Binlog Reader"]:::pipeline
    end

    subgraph "Pipeline (go/logic)"
        Streamer["Event Streamer"]:::pipeline
        Applier["Row Applier"]:::pipeline
        Throttler["Throttler"]:::control
        Migrator["Migrator / Cut-Over Controller"]:::control
        Server["Interactive Control Server"]:::control
        HooksRunner["External Hooks Runner"]:::control
    end

    subgraph "SQL Layer"
        SQLBuilder["SQL Builder & Parser"]:::sql
    end

    subgraph "External Hooks"
        HooksSample["Hook Scripts"]:::hooks
    end

    subgraph "MySQL Server"
        OriginDB["Original Table"]:::db
        GhostDB["Ghost Table"]:::db
    end

    CLI --> Config
    Config --> ConnMgr
    ConnMgr --> BLReader
    ConnMgr --> OriginDB
    BLReader --> Streamer
    Streamer --> Applier
    Applier --> GhostDB
    Streamer --> Throttler
    Applier --> Throttler
    Throttler -.-> Streamer
    Throttler -.-> Applier
    Migrator --> GhostDB
    Migrator --> OriginDB
    Server --> Throttler
    Server --> Migrator
    HooksRunner --> HooksSample
    HooksRunner --> Migrator
    SQLBuilder --> Applier

    click CLI "https://github.com/github/gh-ost/blob/master/go/cmd/gh-ost/main.go"
    click Config "https://github.com/github/gh-ost/tree/master/go/base"
    click ConnMgr "https://github.com/github/gh-ost/tree/master/go/mysql"
    click BLReader "https://github.com/github/gh-ost/tree/master/go/binlog"
    click Streamer "https://github.com/github/gh-ost/blob/master/go/logic/streamer.go"
    click Applier "https://github.com/github/gh-ost/blob/master/go/logic/applier.go"
    click Throttler "https://github.com/github/gh-ost/blob/master/go/logic/throttler.go"
    click Migrator "https://github.com/github/gh-ost/blob/master/go/logic/migrator.go"
    click Server "https://github.com/github/gh-ost/blob/master/go/logic/server.go"
    click HooksRunner "https://github.com/github/gh-ost/blob/master/go/logic/hooks.go"
    click SQLBuilder "https://github.com/github/gh-ost/tree/master/go/sql"
    click HooksSample "https://github.com/github/gh-ost/tree/master/resources/hooks-sample"

    classDef cli fill:#f9f,stroke:#333,stroke-width:1px
    classDef config fill:#fcf,stroke:#333
    classDef mysql fill:#ccf,stroke:#333
    classDef pipeline fill:#bbf,stroke:#333
    classDef control fill:#fbb,stroke:#333
    classDef sql fill:#bfb,stroke:#333
    classDef hooks fill:#ffeb99,stroke:#333
    classDef db fill:#9ff,stroke:#333
```
