CapsuleDB documentation
How CapsuleDB splits database work between a package that owns private tables and the host app that owns the client, with a guide for each side.
CapsuleDB is an Effect library for packages that need their own database tables. A package declares a capsule: its tables, an append-only migration history, and an Effect service. A host application composes the capsules it trusts over the SQL client it already owns, and CapsuleDB applies each capsule’s migrations before its service is available.
Two parties share the work, and each has a guide:
| Role | Owns | Guide |
|---|---|---|
| Package author | the capsule ID, its tables and migrations, its service and errors | Capsule authors |
| Host application | the database client and its lifetime, which capsules to trust, when to prepare, destructive authorization | Host applications |
New here? The quick start builds one capsule and runs it end to end.
Supported databases
CapsuleDB renders one table declaration for PostgreSQL and for SQLite through Bun SQLite, libSQL and Cloudflare D1. Each runs under a provider profile with its own execution model; D1 runs bounded atomic batches instead of transactions. The providers guide has the matrix.
Entry points
| Import | Contents |
|---|---|
capsuledb |
every module below as a namespace (Capsule, Registry, Pg, …) |
capsuledb/<Module> |
one module: Capsule, D1, D1Artifact, Dialect, Emit, Error, Libsql, Manifest, Migration, Pg, Provider, Readiness, Registry, Schema, SqliteBun, Testing |
capsuledb/alchemy |
the Registry Alchemy resource and providers(); needs the optional peers alchemy and @effect/sql-pg |
What CapsuleDB does not do
CapsuleDB is not an ORM, a deployment service, or a second connection lifecycle, and it does not sandbox trusted capsule SQL. Design principles explains each boundary, and Migrations and recovery covers what happens when preparation cannot proceed.
Project
Releases are listed in the changelog. Maintainers cut them with Tegami; the release runbook describes the gates.