@mdxdb/sqlite

Cloudflare Durable Objects SQLite adapter for mdxdb.

Each namespace gets its own Durable Object with isolated SQLite storage. Uses Workers RPC for direct method calls on stubs.

Features

• Namespace isolation: Each namespace (e.g., example.com) gets its own Durable Object with SQLite storage
• Workers RPC: Call methods directly on Durable Object stubs - no fetch/JSON overhead
• Full graph support: Things (nodes), Relationships (edges), with bidirectional traversal
• Vector search ready: Chunked content with embeddings support (client-side embedding)
• Events & Actions: Immutable event log and durable action tracking
• Artifacts: Cached compiled content with TTL support
• Node.js support: Use miniflare for local development and testing

Installation

pnpm add @mdxdb/sqlite

Usage

Cloudflare Workers

import { createMDXClient, MDXDatabase, type Env } from '@mdxdb/sqlite'

// Export the Durable Object class for wrangler.toml
export { MDXDatabase }

export default {
  async fetch(request: Request, env: Env) {
    // Create client for a namespace
    const client = createMDXClient({
      namespace: 'example.com',
      binding: env.MDXDB,
    })

    // CRUD operations
    const post = await client.create({
      ns: 'example.com',
      type: 'Post',
      data: { title: 'Hello World', content: '...' },
    })

    const posts = await client.list({ type: 'Post' })

    // Relationships
    await client.relate({
      type: 'authored',
      from: 'https://example.com/User/alice',
      to: post.url,
    })

    return Response.json(posts)
  }
}

wrangler.toml

name = "my-worker"
compatibility_date = "2024-12-01"

[[durable_objects.bindings]]
name = "MDXDB"
class_name = "MDXDatabase"

[[migrations]]
tag = "v1"
new_sqlite_classes = ["MDXDatabase"]

Node.js with Miniflare

import { createMiniflareClient } from '@mdxdb/sqlite'

// Create client with miniflare backend
const client = await createMiniflareClient({
  namespace: 'example.com',
  persistPath: './.data', // Optional: persist to disk
})

await client.create({
  ns: 'example.com',
  type: 'Post',
  data: { title: 'Hello' },
})

In-Memory Testing

import { createInMemoryBinding, MDXClient } from '@mdxdb/sqlite'

const binding = createInMemoryBinding()
const id = binding.idFromName('test.local')
const stub = binding.get(id)
const client = new MDXClient(stub, 'test.local')

// Use in tests
const thing = await client.create({
  ns: 'test.local',
  type: 'Post',
  data: { title: 'Test' },
})

API

Thing Operations

// Create
const thing = await client.create({
  ns: 'example.com',
  type: 'Post',
  data: { title: 'Hello' },
})

// Read
const thing = await client.get('https://example.com/Post/123')
const thing = await client.getById('Post', '123')

// List
const posts = await client.list({ type: 'Post', limit: 10 })

// Update
await client.update(url, { data: { title: 'Updated' } })

// Upsert
await client.upsert({ ns, type, id, data })

// Delete
await client.delete(url)

// Search
const results = await client.search({ query: 'hello', type: 'Post' })

Relationship Operations

// Create relationship
await client.relate({
  type: 'follows',
  from: userUrl,
  to: otherUserUrl,
})

// Remove relationship
await client.unrelate(from, 'follows', to)

// Get related things
const following = await client.related(userUrl, 'follows', 'from')
const followers = await client.related(userUrl, 'follows', 'to')

// Get relationship objects
const rels = await client.relationships(url, 'follows')

Event Operations

// Track event
const event = await client.track({
  type: 'user.signup',
  source: 'auth',
  data: { userId: '123' },
  correlationId: 'req-456',
})

// Query events
const events = await client.queryEvents({
  type: 'user.signup',
  source: 'auth',
  after: new Date('2024-01-01'),
  limit: 100,
})

Action Operations

// Send action (pending)
const action = await client.send({
  actor: 'user:123',
  object: 'post:456',
  action: 'publish',
})

// Do action (immediately active)
const action = await client.do({
  actor: 'user:123',
  object: 'post:456',
  action: 'publish',
})

// Update action status
await client.startAction(id)
await client.completeAction(id, result)
await client.failAction(id, 'error message')
await client.cancelAction(id)

// Query actions
const pending = await client.queryActions({ status: 'pending' })

Artifact Operations

// Store artifact
const artifact = await client.storeArtifact({
  key: 'post:123:ast',
  type: 'ast',
  source: 'post:123',
  sourceHash: 'abc123',
  content: { type: 'root', children: [] },
  ttl: 3600000, // 1 hour
})

// Get artifact
const artifact = await client.getArtifact('post:123:ast')

// Delete
await client.deleteArtifact(key)

// Clean expired
const count = await client.cleanExpiredArtifacts()

Vector Search

Vector search requires a client-side embedding function:

const client = createMDXClient({
  namespace: 'example.com',
  binding: env.MDXDB,
  embedFn: async (text) => {
    // Call your embedding API (OpenAI, Cloudflare AI, etc.)
    return await embed(text)
  },
})

// Search will automatically embed the query
const results = await client.search({ query: 'machine learning' })

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Cloudflare Workers                       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────────┐    RPC    ┌─────────────────────────────┐  │
│  │  MDXClient  │ ───────▶ │  MDXDatabase (Durable Object) │  │
│  └─────────────┘           │  ┌─────────────────────────┐ │  │
│                            │  │   SQLite Storage        │ │  │
│                            │  │  ┌────────────────────┐ │ │  │
│                            │  │  │ things             │ │ │  │
│                            │  │  │ relationships      │ │ │  │
│                            │  │  │ search (chunks)    │ │ │  │
│                            │  │  │ events             │ │ │  │
│                            │  │  │ actions            │ │ │  │
│                            │  │  │ artifacts          │ │ │  │
│                            │  │  └────────────────────┘ │ │  │
│                            │  └─────────────────────────┘ │  │
│                            └─────────────────────────────┘  │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Each namespace (example.com, app.dev, etc.) maps to a unique Durable Object instance with its own SQLite database.

License

MIT