Ready browser client
src/application.tsconst db = await createThimbleClient();
const notes = db.collection(noteDefinition);One factory configures authority URLs, scope keys, memory cache, encrypted IndexedDB, and layout checks.
Cloudflare-first. Open source. Application-owned.
A small database for small web apps.
ThimbleDB keeps encrypted application data in object storage and a fast browser cache. It gives focused web apps a durable data layer without operating a separate database engine.
npx thimbledb@latest create my-app- Apache-2.0
- 18.7 KB gzip browser build
- 2-package base install
- Node.js 22+
Browser cache
Object storage
For experienced developers
Inspect the boundaries before adopting it.
The protocol, threat model, deletion semantics, benchmarks, and provider contracts are documented with their limitations.
Review the architecture →For AI-assisted builders
Start with a fit check and copyable prompts.
Use the workload checklist, guided examples, and implementation prompts before asking a coding tool to wire the database.
Run the fit guide →ThimbleDB Studio
Inspect scoped data without bypassing the authority.
Browse declared collections, run bounded queries, inspect plans and indexes, and use guarded maintenance tools through the same OIDC session and explicit scope grants as the application.
Small integration surface
Own the deployment. Keep application code direct.
The authority owns credentials, identity, keys, and conditional writes. Application code works with documents and collections.
Bounded indexed query
application.tsconst result = await notes
.where((note) => note.title.eq("First note"))
.orderBy((note) => note.lastModified.desc())
.take(25)
.select(["title", "lastModified"], noteCardSchema)
.get();Declared indexes narrow candidates. Explicit covering fields can satisfy a typed projection without loading complete documents.
Know the fit
Designed for bounded, read-heavy application data.
ThimbleDB serves a deliberate workload. The limits are part of the product, not fine print.
A reasonable candidate
- Records belong to one user, tenant, role, or public scope
- ID reads, declared indexes, or bounded scans cover the workflow
- Writes are modest compared with reads
- The hot working set fits in browser storage
- External OIDC already handles account security
Choose another database
- Multi-record transactions or relational joins are central
- Shared records receive high-frequency concurrent writes
- The application needs full-text, vector, or analytical queries
- Offline writes and automatic conflict resolution are required
- The dataset is not meaningfully bounded
How it works
Three boundaries, one application-owned data path.
The browser gets speed. The authority keeps control. Object storage provides durable encrypted bytes.
Browser
Memory and encrypted IndexedDB keep the active working set close to the user.
Authority
External identity, scope checks, key grants, validation, writes, deletion, and administration stay server-side.
Object storage
Canonical JSON becomes compressed AES-GCM envelopes stored in R2, S3, Azure Blob, or local files.
Cloudflare R2Amazon S3Azure Blob StorageLocal filesystem
Two deployment styles
Keep the authority in-app, or give it its own boundary.
The browser API and stored data stay the same. The choice controls secret isolation, release ownership, failure containment, and which traffic can scale independently.
In-app authority
One deploymentBrowser→App + authority→Storage
Lowest operating overhead. Application and authority share secrets, releases, failures, logs, limits, and scaling.
Separate authority
Independent runtimeBrowser→One origin
Separate secrets, releases, limits, logs, failures, regions, and scaling. Adds routing and another service to operate.
Start from evidence
Documentation for the decision, not just the installation.
Start here
Quickstart
Install ThimbleDB, choose an authority, connect external identity, and create the browser client.
Start hereLocal development
Scaffold a local app, use the safe development identity, and move to production OIDC.
Start hereConfiguration reference
Review authority options, environment variables, provider settings, defaults, and deployment-template coverage.
Start hereUse cases
Check whether a small web application fits ThimbleDB before choosing a storage model.
Start hereShould you use ThimbleDB for a vibe-coded app?
Use an exact fit check to decide whether a vibe-coded or AI-assisted small app matches ThimbleDB.
Start hereTradeoffs
Review verified behaviour, open questions, introduced costs, and workloads that need another database.
Start hereStarter examples
Use maintained Node and Cloudflare repository templates or run the checked-in package examples.
CompareDatabase comparisons
Compare ThimbleDB with D1, SQLite, Firestore, lowdb, and direct object storage by workload.
Published cloud evidence
Measure the workload, then choose the layout.
Across 3,808measured operations in 7 regions, snapshots had the lowest pooled cold point-read p95 at every tested size. Covering indexes stayed bounded, while broad trie scans and simultaneous global writes exposed clear limits.
Cold reads and large writes remain too slow for latency-sensitive request paths. Production fit depends on warm browser cache hits dominating. Tables, graphs, failures, JSON, and CSV are published.
Read the benchmark and limitations →25,000 documents, pooled p951.62 s
Direct answers
Questions to settle before implementation.
What is ThimbleDB?
ThimbleDB is an encrypted, browser first database for small web applications. Object storage is the durable source of truth. An application owned authority handles identity, access checks, key grants, writes, deletion, and administration. Browsers keep a fast encrypted cache in memory and IndexedDB.
What kind of application fits ThimbleDB?
The strongest fits have bounded JSON data, clear user or tenant ownership, more reads than writes, direct reads by ID, and occasional collection scans. Examples include personal workspaces, small internal tools, field guides, catalogues, journals, and bounded context for AI assisted applications.
When should I use another database?
Use another system when the application needs multi record ACID transactions, joins, high frequency shared writes, real time collaboration, full text search, vector search, large analytical queries, or unrestricted reporting across tenants.
Is ThimbleDB a replacement for PostgreSQL or SQLite?
No. ThimbleDB serves a narrower workload. It avoids a continuously running database engine by storing encrypted immutable objects and small mutable location records in object storage. Relational databases remain the better choice when relationships, transactions, and flexible queries are central to the application.
Does ThimbleDB require Cloudflare?
No. Cloudflare Workers and R2 are the reference deployment. The package also includes a Node authority with local filesystem, Azure Blob Storage, Amazon S3, and S3 compatible adapters. The stored protocol remains the same across providers.
Can the authority run in-app or as a separate Worker?
Both are supported. The authority can run in app inside the application deployment or as a separate Worker, container, function, or Node service. A separate process should normally remain behind the same public browser origin through path based routing so Strict cookies, CSRF, Studio, browser caches, and logout coordination retain the documented behaviour. Use an in app authority for the smallest operational surface. Use a separate authority when storage secret isolation, independent release control, failure isolation, regional placement, or independent scaling justifies another service. Separation creates a scaling boundary; it does not remove collection write contention. See In app and separate authority deployment.
Evaluate it against your workload
Start local. Keep the exit criteria visible.
Run the sample application, review the tradeoffs, and compare the result with a managed database before choosing a production data layer.