glm-5.1
6aa2fcc6ff
Reorient @alkdev/storage around a single SQLite database host with Honker
for pub/sub, event streams, and task queues. PostgreSQL is removed as a
target (ADR-038), eliminating dual schema maintenance and infrastructure
complexity. Honker provides DB + pubsub + queues in one .db file (ADR-039).
Add system/tenant DB model (ADR-040): identity tables in system.db, all
graph data in tenant-{orgId}.db files. Identity tables move from the hub
into storage (ADR-041). Scoping columns (ownerId, projectId) added to
graphs table (ADR-042). Graph types get scope (system/tenant/user) to
protect infrastructure schemas (ADR-043).
Define Drizzle-Honker session adapter (ADR-044): ~100-line adapter enabling
Drizzle typed queries and Honker pubsub/queue on a single connection with
transactional consistency.
Resolve OQ-03, OQ-04, OQ-19, OQ-21, OQ-22, OQ-23, OQ-24. Add new
open questions OQ-26 through OQ-29 for Honker integration specifics.
New docs: honker-integration.md (adapter, event patterns, migration).
Scrub all PG/jsonb/libsql references from existing spec docs.
76 lines
3.7 KiB
Markdown
76 lines
3.7 KiB
Markdown
# 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**:
|
|
|
|
```typescript
|
|
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) |