AI-powered database operations with CapnWeb RPC transport for db4
npm install db4ai


The all-in-one client SDK for db4 - a globally distributed database built on Cloudflare's edge infrastructure.
db4ai is the all-in-one client SDK for interacting with db4, a globally distributed document database built on Cloudflare's edge infrastructure. It provides:
- Schema definition with DB() from IceType
- Type-safe queries with full TypeScript inference
- Real-time subscriptions via WebSocket
- Automatic connection pooling and retry logic
- Zero-configuration deployment when used with Cloudflare Workers service bindings
- Works in Cloudflare Workers, Node.js, and browsers
- Type-safe queries powered by IceType schemas
- Real-time subscriptions with WebSocket support
- Automatic connection pooling and retry logic
- Zero-config in Workers with service bindings
``bash`
npm install db4ai
Define your schema using IceType and create a typed client:
`typescript
import { DB, createClient } from 'db4ai'
// Define your schema using IceType
const schema = DB({
User: {
id: 'cuid!',
email: 'string! #unique',
name: 'string?',
posts: '[Post] -> author',
},
Post: {
id: 'cuid!',
title: 'string!',
content: 'text',
author: 'User! <- posts',
},
})
// Create a client from the schema
const db = createClient({ schema })
// Full type inference - no codegen needed
const user = await db.users.create({ email: 'alice@example.com', name: 'Alice' })
const posts = await db.posts.find({ where: { 'author.id': user.id } })
`
For when you have types defined separately:
`typescript
import { db4 } from 'db4ai'
import type { Schema } from './schema'
// Initialize the client
const db = db4
endpoint: 'https://your-db4.workers.dev',
apiKey: process.env.DB4_API_KEY
})
// Create a document
const user = await db.users.create({
name: 'Alice',
email: 'alice@example.com'
})
// Query with type safety
const admins = await db.users.find({
where: { role: 'admin' },
orderBy: { createdAt: 'desc' },
limit: 10
})
// Real-time subscriptions
const unsubscribe = db.users.subscribe(
{ where: { role: 'admin' } },
(users) => console.log('Admins updated:', users)
)
`
When running inside a Cloudflare Worker, use the service binding for zero-latency access:
`typescript
import { db4 } from 'db4ai'
import type { Schema } from './schema'
export default {
async fetch(request: Request, env: Env) {
const db = db4
const users = await db.users.find()
return Response.json(users)
}
}
`
Main client SDK for db4 databases:
`typescript
function db4
interface DB4Client
[K in keyof Schema]: Collection
}
`
`typescript
// Remote endpoint
const db = db4
// Service binding (Workers only)
const db = db4
// With options
const db = db4
endpoint,
apiKey,
timeout: 30000,
retries: 3,
cache: 'default'
})
`
`typescript
// Create
await db.collection.create(document)
await db.collection.createMany(documents)
// Read
await db.collection.get(id)
await db.collection.find(query)
await db.collection.findOne(query)
await db.collection.count(query)
// Update
await db.collection.update(id, changes)
await db.collection.updateMany(query, changes)
await db.collection.upsert(query, document)
// Delete
await db.collection.delete(id)
await db.collection.deleteMany(query)
`
`typescript`
const results = await db.users.find({
where: {
age: { $gte: 18 },
status: 'active'
},
select: ['id', 'name', 'email'],
include: {
posts: { limit: 5 }
},
orderBy: { createdAt: 'desc' },
limit: 100,
offset: 0
})
`typescript`
const result = await db.transaction(async (tx) => {
const user = await tx.users.create({ name: 'Bob' })
await tx.accounts.create({ userId: user.id, balance: 0 })
return user
})
`typescript
// Subscribe to query results
const unsubscribe = db.users.subscribe(query, callback)
// Subscribe to a single document
const unsubscribe = db.users.subscribeOne(id, callback)
// Cleanup
unsubscribe()
`
db4ai provides full TypeScript inference from your IceType schema:
`typescript
import { DB, createClient } from 'db4ai'
// Schema definition using DB()
const schema = DB({
User: {
id: 'cuid!',
name: 'string!',
email: 'string! #unique',
age: 'int?',
posts: '[Post] -> author',
},
Post: {
id: 'cuid!',
title: 'string!',
content: 'text!',
author: 'User! <- posts',
},
})
const db = createClient({ schema })
// Full type inference - no codegen needed
type User = typeof db.types.User
// {
// id: string
// name: string
// email: string
// age?: number
// posts?: Post[]
// }
``
For complete documentation, visit db4.dev/docs
- @db4/worker - Cloudflare Worker runtime
- @db4/schema - IceType schema compiler
- @db4/do - Durable Object implementation
- @db4/query - Query planning and execution
- @db4/storage - Three-tier storage abstraction
- @db4/ai - AI-powered field generation and embeddings
- @db4/client - Lower-level client SDK
MIT