Storage: s3:// (S3 / MinIO)
The disaggregated backend (ObjectStorage) on AWS S3 or any S3-compatible store such as MinIO. Durability bottoms out on object storage; compute becomes stateless and scale-to-zero capable — while your engine, SQL, and API stay identical to file://. See the shared model in the overview.
How it works
Object stores can't do in-place edits or fsync, so this backend is built differently underneath — but the seam above it is unchanged:
- LSM page store — writes accumulate in immutable layers (delta/image) that merge over time.
- CAS commit log — a commit is an atomic compare-and-swap conditional write, which provides ordered durability and single-writer fencing without any separate coordination service.
- Local cache — hot pages stay in-process, keeping object-storage latency off the read hot path.
Open it
import { open } from "@twilldb/bun";
using db = open("s3://my-bucket/mydb");cargo run -p twill-server -- --listen 0.0.0.0:5433 --db s3://my-bucket/mydbBreakdown: s3://<bucket>/<db-prefix> names the bucket and a key prefix for this database. The same URL works for the embedded handle and the server — only the scheme distinguishes backends.
Credentials & configuration
Provide standard AWS credentials via the environment — never in the URL or the repo.
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_REGION=us-east-1
# Temporary credentials also honoured:
# export AWS_SESSION_TOKEN=...MinIO / S3-compatible endpoints
For a non-AWS S3-compatible store (MinIO, Ceph, etc.), point the client at the custom endpoint via your deployment configuration and use path-style addressing as that store requires. Credentials use the same AWS_* variables.
Secrets stay in the environment
Keep bucket credentials in environment configuration, never in connection strings, code, tests, or commits. The secret-scanning hook treats a hit as a stop.
What you gain
- Scale-to-zero — stateless compute can stop when idle (only bytes bill at rest); the next request warms by replaying the WAL. See Scale-to-zero & lifecycle.
- Durable single-writer lease — a monotonic CAS epoch fences stale writers (the split-brain guard), so multiple instances can be pointed at one database safely.
- Branching that copies nothing — a branch is a child key-prefix overlay over shared immutable layers. See Branching.
Cost note
On a disaggregated engine a cache miss reads out of object storage, billed as egress on S3. A cold cache therefore costs more here than on a zero-egress provider — if your workload is read-heavy or frequently cold-started, compare with r2:// (zero egress).