# tursodatabase/turso architecture

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

- Interactive diagram: https://gitdiagram.com/tursodatabase/turso
- Repository: https://github.com/tursodatabase/turso

## Overview

Turso is an in-process SQLite-compatible SQL database with a virtual-machine execution core, language bindings, and documented experimental Postgres and synchronization capabilities. The principal workflow is a client submitting SQL through a frontend or binding; the core translates and executes it against database storage, then returns rows or status. The graph also shows MVCC, extensions, synchronization, and CLI access. README claims inform unsampled capabilities; source excerpts are partial, so uncertain internal wiring is omitted.

Main entry points: [`core/connection.rs`](https://github.com/tursodatabase/turso/blob/main/core/connection.rs) (Database connection), [`core/vdbe/execute.rs`](https://github.com/tursodatabase/turso/blob/main/core/vdbe/execute.rs) (VDBE execution), [`core/storage/pager.rs`](https://github.com/tursodatabase/turso/blob/main/core/storage/pager.rs) (Pager and storage), [`sync/engine/src/database_sync_engine.rs`](https://github.com/tursodatabase/turso/blob/main/sync/engine/src/database_sync_engine.rs) (Database sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Client interfaces"]
  node_cli["Interactive CLI<br/>[app.rs]"]
  node_bindings["Language bindings"]
  node_capi["C API<br/>[lib.rs]"]
  node_pg["Postgres frontend"]
end

subgraph group_engine["SQL engine"]
  node_core["Database connection<br/>[connection.rs]"]
  node_dialect["SQL dialects<br/>[mod.rs]"]
  node_translate["Translate and plan<br/>[mod.rs]"]
  node_vdbe["VDBE execution<br/>[execute.rs]"]
end

subgraph group_storage["Storage and sync"]
  node_mvcc["MVCC concurrency<br/>[mod.rs]"]
  node_storage[("Pager and storage<br/>[pager.rs]")]
  node_sync["Database sync"]
end

subgraph group_features["Database features"]
  node_functions["SQL functions<br/>[mod.rs]"]
  node_vectors["Vector operations<br/>[mod.rs]"]
  node_fts["Full-text search<br/>[mod.rs]"]
  node_incremental["Incremental views<br/>[mod.rs]"]
  node_cdc["Change capture<br/>[cdc.rs]"]
  node_extensions["Extensions"]
end

node_app(("Application"))
node_remote(("Remote sync service"))

node_app -->|"uses API"| node_bindings
node_app -->|"runs SQL"| node_cli
node_app -.->|"sends SQL"| node_pg
node_bindings -->|"submits SQL"| node_core
node_capi -->|"calls database"| node_core
node_cli -->|"queries"| node_core
node_pg -.->|"fronts database"| node_core
node_core -->|"selects dialect"| node_dialect
node_core -->|"translates SQL"| node_translate
node_translate -->|"emits bytecode"| node_vdbe
node_vdbe -->|"reads and writes"| node_storage
node_vdbe -->|"invokes functions"| node_functions
node_vdbe -->|"executes operations"| node_vectors
node_vdbe -->|"queries indexes"| node_fts
node_core -->|"coordinates transactions"| node_mvcc
node_mvcc -->|"persists changes"| node_storage
node_core -->|"tracks changes"| node_cdc
node_incremental -->|"persists state"| node_storage
node_extensions -->|"adds capabilities"| node_core
node_sync -->|"synchronizes pages"| node_storage
node_sync -->|"exchanges changes"| node_remote

click node_cli "https://github.com/tursodatabase/turso/blob/main/cli/app.rs"
click node_bindings "https://github.com/tursodatabase/turso/tree/main/bindings"
click node_capi "https://github.com/tursodatabase/turso/blob/main/bindings/c/src/lib.rs"
click node_pg "https://github.com/tursodatabase/turso/tree/main/postgres"
click node_core "https://github.com/tursodatabase/turso/blob/main/core/connection.rs"
click node_dialect "https://github.com/tursodatabase/turso/blob/main/core/dialect/mod.rs"
click node_translate "https://github.com/tursodatabase/turso/blob/main/core/translate/mod.rs"
click node_vdbe "https://github.com/tursodatabase/turso/blob/main/core/vdbe/execute.rs"
click node_functions "https://github.com/tursodatabase/turso/blob/main/core/functions/mod.rs"
click node_vectors "https://github.com/tursodatabase/turso/blob/main/core/vector/mod.rs"
click node_fts "https://github.com/tursodatabase/turso/blob/main/core/index_method/fts/mod.rs"
click node_incremental "https://github.com/tursodatabase/turso/blob/main/core/incremental/mod.rs"
click node_cdc "https://github.com/tursodatabase/turso/blob/main/core/cdc.rs"
click node_mvcc "https://github.com/tursodatabase/turso/blob/main/core/mvcc/mod.rs"
click node_storage "https://github.com/tursodatabase/turso/blob/main/core/storage/pager.rs"
click node_sync "https://github.com/tursodatabase/turso/blob/main/sync/engine/src/database_sync_engine.rs"
click node_extensions "https://github.com/tursodatabase/turso/tree/main/extensions"

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_bindings,node_capi,node_pg toneBlue
class node_core,node_dialect,node_translate,node_vdbe toneAmber
class node_mvcc,node_storage,node_sync toneMint
class node_functions,node_vectors,node_fts,node_incremental,node_cdc,node_extensions toneRose
class node_app,node_remote toneIndigo
```

## Components

### Client interfaces

- [Interactive CLI](https://github.com/tursodatabase/turso/blob/main/cli/app.rs): `cli/app.rs`
- [Language bindings](https://github.com/tursodatabase/turso/tree/main/bindings): `bindings`
- [C API](https://github.com/tursodatabase/turso/blob/main/bindings/c/src/lib.rs): `bindings/c/src/lib.rs`
- [Postgres frontend](https://github.com/tursodatabase/turso/tree/main/postgres): `postgres`

### SQL engine

- [Database connection](https://github.com/tursodatabase/turso/blob/main/core/connection.rs): `core/connection.rs`
- [SQL dialects](https://github.com/tursodatabase/turso/blob/main/core/dialect/mod.rs): `core/dialect/mod.rs`
- [Translate and plan](https://github.com/tursodatabase/turso/blob/main/core/translate/mod.rs): `core/translate/mod.rs`
- [VDBE execution](https://github.com/tursodatabase/turso/blob/main/core/vdbe/execute.rs): `core/vdbe/execute.rs`

### Storage and sync

- [MVCC concurrency](https://github.com/tursodatabase/turso/blob/main/core/mvcc/mod.rs): `core/mvcc/mod.rs`
- [Pager and storage](https://github.com/tursodatabase/turso/blob/main/core/storage/pager.rs): `core/storage/pager.rs`
- [Database sync](https://github.com/tursodatabase/turso/blob/main/sync/engine/src/database_sync_engine.rs): `sync/engine/src/database_sync_engine.rs`

### Database features

- [SQL functions](https://github.com/tursodatabase/turso/blob/main/core/functions/mod.rs): `core/functions/mod.rs`
- [Vector operations](https://github.com/tursodatabase/turso/blob/main/core/vector/mod.rs): `core/vector/mod.rs`
- [Full-text search](https://github.com/tursodatabase/turso/blob/main/core/index_method/fts/mod.rs): `core/index_method/fts/mod.rs`
- [Incremental views](https://github.com/tursodatabase/turso/blob/main/core/incremental/mod.rs): `core/incremental/mod.rs`
- [Change capture](https://github.com/tursodatabase/turso/blob/main/core/cdc.rs): `core/cdc.rs`
- [Extensions](https://github.com/tursodatabase/turso/tree/main/extensions): `extensions`

### Other components

- **Application**
- **Remote sync service**

## Connections

- Application → Language bindings: uses API
- Application → Interactive CLI: runs SQL
- Application → Postgres frontend: sends SQL
- Language bindings → Database connection: submits SQL
- C API → Database connection: calls database
- Interactive CLI → Database connection: queries
- Postgres frontend → Database connection: fronts database
- Database connection → SQL dialects: selects dialect
- Database connection → Translate and plan: translates SQL
- Translate and plan → VDBE execution: emits bytecode
- VDBE execution → Pager and storage: reads and writes
- VDBE execution → SQL functions: invokes functions
- VDBE execution → Vector operations: executes operations
- VDBE execution → Full-text search: queries indexes
- Database connection → MVCC concurrency: coordinates transactions
- MVCC concurrency → Pager and storage: persists changes
- Database connection → Change capture: tracks changes
- Incremental views → Pager and storage: persists state
- Extensions → Database connection: adds capabilities
- Database sync → Pager and storage: synchronizes pages
- Database sync → Remote sync service: exchanges changes