ThimbleDBv2.1.0
Search/
Browse documentation

Start here

QuickstartLocal developmentShould you use ThimbleDB?Use casesTradeoffsImplementation promptsStarter examples

Use cases

Per-user workspace and draftsMulti-tenant operations portalField guide and inspectionsCatalogue or reference libraryProgress or activity journalStructured AI application context

Compare

Database comparisonsThimbleDB and Cloudflare D1ThimbleDB and SQLiteThimbleDB and FirestoreThimbleDB and lowdbThimbleDB and direct object storage

Understand

ArchitectureSystem diagramsStorage providersAuthentication and identityMachine and service accessSecurity modelObject protocolAdaptive collection layoutsQueries and secondary indexesDeletion and retention

Deploy and operate

Deploy to CloudflareDeploy to AzureDeploy to AWSOperationsLogical migration

Reference

Public package APIVersioning and compatibilityEvaluation harnessR2 browser benchmarksChangelog

Start here

Tradeoffs

Verified behaviour

  • Browsers can read immutable object pages through the authority broker.
  • Memory and IndexedDB materially reduce repeated network reads.
  • ETag revalidation avoids downloading unchanged HEAD objects.
  • A server write can return enough changed pages to update browser caches.
  • Gzip before AES-GCM round-trips in Node and browser-compatible Web Crypto.
  • Private object bodies do not contain plaintext JSON.
  • Persistent browser cache entries can be encrypted with a non-extractable device key.
  • The same envelope, trie, and snapshot code bundles for Node and Cloudflare Workers.
  • Real R2 conditional writes, external sessions, retained deletion, and snapshot migration work on the tested Cloudflare reference deployment.

Not established by the published evidence

  • Lower total cost than a managed database for real user workloads.
  • Better end-user latency than D1, Durable Objects, Turso, or Firestore.
  • Sufficient operational simplicity for non-specialist developers.
  • Safe key rotation at useful scale.
  • Reliable production behaviour under multi-region write contention.
  • A meaningful reduction in coding-agent database mistakes.

Costs introduced by this design

  • Application code must understand eventual cache freshness.
  • Key grants and revocation become part of application security.
  • A collection root is a write-contention point.
  • Identity-provider availability affects new session creation.
  • Garbage collection and lifecycle policy are required.
  • Browser storage quotas and eviction differ by browser.
  • Encrypted object access still exposes ciphertext sizes and traffic patterns to the authority and storage provider.
  • Search, joins, and aggregate views require derived systems.

When to use ThimbleDB

Good candidates:

  • mostly idle web applications
  • per-user or per-tenant datasets
  • catalogues and configuration
  • internal tools
  • offline-tolerant, read-heavy applications with keyed updates
  • applications whose hot working set fits in browser storage

Poor candidates:

  • financial ledgers
  • high-frequency shared counters
  • large cross-tenant queries
  • complex relational transactions
  • workloads with strict immediate revocation
  • applications unable to defend their browser origin against XSS

Use ThimbleDB for small, mostly idle, read-heavy applications that benefit from encrypted browser caching and per-user or per-tenant storage scopes. Do not treat it as a general database replacement. Compare it with a managed database using the application’s real workload before choosing a production data layer.

This page is built from the repository source.

View or improve this page on GitHub

Continue reading

QuickstartInstall ThimbleDB, choose an authority, connect external identity, and create the browser client.Local developmentScaffold a local app, use the safe development identity, and move to production OIDC.Should you use ThimbleDB?Use an exact fit check to decide whether a vibe-coded or AI-assisted small app matches ThimbleDB.