Installation

xqdb ships as two packages built from the same Rust core: xqdb for Python and @xbbg/xqdb for Node.js. Neither package includes a q process. Run kdb+ or KDB-X separately and connect to it over TCP.

Python

python -m pip install xqdb

Requirement	Version
CPython	3.10 to 3.14 (>=3.10,<3.15)
narwhals	2.10.0 or newer, installed automatically
pyarrow	20.0.0 or newer, installed automatically
pandas, polars	Optional. Install the one you select as a DataFrame backend.

PyArrow is the default backend. To use pandas or Polars instead, install that package alongside xqdb:

python -m pip install xqdb polars

Prebuilt wheels

Release 0.1.8 publishes one stable-ABI wheel (cp310-abi3) for each platform below. Each wheel works on every supported CPython version.

Platform	Wheel tag
Windows x64	win_amd64
Linux x86-64, glibc 2.28 or newer	manylinux_2_28_x86_64
macOS on Apple silicon, 11.0 or newer	macosx_11_0_arm64

On any other platform, pip falls back to the source distribution, which needs a Rust toolchain to build.

Check the install

from importlib.metadata import version

import xqdb

print(version("xqdb"))  # 0.1.8
conn = xqdb.Q("localhost", 1800)  # validates options; no network I/O yet

Creating a Q does not open a socket. The first query opens the connection. Selecting a backend that is not installed raises ModuleNotFoundError when the Q is created.

Node.js

npm install @xbbg/xqdb

Requirement	Version
Node.js	20 or newer
Module format	ESM only. Load it with import.
apache-arrow	^21.2.0, installed automatically

The package includes TypeScript declarations. Results are apache-arrow objects, so add apache-arrow as a direct dependency if your code imports Arrow classes such as Table:

npm install @xbbg/xqdb apache-arrow@^21.2.0

Native packages

npm installs a native addon as an optional dependency for your platform:

Platform	Native package	Requirement
Windows x64	@xbbg/xqdb-win32-x64-msvc	Microsoft x64 ABI
Linux x64	@xbbg/xqdb-linux-x64-gnu	glibc 2.28 or newer
macOS arm64	@xbbg/xqdb-darwin-arm64	Apple silicon

No other operating system, CPU, or libc combination is supported in 0.1.8. The addon loads the first time you connect or call a helper, not at import. If it cannot load, for example because optional dependencies were omitted during install, the call rejects with an XqdbIOError whose code is XQDB_NATIVE_LOAD. Reinstall with optional dependencies enabled.

Check the install

import { Q } from "@xbbg/xqdb";

// The constructor validates options synchronously and throws RangeError on bad input.
// It does not connect; the first call does.
const q = new Q({ host: "localhost", port: 1800 });
await q.disconnect(); // safe even if never connected

Building from source

Both packages build with the Rust toolchain pinned in the repository (rust-toolchain.toml, Rust 1.98.0 at the 0.1.8 tag).

git clone https://github.com/underloam/xqdb.git
cd xqdb

# Python: builds the PyO3 extension with setuptools-rust
python -m pip install -e .

# Node.js: builds the napi-rs addon, then the TypeScript facade
cd js-xqdb
npm install
npm run build

Next steps

• Quick Start: connect and run your first queries.
• Connections and TLS: every connection option and when it applies.