@quarry-systems/mcg-store-sqlite

SQLite run store adapter for MCG using Drizzle ORM.

Features

• Local-first: Perfect for development and testing
• Zero-ops: No database server required
• Fast: In-memory or file-based persistence
• Type-safe: Drizzle ORM with full TypeScript support
• Atomic operations: Event sequencing with DB-side increment

Installation

npm install @quarry-systems/mcg-store-sqlite

Usage

import { createSQLiteStore } from '@quarry-systems/mcg-store-sqlite';

// In-memory (for testing)
const store = createSQLiteStore({ filename: ':memory:' });

// File-based (for persistence)
const store = createSQLiteStore({ filename: './data/runs.db' });

// Create a run
const run = await store.createRun({
  graphId: 'my-graph',
  graphVersion: '1.0.0',
  initialContext: { input: 'test' },
  tags: ['test', 'demo']
});

// Append events
await store.appendEvent(run.id, {
  type: 'node_start',
  nodeId: 'node-1',
  timestamp: Date.now(),
  data: {}
});

// Get run with events
const runData = await store.getRun(run.id);
const events = await store.getEvents(run.id);

Integration with MCG

import { ManagedCyclicGraph } from '@quarry-systems/managed-cyclic-graph';
import { createSQLiteStore } from '@quarry-systems/mcg-store-sqlite';

// Create store adapter
const store = createSQLiteStore({ filename: './data/runs.db' });

// Build graph with store plugin
const graph = new ManagedCyclicGraph()
  .use({ services: { store } })
  .node('start', {
    type: 'action',
    action: async (ctx) => {
      console.log('Processing:', ctx.data.input);
      return { processed: true };
    }
  })
  .build();

// Run will be persisted automatically
const result = await graph.run({ input: 'test data' });

// Query runs later
const runs = await store.listRuns({
  graphId: graph.id,
  status: 'completed',
  limit: 10
});

// Get full run history
const run = await store.getRun(result.runId);
const events = await store.getEvents(result.runId);
console.log(`Run ${run.id} had ${events.length} events`);

API

Implements RunStoreAdapter from @quarry-systems/mcg-contracts:

• createRun(metadata) - Create a new run
• getRun(runId) - Get run by ID
• updateRunStatus(runId, status, options) - Update run status
• appendEvent(runId, event) - Append event with atomic sequencing
• getEvents(runId, fromSequence?) - Get events for a run
• saveSnapshot(runId, snapshot) - Save context snapshot
• getSnapshot(runId, version) - Get snapshot by version
• getLatestSnapshot(runId) - Get latest snapshot
• listRuns(filters) - List runs with filtering
• deleteRun(runId) - Delete run and cascade
• pruneOldRuns(olderThanMs) - Delete old completed runs

Configuration

interface SQLiteStoreConfig {
  /** Path to SQLite database file (use ':memory:' for in-memory) */
  filename: string;
  
  /** Enable WAL mode for better concurrency (default: true) */
  walMode?: boolean;
}

Testing

npm test

All tests run in-memory with no external dependencies.

License

MIT