Development Guide

May 25, 2026 · View on GitHub

Prerequisites

  • Node.js: Version >= 20
  • Package Manager: pnpm
  • Database / running mode:
    • Embedded mode: No seekdb server required; install and build, then run examples and tests (using local seekdb.db or a custom path). Depends on the native addon (see packages/bindings). All embedded tests live under packages/seekdb/tests/embedded/ and mirror server-mode scenarios.
    • Server mode: A running seekdb or OceanBase instance (local or remote) is required.
      • Default connection: Host 127.0.0.1, Port 2881, User root, Database test
      • OceanBase mode requires Tenant: sys

Running Modes

  • Embedded mode: new SeekdbClient({ path: "..." }). Data is stored under the given path; no server needed. Admin operations use AdminClient({ path: "..." }), which returns a SeekdbClient. Examples and embedded-only tests run without a database server.
  • Server mode: new SeekdbClient({ host, port, ... }) connects to a deployed seekdb/OceanBase. Start the database and verify connection settings before running server-mode examples.

Run Examples

Setup

Run the following commands in the project root to install dependencies and build the project:

# Install dependencies
pnpm install

# Build all packages
pnpm build

Run Examples

Basic examples (root examples/): run from the examples directory:

cd examples
pnpm install
pnpm run run:simple    # Basic usage
pnpm run run:complete  # Full feature demo
pnpm run run:hybrid    # Hybrid search

ORM integration examples (each has its own package.json under examples/):

  • seekdb-drizzle (Drizzle ORM):

    pnpm --filter seekdb-drizzle-example run start           # Server mode
pnpm --filter seekdb-drizzle-example run start:embedded  # Embedded mode

  • seekdb-prisma (Prisma ORM):

    pnpm --filter seekdb-prisma-example run db:generate
pnpm --filter seekdb-prisma-example run start           # Server (requires db:push and DATABASE_URL)
pnpm --filter seekdb-prisma-example run start:embedded # Embedded (no server)

Running mode:

  • Examples use embedded mode by default where applicable (path: "./seekdb.db"); no seekdb server is required.
  • For server mode, start seekdb/OceanBase and set connection config (e.g. host, port, DATABASE_URL); see each example’s README.

Developers

To participate in SDK development or debugging, follow these steps.

Setup

Run the following commands in the project root to install dependencies and build the project:

# Install dependencies
pnpm install

# Build all packages
pnpm build

Run Tests

The project uses Vitest. From the project root:

# Full suite: seekdb server tests + embedded tests + @seekdb/prisma-adapter (each runs once)
pnpm test

# seekdb only — server-mode tests (paths outside tests/embedded/; need seekdb/OceanBase on SEEKDB_*)
pnpm run test:server

# seekdb only — embedded-mode tests (under tests/embedded/; native addon required)
pnpm run test:embedded

# Watch mode for seekdb (during development)
pnpm --filter seekdb exec vitest

# Run only @seekdb/prisma-adapter tests
pnpm --filter @seekdb/prisma-adapter run test

From packages/seekdb, the same split is available as pnpm run test:server and pnpm run test:embedded.

Tests and running mode:

  • Embedded-mode tests live under packages/seekdb/tests/embedded/ and use a temporary database path per test file. They do not require a seekdb/OceanBase server.
  • Server-mode tests (under packages/seekdb/tests/ but outside embedded/) connect to 127.0.0.1:2881 and require a local seekdb or OceanBase instance. Override with SEEKDB_HOST, SEEKDB_PORT, SEEKDB_USER, SEEKDB_PASSWORD, SEEKDB_DATABASE.
  • Mode consistency tests (tests/embedded/mode-consistency.test.ts) run both embedded and server modes; they require the native addon and a server for the server part.
  • Embedded test coverage vs server is documented in packages/seekdb/tests/embedded/COVERAGE_REPORT.md.

Linting & Formatting

# Run lint check
pnpm lint

# Format code
pnpm prettier