# amacneil/dbmate architecture

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

- Interactive diagram: https://gitdiagram.com/amacneil/dbmate
- Repository: https://github.com/amacneil/dbmate

## Overview

Dbmate is a standalone SQL database migration CLI. The main workflow is to create timestamped migration files, apply or roll them back through the selected database driver, and optionally save a schema dump. The README also documents database creation and removal, status, schema loading, and connection waiting. The graph includes the Go driver layer and the TypeScript npm launcher; some driver internals and command-to-method links are documented capabilities rather than fully sampled implementations.

Main entry points: [`main.go`](https://github.com/amacneil/dbmate/blob/main/main.go) (Go CLI), [`pkg/dbmate/db.go`](https://github.com/amacneil/dbmate/blob/main/pkg/dbmate/db.go) (Migration operations), [`typescript/packages/dbmate/src/resolveBinary.ts`](https://github.com/amacneil/dbmate/blob/main/typescript/packages/dbmate/src/resolveBinary.ts) (Binary resolver), [`pkg/driver/postgres/postgres.go`](https://github.com/amacneil/dbmate/blob/main/pkg/driver/postgres/postgres.go) (Postgres driver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and distribution"]
  node_main["Go CLI<br/>[main.go]"]
  node_npm_cli["npm launcher<br/>[cli.ts]"]
  node_binary_resolver["Binary resolver<br/>[resolveBinary.ts]"]
end

subgraph group_migration["Migration lifecycle"]
  node_migration_files["SQL migration files"]
  node_db_core["Migration operations<br/>[db.go]"]
  node_migration_parser["Migration parsing<br/>[migration.go]"]
end

subgraph group_database["Database drivers"]
  node_driver_api["Driver interface<br/>[driver.go]"]
  node_postgres["Postgres driver<br/>[postgres.go]"]
  node_mysql["MySQL driver<br/>[mysql.go]"]
  node_sqlite["SQLite driver<br/>[sqlite.go]"]
  node_clickhouse["ClickHouse driver<br/>[clickhouse.go]"]
  node_bigquery["BigQuery driver<br/>[bigquery.go]"]
end

subgraph group_support["Schema and utilities"]
  node_dbutil["Database utilities<br/>[dbutil.go]"]
  node_schema_file["Schema file"]
end

node_user(("CLI user"))
node_db_service[("Database server")]

node_user -->|"runs commands"| node_main
node_main -->|"invokes operations"| node_db_core
node_main -->|"imports driver"| node_postgres
node_main -->|"imports driver"| node_mysql
node_main -->|"imports driver"| node_clickhouse
node_main -->|"imports driver"| node_bigquery
node_main -->|"imports driver"| node_sqlite
node_db_core -->|"uses interface"| node_driver_api
node_db_core -->|"uses utilities"| node_dbutil
node_db_core -.->|"reads and writes"| node_migration_files
node_db_core -.->|"dumps or loads"| node_schema_file
node_postgres -.->|"connects to"| node_db_service
node_mysql -.->|"connects to"| node_db_service
node_sqlite -.->|"connects to"| node_db_service
node_clickhouse -.->|"connects to"| node_db_service
node_bigquery -.->|"connects to"| node_db_service
node_npm_cli -->|"resolves binary"| node_binary_resolver
node_binary_resolver -.->|"locates executable"| node_main

click node_main "https://github.com/amacneil/dbmate/blob/main/main.go"
click node_npm_cli "https://github.com/amacneil/dbmate/blob/main/typescript/packages/dbmate/src/cli.ts"
click node_binary_resolver "https://github.com/amacneil/dbmate/blob/main/typescript/packages/dbmate/src/resolveBinary.ts"
click node_db_core "https://github.com/amacneil/dbmate/blob/main/pkg/dbmate/db.go"
click node_migration_parser "https://github.com/amacneil/dbmate/blob/main/pkg/dbmate/migration.go"
click node_driver_api "https://github.com/amacneil/dbmate/blob/main/pkg/dbmate/driver.go"
click node_postgres "https://github.com/amacneil/dbmate/blob/main/pkg/driver/postgres/postgres.go"
click node_mysql "https://github.com/amacneil/dbmate/blob/main/pkg/driver/mysql/mysql.go"
click node_sqlite "https://github.com/amacneil/dbmate/blob/main/pkg/driver/sqlite/sqlite.go"
click node_clickhouse "https://github.com/amacneil/dbmate/blob/main/pkg/driver/clickhouse/clickhouse.go"
click node_bigquery "https://github.com/amacneil/dbmate/blob/main/pkg/driver/bigquery/bigquery.go"
click node_dbutil "https://github.com/amacneil/dbmate/blob/main/pkg/dbutil/dbutil.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_main,node_npm_cli,node_binary_resolver,node_user toneBlue
class node_migration_files,node_db_core,node_migration_parser,node_db_service toneAmber
class node_driver_api,node_postgres,node_mysql,node_sqlite,node_clickhouse,node_bigquery toneMint
class node_dbutil,node_schema_file toneRose
```

## Components

### CLI and distribution

- [Go CLI](https://github.com/amacneil/dbmate/blob/main/main.go): `main.go`
- [npm launcher](https://github.com/amacneil/dbmate/blob/main/typescript/packages/dbmate/src/cli.ts): `typescript/packages/dbmate/src/cli.ts`
- [Binary resolver](https://github.com/amacneil/dbmate/blob/main/typescript/packages/dbmate/src/resolveBinary.ts): `typescript/packages/dbmate/src/resolveBinary.ts`

### Migration lifecycle

- **SQL migration files**
- [Migration operations](https://github.com/amacneil/dbmate/blob/main/pkg/dbmate/db.go): `pkg/dbmate/db.go`
- [Migration parsing](https://github.com/amacneil/dbmate/blob/main/pkg/dbmate/migration.go): `pkg/dbmate/migration.go`

### Database drivers

- [Driver interface](https://github.com/amacneil/dbmate/blob/main/pkg/dbmate/driver.go): `pkg/dbmate/driver.go`
- [Postgres driver](https://github.com/amacneil/dbmate/blob/main/pkg/driver/postgres/postgres.go): `pkg/driver/postgres/postgres.go`
- [MySQL driver](https://github.com/amacneil/dbmate/blob/main/pkg/driver/mysql/mysql.go): `pkg/driver/mysql/mysql.go`
- [SQLite driver](https://github.com/amacneil/dbmate/blob/main/pkg/driver/sqlite/sqlite.go): `pkg/driver/sqlite/sqlite.go`
- [ClickHouse driver](https://github.com/amacneil/dbmate/blob/main/pkg/driver/clickhouse/clickhouse.go): `pkg/driver/clickhouse/clickhouse.go`
- [BigQuery driver](https://github.com/amacneil/dbmate/blob/main/pkg/driver/bigquery/bigquery.go): `pkg/driver/bigquery/bigquery.go`

### Schema and utilities

- [Database utilities](https://github.com/amacneil/dbmate/blob/main/pkg/dbutil/dbutil.go): `pkg/dbutil/dbutil.go`
- **Schema file**

### Other components

- **CLI user**
- **Database server**

## Connections

- CLI user → Go CLI: runs commands (evidence: `README.md`)
- Go CLI → Migration operations: invokes operations (evidence: `main.go`)
- Go CLI → Postgres driver: imports driver (evidence: `main.go`)
- Go CLI → MySQL driver: imports driver (evidence: `main.go`)
- Go CLI → ClickHouse driver: imports driver (evidence: `main.go`)
- Go CLI → BigQuery driver: imports driver (evidence: `main.go`)
- Go CLI → SQLite driver: imports driver
- Migration operations → Driver interface: uses interface (evidence: `pkg/dbmate/db.go`)
- Migration operations → Database utilities: uses utilities (evidence: `pkg/dbmate/db.go`)
- Migration operations → SQL migration files: reads and writes (evidence: `README.md`)
- Migration operations → Schema file: dumps or loads (evidence: `README.md`)
- Postgres driver → Database server: connects to (evidence: `README.md`)
- MySQL driver → Database server: connects to (evidence: `README.md`)
- SQLite driver → Database server: connects to (evidence: `README.md`)
- ClickHouse driver → Database server: connects to (evidence: `README.md`)
- BigQuery driver → Database server: connects to (evidence: `README.md`)
- npm launcher → Binary resolver: resolves binary (evidence: `typescript/packages/dbmate/src/cli.ts`)
- Binary resolver → Go CLI: locates executable
