{"id":17305,"library":"node-lmdb","title":"Node.js LMDB Binding","description":"node-lmdb provides a high-performance Node.js binding to LMDB (Lightning Memory-Mapped Database), a transactional key-value store renowned for its speed and efficiency. It operates as an in-process, zero-copy database, eliminating the overhead of socket communication. The library supports transactions, multiple databases within a single environment, and is designed for multi-threaded and multi-process use, offering crash-proof persistence. The current stable version is 0.10.1, with releases occurring periodically to address bugs and introduce features. Its key differentiators include direct memory-mapped access, support for binary and string values via Node.js Buffers, and an API designed to align with JavaScript conventions while maintaining parity with the underlying LMDB C API. It's suitable for applications requiring extremely fast, durable, local data storage.","status":"active","version":"0.10.1","language":"javascript","source_language":"en","source_url":"https://github.com/Venemo/node-lmdb","tags":["javascript","lmdb","database","mdb","lightning","binding","typescript"],"install":[{"cmd":"npm install node-lmdb","lang":"bash","label":"npm"},{"cmd":"yarn add node-lmdb","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-lmdb","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For ESM, use named imports. For CommonJS, destructure from the require call or access properties.","wrong":"const Env = require('node-lmdb').Env;","symbol":"Env","correct":"import { Env } from 'node-lmdb';"},{"note":"Txn is a named export, not the default module export. Direct require() without destructuring will not work for specific classes.","wrong":"const Txn = require('node-lmdb');","symbol":"Txn","correct":"import { Txn } from 'node-lmdb';"},{"note":"This provides a namespace import for all exports. For CommonJS, `const lmdb = require('node-lmdb');` is the correct pattern to get the module object.","wrong":"const lmdb = require('node-lmdb').default;","symbol":"* as lmdb","correct":"import * as lmdb from 'node-lmdb';"}],"quickstart":{"code":"import { Env } from 'node-lmdb';\nimport * as fs from 'fs';\nimport * as path from 'path';\n\nconst dbPath = path.join(__dirname, 'mydata');\nif (!fs.existsSync(dbPath)) {\n    fs.mkdirSync(dbPath);\n}\n\nconst env = new Env();\nenv.open({\n    path: dbPath,\n    mapSize: 2 * 1024 * 1024 * 1024, // 2GB maximum database size\n    maxDbs: 5 // Allow up to 5 named databases\n});\n\nconst dbi = env.openDbi({\n    name: 'myPrettyDatabase',\n    create: true // Create the database if it doesn't exist\n});\n\ntry {\n    let txn = env.beginTxn();\n    const key1 = 1;\n    let value1 = txn.getString(dbi, key1);\n    \n    console.log(`Initial value for key ${key1}: ${value1}`);\n\n    if (value1 === null) {\n        txn.putString(dbi, key1, \"Hello from node-lmdb!\");\n        console.log(`Set value for key ${key1} to 'Hello from node-lmdb!'`);\n    } else {\n        txn.del(dbi, key1);\n        console.log(`Deleted value for key ${key1}`);\n    }\n    \n    const key2 = 'my_string_key';\n    txn.putBinary(dbi, key2, Buffer.from('Binary data example'));\n    console.log(`Put binary data for key '${key2}'`);\n\n    txn.commit(); // Commit the transaction\n\n    // Read the binary data back in a new transaction\n    txn = env.beginTxn();\n    const binaryValue = txn.getBinary(dbi, key2);\n    console.log(`Retrieved binary data for key '${key2}': ${binaryValue?.toString()}`);\n    txn.abort(); // Abort a read-only transaction\n\n} catch (e) {\n    console.error('LMDB operation failed:', e);\n} finally {\n    dbi.close();\n    env.close();\n    fs.rmSync(dbPath, { recursive: true, force: true }); // Clean up\n}","lang":"typescript","description":"This quickstart demonstrates how to initialize an LMDB environment, open a database, perform read and write operations within a transaction, and then properly close resources. It covers storing strings and binary data, and includes cleanup."},"warnings":[{"fix":"Ensure every call to `env.beginTxn()` is paired with a `txn.commit()` or `txn.abort()` in a `try...finally` block to guarantee transaction closure.","message":"Always explicitly close transactions using `commit()` or `abort()`. Failure to do so can lead to resource leaks, database corruption, or deadlocks, especially in environments with many concurrent operations.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Review the changelog or GitHub releases for specific breaking changes if migrating from older versions. Update to `node-lmdb@^0.10.0` and adapt code as necessary.","message":"Versions prior to 0.7.0 might have different API signatures or less stable behavior. While specific breaking changes are not fully documented in the README, it's generally recommended to upgrade to the latest 0.10.x series for stability and features.","severity":"breaking","affected_versions":"<0.7.0"},{"fix":"Carefully estimate your maximum database size requirements and set `mapSize` generously. It is advisable to set it larger than strictly necessary, as resizing often requires closing and reopening the environment.","message":"The `mapSize` option in `env.open()` sets the maximum size the database file can ever grow to. If your data exceeds this, subsequent writes will fail with an `MDB_MAP_FULL` error.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure your development and deployment environments have `node-gyp` prerequisites installed (Python 3, build tools like GCC/Clang or Visual C++). Consult the `node-gyp` documentation for specific OS requirements.","message":"Node-lmdb is a native binding, meaning it compiles C/C++ code during installation. This can cause issues on systems without proper build tools (e.g., Python, C++ compiler).","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":"Increase the `mapSize` property in `env.open()` to a sufficiently large value. You may need to close and reopen the environment for the change to take effect.","cause":"The configured mapSize for the LMDB environment is too small to accommodate new data or existing data growth.","error":"MDB_MAP_FULL: Environment mapsize limit reached"},{"fix":"Ensure all database operations are performed within the scope of an active transaction. Do not reuse `Txn` objects after `commit()` or `abort()`. Create a new transaction for each logical unit of work.","cause":"Attempting to use a transaction object after it has been committed or aborted, or after the environment/database has been closed.","error":"Error: MDB_BAD_TXN: Transaction has been aborted or is inactive"},{"fix":"This is often expected behavior. Check the return value of `get*()` methods, which will typically be `null` or `undefined` if the key is not found. Handle these cases gracefully in your application logic.","cause":"An attempt was made to retrieve a key that does not exist in the specified database.","error":"Error: MDB_NOTFOUND: No matching key/data pair found"},{"fix":"Install necessary build tools for your operating system. For Windows, install Visual Studio Build Tools. For Linux, install `build-essential` (Debian/Ubuntu) or `Development Tools` (Fedora/RHEL). Ensure Python 3 is installed and configured correctly for `node-gyp`.","cause":"During `npm install`, the native C/C++ binding compilation failed due to missing build tools or incorrect environment setup.","error":"node-gyp rebuild failed"}],"ecosystem":"npm","meta_description":null}