Registry / database / foundationdb

foundationdb

JSON →
library7.4.6jsnpmunverified

The `foundationdb` package provides Node.js bindings for interacting with the FoundationDB distributed transactional key-value store. It is currently at version 2.0.1 and appears to have an active release cadence, with several recent updates following its 1.0.0 and 2.0.0 major releases. This library offers low-level access to FoundationDB's core features, including ACID transactions, range reads, key selectors, watches, and directory management. A key differentiator is its direct C++ binding approach, requiring users to install the FoundationDB client library separately on their system. It includes robust support for tuple and JSON encoding for keys and values, simplifying data serialization and deserialization within transactions. The library mandates setting the API version prior to opening a database connection, and it is compatible with FoundationDB server versions 6.2.0 and newer.

database
npm install foundationdb
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · FOUNDATIONDB
F
foundationdb
databasejavascriptv7.4.6
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

fdb
✓ const fdb = require('foundationdb');
✗ import fdb from 'foundationdb';
The `foundationdb` package primarily uses CommonJS exports as shown in the quickstart. For ESM environments, `import * as fdb from 'foundationdb';` is the correct pattern for importing CommonJS modules to access all exports. Using `import fdb from 'foundationdb';` typically only works for modules with a default ESM export or specific `exports` map in `package.json`.
fdb.setAPIVersion
✓ fdb.setAPIVersion(700); // Must be called before fdb.open()
✗ const dbRoot = fdb.open(); fdb.setAPIVersion(700); // Incorrect order, will throw an error.
This function MUST be called once, at the very start of your application, before any other FoundationDB operations, including `fdb.open()`. The API version chosen (`700` in the example) must be less than or equal to the FoundationDB cluster's major/minor API version.
Database (TypeScript Type)
✓ import type { Database, Transaction, Directory } from 'foundationdb';
The package ships with TypeScript types. Import specific types explicitly for better type checking and IntelliSense.

Demonstrates connecting to FoundationDB, creating a directory, configuring key/value encoding, performing a transactional write, and reading data using the promise-based API.

const fdb = require('foundationdb'); fdb.setAPIVersion(700); // Must be called before database is opened (async () => { const dbRoot = fdb.open(); // or open('/path/to/fdb.cluster') // Scope all of your application's data inside the 'myapp' directory in your database const db = dbRoot.at(await fdb.directory.createOrOpen(dbRoot, 'myapp')) .withKeyEncoding(fdb.encoders.tuple) // automatically encode & decode keys using tuples .withValueEncoding(fdb.encoders.json); // and values using JSON await db.doTransaction(async tn => { console.log('Book 123 is', await tn.get(['books', 123])); // Book 123 is undefined tn.set(['books', 123], { title: 'Reinventing Organizations', author: 'Laloux' }); }); console.log('now book 123 is', await db.get(['books', 123])); // shorthand for db.doTransaction(...) })().catch(err => { console.error('An error occurred:', err); process.exit(1); });
Debug
Known issues
breakingThe `foundationdb` Node.js package requires the FoundationDB C client library (`libfdb_c`) to be installed system-wide on the machine where the application runs. This library is not bundled with the npm package and must be downloaded separately from the official FoundationDB website.
fix
Download and install the appropriate FoundationDB client library for your operating system and architecture from foundationdb.org/download/. Ensure the library is discoverable by your system's dynamic linker (e.g., in PATH on Windows, LD_LIBRARY_PATH on Linux, DYLD_LIBRARY_PATH on macOS).
affects: >=0.1.0
gotchaYou MUST call `fdb.setAPIVersion(version)` exactly once, and it must be the very first FoundationDB-related operation in your application. Calling it after `fdb.open()` or attempting to call it multiple times (even with the same version) can lead to errors or unexpected behavior.
fix
Ensure `fdb.setAPIVersion(version)` is placed at the absolute start of your application's bootstrap logic, prior to any `fdb.open()` calls or other API interactions. If you have multiple calls from different parts of your code, consolidate them.
affects: >=0.1.0
gotchaWindows support for `node-foundationdb` is currently disabled due to a known missing header file (`fdb_c_types.h`) in the FoundationDB Windows MSI installer, which prevents the native bindings from compiling correctly.
fix
Windows users should currently avoid this library or use a Linux/macOS environment. Monitor the FoundationDB forums and GitHub issues for updates on Windows support.
affects: >=1.0.0
gotchaOn macOS, due to binary sandboxing, you may need to explicitly add `export DYLD_LIBRARY_PATH=/usr/local/lib` to your shell profile (`.zshrc` or `.bash_profile`) to help the system locate the `libfdb_c` dynamic library.
fix
Add `export DYLD_LIBRARY_PATH=/usr/local/lib` to your shell configuration file and restart your terminal or shell session for changes to take effect.
affects: >=0.1.0
gotchaThis library only supports FoundationDB server versions 6.2.0 or later. Using it with older server versions may lead to unexpected errors or incompatible API behavior. Additionally, the `setAPIVersion` argument must be less than or equal to the FoundationDB cluster's actual API version.
fix
Ensure your FoundationDB cluster is running version 6.2.0 or newer. Verify that the `setAPIVersion` call matches a supported client API version for your specific server version.
affects: >=0.1.0
Errors
Common errors & fixes
Error: The FoundationDB C client library could not be loaded. Please ensure FoundationDB is installed and libfdb_c is in your dynamic library path.
The native FoundationDB client library (`libfdb_c.so`, `.dylib`, or `.dll`) is not installed on the system, or its location is not included in the operating system's dynamic library search path.
fix
Install the FoundationDB client library for your OS and architecture from foundationdb.org/download/. On Linux, ensure `libfdb_c.so` is in a standard path like `/usr/local/lib` or `LD_LIBRARY_PATH` is set. On macOS, check `DYLD_LIBRARY_PATH`. On Windows, ensure `fdb_c.dll` is in a directory listed in your system's `PATH` environment variable.
Error: API version may be set only once
Attempted to call `fdb.setAPIVersion()` more than once in the application's lifecycle, or after other FoundationDB operations have already initialized the API.
fix
Identify all calls to `fdb.setAPIVersion()` and consolidate them into a single invocation at the absolute entry point of your application before any other FoundationDB API usage.
TypeError: fdb.open is not a function
Incorrect import statement used in an ESM context. When a CommonJS module is imported with `import fdb from 'module';` in ESM, the default export may not contain all expected properties.
fix
In an ESM context, use `import * as fdb from 'foundationdb';` to correctly import all exports from the CommonJS module. If using CommonJS, `const fdb = require('foundationdb');` is correct.
Upgrade
Version history
7.4.6latest on npm
Audit
Dependencies
foundationdb-client-libraryrequiredRuntime dependency on the FoundationDB C client library (`libfdb_c.so`, `libfdb_c.dylib`, or `fdb_c.dll`) which must be installed system-wide and available in the system's dynamic library path. This library provides the core FoundationDB API that the Node.js bindings link against.
Agent activity
11 hits · last 30 days
node
10
Resources
githubhttps://github.com/josephg/node-foundationdb ↗
packagehttps://www.npmjs.com/package/foundationdb ↗
homepagehttps://www.foundationdb.org ↗
foundationdb — npm install foundationdb · libregistry