Documentation
Everything you need to use Twill DB — open a database with a connection string, embed it in your app or run it as a Postgres-wire server, branch your data copy-on-write, and let it scale to zero. New here? Start with the Quickstart.
How Twill DB is delivered
There is one engine and you reach it through one of two front doors. The backend it durably writes to is chosen by the connection string, not by a rebuild.
| You want… | Use | Backend by URL |
|---|---|---|
| In-process, function-call latency (one app) | Embedded via bun:ffi / the C ABI | file:// (local) or s3:// (disaggregated) |
| Multi-client access / existing Postgres tools | Server via the Postgres wire protocol | file:// or s3:///r2:///gs:// |
The one thing to remember
The storage backend is selected purely by the URL scheme passed at open time. file:// is pure-embedded with zero network; s3:// / r2:// / gs:// is storage-disaggregated and scale-to-zero. The engine, the C ABI, and your SQL are identical either way.
Browse the docs
Quickstart
Build the library, open your first embedded database, run SQL, and start a server — in a few minutes.
Connect to your database
The connection model: URL schemes, embedded vs server, and how to choose a backend.
Connect from Bun
Use the @twilldb/bun wrapper over bun:ffi — open, query, parameter-bind, transact, and branch.
Connect with a Postgres client
Point psql, Bun.sql, drivers, or PostgREST at the engine-server over the wire protocol.
Connection pooling
Absorb serverless connection bursts with PgBouncer / pgcat in transaction mode.
Branching
Fork a database in O(1) as a copy-on-write branch; writes diverge in isolation from the base.
Scale-to-zero & lifecycle
Cold-start on first connection, idle teardown, lease heartbeat, and keep-warm — how compute idles to nothing.
SQL reference
The supported SQL surface: DDL, DML, queries, transactions, types, and parameters.
C ABI reference
The frozen embedding contract every runtime binds to — open, exec, query, prepare, transactions.
Looking for design intent?
This section is the user documentation. If you want to understand how and why the engine is built the way it is — the storage seam, MVCC, the S3-CAS commit log, the lifecycle controller — read the Development Guidelines (the fourteen design specifications and implementation maps). To see what has shipped and what is next, see Releases & Roadmap.