108 lines
2.7 KiB
Markdown
108 lines
2.7 KiB
Markdown
# ADR-001: SQLite Library Choice
|
|
|
|
**Date:** 2026-03-23
|
|
**Status:** Accepted
|
|
**Decision:** Use `sql.js` instead of `better-sqlite3`
|
|
|
|
---
|
|
|
|
## Context
|
|
|
|
During MVP development (iteration 3), `better-sqlite3` failed to build on WSL2 with Node.js v22.22.0:
|
|
|
|
```
|
|
error: 'class v8::ObjectTemplate' has no member named 'SetAccessor'
|
|
gyp ERR! build error
|
|
```
|
|
|
|
**Root cause:** `better-sqlite3` native bindings are not compatible with Node.js v22's V8 API changes.
|
|
|
|
**Options considered:**
|
|
|
|
1. **Downgrade Node.js** to v20 LTS
|
|
- ❌ Impacts other workspace projects
|
|
- ❌ Not sustainable long-term
|
|
|
|
2. **Wait for better-sqlite3 update**
|
|
- ❌ Blocks autonomous development
|
|
- ❌ Timeline uncertain
|
|
|
|
3. **Switch to sql.js** (pure JavaScript SQLite)
|
|
- ✅ Zero native dependencies
|
|
- ✅ Works everywhere (WSL2, Docker, browser)
|
|
- ✅ Synchronous API available
|
|
- ⚠️ Slightly slower than native (acceptable for single-household use)
|
|
|
|
4. **Switch to node-sqlite3** (callback-based)
|
|
- ⚠️ Async API violates ARCHITECTURE.md sync preference
|
|
- ⚠️ May have similar v22 compatibility issues
|
|
|
|
---
|
|
|
|
## Decision
|
|
|
|
Use **sql.js** (https://github.com/sql-js/sql.js) for MVP and beyond.
|
|
|
|
**Rationale:**
|
|
- Enables autonomous overnight agent work (no environment blockers)
|
|
- Synchronous API matches original architecture vision
|
|
- Pure JavaScript = portable across all environments
|
|
- Performance difference negligible for ~1000 recipes
|
|
- Can persist to filesystem same as better-sqlite3
|
|
|
|
---
|
|
|
|
## Implementation Notes
|
|
|
|
**Package:** `sql.js` (npm install sql.js)
|
|
|
|
**Usage pattern:**
|
|
```typescript
|
|
import initSqlJs from 'sql.js';
|
|
|
|
const SQL = await initSqlJs();
|
|
const db = new SQL.Database();
|
|
// ... same SQL queries as before
|
|
```
|
|
|
|
**Persistence:**
|
|
```typescript
|
|
// Save to file
|
|
const data = db.export();
|
|
fs.writeFileSync('data/recipes.db', Buffer.from(data));
|
|
|
|
// Load from file
|
|
const buffer = fs.readFileSync('data/recipes.db');
|
|
db = new SQL.Database(buffer);
|
|
```
|
|
|
|
**Migration path:**
|
|
- If future performance issues arise, can revisit when better-sqlite3 supports Node v22+
|
|
- Database file format is standard SQLite (portable)
|
|
|
|
---
|
|
|
|
## Consequences
|
|
|
|
**Positive:**
|
|
- ✅ Unblocked autonomous development
|
|
- ✅ Zero native build dependencies
|
|
- ✅ Easier Docker deployment
|
|
- ✅ Works in browser (future PWA feature)
|
|
|
|
**Negative:**
|
|
- ⚠️ ~10-20% slower than native bindings (negligible for our use case)
|
|
- ⚠️ Requires explicit save() calls (better-sqlite3 auto-persists)
|
|
|
|
**Neutral:**
|
|
- Same SQL syntax and database schema
|
|
- Same overall architecture (just the driver changes)
|
|
|
|
---
|
|
|
|
## Status
|
|
|
|
**Accepted** — 2026-03-23
|
|
|
|
Documented environment blocker, evaluated alternatives, chose pragmatic path forward per agent-harness methodology (keep moving vs block on environment).
|