Build With React Native

Install

Install the package for the app path you own, then build the native app binary. The runtime uses Swift and Kotlin code, so package installation alone is not the last step. The installed app must contain the native module and selected runtime resources before JavaScript calls Oliphaunt.open().

Expo apps:

npx expo install @oliphaunt/react-native
npx expo prebuild
npx expo run:ios
npx expo run:android

Expo apps use the config plugin so selected native runtime and extension artifacts are included in the app build.

{
  "expo": {
    "plugins": [
      [
        "@oliphaunt/react-native",
        {
          "extensions": ["vector"]
        }
      ]
    ]
  }
}

React Native apps without Expo still use the same package, but native projects own the equivalent Pod, Gradle, and resource configuration. Rebuild after changing native runtime or extension selection because those choices affect the installed app binary.

Open and query

Open a database from TypeScript, run SQL, and close it when the app no longer needs the handle.

import { Oliphaunt } from '@oliphaunt/react-native';

const db = await Oliphaunt.open({
  root: 'main.oliphaunt',
  engine: 'nativeDirect',
  extensions: ['vector'],
});

const rows = await db.query('SELECT 1::text AS value');
const value = rows.getText(0, 'value');

await db.close();

Keep the database handle in app state or a service object. Multiple JavaScript objects share the same mobile direct session through the platform SDK.

Create app data

Use the SQL helpers for application queries. This keeps most React Native code away from PostgreSQL protocol details:

await db.execute(`
  CREATE TABLE IF NOT EXISTS notes (
    id bigserial PRIMARY KEY,
    title text NOT NULL,
    body text NOT NULL,
    created_at timestamptz NOT NULL DEFAULT now()
  )
`);

await db.query(
  'INSERT INTO notes (title, body) VALUES ($1, $2) RETURNING id::text AS id',
  ['First note', 'Stored in an embedded PostgreSQL root'],
);

const notes = await db.query(
  'SELECT id, title FROM notes ORDER BY id DESC LIMIT 20',
);
const firstTitle = notes.getText(0, 'title');

Reach for raw protocol APIs only when building adapters, COPY flows, or streaming paths that need PostgreSQL wire messages directly.

Configure

Configure root, mode, selected exact extensions, durability, startup identity, and native runtime overrides through the JS API and config plugin. Build-time extension selection controls what ships in the app bundle; runtime root configuration controls where app data lives.

Keep build-time and runtime settings separate. The config plugin controls native artifacts in the installed app. Oliphaunt.open() controls the database root, mode, durability, and extension activation for that app run.

Choose a mode

React Native starts with nativeDirect on mobile. The database work is delegated to Swift on Apple platforms and Kotlin on Android, so capabilities() is the source of truth for additional broker or server mode reports. OpenConfig.engine currently accepts nativeDirect only.

Use binary transport

New Architecture builds use binary ArrayBuffer/JSI transport for raw protocol bytes and chunked streaming. Bulk payloads stay in binary buffers.

Treat JSI transport as the bulk-byte boundary. Small configuration and lifecycle calls use the TurboModule API; protocol payloads and streamed chunks stay in binary buffers.

Handle lifecycle

Use the SDK lifecycle hooks around background/foreground transitions. Direct mobile mode is same-root logically reopenable inside one resident app process. Broker and server runtimes add a process boundary on targets that advertise those modes.

Call the JavaScript lifecycle API from app-level lifecycle handlers. The Swift and Kotlin SDKs own the platform-specific details underneath that call.

Select extensions

Select exact SQL extension names in configuration. The native app packages include only selected extensions plus declared dependencies. CREATE EXTENSION succeeds when the selected runtime resources contain that extension for the target platform.

Back up and restore

Use the React Native backup and restore APIs instead of copying platform storage directories from JavaScript. The SDK delegates archive validation and root materialization to Swift or Kotlin, so platform storage rules stay native.