writeonce/docs/runtime/database.md

Document & Graph Database — Design Series

A seven-phase design series that starts with "should writeonce use a document or graph database?" and arrives at a full-stack declarative application platform — then plans the migration from writeonce's current flat-file store to that platform.

Start here if you're new: wo-language.md — the user-facing overview of what writeonce is (a programming language with DB + HTTP in its runtime, Go-style toolchain). This series is the engineering plan that gets you there.

Each phase is self-contained and shippable on its own. Every phase after Phase 1 builds on the previous ones.

Phases

Phase	Document	Summary
1	Database Evaluation	Evaluate CouchDB, Postgres, Neo4j, petgraph against writeonce's needs. Decision: no external DB; add petgraph-backed mappings.idx.
2	The .wo Language & ACID Engine	Design a two-layer .wo language (unified type schema layer + hybrid SQL/Cypher query layer with fixed glue) for an e-commerce platform with ACID transactions across relational, document, and graph storage.
3	In-Memory Engine	RAM-primary, SSD-durable storage engine using io_uring, mlockall, group commit. 64 GB Linux machine.
4	Client API: Wire Protocol & Subscriptions	Native binary protocol + GraphQL over WebSocket. Subscription engine inside the transaction coordinator — no polling anywhere.
5	Go Client SDK	Typed Go client with subscription-first design. gen codegen from .wo schema. Subscribe to a live query in 5 lines.
6	Low-Code Full-Stack	Expand .wo into an application language (like SAP CDS): ##ui, ##logic, ##policy, ##service blocks compiled into a single binary.
7	Replacing wo-seg	Phased coexistence plan: abstract the article store behind a trait, stand up the .wo engine as a second impl, dual-run, cut over, decommission wo-seg.

Build Order

Phase 1: Evaluation          ← writeonce today (blog, flat files)
    │
    ▼
Phase 2: .wo Language         ← query language + ACID engine design
    │
    ▼
Phase 3: In-Memory Engine     ← RAM-primary storage, io_uring, WAL
    │
    ▼
Phase 4: Client API           ← wire protocol, subscriptions, GraphQL
    │
    ▼
Phase 5: Go SDK               ← typed client, codegen, subscription channels
    │
    ▼
Phase 6: Low-Code Full-Stack  ← .wo as application DSL, UI generation, CLI
    │
    ▼
Phase 7: Replace wo-seg       ← trait abstraction, dual-run, cutover, decommission

Cumulative Scope

After Phase	What exists	Rough cumulative effort
1	petgraph mappings.idx in writeonce	~200 lines
2	.wo parser + planner + ACID engine prototype	5–10 months
3	In-memory engine with io_uring durability	8–16 months
4	Wire protocol + subscription engine	14–28 months
5	Go SDK with typed subscriptions	16–32 months
6	Full-stack low-code platform	28–56 months
7	wo-seg replaced by the .wo engine in writeonce	+2–4 months on top of Phase 2 arrival

Related Documents

• wo-language.md — writeonce as a programming language: toolchain, hello-world, stdlib, client model
• surreal-case-study.md — SurrealDB runtime analysis; why writeonce does not use a multi-model DB for live queries
• async.md — custom async runtime using Linux kernel primitives
• 05-datalayer.md — current .seg + .idx implementation (8 crates, 44 tests)
• 03-data.md — data layer design with subscription model
• 06-markdown-render.md — markdown-first content model
• ai-agents-content-management.md — the mappings feature that started this series