ADR-003: rusqlite 0.39 com feature bundled

Date: 2026-05-24 Status: Accepted Author: Rômulo Febasi

Context

Synapse usa SQLite como índice (FTS5 obrigatório; possivelmente sqlite-vec em fase 2). Em Rust as opções viáveis para acesso a SQLite são rusqlite (síncrono), sqlx (async), libsql (fork da Turso).

Synapse roda como processo único, local, sem concorrência alta. A maioria das chamadas é leitura ad-hoc; escritas são raras e curtas.

Decision

rusqlite = "0.39" com features:

features = ["bundled", "modern_sqlite", "blob", "backup",
            "functions", "load_extension"]

• bundled compila libsqlite junto: elimina dependência da versão de SQLite no host (importante: macOS 14 ainda manda SQLite 3.43, antigo para nossas necessidades de FTS5/vec).
• load_extension necessário para futuro sqlite-vec (fase 2).

Em chamadas vindas do MCP (que roda em tokio), envolver com tokio::task::spawn_blocking.

Consequences

• + mesmo binário, mesmo SQLite, em macOS/Linux/Windows.
• + FTS5 sempre disponível.
• + API síncrona simples mapeia bem para um processo single-user.
• + binário ~2 MB maior; aceitável.
• − tokio precisa de wrapper spawn_blocking nas bordas async.

Alternatives considered

• sqlx: overkill: toda sua complexidade (query macros, pool, compile-time check) endereça problemas de server multi-conexão que Synapse não tem.
• libsql: pertinente só se quiséssemos replicação Turso, o que não é o caso. Comunidade menor, menos extensões funcionam.
• rusqlite sem bundled: causa “funciona-na-minha-máquina” clássico: versão da libsqlite varia por SO.