> ## Documentation Index
> Fetch the complete documentation index at: https://boutiquedb.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Engine Architecture

> How the embedded Turso engine, Swift bindings, and database actor fit together.

# Engine architecture

The BoutiqueDB engine is a Rust rewrite of SQLite. It keeps the SQLite file format and SQL dialect but replaces the query execution, storage, and I/O layers with Rust code.

## High-level components

| Component | Location in engine repo | Responsibility |
| - | - | - |
| SQL parser | `sqlite/parser/src/parser.rs` | Recursive-descent parser, lexer, AST |
| Query compiler / optimizer | `core/translate/` and `core/translate/optimizer/` | AST → VDBE bytecode, query plans |
| Virtual machine | `core/vdbe/execute.rs` | Bytecode interpreter |
| B-tree / pages | `core/storage/btree.rs` | SQLite-compatible page format |
| WAL / durability | `core/storage/wal.rs` | Write-ahead log, checkpointing |
| Async I/O | `core/io/` | `io_uring`, syscall, Windows IOCP backends |
| MVCC | `core/mvcc/` and `docs/internals/mvcc/` | Multi-version concurrency control |

## Compilation pipeline

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
SQL → Parser → AST → Translator/Optimizer → VDBE bytecode → Execute
```

The VDBE (Virtual Database Engine) is a register-based virtual machine similar to SQLite’s. Its bytecode is general enough to host multiple frontends; SQLite is the primary frontend, and Postgres is an experimental frontend.

## I/O model

The engine supports pluggable I/O backends:

* `syscall` — generic blocking file I/O.
* `io_uring` — Linux kernel-queued async I/O.
* `experimental_win_iocp` — Windows I/O completion ports.

With `async_io` enabled, the engine returns `TURSO_IO` from `step()` and expects the caller to drive `run_io()` until the operation completes.

## Storage compatibility

* Page size defaults to 4096 bytes.
* The on-disk format is SQLite-compatible for standard tables and indexes.
* Turso-only features (custom index methods, generated columns, materialized views, custom types) may write extra state that SQLite does not understand.

For more detail, see the engine repo’s `docs/agent-guides/` and `docs/internals/mvcc/`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.