handle database migrations for scuttlebutt

Usage no npm install needed!

<script type="module">
  import ssbMigrate from '';



Helper for performing database migrations. Records database migrations that have been done and performs those which haven't been done yet.

Example Usage

const Migrate = require('ssb-migrate')

const migrate = new Migrate(ssb, path.join(__dirname, '../migrations')) => {
  // ..

Migration files

mirgation files must:

  • be named in format ${UnixTime}-${kebab-case-description}.js
  • export and Object with function up
// 1632689651072-add-kaitiki-subgroups.js

modules.exports = {
  up (ssb, misc, cb) {
    // does the migration
    cb(null) // make sure you remember to callback

  // down (ssb, misc, cb) {
  //   // undoes the migration
  // }


new Migrate(ssb, path, opts) => migrate


  • ssb - a scuttlebutt instance
  • path - the absolute path to a folder with migrations in it
  • opts (optional) object
    • opts.verbose Boolean - if set to true logs migration progress loads:
  • list of migrations in the path folder
  • the "database" (file) containing list of completed migrations
    • this file is stored in ssb.config.path

returns migrate instance


Calls back with the current state of migrations, in format:

  complete: []
  todo: [

alias await migrate.state()

Runs outstanding migrations


  • add validations
    • protect against migrations being inserted between migrations that have already been run
    • force migrations to start with a timestamp for order