# go-gormigrate/gormigrate architecture

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

- Interactive diagram: https://gitdiagram.com/go-gormigrate/gormigrate
- Repository: https://github.com/go-gormigrate/gormigrate

## Overview

##### Project type and purpose
- This is an open-source Go library (“Gormigrate”) that provides versioned schema migrations on top of the GORM ORM.
- It is not a full-stack application but a reusable tool that integrates into Go applications and supports multiple SQL databases.

##### File structure
- Top-level files:
- gormigrate.go – the library’s main code
- go.mod / go.sum – Go module definitions
- Taskfile.yml – automated tasks (build, test, docker orchestration)
- .github/workflows – CI definitions for linting and integration tests
- integration-test directory:
- docker-compose.yml – spins up database containers for testing
- .example.env – sample environment variables per database
- individual Go tests per supported database (mysql, postgres, sqlite, etc.)

##### README for additional insights
- Describes usage: how a client imports gormigrate, instantiates it with a GORM DB handle, defines migrations and optionally an InitSchema function.
- Lists supported databases (MySQL, MariaDB, PostgreSQL, SQLite, SQL Server, etc.)
- Mentions Options struct (custom table name, transactional behavior, validation flags).
- Details the integration-test prerequisites (Task runner, Docker, .env configuration).

a. Main components to model
1. Client Application (your Go app)
2. Gormigrate Library Core
– Migration Manager
– Migration Definitions (ID, Migrate/​Rollback functions)
– Options
3. GORM ORM
4. Database Drivers (gorm.io/driver/mysql, postgres, sqlite, mssql, etc.)
5. Target Databases (MariaDB, MySQL, PostgreSQL, SQLite, SQL Server)
6. InitSchema (optional code path for fresh databases)
7. Integration Test Suite
– Task CLI (Taskfile)
– Docker-Compose (DB containers)
– Go test runner
8. CI/CD Pipelines (.github/workflows)

b. Relationships and data flows
- Client App imports Gormigrate → calls gorm.Open → obtains *gorm.DB
- Client constructs a []*gormigrate.Migration list → passes to gormigrate.New along with Options
- Gormigrate invokes each Migration.Migrate(tx *gorm.DB) in order, or InitSchema if no prior migrations run
- Under the hood, Gormigrate calls GORM’s Migrator API (CreateTable, AddColumn, DropTable, etc.) → routed through the appropriate Database Driver → executes SQL on the target database
- Rollback functions reverse operations when requested
- Integration tests:
- Task CLI “docker:compose:up” launches containers
- Task CLI “test:all” runs go test in integration-test against each DB
- CI pipeline triggers linting, then launches integration tests in parallel

c. Architectural patterns and design principles
- Plugin-style migration definitions: each migration is self-contained with Migrate/Rollback pairs
- Optional InitSchema hook for new database bootstrap
- Dependency injection of *gorm.DB for testability and decoupling
- Transactional option flag to wrap all migrations in a single transaction (if supported)
- Minimal external dependencies to keep the library lightweight

