npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@oceanbase/seekdb-node

v1.4.0

Published

Local seekdb lifecycle bindings for Node.js and TypeScript

Readme

@oceanbase/seekdb-node

Run a local seekdb database from Node.js or TypeScript, with a bundled native runtime and a small lifecycle API.

seekdb.open() starts or reuses a separate seekdb server process and returns a handle. connectionOptions() supplies the endpoint for your MySQL-protocol client, and close() releases the handle. This is not an in-process SQL engine or a SQL client: your application owns its SQL connections and queries.

Source repository · Report an issue

Install

npm install @oceanbase/seekdb-node

Keep npm optional dependencies enabled: npm selects the matching native runtime package for your operating system and CPU. You do not need to install a platform package manually, compile seekdb, or install a separate database server on a supported platform. The native runtime makes the download larger than a JavaScript-only package.

To run the SQL example below, also install mysql2:

npm install mysql2

mysql2 is an example client, not a dependency of this lifecycle binding.

Supported environments

Node.js 22 or newer is required; the release has been tested with Node.js 22 and 24. The package uses ES modules (import) and includes TypeScript declarations. CommonJS require() is not an advertised entry point. Bun and Deno have not been validated.

| Operating system | CPU | Requirements / validation | |---|---|---| | Linux | x86_64 (x64) | glibc 2.28 or newer | | Linux | aarch64 (arm64) | glibc 2.28 or newer | | macOS | Apple Silicon (arm64) | macOS 15.6.1 or newer, required by the bundled server | | Windows | x86_64 (x64) | Tested on Windows 11; older Windows versions are not validated |

This release does not provide macOS Intel, Windows ARM64, 32-bit, or Alpine/musl native packages. Do not copy node_modules between different platforms; install dependencies on the target platform.

Quick start

Save the following as example.mjs, then run node example.mjs:

import { seekdb } from "@oceanbase/seekdb-node";
import mysql from "mysql2/promise";

const db = await seekdb.open("./seekdb.db", {
  parameters: { memory_budget: "2G" },
});
let connection;
try {
  const endpoint = db.connectionOptions();
  let location;
  if (endpoint.transport === "tcp") {
    location = { host: endpoint.host, port: endpoint.port };
  } else if (endpoint.transport === "unix_socket") {
    location = { socketPath: endpoint.unixSocket };
  } else {
    throw new Error("This example uses TCP or Unix sockets; configure TCP or use a named-pipe-capable client.");
  }
  connection = await mysql.createConnection({
    ...location,
    user: endpoint.user,
    password: "",
    database: "test",
  });
  const [rows] = await connection.query("SELECT 1 AS value");
  console.log(rows); // [{ value: 1 }]
} finally {
  try {
    if (connection) await connection.end();
  } finally {
    db.close();
  }
}

The example needs enough free memory for the requested 2G database budget plus Node.js and the operating system. The first open initializes the database directory and can take longer than subsequent opens. Reopening the same directory preserves its data.

The Windows release was tested over TCP. If you configure named-pipe transport, use a client with a compatible adapter; connectionOptions() is transport information, not a client-specific configuration object. To request a random TCP port when spawning on Windows, pass mysql_port_mode: "random" in parameters. Connect using the returned endpoint rather than a hard-coded port.

API

await seekdb.open(dbDir, options?)

Opens a local runtime handle, starting or reusing the server for dbDir. dbDir must be a nonempty string. options.parameters is a record of server parameter names and string values, for example { parameters: { memory_budget: "2G" } }.

Ordinary server parameters apply on first initialization and are then persisted by seekdb. Operational parameters such as port and mysql_port_mode apply when a server is spawned. Opening another handle does not reconfigure an already-running server.

db.connectionOptions()

Returns one of these endpoint shapes while the handle is open:

type ConnectionOptions =
  | { transport: "tcp"; user: string; host: string; port: number }
  | { transport: "unix_socket"; user: string; unixSocket: string }
  | { transport: "named_pipe"; user: string; namedPipe: string };

Use the transport discriminator to adapt it to your SQL client. Calling this method after close() throws an error.

db.close(), db.closed, and db.dbDir

  • close() synchronously releases this lifecycle handle. It is idempotent, does not delete database files, and does not guarantee immediate server exit.
  • Close SQL clients before releasing their lifecycle handle. Other open handles can continue using the same database.
  • closed reports whether this handle has been closed.
  • dbDir is the absolute, normalized database directory.

Call close() explicitly; do not rely on garbage collection for cleanup.

Errors

Invalid JavaScript arguments are rejected with TypeError. Native startup failures reject open() with an exported seekdbError, whose returnCode and message contain the native error code and diagnostic.

Troubleshooting and scope

  • Missing native package: keep optional dependencies enabled and reinstall on the target machine. Verify that its OS, architecture, libc and Node.js version are supported.
  • Startup failure: inspect the error message, database directory permissions, and available memory and disk space. Initialization and restart can take time.
  • SQL client failure: use the endpoint returned by connectionOptions(); keep the handle open while the SQL connection is in use.
  • Local use: the example connects as the local root user with an empty password. Do not expose this endpoint to untrusted networks without separately configuring and validating authentication and network access controls.
  • Different SDK API: this is not a drop-in replacement for @seekdb/js-bindings. It exposes open / connectionOptions / close, not the other SDK's open / connect / execute interface.

For a bug report, include your OS/version, CPU architecture, Node.js version, package version, and a minimal reproduction. Remove credentials and private database contents from logs before sharing them.

Building and contributing

Normal npm users do not need a compiler. For source builds, initialize the repository submodules and use Node.js, CMake and a compatible native toolchain:

git submodule update --init --recursive
cd typescript
npm ci --ignore-scripts
SEEKDB_BIN=/path/to/seekdb npm test

npm test builds the C driver, Node-API addon and TypeScript before testing. Linux source builds also need readelf, ldd and patchelf. Compiler overrides CC, CXX and LDFLAGS are preserved; macOS uses the active Xcode toolchain when no compiler override is supplied.

Alternatively, reuse an extracted, compatible libseekdb SDK. Its public C header must match the source checkout; only the Node addon and TypeScript are rebuilt:

SEEKDB_SDK_DIR=/path/to/libseekdb-sdk npm test
npm run pack:release -- --out-dir /path/to/artifacts

On Windows PowerShell, assign environment variables with $env:NAME = "value" instead of the POSIX syntax above. Initialize the Windows SDK/MSVC support environment and set SEEKDB_MSVC_RUNTIME_DIR to the x64 Microsoft.VC143.CRT redistributable directory when staging the Windows runtime.

Release packaging produces a common package and an exact-version platform runtime package. Linux binaries must remain compatible with glibc 2.28; the macOS minimum is determined by the bundled binaries. Test the installed tarballs outside the source checkout on Node.js 22 and 24. Packing does not publish anything to npm. The standalone Linux-only pack:linux route is for development and is not the multi-platform release layout.

License

The bindings are licensed under Apache-2.0. Bundled seekdb and third-party runtime components retain their own license and notice terms; see the license and notice files included in each native package.