storage/docs/architecture/decisions/044-drizzle-honker-adapter.md

ADR-044: Drizzle-Honker Session Adapter

Status

Accepted

Context

Drizzle ORM provides typed query builders for SQLite via driver packages (drizzle-orm/better-sqlite3, drizzle-orm/libsql). Honker provides SQLite with pubsub/queue extensions but is not a Drizzle driver.

Running both simultaneously against the same .db file would require two separate connections, losing the transactional consistency that Honker provides (data writes + event notifications in one transaction).

Decision

Implement a thin session adapter (~100 lines) that wraps Honker's Node.js Database.query()/Transaction.execute() API inside Drizzle's SQLiteSession<'sync'> contract. No Drizzle fork required.

The adapter implements:

• HonkerSQLiteSession — extends SQLiteSession<'sync', HonkerRunResult, ...>. Implements prepareQuery() and transaction().
• HonkerPreparedQuery — extends SQLitePreparedQuery. Implements run(), all(), get(), values().
• HonkerSQLiteTransaction — extends SQLiteTransaction<'sync', ...>. Provides $honkerTx for access to Honker's transaction methods.
• drizzle(client, config) — factory function that creates a Drizzle database instance from a Honker Database.

Key integration points:

• prepareQuery() delegates to honkerDb.query(sql, params) for reads and tx.execute(sql, params) for writes
• transaction() wraps honker's explicit begin/commit/rollback in Drizzle's callback pattern
• $client on the database instance exposes the Honker Database for notify(), queue(), stream(), listen(), scheduler()
• $honkerTx on the transaction object exposes the Honker Transaction for notify() and enqueueTx() within a Drizzle transaction callback
• run() returns { changes, lastInsertRowid } where lastInsertRowid is obtained via SELECT last_insert_rowid() (pending a small Rust addition to honker-node for zero-overhead access)

Usage:

import { open } from '@russellthehippo/honker-node';
import { drizzle } from '@alkdev/storage/sqlite/honker-adapter';
import * as schema from './schema';

const honkerDb = open('app.db');
const db = drizzle(honkerDb, { schema });

// Drizzle typed queries
const activeGraphs = db.select().from(schema.graphs)
  .where(eq(schema.graphs.status, 'active'));

// Honker + Drizzle in one transaction
db.transaction((tx) => {
  tx.insert(schema.nodes).values({ graphId, key: 'call-1', attributes: {} }).run();
  tx.$honkerTx.notify('graph:updated', { graphId });
});

Consequences

Positive:

• Single connection — Drizzle queries and Honker pubsub/queue share the same SQLite file and transaction context
• No Drizzle fork — the adapter is consumer-side code (~100 lines)
• Full Drizzle type safety for all queries
• Full Honker feature access via $client and $honkerTx
• Transactional consistency: data writes and event notifications commit atomically
• The adapter could be open-sourced independently as drizzle-honker for community use

Negative:

• lastInsertRowid requires an extra query until honker-node adds a native method
• No prepared statement handle reuse at the JS level (mitigated by Rust-side prepare_cached)
• The adapter depends on Drizzle's internal SQLite session API path (drizzle-orm/sqlite-core/session) — if Drizzle restructures, the adapter needs updating
• Object-to-array conversion for Drizzle's values() method relies on JS object property insertion order, which matches SQLite column order but is a subtle dependency

References

• Honker Node binding: /workspace/honker/packages/honker-node/
• Drizzle SQLite session: /workspace/drizzle-orm/src/sqlite-core/session.ts
• ADR-039: Honker as SQLite extension
• ADR-004: Injectable clients (adapter pattern is consistent)