# getml/sqlgen architecture

> Architecture diagram of the GitHub repository getml/sqlgen, 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/getml/sqlgen
- Repository: https://github.com/getml/sqlgen

## Overview

sqlgen is a C++20, reflection-integrated ORM and SQL query generator. The principal workflow maps model types and composable read/write operations into dynamic statements, translates those statements into backend-specific SQL, and uses a database connection to execute operations and parse results. Its documented surface also includes schema creation, inserts, updates, deletes, indexes, joins, aggregations, and explicit transactions. The graph reflects the README and sampled transpilation, parsing, session, and dialect code; backend execution details not shown in the excerpts are represented at their existing backend directories.

Main entry points: [`include/sqlgen/Session.hpp`](https://github.com/getml/sqlgen/blob/main/include/sqlgen/Session.hpp) (Session Operations), [`include/sqlgen/transpilation/to_sql.hpp`](https://github.com/getml/sqlgen/blob/main/include/sqlgen/transpilation/to_sql.hpp) (Dialect SQL Generation), [`include/sqlgen/parsing/Parser.hpp`](https://github.com/getml/sqlgen/blob/main/include/sqlgen/parsing/Parser.hpp) (Type Parsing), [`include/sqlgen/sqlite/Connection.hpp`](https://github.com/getml/sqlgen/blob/main/include/sqlgen/sqlite/Connection.hpp) (SQLite Backend)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["C++ ORM API"]
  node_models["Reflected Models"]
  node_read_api["Read API<br/>[read.hpp]"]
  node_write_api["Write API<br/>[write.hpp]"]
end

subgraph group_query["Query and Schema"]
  node_query_builders["Query Builders<br/>[select_from.hpp]"]
  node_transpilation["Query Transpilation<br/>[to_select_from.hpp]"]
  node_schema["Schema DDL<br/>[create_table.hpp]"]
  node_dynamic["Dynamic Statements<br/>[Statement.hpp]"]
end

subgraph group_runtime["Execution Runtime"]
  node_parsing["Type Parsing<br/>[Parser.hpp]"]
  node_session["Session Operations<br/>[Session.hpp]"]
  node_transactions["Transactions<br/>[Transaction.hpp]"]
  node_result["Typed Results<br/>[Result.hpp]"]
end

subgraph group_backends["Database Backends"]
  node_sqlite["SQLite Backend<br/>[Connection.hpp]"]
  node_postgres["PostgreSQL Backend<br/>[Connection.hpp]"]
  node_mysql["MySQL Backend<br/>[Connection.hpp]"]
  node_duckdb["DuckDB Backend<br/>[Connection.hpp]"]
  node_sql_dialects["Dialect SQL Generation<br/>[to_sql.hpp]"]
end

node_developer(("C++ Application"))
node_database[("Database")]

node_developer -->|"builds read"| node_read_api
node_developer -->|"writes models"| node_write_api
node_models -->|"provides schema"| node_transpilation
node_read_api -->|"composes query"| node_query_builders
node_query_builders -->|"translates query"| node_transpilation
node_write_api -->|"creates table"| node_schema
node_write_api -->|"forms write"| node_dynamic
node_schema -->|"forms DDL"| node_dynamic
node_transpilation -->|"forms query"| node_dynamic
node_dynamic -->|"supplies statements"| node_session
node_session -->|"requests SQL"| node_sql_dialects
node_session -->|"parses values"| node_parsing
node_session -->|"runs transaction"| node_transactions
node_session -->|"returns outcomes"| node_result
node_session -->|"dispatches operations"| node_sqlite
node_session -->|"dispatches operations"| node_postgres
node_session -.->|"dispatches operations"| node_mysql
node_session -.->|"dispatches operations"| node_duckdb
node_sql_dialects -->|"generates SQL"| node_sqlite
node_sql_dialects -->|"generates SQL"| node_postgres
node_sql_dialects -.->|"generates SQL"| node_mysql
node_sql_dialects -.->|"generates SQL"| node_duckdb
node_sqlite -->|"executes SQL"| node_database
node_postgres -->|"executes SQL"| node_database
node_mysql -.->|"executes SQL"| node_database
node_duckdb -.->|"executes SQL"| node_database
node_sqlite -->|"provides rows"| node_parsing
node_postgres -->|"provides rows"| node_parsing
node_mysql -.->|"provides rows"| node_parsing
node_duckdb -.->|"provides rows"| node_parsing

click node_read_api "https://github.com/getml/sqlgen/blob/main/include/sqlgen/read.hpp"
click node_write_api "https://github.com/getml/sqlgen/blob/main/include/sqlgen/write.hpp"
click node_query_builders "https://github.com/getml/sqlgen/blob/main/include/sqlgen/select_from.hpp"
click node_transpilation "https://github.com/getml/sqlgen/blob/main/include/sqlgen/transpilation/to_select_from.hpp"
click node_schema "https://github.com/getml/sqlgen/blob/main/include/sqlgen/create_table.hpp"
click node_dynamic "https://github.com/getml/sqlgen/blob/main/include/sqlgen/dynamic/Statement.hpp"
click node_parsing "https://github.com/getml/sqlgen/blob/main/include/sqlgen/parsing/Parser.hpp"
click node_session "https://github.com/getml/sqlgen/blob/main/include/sqlgen/Session.hpp"
click node_transactions "https://github.com/getml/sqlgen/blob/main/include/sqlgen/Transaction.hpp"
click node_sqlite "https://github.com/getml/sqlgen/blob/main/include/sqlgen/sqlite/Connection.hpp"
click node_postgres "https://github.com/getml/sqlgen/blob/main/include/sqlgen/postgres/Connection.hpp"
click node_mysql "https://github.com/getml/sqlgen/blob/main/include/sqlgen/mysql/Connection.hpp"
click node_duckdb "https://github.com/getml/sqlgen/blob/main/include/sqlgen/duckdb/Connection.hpp"
click node_sql_dialects "https://github.com/getml/sqlgen/blob/main/include/sqlgen/transpilation/to_sql.hpp"
click node_result "https://github.com/getml/sqlgen/blob/main/include/sqlgen/Result.hpp"

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_models,node_read_api,node_write_api toneBlue
class node_query_builders,node_transpilation,node_schema,node_dynamic,node_database toneAmber
class node_parsing,node_session,node_transactions,node_result toneMint
class node_sqlite,node_postgres,node_mysql,node_duckdb,node_sql_dialects toneRose
class node_developer toneIndigo
```

## Components

### C++ ORM API

- **Reflected Models**
- [Read API](https://github.com/getml/sqlgen/blob/main/include/sqlgen/read.hpp): `include/sqlgen/read.hpp`
- [Write API](https://github.com/getml/sqlgen/blob/main/include/sqlgen/write.hpp): `include/sqlgen/write.hpp`

### Query and Schema

- [Query Builders](https://github.com/getml/sqlgen/blob/main/include/sqlgen/select_from.hpp): `include/sqlgen/select_from.hpp`
- [Query Transpilation](https://github.com/getml/sqlgen/blob/main/include/sqlgen/transpilation/to_select_from.hpp): `include/sqlgen/transpilation/to_select_from.hpp`
- [Schema DDL](https://github.com/getml/sqlgen/blob/main/include/sqlgen/create_table.hpp): `include/sqlgen/create_table.hpp`
- [Dynamic Statements](https://github.com/getml/sqlgen/blob/main/include/sqlgen/dynamic/Statement.hpp): `include/sqlgen/dynamic/Statement.hpp`

### Execution Runtime

- [Type Parsing](https://github.com/getml/sqlgen/blob/main/include/sqlgen/parsing/Parser.hpp): `include/sqlgen/parsing/Parser.hpp`
- [Session Operations](https://github.com/getml/sqlgen/blob/main/include/sqlgen/Session.hpp): `include/sqlgen/Session.hpp`
- [Transactions](https://github.com/getml/sqlgen/blob/main/include/sqlgen/Transaction.hpp): `include/sqlgen/Transaction.hpp`
- [Typed Results](https://github.com/getml/sqlgen/blob/main/include/sqlgen/Result.hpp): `include/sqlgen/Result.hpp`

### Database Backends

- [SQLite Backend](https://github.com/getml/sqlgen/blob/main/include/sqlgen/sqlite/Connection.hpp): `include/sqlgen/sqlite/Connection.hpp`
- [PostgreSQL Backend](https://github.com/getml/sqlgen/blob/main/include/sqlgen/postgres/Connection.hpp): `include/sqlgen/postgres/Connection.hpp`
- [MySQL Backend](https://github.com/getml/sqlgen/blob/main/include/sqlgen/mysql/Connection.hpp): `include/sqlgen/mysql/Connection.hpp`
- [DuckDB Backend](https://github.com/getml/sqlgen/blob/main/include/sqlgen/duckdb/Connection.hpp): `include/sqlgen/duckdb/Connection.hpp`
- [Dialect SQL Generation](https://github.com/getml/sqlgen/blob/main/include/sqlgen/transpilation/to_sql.hpp): `include/sqlgen/transpilation/to_sql.hpp`

### Other components

- **C++ Application**
- **Database**

## Connections

- C++ Application → Read API: builds read
- C++ Application → Write API: writes models
- Reflected Models → Query Transpilation: provides schema
- Read API → Query Builders: composes query
- Query Builders → Query Transpilation: translates query
- Write API → Schema DDL: creates table
- Write API → Dynamic Statements: forms write
- Schema DDL → Dynamic Statements: forms DDL
- Query Transpilation → Dynamic Statements: forms query
- Dynamic Statements → Session Operations: supplies statements
- Session Operations → Dialect SQL Generation: requests SQL
- Session Operations → Type Parsing: parses values
- Session Operations → Transactions: runs transaction
- Session Operations → Typed Results: returns outcomes
- Session Operations → SQLite Backend: dispatches operations
- Session Operations → PostgreSQL Backend: dispatches operations
- Session Operations → MySQL Backend: dispatches operations
- Session Operations → DuckDB Backend: dispatches operations
- Dialect SQL Generation → SQLite Backend: generates SQL
- Dialect SQL Generation → PostgreSQL Backend: generates SQL
- Dialect SQL Generation → MySQL Backend: generates SQL
- Dialect SQL Generation → DuckDB Backend: generates SQL
- SQLite Backend → Database: executes SQL
- PostgreSQL Backend → Database: executes SQL
- MySQL Backend → Database: executes SQL
- DuckDB Backend → Database: executes SQL
- SQLite Backend → Type Parsing: provides rows
- PostgreSQL Backend → Type Parsing: provides rows
- MySQL Backend → Type Parsing: provides rows
- DuckDB Backend → Type Parsing: provides rows