# golang-migrate/migrate architecture

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

- Interactive diagram: https://gitdiagram.com/golang-migrate/migrate
- Repository: https://github.com/golang-migrate/migrate

## Overview

golang-migrate is a Go library and CLI for applying ordered, versioned database migrations. Its principal workflow is to open a migration source and database driver, read up/down migration streams, and apply them while tracking migration state; the CLI is a thin entry point to the same engine. The README documents filesystem, embedded, Git-hosted, and cloud sources plus many database backends. Source excerpts are limited, so subsystem-level links rely on the README rather than inferred calls between individual drivers.

Main entry points: [`source/driver.go`](https://github.com/golang-migrate/migrate/blob/master/source/driver.go) (Source driver API), [`migrate.go`](https://github.com/golang-migrate/migrate/blob/master/migrate.go) (Migration engine), [`database/driver.go`](https://github.com/golang-migrate/migrate/blob/master/database/driver.go) (Database driver API), [`internal/cli/main.go`](https://github.com/golang-migrate/migrate/blob/master/internal/cli/main.go) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entrypoints"]
  node_cli["CLI<br/>[main.go]"]
end

subgraph group_engine["Migration engine"]
  node_engine_core["Migration engine<br/>[migrate.go]"]
  node_migration_model["Migration model<br/>[migration.go]"]
end

subgraph group_sources["Migration sources"]
  node_source_registry["Source driver API<br/>[driver.go]"]
  node_source_parse["Migration parsing<br/>[parse.go]"]
  node_local_sources["Filesystem sources<br/>[file.go]"]
  node_embedded_sources["Embedded sources<br/>[iofs.go]"]
  node_git_sources["Git hosting sources<br/>[github.go]"]
  node_cloud_sources["Cloud storage sources<br/>[s3.go]"]
end

subgraph group_databases["Database drivers"]
  node_database_api["Database driver API<br/>[driver.go]"]
  node_sql_drivers["SQL database drivers<br/>[postgres.go]"]
  node_nosql_drivers["NoSQL database drivers<br/>[mongodb.go]"]
end

node_cli_user(("CLI user"))
node_go_app(("Go application"))
node_database_system[("Target database")]

node_cli_user -->|"runs commands"| node_cli
node_cli -->|"initializes"| node_engine_core
node_go_app -->|"calls API"| node_engine_core
node_engine_core -->|"reads migrations"| node_source_registry
node_engine_core -->|"applies migrations"| node_database_api
node_local_sources -->|"implements"| node_source_registry
node_embedded_sources -->|"implements"| node_source_registry
node_git_sources -->|"implements"| node_source_registry
node_cloud_sources -->|"implements"| node_source_registry
node_source_parse -.->|"parses files"| node_migration_model
node_sql_drivers -->|"implements"| node_database_api
node_nosql_drivers -->|"implements"| node_database_api
node_database_api -->|"executes against"| node_database_system

click node_cli "https://github.com/golang-migrate/migrate/blob/master/internal/cli/main.go"
click node_engine_core "https://github.com/golang-migrate/migrate/blob/master/migrate.go"
click node_migration_model "https://github.com/golang-migrate/migrate/blob/master/migration.go"
click node_source_registry "https://github.com/golang-migrate/migrate/blob/master/source/driver.go"
click node_source_parse "https://github.com/golang-migrate/migrate/blob/master/source/parse.go"
click node_local_sources "https://github.com/golang-migrate/migrate/blob/master/source/file/file.go"
click node_embedded_sources "https://github.com/golang-migrate/migrate/blob/master/source/iofs/iofs.go"
click node_git_sources "https://github.com/golang-migrate/migrate/blob/master/source/github/github.go"
click node_cloud_sources "https://github.com/golang-migrate/migrate/blob/master/source/aws_s3/s3.go"
click node_database_api "https://github.com/golang-migrate/migrate/blob/master/database/driver.go"
click node_sql_drivers "https://github.com/golang-migrate/migrate/blob/master/database/postgres/postgres.go"
click node_nosql_drivers "https://github.com/golang-migrate/migrate/blob/master/database/mongodb/mongodb.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_cli_user toneBlue
class node_engine_core,node_migration_model,node_database_system toneAmber
class node_source_registry,node_source_parse,node_local_sources,node_embedded_sources,node_git_sources,node_cloud_sources toneMint
class node_database_api,node_sql_drivers,node_nosql_drivers toneRose
class node_go_app toneIndigo
```

## Components

### Entrypoints

- [CLI](https://github.com/golang-migrate/migrate/blob/master/internal/cli/main.go): `internal/cli/main.go`

### Migration engine

- [Migration engine](https://github.com/golang-migrate/migrate/blob/master/migrate.go): `migrate.go`
- [Migration model](https://github.com/golang-migrate/migrate/blob/master/migration.go): `migration.go`

### Migration sources

- [Source driver API](https://github.com/golang-migrate/migrate/blob/master/source/driver.go): `source/driver.go`
- [Migration parsing](https://github.com/golang-migrate/migrate/blob/master/source/parse.go): `source/parse.go`
- [Filesystem sources](https://github.com/golang-migrate/migrate/blob/master/source/file/file.go): `source/file/file.go`
- [Embedded sources](https://github.com/golang-migrate/migrate/blob/master/source/iofs/iofs.go): `source/iofs/iofs.go`
- [Git hosting sources](https://github.com/golang-migrate/migrate/blob/master/source/github/github.go): `source/github/github.go`
- [Cloud storage sources](https://github.com/golang-migrate/migrate/blob/master/source/aws_s3/s3.go): `source/aws_s3/s3.go`

### Database drivers

- [Database driver API](https://github.com/golang-migrate/migrate/blob/master/database/driver.go): `database/driver.go`
- [SQL database drivers](https://github.com/golang-migrate/migrate/blob/master/database/postgres/postgres.go): `database/postgres/postgres.go`
- [NoSQL database drivers](https://github.com/golang-migrate/migrate/blob/master/database/mongodb/mongodb.go): `database/mongodb/mongodb.go`

### Other components

- **CLI user**
- **Go application**
- **Target database**

## Connections

- CLI user → CLI: runs commands (evidence: `README.md`)
- CLI → Migration engine: initializes (evidence: `internal/cli/main.go`)
- Go application → Migration engine: calls API (evidence: `README.md`)
- Migration engine → Source driver API: reads migrations (evidence: `README.md`)
- Migration engine → Database driver API: applies migrations (evidence: `README.md`)
- Filesystem sources → Source driver API: implements (evidence: `README.md`)
- Embedded sources → Source driver API: implements (evidence: `README.md`)
- Git hosting sources → Source driver API: implements (evidence: `README.md`)
- Cloud storage sources → Source driver API: implements (evidence: `README.md`)
- Migration parsing → Migration model: parses files
- SQL database drivers → Database driver API: implements (evidence: `README.md`)
- NoSQL database drivers → Database driver API: implements (evidence: `README.md`)
- Database driver API → Target database: executes against (evidence: `README.md`)
