ssb-db

Common errors

• Error: EADDRINUSE: address already in use :::[PORT_NUMBER] or file lock errors (e.g., EBUSY)

  cause Attempting to run multiple `ssb-db` instances simultaneously using the same database directory or network port, or failing to properly close a previous instance, resulting in resource contention.
  fix Ensure all `ssb-db` instances are properly closed (`app.close()` in `secret-stack`) before attempting to start a new one, or configure each instance to use a unique database directory and port.

• Error: message.type is required (or similar validation error in `app.publish` callback)

  cause Publishing a message to `app.publish()` without including the mandatory `type` attribute in the message object.
  fix Always include a `type` property in the message object passed to `app.publish()`, for example: `{ type: 'post', text: 'My message' }`.

• Unboxed private messages not appearing or incorrect data in indexes after adding new unboxers

  cause New unboxers (e.g., for private group formats) are added to an `ssb-db` instance, but the existing flume indexes, which process encrypted messages, are not rebuilt, leading to unboxed content not appearing in views or queries.
  fix After registering a new unboxer, explicitly call `app.rebuild()` (exposed since v20.1.0) on your `ssb-db` instance to ensure all flume indexes are reprocessed with the new unboxer.

Warnings

• breaking The `addBoxer` API changed in v20.3.0 to provide the `previous` messageId, which is required for modules like `ssb-tribes`. Existing implementations of `addBoxer` will need updates to function correctly.
  Fix: Update custom `addBoxer` implementations to accept and utilize the `previous` messageId parameter.
• breaking In v20.2.0, the `addBoxer` method was modified to accept an `init` method, and `ssb-db` methods now wait for boxer initialization. This impacts custom boxer implementations and their lifecycle.
  Fix: Review and update custom `addBoxer` implementations to include an `init` method if necessary and account for initialization delays, ensuring they complete before dependent db operations.
• breaking With v20.0.1, `addBoxer` / `addUnboxer` methods were exposed with an initialization step, and `ssb-private1` was extracted as a standalone module. When including a *new* unboxer, you *must* rebuild your indexes to correctly process and expose unboxed content, which can be a time-consuming operation.
  Fix: After adding a new unboxer (e.g., for a new private group format), call the `rebuild` function (exposed since v20.1.0) on your `ssb-db` instance to ensure all flume indexes are consistent.
• deprecated Version 20.0.0 deprecated behavior by exposing unboxed messages on certain methods that other plugins were also exposing. This could lead to conflicts or unexpected data exposure if multiple plugins tried to expose or modify the same message format.
  Fix: Review how unboxed messages are handled if using v20.0.0 and update to a later version to ensure consistent behavior, or modify downstream plugins accordingly to avoid conflicts.
• gotcha `ssb-db` instances acquire OS-level locks on port and database files. Therefore, only *one instance* of `ssb-db` can be created and run at a time on a given system/directory without conflicts.
  Fix: Ensure only one `secret-stack` application using `ssb-db` is running at any given time, or configure different database directories and network ports for multiple instances if necessary.

Install

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

Imports

• createApp
  wrong:

  import { createApp } from 'secret-stack'

  correct:

  const createApp = require('secret-stack')

  `secret-stack` and `ssb-db` are typically used in a CommonJS Node.js environment. ESM `import` is not directly supported for these packages.
• ssb-db (plugin object)
  wrong:

  import ssbdb from 'ssb-db'

  correct:

  .use(require('ssb-db'))

  `ssb-db` is instantiated by `secret-stack` when registered via `.use()`. Direct `require()` is for the *plugin object*, not the running instance.
• pull
  wrong:

  import pull from 'pull-stream'

  correct:

  var pull = require('pull-stream')

  `pull-stream` is a widely used streaming library in the SSB ecosystem. Ensure correct `require` syntax for older Node.js contexts.

Quickstart

This example demonstrates initializing an `ssb-db` instance using `secret-stack`, publishing a new message to the current identity's feed, and then streaming all messages from the log and specifically from the current identity's history. It showcases basic message creation and retrieval patterns.

/**
 * create an ssb-db instance and add a message to it.
 */
var pull = require('pull-stream')

//create a secret-stack instance and add ssb-db, for persistence.
var createApp = require('secret-stack')({})
  .use(require('ssb-db'))


// create the db instance.
// Only one instance may be created at a time due to os locks on port and database files.

var app = createApp(require('ssb-config'))

//your public key, the default key of this instance.
console.log("App ID:", app.id)

//or, called remotely
app.whoami(function (err, data) {
  if (err) return console.error(err)
  console.log("Whoami ID:", data.id) //your id
})

// publish a message to default identity
//  - feed.add appends a message to your key's chain.
//  - the `type` attribute is required.

app.publish({ type: 'post', text: 'My First Post!' }, function (err, msg) {
  if (err) return console.error(err)
  // the message as it appears in the database:
  console.log("Published message:", msg)

  // and its hash:
  console.log("Message key:", msg.key)

  // collect all the messages into an array, calls back, and then ends
  // https://github.com/pull-stream/pull-stream/blob/master/docs/sinks/collect.md
  pull(
    app.createLogStream(),
    pull.collect(function (err, messagesArray) {
      if (err) return console.error(err)
      console.log("All messages in log:", messagesArray)
    })
  )

  // collect all messages for a particular keypair into an array, calls back, and then ends
  // https://github.com/pull-stream/pull-stream/blob/master/docs/sinks/collect.md
  pull(
    app.createHistoryStream({id: app.id}),
    pull.collect(function (err, messagesArray) {
      if (err) return console.error(err)
      console.log("Messages for app.id:", messagesArray)
      app.close() // Close the app instance to release locks
    })
  )
})