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
Architecture
The mental model: one engine, one storage seam, two front doors. Read this first.
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 as embedded
Framework examples — Next.js, Hono, Elysia, and plain Bun — over @twilldb/bun.
Connect as server
Postgres-wire clients per language (Node/Bun, Python, Go) and ORMs (Drizzle, Prisma).
Storage backends
file:// local, and s3:// / r2:// / gs:// disaggregated — chosen by the URL.
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 — the design specifications are indexed with their status on the Release page. To see what shipped in each version, see the Changelog.
Project status & license
Twill DB is an experimental, maintainer-led project. The source is public to read, evaluate, and self-host, and issues and feedback are welcome — but it is not accepting external pull requests at this stage (they may be closed without review).
Licensed under BUSL-1.1 (source-available)
Twill DB ships under the Business Source License 1.1 — a source-available, not open source, license. You may read, modify, and self-host it, including in production as the database behind your own applications. You may not offer Twill DB to third parties as a hosted or managed database service. Each released version converts to the Apache License 2.0 on its Change Date (four years after release). See CONTRIBUTING and GOVERNANCE for the contribution policy.