# transact-rs/sqlx architecture

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

- Interactive diagram: https://gitdiagram.com/transact-rs/sqlx
- Repository: https://github.com/transact-rs/sqlx

## Overview

SQLx is an asynchronous Rust SQL toolkit. In the main workflow, an application builds a query, binds Rust values, executes it through an executor and database driver, then consumes decoded rows. The repository also provides compile-time query checking and derives, connection pooling, runtime-selectable `Any`, migrations and PostgreSQL notifications. Driver internals and some CLI relationships are represented at subsystem level where the supplied excerpts do not establish finer-grained calls; those links are omitted or marked unverified.

Main entry points: [`sqlx-core/src/executor.rs`](https://github.com/transact-rs/sqlx/blob/main/sqlx-core/src/executor.rs) (Executor API), [`sqlx-core/src/query.rs`](https://github.com/transact-rs/sqlx/blob/main/sqlx-core/src/query.rs) (Query builders), [`sqlx-cli/src/lib.rs`](https://github.com/transact-rs/sqlx/blob/main/sqlx-cli/src/lib.rs) (SQLx CLI), [`sqlx-core/src/query_as.rs`](https://github.com/transact-rs/sqlx/blob/main/sqlx-core/src/query_as.rs) (Typed queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Query API"]
  node_query["Query builders<br/>[query.rs]"]
  node_typed_query["Typed queries<br/>[query_as.rs]"]
  node_query_builder["Dynamic builder<br/>[query_builder.rs]"]
end

subgraph group_core["Execution Core"]
  node_executor["Executor API<br/>[executor.rs]"]
  node_pool["Connection pool<br/>[mod.rs]"]
  node_transactions["Transactions<br/>[transaction.rs]"]
  node_conversion["Value conversion<br/>[encode.rs]"]
  node_row_mapping["Row mapping<br/>[from_row.rs]"]
end

subgraph group_drivers["Database Drivers"]
  node_postgres["PostgreSQL driver<br/>[executor.rs]"]
  node_mysql["MySQL driver<br/>[executor.rs]"]
  node_sqlite["SQLite driver<br/>[executor.rs]"]
  node_any["Runtime Any driver<br/>[driver.rs]"]
  node_notifications["PG notifications<br/>[listener.rs]"]
end

subgraph group_compile["Compile-Time Support"]
  node_macros["Query macros<br/>[mod.rs]"]
  node_derives["Type derives<br/>[mod.rs]"]
end

subgraph group_cli["CLI Operations"]
  node_cli["SQLx CLI<br/>[lib.rs]"]
  node_migrations["Migration commands<br/>[migrate.rs]"]
  node_database_admin["Database commands<br/>[database.rs]"]
  node_offline_prepare["Offline preparation<br/>[prepare.rs]"]
end

node_app(("Rust application"))
node_database[("Database server")]

node_app -->|"builds query"| node_query
node_app -->|"maps results"| node_typed_query
node_query -->|"executes through"| node_executor
node_typed_query -->|"fetches through"| node_executor
node_query_builder -->|"builds query"| node_query
node_query -->|"encodes bindings"| node_conversion
node_typed_query -->|"maps rows"| node_row_mapping
node_executor -.->|"uses pooled connections"| node_pool
node_executor -.->|"dispatches execution"| node_postgres
node_executor -.->|"dispatches execution"| node_mysql
node_executor -.->|"dispatches execution"| node_sqlite
node_executor -.->|"supports runtime driver"| node_any
node_postgres -.->|"speaks protocol"| node_database
node_mysql -.->|"speaks protocol"| node_database
node_sqlite -.->|"queries embedded store"| node_database
node_app -->|"checks queries"| node_macros
node_app -.->|"derives mappings"| node_derives
node_cli -->|"runs migrations"| node_migrations
node_cli -->|"runs database commands"| node_database_admin
node_cli -.->|"prepares queries"| node_offline_prepare
node_app -->|"acquires connections"| node_pool
node_app -->|"starts transactions"| node_transactions
node_app -->|"listens for events"| node_notifications

click node_query "https://github.com/transact-rs/sqlx/blob/main/sqlx-core/src/query.rs"
click node_typed_query "https://github.com/transact-rs/sqlx/blob/main/sqlx-core/src/query_as.rs"
click node_query_builder "https://github.com/transact-rs/sqlx/blob/main/sqlx-core/src/query_builder.rs"
click node_executor "https://github.com/transact-rs/sqlx/blob/main/sqlx-core/src/executor.rs"
click node_pool "https://github.com/transact-rs/sqlx/blob/main/sqlx-core/src/pool/mod.rs"
click node_transactions "https://github.com/transact-rs/sqlx/blob/main/sqlx-core/src/transaction.rs"
click node_conversion "https://github.com/transact-rs/sqlx/blob/main/sqlx-core/src/encode.rs"
click node_row_mapping "https://github.com/transact-rs/sqlx/blob/main/sqlx-core/src/from_row.rs"
click node_postgres "https://github.com/transact-rs/sqlx/blob/main/sqlx-postgres/src/connection/executor.rs"
click node_mysql "https://github.com/transact-rs/sqlx/blob/main/sqlx-mysql/src/connection/executor.rs"
click node_sqlite "https://github.com/transact-rs/sqlx/blob/main/sqlx-sqlite/src/connection/executor.rs"
click node_any "https://github.com/transact-rs/sqlx/blob/main/sqlx-core/src/any/driver.rs"
click node_macros "https://github.com/transact-rs/sqlx/blob/main/sqlx-macros-core/src/query/mod.rs"
click node_derives "https://github.com/transact-rs/sqlx/blob/main/sqlx-macros-core/src/derives/mod.rs"
click node_cli "https://github.com/transact-rs/sqlx/blob/main/sqlx-cli/src/lib.rs"
click node_migrations "https://github.com/transact-rs/sqlx/blob/main/sqlx-cli/src/migrate.rs"
click node_database_admin "https://github.com/transact-rs/sqlx/blob/main/sqlx-cli/src/database.rs"
click node_offline_prepare "https://github.com/transact-rs/sqlx/blob/main/sqlx-cli/src/prepare.rs"
click node_notifications "https://github.com/transact-rs/sqlx/blob/main/sqlx-postgres/src/listener.rs"

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_query,node_typed_query,node_query_builder toneBlue
class node_executor,node_pool,node_transactions,node_conversion,node_row_mapping,node_database toneAmber
class node_postgres,node_mysql,node_sqlite,node_any,node_notifications toneMint
class node_macros,node_derives toneRose
class node_cli,node_migrations,node_database_admin,node_offline_prepare,node_app toneIndigo
```

## Components

### Query API

- [Query builders](https://github.com/transact-rs/sqlx/blob/main/sqlx-core/src/query.rs): `sqlx-core/src/query.rs`
- [Typed queries](https://github.com/transact-rs/sqlx/blob/main/sqlx-core/src/query_as.rs): `sqlx-core/src/query_as.rs`
- [Dynamic builder](https://github.com/transact-rs/sqlx/blob/main/sqlx-core/src/query_builder.rs): `sqlx-core/src/query_builder.rs`

### Execution Core

- [Executor API](https://github.com/transact-rs/sqlx/blob/main/sqlx-core/src/executor.rs): `sqlx-core/src/executor.rs`
- [Connection pool](https://github.com/transact-rs/sqlx/blob/main/sqlx-core/src/pool/mod.rs): `sqlx-core/src/pool/mod.rs`
- [Transactions](https://github.com/transact-rs/sqlx/blob/main/sqlx-core/src/transaction.rs): `sqlx-core/src/transaction.rs`
- [Value conversion](https://github.com/transact-rs/sqlx/blob/main/sqlx-core/src/encode.rs): `sqlx-core/src/encode.rs`
- [Row mapping](https://github.com/transact-rs/sqlx/blob/main/sqlx-core/src/from_row.rs): `sqlx-core/src/from_row.rs`

### Database Drivers

- [PostgreSQL driver](https://github.com/transact-rs/sqlx/blob/main/sqlx-postgres/src/connection/executor.rs): `sqlx-postgres/src/connection/executor.rs`
- [MySQL driver](https://github.com/transact-rs/sqlx/blob/main/sqlx-mysql/src/connection/executor.rs): `sqlx-mysql/src/connection/executor.rs`
- [SQLite driver](https://github.com/transact-rs/sqlx/blob/main/sqlx-sqlite/src/connection/executor.rs): `sqlx-sqlite/src/connection/executor.rs`
- [Runtime Any driver](https://github.com/transact-rs/sqlx/blob/main/sqlx-core/src/any/driver.rs): `sqlx-core/src/any/driver.rs`
- [PG notifications](https://github.com/transact-rs/sqlx/blob/main/sqlx-postgres/src/listener.rs): `sqlx-postgres/src/listener.rs`

### Compile-Time Support

- [Query macros](https://github.com/transact-rs/sqlx/blob/main/sqlx-macros-core/src/query/mod.rs): `sqlx-macros-core/src/query/mod.rs`
- [Type derives](https://github.com/transact-rs/sqlx/blob/main/sqlx-macros-core/src/derives/mod.rs): `sqlx-macros-core/src/derives/mod.rs`

### CLI Operations

- [SQLx CLI](https://github.com/transact-rs/sqlx/blob/main/sqlx-cli/src/lib.rs): `sqlx-cli/src/lib.rs`
- [Migration commands](https://github.com/transact-rs/sqlx/blob/main/sqlx-cli/src/migrate.rs): `sqlx-cli/src/migrate.rs`
- [Database commands](https://github.com/transact-rs/sqlx/blob/main/sqlx-cli/src/database.rs): `sqlx-cli/src/database.rs`
- [Offline preparation](https://github.com/transact-rs/sqlx/blob/main/sqlx-cli/src/prepare.rs): `sqlx-cli/src/prepare.rs`

### Other components

- **Rust application**
- **Database server**

## Connections

- Rust application → Query builders: builds query
- Rust application → Typed queries: maps results
- Query builders → Executor API: executes through (evidence: `sqlx-core/src/query.rs`)
- Typed queries → Executor API: fetches through (evidence: `sqlx-core/src/query_as.rs`)
- Dynamic builder → Query builders: builds query (evidence: `sqlx-core/src/query_builder.rs`)
- Query builders → Value conversion: encodes bindings (evidence: `sqlx-core/src/query.rs`)
- Typed queries → Row mapping: maps rows (evidence: `sqlx-core/src/query_as.rs`)
- Executor API → Connection pool: uses pooled connections (evidence: `sqlx-core/src/executor.rs`)
- Executor API → PostgreSQL driver: dispatches execution
- Executor API → MySQL driver: dispatches execution
- Executor API → SQLite driver: dispatches execution
- Executor API → Runtime Any driver: supports runtime driver
- PostgreSQL driver → Database server: speaks protocol
- MySQL driver → Database server: speaks protocol
- SQLite driver → Database server: queries embedded store
- Rust application → Query macros: checks queries
- Rust application → Type derives: derives mappings
- SQLx CLI → Migration commands: runs migrations (evidence: `sqlx-cli/src/lib.rs`)
- SQLx CLI → Database commands: runs database commands (evidence: `sqlx-cli/src/lib.rs`)
- SQLx CLI → Offline preparation: prepares queries (evidence: `sqlx-cli/src/lib.rs`)
- Rust application → Connection pool: acquires connections
- Rust application → Transactions: starts transactions
- Rust application → PG notifications: listens for events
