Melon-db — offline-first local database

createDatabase wires your schema to a StorageAdapter and exposes collections, read/write scopes, and optional sync APIs.

createDatabase

import { createDatabase } from '@melon-db/db';

const db = createDatabase({
  schema: appSchema,
  adapter,
  migrations,           // optional Migration[]
  devtools,             // optional DevtoolsBridge
  sync: {},             // optional — enables sync outbox + checkpoint APIs
});

The database lazy-initializes the adapter on first use (initialize(schema, { migrations, sync })).

Adapter options by runtime

Runtime	Package / entry	Notes
Tests, playgrounds	`@melon-db/db` → `createInMemoryAdapter()`	No native deps
Bun / Node	`@melon-db/db-sqlite` → `createNodeSqliteAdapter({ filename })`	Uses better-sqlite3 when available
Expo Go	`@melon-db/db-sqlite/expo` → `createExpoSqliteAdapter({ database })`	`expo-sqlite` async API
RN dev client (new arch)	`@melon-db/db-sqlite` → native JSI sync path	See Native architecture

Expo Go example

From apps/playground-rn:

import * as SQLite from 'expo-sqlite';
import { createExpoSqliteAdapter } from '@melon-db/db-sqlite/expo';
import { createDatabase } from '@melon-db/db';

async function bootstrap() {
  const database = await SQLite.openDatabaseAsync('app.db');
  const adapter = createExpoSqliteAdapter({ database });

  return createDatabase({
    schema: taskSchema,
    adapter,
    sync: {}, // enable sync outbox when using @melon-db/sync
  });
}

In-memory (tests)

import { createDatabase, createInMemoryAdapter } from '@melon-db/db';

const db = createDatabase({
  schema: taskSchema,
  adapter: createInMemoryAdapter(),
});

Sync flag

Pass sync: {} (or sync: { respectLocalOnly: true }) to enable:

db.getLocalChanges() — read pending outbox entries for push
db.applyRemoteChanges(changes, options) — apply server pull
db.markLocalChangesPushed() — ack after successful push
Checkpoint storage via adapter meta when available

Without sync, those methods throw SYNC_NOT_ENABLED. See Sync frontend.

Devtools

Pass a DevtoolsBridge from @melon-db/db-devtools to capture queries, writes, and timings:

import { createReactiveDevtoolsBridge } from '@melon-db/db-devtools';

const db = createDatabase({
  schema,
  adapter,
  devtools: createReactiveDevtoolsBridge(),
});

Lifecycle

await db.unsafeReset(); // dev/test — wipe local data
await db.adapter.close(); // release native handles when shutting down

Getting started — install and first run
Read & write — transaction boundaries
Sync — pull/push after sync: {}

Database & adapters