d. Key technologies, frameworks, libraries
- Go modules (go.mod)
- GORM v2 (ORM)
- gormigrate/v2 (this library)
- Docker & Docker-Compose (for integration tests)
- Task (Taskfile.yml) as build/test orchestrator
- GitHub Actions (lint.yml, integration-test.yml)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Application
    subgraph "Client Application"
        Client["Client Application"]:::external
    end

    %% Gormigrate Core Library
    subgraph "Gormigrate Core"
        MG["Migration Manager"]:::library
        OP["Options Handler"]:::library
        IS["InitSchema Handler"]:::library
        GoMod["Go Modules (go.mod/go.sum)"]:::library
    end

    %% GORM ORM
    GORM["GORM ORM"]:::external

    %% Database Drivers
    subgraph "DB Drivers"
        MySQLDrv["mysql driver"]:::external
        PGDrv["postgres driver"]:::external
        SQLiteDrv["sqlite driver"]:::external
        MSSQLDrv["mssql driver"]:::external
    end

    %% Supported Databases
    subgraph "Supported RDBMS"
        Maria["MariaDB"]:::external
        MySQLDB["MySQL"]:::external
        PostgreSQL["PostgreSQL"]:::external
        SQLiteDB["SQLite"]:::external
        SQLServer["SQL Server"]:::external
    end

    %% Integration Test Suite
    subgraph "Integration Test Suite"
        TaskCLI["Task CLI"]:::test
        DockerComp["Docker-Compose"]:::test
        Env["Sample .env"]:::test
        subgraph "Test Files"
            GMTest["gormigrate_test.go"]:::test
            MyTest["mysql_test.go"]:::test
            MariaTest["mariadb_test.go"]:::test
            PGTest["postgres_test.go"]:::test
            SQLiteTest["sqlite_test.go"]:::test
            SQLiteGoTest["sqlitego_test.go"]:::test
            MSSQLTest["sqlserver_test.go"]:::test
            ModInt["go.mod/go.sum"]:::test
        end
    end

    %% CI/CD Pipelines
    subgraph "CI/CD Pipelines"
        LintCI["Lint Workflow"]:::test
        TestCI["Integration-Test Workflow"]:::test
    end

    %% Documentation
    subgraph "Project Documentation"
        README["README.md"]:::doc
        CHANGELOG["CHANGELOG.md"]:::doc
        LICENSE["LICENSE"]:::doc
        GITIGNORE[".gitignore"]:::doc
    end

    %% Connections
    Client -->|"Defines migrations, calls Migrate()"| MG
    MG -->|"uses Options"| OP
    MG -->|"calls InitSchema if none"| IS
    MG -->|"imports modules"| GoMod
    MG -->|"calls GORM Migrator"| GORM
    GORM -->|"via driver"| MySQLDrv & PGDrv & SQLiteDrv & MSSQLDrv
    MySQLDrv -->|"executes SQL"| Maria & MySQLDB
    PGDrv -->|"executes SQL"| PostgreSQL
    SQLiteDrv -->|"executes SQL"| SQLiteDB
    MSSQLDrv -->|"executes SQL"| SQLServer

    TaskCLI -->|"run docker:compose:up"| DockerComp
    TaskCLI -->|"run test:all"| GMTest & MyTest & MariaTest & PGTest & SQLiteTest & SQLiteGoTest & MSSQLTest
    DockerComp -->|"provides DB containers"| Maria & MySQLDB & PostgreSQL & SQLiteDB & SQLServer

    TestCI -->|"invokes Task CLI"| TaskCLI
    LintCI -->|"after lint"| TestCI

    %% Click Events
    click MG "https://github.com/go-gormigrate/gormigrate/blob/master/gormigrate.go"
    click GoMod "https://github.com/go-gormigrate/gormigrate/blob/master/go.mod"
    click GoMod "https://github.com/go-gormigrate/gormigrate/blob/master/go.sum"
    click TaskCLI "https://github.com/go-gormigrate/gormigrate/blob/master/Taskfile.yml"
    click LintCI "https://github.com/go-gormigrate/gormigrate/blob/master/.github/workflows/lint.yml"
    click TestCI "https://github.com/go-gormigrate/gormigrate/blob/master/.github/workflows/integration-test.yml"
    click GMTest "https://github.com/go-gormigrate/gormigrate/blob/master/integration-test/gormigrate_test.go"
    click MyTest "https://github.com/go-gormigrate/gormigrate/blob/master/integration-test/mysql_test.go"
    click MariaTest "https://github.com/go-gormigrate/gormigrate/blob/master/integration-test/mariadb_test.go"
    click PGTest "https://github.com/go-gormigrate/gormigrate/blob/master/integration-test/postgres_test.go"
    click SQLiteTest "https://github.com/go-gormigrate/gormigrate/blob/master/integration-test/sqlite_test.go"
    click SQLiteGoTest "https://github.com/go-gormigrate/gormigrate/blob/master/integration-test/sqlitego_test.go"
    click MSSQLTest "https://github.com/go-gormigrate/gormigrate/blob/master/integration-test/sqlserver_test.go"
    click ModInt "https://github.com/go-gormigrate/gormigrate/blob/master/integration-test/go.mod"
    click ModInt "https://github.com/go-gormigrate/gormigrate/blob/master/integration-test/go.sum"
    click DockerComp "https://github.com/go-gormigrate/gormigrate/blob/master/integration-test/docker-compose.yml"
    click Env "https://github.com/go-gormigrate/gormigrate/blob/master/integration-test/.example.env"
    click README "https://github.com/go-gormigrate/gormigrate/blob/master/README.md"
    click CHANGELOG "https://github.com/go-gormigrate/gormigrate/blob/master/CHANGELOG.md"
    click LICENSE "https://github.com/go-gormigrate/gormigrate/tree/master/LICENSE"
    click GITIGNORE "https://github.com/go-gormigrate/gormigrate/blob/master/.gitignore"

    %% Styles
    classDef library fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px
    classDef test fill:#F9F871,stroke:#333,stroke-width:1px
    classDef doc fill:#D3D3D3,stroke:#333,stroke-width:1px
```
