Roadmap
Phase-by-phase implementation history, shipped status, and deferred work.
This page is the living status for Melon-db. Update it when features land or deferrals change. For product vision see About Melon-db. For requirement-by-requirement PRD tracking see PRD compliance.
| Area | Count / status |
|---|
| Packages | 12 under packages/* (core through sync-server + native) |
| Example apps | 5 — playground-node, playground-rn, playground-rn-dev, playground-web, docs |
| Implementation phases | 0–34 shipped (see chronology below) |
| Out-of-cycle | Fumadocs docs site, TypeDoc API, playgrounds (ongoing maintenance) |
| Next | Phase 35+ feature work; Phase 34 shipped release engineering |
Quick links: Architecture · Phase ADRs · Packages · Performance
Each phase was executed as a focused delivery increment. Phases 0–7 established the core stack; Phases 8–19 expanded RN, sync, and migration tooling; Phases 20–26 delivered native SQLite performance.
| Phase | Title | Packages | Key deliverables | Status |
|---|
| 0 | Monorepo bootstrap | workspace | Bun workspaces, tooling, @melon-db/db skeleton | Shipped |
| 1 | @melon-db/db M0 | @melon-db/db | Schema, AST, adapter types, query pipeline stubs | Shipped |
| 2 | @melon-db/db M1 | @melon-db/db | In-memory adapter, CRUD, serialized write queue | Shipped |
| 3 | @melon-db/db M2 | @melon-db/db | ChangeEmitter, observe, collection subscriptions | Shipped |
| 4 | @melon-db/db-sqlite M0 | @melon-db/db-sqlite | AST → SQL compiler, predicate tests | Shipped |
| 5 | @melon-db/db-sqlite M1 | @melon-db/db-sqlite | Bun SQLite adapter, DDL, integration tests | Shipped |
| 6 | Planned M2/M3 | — | RN native + perf milestones from db-core RFC | Superseded by Phases 8–10, 20–26 |
| 7 | Downstream packages | query, react, mango, prisma, devtools, testkit | Fluent/Mango/Prisma surfaces, hooks, testkit | Shipped |
| — | Hardening (post-7) | CI, playground-node | GitHub Actions, adapter CRUD vectors, initial benchmarks, devtools SQL snapshots | Shipped |
| Phase | Title | Packages | Key deliverables | Status |
|---|
| 8 | RN / Expo integration | @melon-db/db-sqlite, @melon-db/db-react | expo-sqlite adapter, SQLite change notifications, playground-rn | Shipped |
| 9 | API completeness | db, react, prisma | useFindMany/useMangoQuery, migrations, belongsTo includes, Prisma CLI | Shipped |
| 10 | Perf & hardening | @melon-db/db-sqlite | SQL test coverage, debug flag, 10k/50k/100k benchmarks, Node driver | Shipped |
| Phase | Title | Packages | Key deliverables | Status |
|---|
| 11 | Codemods v1 | @melon-db/db-codemods | Query translator, migrate-queries/writes/react CLI | Shipped |
| 19 | Codemods v2 | @melon-db/db-codemods | Nested Q.and/or, fetch/observe handles, delete, migrate-schema spike, Q.on recipes | Shipped |
| Phase | Title | Packages | Key deliverables | Status |
|---|
| 12 | Sync foundation | @melon-db/db, @melon-db/sync | Outbox, getLocalChanges/applyRemoteChanges, synchronize() alpha | Shipped |
| 13 | Sync integration | sync, sync-server, react | Persistent checkpoints, HTTP server, useSync/useSyncStatus, RN sync demo | Shipped |
| 14 | Devtools + docs site | devtools, docs | Reactive bridge, inspector panel, Fumadocs + TanStack Start, CRUD/sync playgrounds | Shipped |
| 15 | Sync reliability | sync, db | Retry/cancellation, network monitor, conflict policies, migration-aware sync | Shipped |
| 16 | Postgres backend | @melon-db/sync-server | PostgresSyncStore, SQL migrations, Docker compose | Shipped |
| 17 | Merge-by-field | @melon-db/db, sync | pendingFields outbox, field-level merge on apply | Shipped |
| 18 | Custom conflict resolver | @melon-db/db, sync, react | conflictPolicy: 'custom' + conflictResolver hook | Shipped |
| Phase | Title | Packages | Key deliverables | Status |
|---|
| 20 | Native SQLite spike | @melon-db/db-sqlite-native, /rn | iOS bridge module, native driver factory, initial spike | Shipped |
| 21 | Android + hardening | native, playground-rn-dev | Real Android SQLite, iOS busy timeout/basePath, dev build app split | Shipped |
| 22 | TurboModule (iOS) | native | Codegen MelonSQLiteSpec, iOS TurboModule | Shipped |
| 23 | TurboModule (Android) | native | Android codegen parity with iOS | Shipped |
| 24 | WDB benchmarks | @melon-db/db-sqlite, docs | bench:compare, CI bench-compare, performance comparison docs | Shipped |
| 25 | C++ JSI (iOS) | native | MelonSQLiteHostObject, native DB thread, global.melonSqliteJsi | Shipped |
| 26 | C++ JSI (Android) | native | NDK/JNI, libmelon_sqlite, Android worker thread parity | Shipped |
| 27 | Native observeQuery | @melon-db/db-sqlite | Predicate-aware invalidation, SQLite triggers foundation, reactiveSubscriptions: true | Shipped |
| 28 | RN on-device benchmarks | @melon-db/db-sqlite/bench, playground-rn-dev | Dev benchmark screen, jsi-sync vs turbo JSON report, shared scenario lib | Shipped |
| 29 | Trigger-driven observation | @melon-db/db-sqlite, @melon-db/db-sqlite-native | Process _melon_observation_events, flushObservationQueue, native sqlite3_update_hook on JSI | Shipped |
| 30 | Query + React DX | @melon-db/db, @melon-db/db-query, @melon-db/db-react | collection.query(builder), findMany/count builder input, QueryBuilder.not(), useRecord, *State hooks, ADR-010 | Shipped |
| 31 | PRD compliance + DX | docs, devtools, playground-web | prd-4 matrix, walkthroughs, devtools Plan/SQL params, AGENTS.md + melon-dev skill, typing pass | Shipped |
| 32 | Query engine — relations | @melon-db/db, @melon-db/db-sqlite, codemods | hasMany includes (post-fetch), relationFilters / Q.on via SQL IN subquery, Prisma include parity | Shipped |
| 33 | observeQuery precision | @melon-db/db, @melon-db/db-sqlite | Cross-collection relationFilters invalidation, field-aware updates, trigger delete fix, schema-aware subscription fingerprint | Shipped |
| 34 | Alpha / open-source release | all publishable packages | Publishable tarballs, CI smoke from packed tarballs, release workflow + docs/support policy | Shipped |
| Phase | Title | Packages | Key deliverables | Status |
|---|
| — | Fumadocs + docs site | apps/docs | MDX guides, 12 package pages, TypeDoc API, search, live playgrounds | Shipped |
| — | Docs expansion (this cycle) | docs | About/vision, phase history, architecture ADRs, package-scoped API titles | Shipped |
Core engine, all three query surfaces, React/sync hooks, devtools, codemods, full sync stack (HTTP + Postgres), dual RN SQLite paths (Expo + native JSI on iOS/Android), predicate-aware observeQuery with trigger-event processing and JSI update_hook, Node + on-device benchmark harnesses, and CI (test, typecheck, biome, bench-smoke, bench-compare, postgres-sync, docs build).
See PRD compliance — Phase 29+ decisions for rationale.
| Area | Notes |
|---|
| EAS Build CI | Release automation for dev client artifacts |
| Full multi-file schema codemods | Beyond single-model migrate-schema spike |
| Background sync service | OS-level scheduling |
| Per-field timestamps / three-way merge | Advanced conflict resolution |
SQL SELECT JOIN result shaping | Includes use post-fetch; capabilities.joins stays false |
getChangedCollections on adapters | Sync uses outbox today |
Sync merging state | Apply is synchronous in v1 |
playground-web SQLite | In-memory Vite app shipped; web SQLite adapter still deferred |
| Sliding window (prd-4) | Org-aware retention, prune ledger, pressure modes — see prd-4.mdc |
| Alpha / open-source release | npm @melon-db org, public GitHub, LICENSE/SECURITY, publish CI — see PRD compliance — Alpha release |
- All mutations must run inside
db.write().
- SQLite migrations: add-column and create-table only.
- Relation includes:
belongsTo + hasMany via post-fetch (not SQL JOIN); nested includes and per-parent take deferred.
Q.on / relationFilters: belongsTo only; experimental Watermelon join tables unsupported.observeQuery: field-aware invalidation for WHERE + relationFilters + orderBy; orderBy+limit top-N membership may still over-invalidate in edge cases; in-memory adapter uses collection-wide ChangeEmitter fallback.
Per-package M0–M2 goals from the monorepo RFCs are reflected in the phase history above. Each package page lists alpha vs shipped status and setup examples.
