# github/skeema architecture

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

- Interactive diagram: https://gitdiagram.com/github/skeema
- Repository: https://github.com/github/skeema

## Overview

##### Project type and purpose
- This is an open-source command-line tool (“Skeema”) for declaratively managing MySQL schemas.
- The README describes its role: exporting CREATE TABLE statements, diffing live schemas vs. repo, linting, and pushing ALTER statements (optionally via online schema-change tools).

##### File structure
- Top-level CLI entrypoints:
- skeema.go – initializes the CLI
- cmd_*.go – handlers for subcommands (diff, pull, push, init, lint, format, add-env, etc.)
- Core subpackages:
- util – config loader, caching, shell-out wrapper
- fs – filesystem abstraction for discovering/managing .skeema files and .sql files
- dumper – logic to connect to a live MySQL instance and export CREATE statements to disk
- linter – rules engine to validate SQL schemas against best practices
- applier – generates and applies DDL ALTER statements to live databases
- workspace – isolated temporary schemas for safe diffing/applying
- External integration points:
- MySQL servers (various versions)
- Optional online-schema-change CLI tools (e.g., pt-online-schema-change)
- Filesystem (git repo, local disk)
- Configuration files: .skeema files in directory tree; goreleaser/travis for CI; vendor for dependencies.

##### Key insights from the README
- Declarative workflow: schemas live in filesystem; CLI syncs repo ↔ live DBs
- Multi-environment management: dev, staging, prod targets
- Pull-request based workflow and optional CI integration

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Interaction
    User["User"]:::external -->|"runs commands"| SkeemaGO

    %% CLI Orchestrator
    subgraph "CLI Orchestrator"
        direction TB
        SkeemaGO["skeema.go"]:::cli
        CMD_DIFF["cmd_diff.go"]:::cli
        CMD_PULL["cmd_pull.go"]:::cli
        CMD_PUSH["cmd_push.go"]:::cli
        CMD_LINT["cmd_lint.go"]:::cli
        CMD_INIT["cmd_init.go"]:::cli
        CMD_FORMAT["cmd_format.go"]:::cli
        CMD_ADDENV["cmd_add_env.go"]:::cli
        SkeemaGO --> CMD_DIFF
        SkeemaGO --> CMD_PULL
        SkeemaGO --> CMD_PUSH
        SkeemaGO --> CMD_LINT
        SkeemaGO --> CMD_INIT
        SkeemaGO --> CMD_FORMAT
        SkeemaGO --> CMD_ADDENV
    end

    %% Util & Config
    subgraph "Config & Utilities"
        direction TB
        Config["util/config.go"]:::util
        Cache["util/cache.go"]:::util
        ShellOut["util/shellout.go"]:::util
        ExitLog["exit.go\nlog.go"]:::util
    end

    %% Filesystem Abstraction
    subgraph "Filesystem Abstraction"
        direction TB
        FS_DIR["fs/dir.go"]:::fs
        FS_SQL["fs/sqlfile.go"]:::fs
        FS_STMT["fs/statement.go"]:::fs
    end

    %% Engines
    subgraph "Engines"
        direction TB
        subgraph "Dumper Engine"
            DConfig["dumper/config.go"]:::engine
            Dumper["dumper/dumper.go"]:::engine
            DConfig --> Dumper
        end
        subgraph "Linter Engine"
            LConfig["linter/config.go"]:::engine
            Linter["linter/linter.go"]:::engine
            Check1["linter/check_auto_inc.go"]:::engine
            Check2["linter/check_charset.go"]:::engine
            Check3["linter/check_definer.go"]:::engine
            Check4["linter/check_display_width.go"]:::engine
            Check5["linter/check_dupe_index.go"]:::engine
            Check6["linter/check_engine.go"]:::engine
            Check7["linter/check_has_fk.go"]:::engine
            Check8["linter/check_has_float.go"]:::engine
            Check9["linter/check_has_routine.go"]:::engine
            Check10["linter/check_has_time.go"]:::engine
            Check11["linter/check_pk.go"]:::engine
            Result["linter/result.go"]:::engine
            LConfig --> Linter
            Linter --> Check1
            Linter --> Check2
            Linter --> Check3
            Linter --> Check4
            Linter --> Check5
            Linter --> Check6
            Linter --> Check7
            Linter --> Check8
            Linter --> Check9
            Linter --> Check10
            Linter --> Check11
            Linter --> Result
        end
        subgraph "Applier Engine"
            Applier["applier/applier.go"]:::engine
            DDL["applier/ddlstatement.go"]:::engine
            Printer["applier/printer.go"]:::engine
            Target["applier/target.go"]:::engine
            Applier --> DDL
            Applier --> Printer
            Applier --> Target
        end
    end

    %% Workspace
    subgraph "Workspace Manager"
        direction TB
        WS["workspace/workspace.go"]:::engine
        TempSchema["workspace/tempschema.go"]:::engine
        LocalDocker["workspace/localdocker.go"]:::engine
        WS --> TempSchema
        WS --> LocalDocker
    end

    %% External Systems
    subgraph "External Integrations"
        direction TB
        MySQL["MySQL Instances"]:::db
        OnlineTool["pt-online-schema-change"]:::external
        GitRepo["Git Repository"]:::external
    end

    %% Core Flows
    SkeemaGO -->|"load config"| Config
    SkeemaGO -->|"scan files"| FS_DIR
    FS_DIR --> FS_SQL
    FS_SQL --> FS_STMT

    CMD_PULL -->|"invoke"| Dumper
    Dumper -->|"SQL over TCP"| MySQL
    Dumper -->|"writes CREATEs"| FS_SQL

    CMD_DIFF -->|"setup temp"| WS
    WS -->|"clone schema"| MySQL
    WS -->|"produce files"| FS_SQL
    FS_SQL -->|"compare"| CMD_DIFF

    CMD_LINT -->|"read SQL"| FS_SQL
    FS_SQL -->|"lint rules"| Linter
    Linter -->|"warnings"| SkeemaGO

    CMD_PUSH -->|"generate DDL"| Applier
    FS_SQL --> Applier
    Applier -->|"apply TCP"| MySQL
    Applier -->|"shell out"| ShellOut
    ShellOut --> OnlineTool
    OnlineTool --> MySQL

    SkeemaGO --> ExitLog

    %% Version Control
    FS_DIR --> GitRepo

    %% Click Events
    click SkeemaGO "https://github.com/github/skeema/blob/master/skeema.go"
    click CMD_DIFF "https://github.com/github/skeema/blob/master/cmd_diff.go"
    click CMD_PULL "https://github.com/github/skeema/blob/master/cmd_pull.go"
    click CMD_PUSH "https://github.com/github/skeema/blob/master/cmd_push.go"
    click CMD_LINT "https://github.com/github/skeema/blob/master/cmd_lint.go"
    click CMD_INIT "https://github.com/github/skeema/blob/master/cmd_init.go"
    click CMD_FORMAT "https://github.com/github/skeema/blob/master/cmd_format.go"
    click CMD_ADDENV "https://github.com/github/skeema/blob/master/cmd_add_env.go"
    click Config "https://github.com/github/skeema/blob/master/util/config.go"
    click Cache "https://github.com/github/skeema/blob/master/util/cache.go"
    click ShellOut "https://github.com/github/skeema/blob/master/util/shellout.go"
    click FS_DIR "https://github.com/github/skeema/blob/master/fs/dir.go"
    click FS_SQL "https://github.com/github/skeema/blob/master/fs/sqlfile.go"
    click FS_STMT "https://github.com/github/skeema/blob/master/fs/statement.go"
    click DConfig "https://github.com/github/skeema/blob/master/dumper/config.go"
    click Dumper "https://github.com/github/skeema/blob/master/dumper/dumper.go"
    click LConfig "https://github.com/github/skeema/blob/master/linter/config.go"
    click Linter "https://github.com/github/skeema/blob/master/linter/linter.go"
    click Check1 "https://github.com/github/skeema/blob/master/linter/check_auto_inc.go"
    click Check2 "https://github.com/github/skeema/blob/master/linter/check_charset.go"
    click Check3 "https://github.com/github/skeema/blob/master/linter/check_definer.go"
    click Check4 "https://github.com/github/skeema/blob/master/linter/check_display_width.go"
    click Check5 "https://github.com/github/skeema/blob/master/linter/check_dupe_index.go"
    click Check6 "https://github.com/github/skeema/blob/master/linter/check_engine.go"
    click Check7 "https://github.com/github/skeema/blob/master/linter/check_has_fk.go"
    click Check8 "https://github.com/github/skeema/blob/master/linter/check_has_float.go"
    click Check9 "https://github.com/github/skeema/blob/master/linter/check_has_routine.go"
    click Check10 "https://github.com/github/skeema/blob/master/linter/check_has_time.go"
    click Check11 "https://github.com/github/skeema/blob/master/linter/check_pk.go"
    click Result "https://github.com/github/skeema/blob/master/linter/result.go"
    click Applier "https://github.com/github/skeema/blob/master/applier/applier.go"
    click DDL "https://github.com/github/skeema/blob/master/applier/ddlstatement.go"
    click Printer "https://github.com/github/skeema/blob/master/applier/printer.go"
    click Target "https://github.com/github/skeema/blob/master/applier/target.go"
    click WS "https://github.com/github/skeema/blob/master/workspace/workspace.go"
    click TempSchema "https://github.com/github/skeema/blob/master/workspace/tempschema.go"
    click LocalDocker "https://github.com/github/skeema/blob/master/workspace/localdocker.go"

    %% Styles
    classDef cli fill:#f9f,stroke:#333,stroke-width:1px
    classDef util fill:#ff9,stroke:#333,stroke-width:1px
    classDef fs fill:#9ff,stroke:#333,stroke-width:1px
    classDef engine fill:#9f9,stroke:#333,stroke-width:1px
    classDef external fill:#f99,stroke:#333,stroke-width:1px
    classDef db fill:#99f,stroke:#333,stroke-width:1px
```
