Registry / database / ssb-db2

ssb-db2

JSON →
library8.1.0jsnpmunverified

SSB-DB2 is a new database for secure-scuttlebutt, designed as a replacement for the older `ssb-db`. Currently at version 8.1.0, it offers significant architectural changes aimed at improving performance and flexibility. Key differentiators include using `bipf` for data storage, replacing `flume` with `jitdb` for specialized indexes, supporting browser environments via `ssb-browser-core`, and enabling efficient partial replication. It has expanded capabilities beyond `ssb-db`, featuring deletion and compaction, support for customizable feed and encryption formats (defaulting to `ssb-classic`), and a powerful query language based on composable JavaScript functions. SSB-DB2 operates as a `secret-stack` plugin, registering within the `db` namespace, and is optimized for modern Node.js environments (>=16).

databaseserialization
npm install ssb-db2
github ↗package ↗
INSTALL
IMPORT
SIG · SSB-DB2
S
ssb-db2
databasejavascriptv8.1.0
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.

SecretStack
✓ import SecretStack from 'secret-stack'
✗ const SecretStack = require('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
✓ import ssbdb2 from 'ssb-db2'
✗ 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 }
✓ import { where, and, type, author, toCallback } from 'ssb-db2/operators'
✗ const { where, and, type, author, toCallback } = require('ssb-db2')
Query operators are imported as named exports from a dedicated `operators` submodule. Direct `require('ssb-db2')` will not expose these.

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 }) ); });
Debug
Known issues
breakingSSB-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`.
affects: >=1.0.0
breakingSSB-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.
affects: <16
gotchaSome 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.
affects: >=1.0.0
gotchaSSB-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.
affects: >=1.0.0
Errors
Common errors & fixes
Error: method:db.create is not in list of allowed methods.
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')
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
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'
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')`.
Upgrade
Version history
8.1.0latest on npm
Audit
Dependencies
secret-stackrequiredSSB-DB2 is designed as a secret-stack plugin and requires it for integration into an SSB peer.
ssb-capsrequiredRequired for `secret-stack` configuration, specifically for the `appKey`.
Agent activity
18 hits · last 30 days
node
14
Meta
2
OpenAI (training)
1
Resources
githubhttps://github.com/ssb-ngi-pointer/ssb-db2 ↗
packagehttps://www.npmjs.com/package/ssb-db2 ↗