# sqlc-dev/sqlc architecture

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

- Interactive diagram: https://gitdiagram.com/sqlc-dev/sqlc
- Repository: https://github.com/sqlc-dev/sqlc

## Overview

sqlc is a SQL compiler: users provide SQL queries, schema and configuration, then invoke the CLI to produce type-safe application code. The principal workflow parses and analyzes SQL against a database dialect/catalog, then passes compiled query metadata to a language generator. The tree also exposes analysis, vetting, formatting, diff/verification, and database-management commands, plus plugin support. The compiler excerpt confirms dialect-specific setup and a core analysis path; wiring for several command and plugin branches is inferred only at the documented capability level.

Main entry points: [`internal/cmd`](https://github.com/sqlc-dev/sqlc/tree/main/internal/cmd) (Command Handlers), [`internal/compiler/engine.go`](https://github.com/sqlc-dev/sqlc/blob/main/internal/compiler/engine.go) (Compiler), [`pkg/cli/cli.go`](https://github.com/sqlc-dev/sqlc/blob/main/pkg/cli/cli.go) (CLI), [`internal/codegen/golang/gen.go`](https://github.com/sqlc-dev/sqlc/blob/main/internal/codegen/golang/gen.go) (Go Generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and Config"]
  node_cli["CLI<br/>[cli.go]"]
  node_commands["Command Handlers"]
  node_configuration["Configuration<br/>[config.go]"]
end

subgraph group_compile["SQL Compilation"]
  node_parse["SQL Parsing<br/>[parse.go]"]
  node_engine["Dialect Engines"]
  node_compiler["Compiler<br/>[engine.go]"]
  node_catalog["Schema Catalog<br/>[catalog.go]"]
  node_querycatalog["Query Catalog<br/>[query_catalog.go]"]
  node_analysis["Query Analysis<br/>[analyze.go]"]
end

subgraph group_generate["Code Generation"]
  node_go_codegen["Go Generator<br/>[gen.go]"]
  node_json_codegen["JSON Generator<br/>[gen.go]"]
  node_plugin["Plugin Protocol<br/>[codegen.pb.go]"]
  node_plugin_ext["Plugin Runtime<br/>[handler.go]"]
end

subgraph group_services["Validation and Services"]
  node_analysis_cmd["Analyze and Vet<br/>[analyze.go]"]
  node_format_cmd["Format and Diff<br/>[fmt.go]"]
  node_verify_cmd["Verify Queries<br/>[verify.go]"]
  node_dbmanager["Managed Databases<br/>[client.go]"]
end

node_user(("Developer"))
node_inputs["SQL and Config"]
node_generated["Generated Files"]
node_database[("SQL Database")]

node_user -->|"invokes"| node_cli
node_inputs -->|"supplies inputs"| node_commands
node_cli -->|"dispatches"| node_commands
node_commands -->|"loads settings"| node_configuration
node_commands -->|"compiles queries"| node_compiler
node_compiler -->|"parses SQL"| node_parse
node_compiler -->|"selects dialect"| node_engine
node_compiler -->|"builds catalog"| node_catalog
node_compiler -->|"resolves relations"| node_querycatalog
node_compiler -->|"analyzes queries"| node_analysis
node_commands -->|"generates Go"| node_go_codegen
node_commands -->|"requests generation"| node_plugin
node_plugin -.->|"dispatches plugin"| node_plugin_ext
node_plugin_ext -.->|"invokes JSON"| node_json_codegen
node_go_codegen -->|"writes code"| node_generated
node_json_codegen -->|"returns files"| node_generated
node_commands -->|"runs analysis"| node_analysis_cmd
node_commands -->|"runs formatting"| node_format_cmd
node_commands -->|"runs verification"| node_verify_cmd
node_commands -->|"creates database"| node_dbmanager
node_dbmanager -->|"creates and migrates"| node_database
node_analysis_cmd -->|"analyzes SQL"| node_compiler
node_verify_cmd -->|"checks queries"| node_compiler
node_user -->|"uses generated code"| node_generated

click node_cli "https://github.com/sqlc-dev/sqlc/blob/main/pkg/cli/cli.go"
click node_commands "https://github.com/sqlc-dev/sqlc/tree/main/internal/cmd"
click node_configuration "https://github.com/sqlc-dev/sqlc/blob/main/internal/config/config.go"
click node_parse "https://github.com/sqlc-dev/sqlc/blob/main/internal/compiler/parse.go"
click node_engine "https://github.com/sqlc-dev/sqlc/tree/main/internal/engine"
click node_compiler "https://github.com/sqlc-dev/sqlc/blob/main/internal/compiler/engine.go"
click node_catalog "https://github.com/sqlc-dev/sqlc/blob/main/internal/core/catalog.go"
click node_querycatalog "https://github.com/sqlc-dev/sqlc/blob/main/internal/compiler/query_catalog.go"
click node_analysis "https://github.com/sqlc-dev/sqlc/blob/main/internal/compiler/analyze.go"
click node_go_codegen "https://github.com/sqlc-dev/sqlc/blob/main/internal/codegen/golang/gen.go"
click node_json_codegen "https://github.com/sqlc-dev/sqlc/blob/main/internal/codegen/json/gen.go"
click node_plugin "https://github.com/sqlc-dev/sqlc/blob/main/internal/plugin/codegen.pb.go"
click node_plugin_ext "https://github.com/sqlc-dev/sqlc/blob/main/internal/ext/handler.go"
click node_analysis_cmd "https://github.com/sqlc-dev/sqlc/blob/main/internal/cmd/analyze.go"
click node_format_cmd "https://github.com/sqlc-dev/sqlc/blob/main/internal/cmd/fmt.go"
click node_verify_cmd "https://github.com/sqlc-dev/sqlc/blob/main/internal/cmd/verify.go"
click node_dbmanager "https://github.com/sqlc-dev/sqlc/blob/main/internal/dbmanager/client.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_commands,node_configuration toneBlue
class node_parse,node_engine,node_compiler,node_catalog,node_querycatalog,node_analysis,node_database toneAmber
class node_go_codegen,node_json_codegen,node_plugin,node_plugin_ext toneMint
class node_analysis_cmd,node_format_cmd,node_verify_cmd,node_dbmanager toneRose
class node_user,node_inputs,node_generated toneIndigo
```

## Components

### CLI and Config

- [CLI](https://github.com/sqlc-dev/sqlc/blob/main/pkg/cli/cli.go): `pkg/cli/cli.go`
- [Command Handlers](https://github.com/sqlc-dev/sqlc/tree/main/internal/cmd): `internal/cmd`
- [Configuration](https://github.com/sqlc-dev/sqlc/blob/main/internal/config/config.go): `internal/config/config.go`

### SQL Compilation

- [SQL Parsing](https://github.com/sqlc-dev/sqlc/blob/main/internal/compiler/parse.go): `internal/compiler/parse.go`
- [Dialect Engines](https://github.com/sqlc-dev/sqlc/tree/main/internal/engine): `internal/engine`
- [Compiler](https://github.com/sqlc-dev/sqlc/blob/main/internal/compiler/engine.go): `internal/compiler/engine.go`
- [Schema Catalog](https://github.com/sqlc-dev/sqlc/blob/main/internal/core/catalog.go): `internal/core/catalog.go`
- [Query Catalog](https://github.com/sqlc-dev/sqlc/blob/main/internal/compiler/query_catalog.go): `internal/compiler/query_catalog.go`
- [Query Analysis](https://github.com/sqlc-dev/sqlc/blob/main/internal/compiler/analyze.go): `internal/compiler/analyze.go`

### Code Generation

- [Go Generator](https://github.com/sqlc-dev/sqlc/blob/main/internal/codegen/golang/gen.go): `internal/codegen/golang/gen.go`
- [JSON Generator](https://github.com/sqlc-dev/sqlc/blob/main/internal/codegen/json/gen.go): `internal/codegen/json/gen.go`
- [Plugin Protocol](https://github.com/sqlc-dev/sqlc/blob/main/internal/plugin/codegen.pb.go): `internal/plugin/codegen.pb.go`
- [Plugin Runtime](https://github.com/sqlc-dev/sqlc/blob/main/internal/ext/handler.go): `internal/ext/handler.go`

### Validation and Services

- [Analyze and Vet](https://github.com/sqlc-dev/sqlc/blob/main/internal/cmd/analyze.go): `internal/cmd/analyze.go`
- [Format and Diff](https://github.com/sqlc-dev/sqlc/blob/main/internal/cmd/fmt.go): `internal/cmd/fmt.go`
- [Verify Queries](https://github.com/sqlc-dev/sqlc/blob/main/internal/cmd/verify.go): `internal/cmd/verify.go`
- [Managed Databases](https://github.com/sqlc-dev/sqlc/blob/main/internal/dbmanager/client.go): `internal/dbmanager/client.go`

### Other components

- **Developer**
- **SQL and Config**
- **Generated Files**
- **SQL Database**

## Connections

- Developer → CLI: invokes
- SQL and Config → Command Handlers: supplies inputs
- CLI → Command Handlers: dispatches
- Command Handlers → Configuration: loads settings
- Command Handlers → Compiler: compiles queries
- Compiler → SQL Parsing: parses SQL
- Compiler → Dialect Engines: selects dialect
- Compiler → Schema Catalog: builds catalog
- Compiler → Query Catalog: resolves relations
- Compiler → Query Analysis: analyzes queries
- Command Handlers → Go Generator: generates Go
- Command Handlers → Plugin Protocol: requests generation
- Plugin Protocol → Plugin Runtime: dispatches plugin
- Plugin Runtime → JSON Generator: invokes JSON
- Go Generator → Generated Files: writes code
- JSON Generator → Generated Files: returns files
- Command Handlers → Analyze and Vet: runs analysis
- Command Handlers → Format and Diff: runs formatting
- Command Handlers → Verify Queries: runs verification
- Command Handlers → Managed Databases: creates database
- Managed Databases → SQL Database: creates and migrates
- Analyze and Vet → Compiler: analyzes SQL
- Verify Queries → Compiler: checks queries
- Developer → Generated Files: uses generated code