{"id":16364,"library":"foundationdb","title":"FoundationDB Node.js Bindings","description":"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.","status":"active","version":"2.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/josephg/node-foundationdb","tags":["javascript","foundationdb","fdb","database","NoSQL","ACID","typescript"],"install":[{"cmd":"npm install foundationdb","lang":"bash","label":"npm"},{"cmd":"yarn add foundationdb","lang":"bash","label":"yarn"},{"cmd":"pnpm add foundationdb","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime 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.","package":"foundationdb-client-library","optional":false}],"imports":[{"note":"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`.","wrong":"import fdb from 'foundationdb';","symbol":"fdb","correct":"const fdb = require('foundationdb');"},{"note":"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.","wrong":"const dbRoot = fdb.open();\nfdb.setAPIVersion(700); // Incorrect order, will throw an error.","symbol":"fdb.setAPIVersion","correct":"fdb.setAPIVersion(700); // Must be called before fdb.open()"},{"note":"The package ships with TypeScript types. Import specific types explicitly for better type checking and IntelliSense.","symbol":"Database (TypeScript Type)","correct":"import type { Database, Transaction, Directory } from 'foundationdb';"}],"quickstart":{"code":"const fdb = require('foundationdb');\nfdb.setAPIVersion(700); // Must be called before database is opened\n\n(async () => {\n  const dbRoot = fdb.open(); // or open('/path/to/fdb.cluster')\n\n  // Scope all of your application's data inside the 'myapp' directory in your database\n  const db = dbRoot.at(await fdb.directory.createOrOpen(dbRoot, 'myapp'))\n    .withKeyEncoding(fdb.encoders.tuple) // automatically encode & decode keys using tuples\n    .withValueEncoding(fdb.encoders.json); // and values using JSON\n\n  await db.doTransaction(async tn => {\n    console.log('Book 123 is', await tn.get(['books', 123])); // Book 123 is undefined\n\n    tn.set(['books', 123], {\n      title: 'Reinventing Organizations',\n      author: 'Laloux'\n    });\n  });\n  \n  console.log('now book 123 is', await db.get(['books', 123])); // shorthand for db.doTransaction(...)\n})().catch(err => {\n  console.error('An error occurred:', err);\n  process.exit(1);\n});","lang":"javascript","description":"Demonstrates connecting to FoundationDB, creating a directory, configuring key/value encoding, performing a transactional write, and reading data using the promise-based API."},"warnings":[{"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).","message":"The `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.","severity":"breaking","affected_versions":">=0.1.0"},{"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.","message":"You 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"Windows 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"On 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"This 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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"Error: The FoundationDB C client library could not be loaded. Please ensure FoundationDB is installed and libfdb_c is in your dynamic library path."},{"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.","cause":"Attempted to call `fdb.setAPIVersion()` more than once in the application's lifecycle, or after other FoundationDB operations have already initialized the API.","error":"Error: API version may be set only once"},{"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.","cause":"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.","error":"TypeError: fdb.open is not a function"}],"ecosystem":"npm"}