SSB-DB2

Common errors

• Error: method:db.create is not in list of allowed methods.

  cause The `ssb-db2` plugin was not correctly registered with the `secret-stack` instance.
  fix Ensure `sbot.use(require('ssb-db2'))` is called on your `secret-stack` instance before `sbot.call(null, config)`.

• TypeError: Cannot read properties of undefined (reading 'query')

  cause The `db` namespace, where `ssb-db2` registers its API, is undefined, typically because `ssb-db2` failed to load or `secret-stack` was not properly initialized.
  fix Verify that `secret-stack` is initialized with `caps` and that `ssb-db2` is correctly added as a plugin before attempting to access `sbot.db`.

• ReferenceError: require is not defined

  cause Attempting to use CommonJS `require` syntax in an ESM module context (e.g., a file with `"type": "module"` in `package.json` or a `.mjs` file).
  fix Convert your imports to ESM syntax (e.g., `import SecretStack from 'secret-stack'`) or ensure your files are treated as CommonJS modules.

• Error: Unknown operator 'foo'

  cause Attempting to use a non-existent or misspelled query operator, or trying to import operators from the wrong path.
  fix Double-check the spelling of the operator. Ensure all query operators are imported specifically from `ssb-db2/operators`, e.g., `const { where, type } = require('ssb-db2/operators')`.

Warnings

• breaking SSB-DB2 is a replacement for `ssb-db` and is *not* 100% backwards compatible. It uses a different underlying log format (`bipf` instead of `flume`) and requires a migration process if you intend to query existing `ssb-db` data. Attempting to use write APIs on `ssb-db2` while an old log exists and is being migrated can lead to inconsistent states or 'forking feeds'.
  Fix: Review the 'Migrating from ssb-db' and 'Preventing forking feeds' sections in the `ssb-db2` documentation. For writing to the new log, ensure the old log is fully migrated and deleted, potentially using `config.dangerouslyKillFlumeWhenMigrated`.
• breaking SSB-DB2 explicitly requires Node.js version 16 or higher. Older Node.js versions are not supported and will likely result in runtime errors.
  Fix: Upgrade your Node.js environment to version 16 or newer. Use a tool like `nvm` to manage Node.js versions.
• gotcha Some advanced queries require additional LevelDB index plugins, as the default `jitdb` (Just-In-Time Database) indexing only covers basic functionality. Queries relying on specific data patterns not covered by the base index will not return expected results.
  Fix: Consult the `ssb-db2` documentation on 'Leveldb plugins' to understand which plugins are needed for specific query types (e.g., `ssb-db2/full-mentions`). Integrate these plugins into your `secret-stack` configuration.
• gotcha SSB-DB2 registers itself in the `db` namespace of a `secret-stack` instance. If `ssb-db` (or another plugin also registering in `db`) is used concurrently without proper compatibility layers, it can lead to conflicts or unexpected behavior.
  Fix: When migrating or using both, utilize `ssb-db2/compat` if you need to run both `ssb-db` and `ssb-db2` simultaneously, or ensure you've fully transitioned to `ssb-db2` as the primary database.

Install

• npm install ssb-db2 npm
• yarn add ssb-db2 yarn
• pnpm add ssb-db2 pnpm

Imports

• SecretStack
  wrong:

  const SecretStack = require('secret-stack')

  correct:

  import SecretStack from 'secret-stack'

  While the documentation examples use `require`, SecretStack supports ESM import. This is the primary entry point for building an SSB peer.
• ssb-db2
  wrong:

  import { ssbdb2 } from 'ssb-db2'

  correct:

  import ssbdb2 from 'ssb-db2'

  SSB-DB2 is typically imported as a SecretStack plugin. When used with `secret-stack`, it is loaded via `.use(require('ssb-db2'))` in CJS or via dynamic import in ESM if `secret-stack` supports it.
• { where, and, type, author, toCallback }
  wrong:

  const { where, and, type, author, toCallback } = require('ssb-db2')

  correct:

  import { where, and, type, author, toCallback } from 'ssb-db2/operators'

  Query operators are imported as named exports from a dedicated `operators` submodule. Direct `require('ssb-db2')` will not expose these.

Quickstart

This quickstart demonstrates how to set up an SSB peer with ssb-db2, publish a message, and then query for 'post' messages using the new query operators.

const SecretStack = require('secret-stack')
const caps = require('ssb-caps')
const fs = require('fs')
const path = require('path')

const testPath = './temp-ssb-db2-quickstart'

// Ensure a clean state for the quickstart
if (fs.existsSync(testPath)) {
  fs.rmSync(testPath, { recursive: true, force: true });
}
fs.mkdirSync(testPath, { recursive: true });

const sbot = SecretStack({ caps })
  .use(require('ssb-db2'))
  .call(null, { path: testPath })

sbot.db.create({ content: { type: 'post', text: 'hello from ssb-db2!' } }, (err, msg) => {
  if (err) {
    console.error('Error publishing message:', err);
    sbot.close()
    return;
  }
  console.log('Published message:', msg.value.content);

  const { where, type, toCallback } = require('ssb-db2/operators');
  sbot.db.query(
    where(type('post')),
    toCallback((err, msgs) => {
      if (err) {
        console.error('Error querying messages:', err);
      } else {
        console.log('Found ' + msgs.length + ' post messages:');
        msgs.forEach(m => console.log('- ' + m.value.content.text));
      }
      sbot.close();
      fs.rmSync(testPath, { recursive: true, force: true }); // Clean up
    })
  );
});