# volatiletech/sqlboiler architecture

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

- Interactive diagram: https://gitdiagram.com/volatiletech/sqlboiler
- Repository: https://github.com/volatiletech/sqlboiler

## Overview

SQLBoiler is a database-first Go ORM generator. The principal workflow is to invoke its CLI with a database driver, inspect an existing schema, and generate tailored Go model code from templates. Generated models then provide typed query construction and database execution, with documented relationship/eager-loading, hooks, transaction, and custom database-type capabilities. The graph separates generation from the runtime support library. Some subsystem links are documented rather than directly visible in the sampled excerpts; those are marked dashed where implementation wiring is unverified.

Main entry points: [`drivers/interface.go`](https://github.com/volatiletech/sqlboiler/blob/master/drivers/interface.go) (Driver metadata API), [`main.go`](https://github.com/volatiletech/sqlboiler/blob/master/main.go) (SQLBoiler CLI), [`boilingcore/boilingcore.go`](https://github.com/volatiletech/sqlboiler/blob/master/boilingcore/boilingcore.go) (Generation state), [`boilingcore/output.go`](https://github.com/volatiletech/sqlboiler/blob/master/boilingcore/output.go) (Output rendering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generation["Code generation"]
  node_cli["SQLBoiler CLI<br/>[main.go]"]
  node_core["Generation state<br/>[boilingcore.go]"]
  node_config["Generation config<br/>[config.go]"]
  node_template["Template system<br/>[templates.go]"]
  node_render["Output rendering<br/>[output.go]"]
  node_imports["Import mapping<br/>[imports.go]"]
end

subgraph group_drivers["Schema drivers"]
  node_driverapi["Driver metadata API<br/>[interface.go]"]
  node_pgdriver["PostgreSQL driver<br/>[psql.go]"]
  node_mysqldriver["MySQL driver<br/>[mysql.go]"]
  node_mssqldriver["MSSQL driver<br/>[mssql.go]"]
  node_sqlite_driver["SQLite driver<br/>[sqlite3.go]"]
end

subgraph group_runtime["ORM runtime"]
  node_executor["DB executor<br/>[db.go]"]
  node_querymods["Query modifiers<br/>[query_mods.go]"]
  node_query["Query execution<br/>[query.go]"]
  node_eager["Eager loading<br/>[eager_load.go]"]
  node_reflect["Model reflection<br/>[reflect.go]"]
  node_hooks["Model hooks<br/>[hooks.go]"]
end

subgraph group_types["Database types"]
  node_db_types["Extended DB types<br/>[array.go]"]
  node_pg_types["PostgreSQL geo types<br/>[main.go]"]
end

node_developer(("Developer"))
node_schema_db[("Existing database")]
node_generated_models["Generated Go models"]

node_developer -->|"runs"| node_cli
node_cli -->|"selects driver"| node_driverapi
node_cli -->|"starts generation"| node_core
node_cli -.->|"provides options"| node_config
node_pgdriver -->|"reads schema"| node_schema_db
node_mysqldriver -->|"reads schema"| node_schema_db
node_mssqldriver -.->|"reads schema"| node_schema_db
node_sqlite_driver -.->|"reads schema"| node_schema_db
node_driverapi -->|"defines contract"| node_pgdriver
node_driverapi -->|"defines contract"| node_mysqldriver
node_driverapi -->|"defines contract"| node_mssqldriver
node_driverapi -->|"defines contract"| node_sqlite_driver
node_core -->|"loads metadata"| node_driverapi
node_core -->|"uses templates"| node_template
node_core -->|"generates files"| node_render
node_render -->|"formats imports"| node_imports
node_render -->|"writes code"| node_generated_models
node_generated_models -.->|"builds queries"| node_querymods
node_querymods -->|"modifies query"| node_query
node_query -->|"executes SQL"| node_executor
node_query -->|"uses dialect"| node_driverapi
node_generated_models -.->|"loads relations"| node_eager
node_generated_models -.->|"runs hooks"| node_hooks
node_generated_models -.->|"maps records"| node_reflect
node_generated_models -.->|"uses column types"| node_db_types
node_generated_models -.->|"uses geo types"| node_pg_types

click node_cli "https://github.com/volatiletech/sqlboiler/blob/master/main.go"
click node_core "https://github.com/volatiletech/sqlboiler/blob/master/boilingcore/boilingcore.go"
click node_config "https://github.com/volatiletech/sqlboiler/blob/master/boilingcore/config.go"
click node_template "https://github.com/volatiletech/sqlboiler/blob/master/boilingcore/templates.go"
click node_render "https://github.com/volatiletech/sqlboiler/blob/master/boilingcore/output.go"
click node_imports "https://github.com/volatiletech/sqlboiler/blob/master/importers/imports.go"
click node_driverapi "https://github.com/volatiletech/sqlboiler/blob/master/drivers/interface.go"
click node_pgdriver "https://github.com/volatiletech/sqlboiler/blob/master/drivers/sqlboiler-psql/driver/psql.go"
click node_mysqldriver "https://github.com/volatiletech/sqlboiler/blob/master/drivers/sqlboiler-mysql/driver/mysql.go"
click node_mssqldriver "https://github.com/volatiletech/sqlboiler/blob/master/drivers/sqlboiler-mssql/driver/mssql.go"
click node_sqlite_driver "https://github.com/volatiletech/sqlboiler/blob/master/drivers/sqlboiler-sqlite3/driver/sqlite3.go"
click node_executor "https://github.com/volatiletech/sqlboiler/blob/master/boil/db.go"
click node_querymods "https://github.com/volatiletech/sqlboiler/blob/master/queries/qm/query_mods.go"
click node_query "https://github.com/volatiletech/sqlboiler/blob/master/queries/query.go"
click node_eager "https://github.com/volatiletech/sqlboiler/blob/master/queries/eager_load.go"
click node_reflect "https://github.com/volatiletech/sqlboiler/blob/master/queries/reflect.go"
click node_hooks "https://github.com/volatiletech/sqlboiler/blob/master/boil/hooks.go"
click node_db_types "https://github.com/volatiletech/sqlboiler/blob/master/types/array.go"
click node_pg_types "https://github.com/volatiletech/sqlboiler/blob/master/types/pgeo/main.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_core,node_config,node_template,node_render,node_imports toneBlue
class node_driverapi,node_pgdriver,node_mysqldriver,node_mssqldriver,node_sqlite_driver,node_schema_db toneAmber
class node_executor,node_querymods,node_query,node_eager,node_reflect,node_hooks toneMint
class node_db_types,node_pg_types toneRose
class node_developer,node_generated_models toneIndigo
```

## Components

### Code generation

- [SQLBoiler CLI](https://github.com/volatiletech/sqlboiler/blob/master/main.go): `main.go`
- [Generation state](https://github.com/volatiletech/sqlboiler/blob/master/boilingcore/boilingcore.go): `boilingcore/boilingcore.go`
- [Generation config](https://github.com/volatiletech/sqlboiler/blob/master/boilingcore/config.go): `boilingcore/config.go`
- [Template system](https://github.com/volatiletech/sqlboiler/blob/master/boilingcore/templates.go): `boilingcore/templates.go`
- [Output rendering](https://github.com/volatiletech/sqlboiler/blob/master/boilingcore/output.go): `boilingcore/output.go`
- [Import mapping](https://github.com/volatiletech/sqlboiler/blob/master/importers/imports.go): `importers/imports.go`

### Schema drivers

- [Driver metadata API](https://github.com/volatiletech/sqlboiler/blob/master/drivers/interface.go): `drivers/interface.go`
- [PostgreSQL driver](https://github.com/volatiletech/sqlboiler/blob/master/drivers/sqlboiler-psql/driver/psql.go): `drivers/sqlboiler-psql/driver/psql.go`
- [MySQL driver](https://github.com/volatiletech/sqlboiler/blob/master/drivers/sqlboiler-mysql/driver/mysql.go): `drivers/sqlboiler-mysql/driver/mysql.go`
- [MSSQL driver](https://github.com/volatiletech/sqlboiler/blob/master/drivers/sqlboiler-mssql/driver/mssql.go): `drivers/sqlboiler-mssql/driver/mssql.go`
- [SQLite driver](https://github.com/volatiletech/sqlboiler/blob/master/drivers/sqlboiler-sqlite3/driver/sqlite3.go): `drivers/sqlboiler-sqlite3/driver/sqlite3.go`

### ORM runtime

- [DB executor](https://github.com/volatiletech/sqlboiler/blob/master/boil/db.go): `boil/db.go`
- [Query modifiers](https://github.com/volatiletech/sqlboiler/blob/master/queries/qm/query_mods.go): `queries/qm/query_mods.go`
- [Query execution](https://github.com/volatiletech/sqlboiler/blob/master/queries/query.go): `queries/query.go`
- [Eager loading](https://github.com/volatiletech/sqlboiler/blob/master/queries/eager_load.go): `queries/eager_load.go`
- [Model reflection](https://github.com/volatiletech/sqlboiler/blob/master/queries/reflect.go): `queries/reflect.go`
- [Model hooks](https://github.com/volatiletech/sqlboiler/blob/master/boil/hooks.go): `boil/hooks.go`

### Database types

- [Extended DB types](https://github.com/volatiletech/sqlboiler/blob/master/types/array.go): `types/array.go`
- [PostgreSQL geo types](https://github.com/volatiletech/sqlboiler/blob/master/types/pgeo/main.go): `types/pgeo/main.go`

### Other components

- **Developer**
- **Existing database**
- **Generated Go models**

## Connections

- Developer → SQLBoiler CLI: runs
- SQLBoiler CLI → Driver metadata API: selects driver (evidence: `main.go`)
- SQLBoiler CLI → Generation state: starts generation (evidence: `main.go`)
- SQLBoiler CLI → Generation config: provides options
- PostgreSQL driver → Existing database: reads schema (evidence: `drivers/sqlboiler-psql/driver/psql.go`)
- MySQL driver → Existing database: reads schema (evidence: `drivers/sqlboiler-mysql/driver/mysql.go`)
- MSSQL driver → Existing database: reads schema
- SQLite driver → Existing database: reads schema
- Driver metadata API → PostgreSQL driver: defines contract (evidence: `drivers/sqlboiler-psql/driver/psql.go`)
- Driver metadata API → MySQL driver: defines contract (evidence: `drivers/sqlboiler-mysql/driver/mysql.go`)
- Driver metadata API → MSSQL driver: defines contract (evidence: `drivers/sqlboiler-mssql/driver/mssql.go`)
- Driver metadata API → SQLite driver: defines contract (evidence: `drivers/sqlboiler-sqlite3/driver/sqlite3.go`)
- Generation state → Driver metadata API: loads metadata (evidence: `boilingcore/boilingcore.go`)
- Generation state → Template system: uses templates (evidence: `boilingcore/boilingcore.go`)
- Generation state → Output rendering: generates files (evidence: `boilingcore/boilingcore.go`)
- Output rendering → Import mapping: formats imports (evidence: `boilingcore/output.go`)
- Output rendering → Generated Go models: writes code
- Generated Go models → Query modifiers: builds queries
- Query modifiers → Query execution: modifies query (evidence: `queries/qm/query_mods.go`)
- Query execution → DB executor: executes SQL (evidence: `queries/query.go`)
- Query execution → Driver metadata API: uses dialect (evidence: `queries/query.go`)
- Generated Go models → Eager loading: loads relations
- Generated Go models → Model hooks: runs hooks
- Generated Go models → Model reflection: maps records
- Generated Go models → Extended DB types: uses column types
- Generated Go models → PostgreSQL geo types: uses geo types
