# pressly/goose architecture

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

- Interactive diagram: https://gitdiagram.com/pressly/goose
- Repository: https://github.com/pressly/goose

## Overview

##### Main Components
- CLI Module – Represented by the “cmd/goose” directory, which contains the main executable, various driver integrations (for Postgres, MySQL, SQLite, YDB, etc.), and the entry point (main.go).
- Core Library – The heart of goose is in the library functions that handle migration management. This includes migration execution, versioning (up, down, status, etc.), and the “create”, “fix”, and “validate” operations.
- Internal Modules – There are several internal packages:
- Migration handling: files like migrate.go, migration.go, down.go, up.go, version.go.
- Dialect Abstraction: “database”, “internal/dialect” and associated files that handle SQL dialects for each supported database.
- SQL Parser: The “internal/sqlparser” component responsible for parsing migration files and handling special annotations (like “+goose Up”, “+goose Down”, “NO TRANSACTION”, etc.).
- Utility Packages: “internal/gooseutil”, “globals.go” and testing packages under “internal/testing” that encapsulate helper functions, migration stats (“internal/migrationstats”), and migration register functionality.
- Tests & Examples – A clear separation exists in directories like “tests”, “internal/testing” and “examples”, showing the separation of production code from test harnesses and sample migration projects.

##### Relationships and Data Flow
- The user (or CI/CD system) interacts with the CLI, which in turn calls the core library functions.
- The core library uses the SQL parser to interpret migration files (whether SQL or Go) and employs the appropriate dialect modules to generate the correct SQL commands.
- Database driver implementations (e.g., for Postgres, MySQL, etc.) – each driver file (found under cmd/goose and internal/dialect/dialectquery) encapsulate the connection and dialect-specific behavior. These components communicate directly with the target database.
- In addition, environment variable management (as described in the README regarding GOOSE_DRIVER, GOOSE_DBSTRING, and GOOSE_MIGRATION_DIR) is used to configure the runtime behavior and is integrated into the CLI’s initialization and subsequent migration execution.

##### Architectural Patterns & Design Principles
- Modularity: The project is structured in a modular way. Each package (e.g., migration, dialect, SQL parser) is encapsulated and can be maintained separately.
- Separation of Concerns: The CLI (user interface), migration execution logic, and database-specific drivers are all separated into their own components.
- Extensibility: The presence of “internal” directories (for dialects, migration stats, etc.) and support for plugins (via Go migration functions) speaks to an architecture built for extension.
- Testing Isolation: A robust test suite (integration and unit tests) further enforces clear application boundaries and decoupling.

##### Final Detailing
- Where needed, add annotations describing behaviors (e.g., “handles out-of-order migrations”, “embedded migration support via Go 1.16 embed”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    ENV["Environment Variables (GOOSE_DRIVER,GOOSE_DBSTRING,GOOSE_MIGRATION_DIR)"]:::config

    subgraph "User Interface"
        CLI["CLI (cmd/goose)"]:::cli
        LIB["Library API"]:::cli
    end

    CORE["Core Migration Engine"]:::core
    SQLPARSER["SQL Parser & Migration File Interpreter"]:::parser

    subgraph "Dialect Modules & Database Drivers"
        DBAbs["Database Abstraction"]:::dialect
        DialQ["Dialect Query"]:::dialect
    end

    DB["Database (External)"]:::external

    subgraph "Internal Utilities"
        GU["Goose Util"]:::util
        MS["Migration Stats"]:::util
    end

    subgraph "Testing & Examples"
        TESTS["Tests"]:::test
        IT["Internal Testing"]:::test
        EX["Examples"]:::test
    end

    %% Data Flow
    ENV -->|"configures"| CLI
    ENV -->|"configures"| LIB
    CLI -->|"invokes"| CORE
    LIB -->|"calls"| CORE
    CORE -->|"parsesMigration"| SQLPARSER
    CORE -->|"executesVia"| DBAbs
    CORE -->|"executesVia"| DialQ
    DBAbs -->|"communicates"| DB
    DialQ -->|"communicates"| DB
    CORE -- "utilizes" --> GU
    CORE -- "reportsTo" --> MS
    TESTS -.-> CORE
    IT -.-> CORE
    EX -.-> CORE

    %% Click Events
    click CLI "https://github.com/pressly/goose/tree/main/cmd/goose"
    click CORE "https://github.com/pressly/goose/blob/main/goose.go"
    click SQLPARSER "https://github.com/pressly/goose/tree/main/internal/sqlparser"
    click DBAbs "https://github.com/pressly/goose/tree/main/database"
    click DialQ "https://github.com/pressly/goose/tree/main/internal/dialect"
    click GU "https://github.com/pressly/goose/tree/main/internal/gooseutil"
    click MS "https://github.com/pressly/goose/tree/main/internal/migrationstats"
    click TESTS "https://github.com/pressly/goose/tree/main/tests"
    click IT "https://github.com/pressly/goose/tree/main/internal/testing"
    click EX "https://github.com/pressly/goose/tree/main/examples"

    %% Styling
    classDef cli fill:#f9f,stroke:#333,stroke-width:2px;
    classDef core fill:#b3d9ff,stroke:#333,stroke-width:2px;
    classDef parser fill:#c6f7c3,stroke:#333,stroke-width:2px;
    classDef dialect fill:#ffd6cc,stroke:#333,stroke-width:2px;
    classDef external fill:#e0e0e0,stroke:#333,stroke-width:2px,stroke-dasharray: 5,5;
    classDef util fill:#ffe699,stroke:#333,stroke-width:2px;
    classDef test fill:#d9b3ff,stroke:#333,stroke-width:2px;
    classDef config fill:#f2c2e0,stroke:#333,stroke-width:2px;
```
