AtmosDB is a unified SDK-driven backend framework designed exclusively for Cloudflare Workers. It abstracts Cloudflare D1 (SQL), Vectorize (semantic search), and R2 (storage) into a single, developer-friendly interface, bringing the "Supabase" experience strictly to the Edge.
AtmosDB follows a clean layered architecture that unifies Cloudflare's edge services (D1, Vectorize, R2, Workers AI) into a single TypeScript SDK. See detailed architecture documentation for complete diagrams and data flow patterns.
- D1 (Relational Store): Handled by
AtmosDB. Provides blazing-fast edge CRUD operations without leaving the worker environment. - Vectorize (Semantic Store): Handled by
AtmosVector. Seamlessly linked with D1 data for semantic lookups. - Workers AI (Auto-Embed): Handled by
AtmosEmbedder. Automatically parses row inputs into searchable vectors. - R2 (Storage): Handled by
AtmosStorage. Serves as reliable edge file storage.
The analytics functionality (DuckDB integration) is not available in Cloudflare Workers due to Web Worker API restrictions. The analytics example endpoints return appropriate error messages. For analytics capabilities, consider using:
- Separate Node.js services
- Serverless functions on other platforms
- Client-side analytics with DuckDB WASM
- Zero Egress: Run everything on Cloudflare's edge, eliminating costly cross-region or cross-cloud data transfers.
- Edge-Native: Purpose-built for Cloudflare Workers. It brings D1, R2, Vectorize and Workers AI under one roof.
- AI-Native Space: Auto-embedding support out of the box, allowing simple
.search()calls over unstructured string data.
import { Atmos } from 'atmos-sdk'
import { Hono } from 'hono'
// Inject the bindings
const app = new Hono<{ Bindings: { DB: any, VECTORIZE: any, AI: any, BUCKET: any } }>()
app.post('/seed', async (c) => {
const db = new Atmos({
bindings: c.env,
ctx: c.executionCtx, // <--- ZERO LATENCY background embeddings!
options: { autoEmbed: true }
})
await db.set('users', { name: 'PYE', bio: 'Building things.' })
return c.text('Seeded!')
})With autoEmbed: true, Atmos seamlessly extracts your string fields, asks Workers AI for embeddings, saves vectors, and manages your structured data.
const semanticMatches = await db.search('users', 'people who construct objects')
// Returns 'Aarav'Explore the comprehensive documentation for each module:
- Getting Started
- Architecture Overview
- Architecture FAQ & Scaling
- Database Operations (D1)
- Semantic Search (Vectorize)
- Storage (R2)
- Authentication & Security
- Middleware & Rate Limiting
- Error Handling
-
atmos.set(table, data): Insert to D1 (+ Vectorize if autoEmbed=true). -
atmos.get(table, id): Retrieve from D1. -
atmos.search(table, query): Embed query, search semantic matches, pull raw D1 records. -
atmos.remove(table, id): Purge from both DB and Vectors. -
atmos.store: Proxy for R2 storage APIs. -
atmos.auth: JWT validation logic.
To start properly you need these configured locally and on CF dashboard:
wrangler d1 create atmos-local
wrangler vectorize create atmos-vectors --dimensions=768 --metric=cosine
wrangler r2 bucket create atmos-storageBefore using atmos.set(), you must initialize your tables. AtmosDB provides a simple migration helper:
const atmos = new Atmos({ bindings: env });
const migrations = new AtmosMigrations(atmos.db);
await migrations.up(['users', 'posts', 'products']);- v0.1.0: Unified CRUD, Auto-Embeddings, Semantic Search, KV-based Rate Limiting, JWT & CF Access Auth.
- v0.2 (Roadmap): CLI tool (
atmos init,atmos deploy), built-in Schema validation (Zod). - Future Ideas: Edge Analytics (Serverless DuckDB/Parquet integration, currently unsupported due to Workers API limitations).
Created by Pavan Yellathakota
- Email: pavan.yellathakota.ds@gmail.com
- LinkedIn: https://www.linkedin.com/in/yellatp
- Portfolio: https://pye.pages.dev
Released under the Apache 2.0 License.