bdb (bcoin-org) - LevelDB Backend

Common errors

• TypeError: bdb is not a function

  cause Attempting to call the `bdb` module itself as a function, often due to a misunderstanding of how the module's API is exposed.
  fix The main `bdb` export is an object. To create a database instance, use `bdb.create()`. For key utilities, use `bdb.key()`.

• Error: IO error: While open a file for appending: /path/to/my.db/LOG: Permission denied

  cause The application lacks write permissions to the specified database directory.
  fix Ensure the Node.js process has read and write permissions for the database directory path provided to `bdb.create()`. Check directory ownership and permissions.

• ERR_REQUIRE_ESM: require() of ES Module ... not supported. Instead change the require of index.js in ... to a dynamic import() which is available in all CommonJS modules.

  cause You are attempting to use `require()` in an ES module environment where it's not directly compatible, or trying to `import` a CommonJS module incorrectly.
  fix bdb is CommonJS. If your project is ESM, you might need to use dynamic `import('bdb')` or convert the surrounding code to CommonJS, or use a build tool to handle the interoperability.

Warnings

• gotcha bdb is a CommonJS module and does not natively support ES module `import` syntax. Attempting to `import bdb from 'bdb'` directly will result in runtime errors in an ESM context.
  Fix: Always use `const bdb = require('bdb');` to import the module in both CommonJS and hybrid environments.
• gotcha Key encoding/decoding is central to bdb's design. Incorrectly defining `bdb.key` formats or attempting to read keys with a mismatched format will lead to data corruption or incorrect parsing, returning unexpected values or errors.
  Fix: Strictly define and adhere to your `bdb.key` schemas. Always use the corresponding `bdb.key.encode()` for writing and `bdb.key.decode()` for reading data, ensuring types match the definition.
• gotcha Not closing database instances (`db.close()`) or iterators (`iter.end()`) can lead to file descriptor leaks, corrupted databases, or resource exhaustion, especially in long-running applications.
  Fix: Ensure all `db` instances are explicitly closed when no longer needed. Similarly, always call `iterator.end()` after completing iteration to release underlying resources, ideally within a `finally` block or using `for await...of` which handles iterator closing implicitly for async iterators.

Install

• npm install bdb npm
• yarn add bdb yarn
• pnpm add bdb pnpm

Imports

• bdb
  wrong:

  import bdb from 'bdb';

  correct:

  const bdb = require('bdb');

  bdb is a CommonJS module and primarily consumed via `require()`. Direct ESM `import` statements are not supported.
• bdb.create

  const bdb = require('bdb');
  const db = bdb.create('/path/to/my.db');

  The `create` method is accessed directly from the required bdb object to initialize a new database instance.
• bdb.key

  const bdb = require('bdb');
  const myKey = bdb.key('prefix', ['type1', 'type2']);

  The `key` utility for structured key encoding/decoding is a static method on the main bdb object.

Quickstart

Demonstrates opening a bdb database, creating a bucket, encoding/decoding structured keys, performing batch writes, and iterating over stored key-value pairs using both callback-based and async iterators, then properly closing and cleaning up the database.

const bdb = require('bdb');
const path = require('path');
const os = require('os');
const fs = require('fs/promises');

async function runDbExample() {
  const dbPath = path.join(os.tmpdir(), `bdb-example-${Date.now()}`);
  await fs.mkdir(dbPath, { recursive: true });
  
  const db = bdb.create(dbPath);

  try {
    await db.open();
    console.log('Database opened at:', dbPath);

    const myPrefix = bdb.key('r');
    const myKey = bdb.key('t', ['hash160', 'uint32']);

    const bucket = db.bucket(myPrefix.encode());
    const batch = bucket.batch();

    const hash = Buffer.alloc(20, 0x11); // Example 20-byte hash

    // Write `foo` to `rt[11...11][00000000]`
    batch.put(myKey.encode(hash, 0), Buffer.from('foo'));
    batch.put(myKey.encode(Buffer.alloc(20, 0x22), 1), Buffer.from('bar'));

    await batch.write();
    console.log('Batch write complete.');

    // Iterate:
    const iter = bucket.iterator({
      gte: myKey.min(),
      lte: myKey.max(),
      values: true
    });

    console.log('\nIterating through records:');
    await iter.each((key, value) => {
      const [decodedHash, index] = myKey.decode(key);
      console.log('  Key:', key.toString('hex'), '-> Hash:', decodedHash.toString('hex'), 'Index:', index, 'Value:', value.toString());
    });
    
    await iter.end(); // Important to close iterator resources

    // Using async iterator:
    console.log('\nIterating with async iterator:');
    const asyncIter = bucket.iterator({
      gte: myKey.min(),
      lte: myKey.max(),
      values: true
    });

    for await (const {key, value} of asyncIter) {
      const [decodedHash, index] = myKey.decode(key);
      console.log('  Key:', key.toString('hex'), '-> Hash:', decodedHash.toString('hex'), 'Index:', index, 'Value:', value.toString());
    }

    await db.close();
    console.log('\nDatabase closed.');
  } catch (error) {
    console.error('Database operation failed:', error);
  } finally {
    await fs.rm(dbPath, { recursive: true, force: true });
    console.log('Cleaned up database directory:', dbPath);
  }
}

runDbExample();