AtmosDB — Supabase for the Edge

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.

Architecture Overview

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.

Core Services:

• 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.

⚠️ Current Limitations

Analytics Feature

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

Why AtmosDB

• 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.

Quickstart

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!')
})

Auto-Embed Magic

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'

Documentation

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

API Reference

• 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.

Cloudflare Setup

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-storage

Database Initialization

Before 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']);

Current State & Roadmap

• 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).

Author & Contact

Created by Pavan Yellathakota

• Email: [email protected]
• LinkedIn: https://www.linkedin.com/in/yellatp

License

Released under the Apache 2.0 License.