# ssb-migrate

> handle database migrations for scuttlebutt

Latest version **1.3.0** (published 2022-05-13) · AGPL-3.0 license · 0 weekly downloads

## Install

```sh
npm install ssb-migrate
pnpm add ssb-migrate
yarn add ssb-migrate
bun add ssb-migrate
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.3.0 |
| Published | 2022-05-13 |
| First published | 2021-09-26 |
| Weekly downloads | 0 |
| License | AGPL-3.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 22.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | mixmix |
| Maintainers | chereseeriepa, mixmix |
| Keywords | ssb, scuttlebutt, migrations |

## Links

- npm: https://www.npmjs.com/package/ssb-migrate
- Repository: https://gitlab.com/ahau/lib/ssb-migrate
- Homepage: https://gitlab.com/ahau/lib/ssb-migrate#readme
- Issues: https://gitlab.com/ahau/lib/ssb-migrate/issues
- npm.io page: https://npm.io/package/ssb-migrate

## Dependencies (2)

- [obz](https://npm.io/package/obz.md) ^1.1.0
- [pull-stream](https://npm.io/package/pull-stream.md) ^3.6.14

## Recent versions

- 1.3.0 (latest) — 2022-05-13
- 1.2.0 — 2022-04-13
- 1.1.2 — 2021-09-28
- 1.1.1 — 2021-09-28
- 1.1.0 — 2021-09-28
- 1.0.1 — 2021-09-28
- 1.0.0 — 2021-09-26

## README

# ssb-migrate

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

## Example Usage

```js
const Migrate = require('ssb-migrate')

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

migrate.run((err) => {
  // ..
})
```

## Migration files

mirgation files must:
- be named in format `${UnixTime}-${kebab-case-description}.js`
- export and Object with function `up`

```js
// 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
  // }
}
```

## API

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

takes:
- `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
    - `opts.migration` *Object*
        - manually provide the migrations, useful for bundling
        - format: `{ fileName: migration }`
    - `opts.resetIfCorrupt` *Boolean*
        - this module uses a JSON file to record the migrations it has completed
        - if this is corrupted, the default action is to throw. this lets you over-ride and tell `ssb-migrate` to just start over with everything
        - default: `false`
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


### `migrate.state(cb)`

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

```js
{
  complete: []
  todo: [
    '1632689651072-add-kaitiki-subgroups'
  ]
}
```

_alias await migrate.state()_

### `migrate.run(cb)`

Runs outstanding migrations

## TODO

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

---
_Source: https://npm.io/package/ssb-migrate · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._