@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-nodeKeep 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 mysql2mysql2 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.
closedreports whether this handle has been closed.dbDiris 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
rootuser 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 exposesopen/connectionOptions/close, not the other SDK'sopen/connect/executeinterface.
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 testnpm 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/artifactsOn 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.
