State & Storage

Key-value store, collections, and append-only streams.

Beyond your application database, Chimpbase provides built-in storage primitives for operational state.

Key-Value Store

Simple key-value storage for configuration, flags, and lightweight state:

// Set a value
await ctx.kv.set("config:feature-flags", { darkMode: true });

// Get a value
const flags = await ctx.kv.get("config:feature-flags");

// Delete a key
await ctx.kv.delete("config:feature-flags");

// List keys by prefix
const keys = await ctx.kv.list("config:");

Stored in the _chimpbase_kv table.

Collections

Schemaless JSON document storage for data that doesn't need a rigid schema:

// Insert a document
await ctx.collection.insert("notes", {
  title: "Meeting notes",
  content: "...",
});

// Find documents
const notes = await ctx.collection.find("notes", {
  filter: { title: "Meeting notes" },
});

// Find one
const note = await ctx.collection.findOne("notes", { id: noteId });

// Update
await ctx.collection.update("notes", noteId, { content: "updated" });

// Delete
await ctx.collection.delete("notes", noteId);

Stored in the _chimpbase_collections table.

Streams

Append-only event streams for audit logs, activity feeds, and event sourcing patterns:

// Append an event
await ctx.stream.append("audit.todos", "todo.created", {
  todoId: todo.id,
  createdBy: input.userId,
});

// Read events from a stream
const events = await ctx.stream.read("audit.todos");

Stored in the _chimpbase_stream_events table.

Storage Engines

Chimpbase supports three storage engines. PostgreSQL is the recommended default for production.

PostgreSQL (Recommended)

Full distributed coordination. Use PostgreSQL when:

  • Multiple runtime instances need to coordinate
  • You need durable queues, workflows, and cron across processes
  • You want application data and operational state in the same database
const chimpbase = await createChimpbase({
  storage: { engine: "postgres", url: process.env.DATABASE_URL! },
});

SQLite

Single-process coordination. Good for:

  • Local development
  • Tests
  • Isolated single-runtime deployments
const chimpbase = await createChimpbase({
  storage: { engine: "sqlite", path: "./dev.db" },
});

SQLite is available across Bun, Deno, and Node hosts.

In-Memory

Ephemeral storage for tests:

const chimpbase = await createChimpbase({
  storage: { engine: "memory" },
});

All state is lost when the process exits.

Internal Tables

Chimpbase manages its own tables, prefixed with _chimpbase_:

TablePurpose
_chimpbase_eventsPub/sub event bus
_chimpbase_kvKey-value store
_chimpbase_collectionsJSON document storage
_chimpbase_stream_eventsAppend-only event streams
_chimpbase_cron_schedulesDurable cron metadata
_chimpbase_workflowsWorkflow state
_chimpbase_queue_jobsJob queue with retry tracking
_chimpbase_logsPersisted log entries
_chimpbase_metricsPersisted metrics
_chimpbase_tracesPersisted trace spans

These tables are created and migrated automatically. Your application tables live alongside them in the same database.

Schema Management

Use the CLI to generate and check schema migrations:

# Generate migration SQL for internal tables
bun run chimpbase.app.ts schema generate

# Check if the current schema matches expected state
bun run chimpbase.app.ts schema check
Database
Raw SQL and typed Kysely access through the context.
Telemetry
Structured logging, metrics, and traces with optional persistence.