# arangrate2

> ArangoDB migrations for node.js (for use within other code)

Latest version **2.0.0** (published 2022-02-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install arangrate2
pnpm add arangrate2
yarn add arangrate2
bun add arangrate2
```

## Health

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

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2022-02-18 |
| First published | 2022-02-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >= 16.0.0 |
| Dependencies | 1 |
| Unpacked size | 15.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | David L. Dyess II, David Trapp |
| Maintainers | cherrydt |
| Keywords | ArangoDB, migration, migrate, node.js |

## Links

- npm: https://www.npmjs.com/package/arangrate2
- Repository: https://github.com/CherryDT/arangrate2
- Homepage: https://github.com/CherryDT/arangrate2#readme
- Issues: https://github.com/CherryDT/arangrate2/issues
- npm.io page: https://npm.io/package/arangrate2

## Dependencies (1)

- [logade](https://npm.io/package/logade.md) ^1.0.0

## Recent versions

- 2.0.0 (latest) — 2022-02-18

## README

# arangrate2

Arangrate2 is a flexible ArangoDB migration package for node.js.

It is a fork of [arangrate](https://github.com/daviddyess/arangrate) with a few changes, most importantly catering more towards usage from inside existing code instead of targeting CLI, allowing more flexible use as module without tying the database connection info to environment variables.

_By David Dyess II and David Trapp._

## Install

```none
npm install arangrate2 --save
```

## Usage

**src/migrate.js**

```js
import { fileURLToPath } from 'url'
import Arangrate from 'arangrate2'

const arangrate = new Arangrate({
  database: { // Can come from some configuration file, or can be a precreated client instance
    url: 'http://localhost:8529',
    auth: {
      username: 'root',
      password: 'root'
    },
    databaseName: 'mydb'
  },
  path: fileURLToPath(new URL('../migrations', import.meta.url)),
  collection: 'migrations'
})

export async function migrate (target) {
  await arangrate.migrate(target)
}
```

You have to call your migrate script yourself as needed.

#### Options

- database: A database connection info object passed to arangojs' `Database` constructor, or optionally a precreated database client instance.
- path: The location of your migrations, relative to the main entry point (required).
- (optional) collection: The database collection used to track migrations. Default: `migrations`

### Migrations

Arangrate2 has a **peer dependency** to the `arangojs` package to handle connections and also exports a few helper functions:

- db
  - Database instance
- aql
  - Template strings from `arangojs`
- createCollection
- createEdgeCollection
- dropCollection

Anything that can be done with the `Database` class from `arangojs` can be done with the `db` object here.

Usage of the helper functions is demonstrated in the examples below.

Arangrate2 provides flexibility for your migrations. Migrations will be stored as determined in the migration script you created. You are also allowed to choose the naming convention for your migrations, with the following format:

- [indentifier].do.[title].js

Reversions use `.undo.` instead of `.do.`, but should use the same identifier and title in the following format:

- [identifier].undo.[title].js

The `identifier` should provide an alphabetical or numerical order, such as `0001`, `0002`, `0003`...

The `title` is displayed in the console log and stored in the migrations collection for reference later.

I recommend using a logger in the migration scripts `arangrate2` uses the `logade` npm package for logging, so that is what is used in the examples.

The only requirement for arangrate to run the script is for it to have a default export: `export default async fuction setup() { ... }` to handle the migration. You write the queries or use the arangrate helpers to perform the migration. Arangrate2 will execute the `setup()` function to perform the migration and record it in the database. If the function returns `false`, the operation will not be recorded and will thereby run again next time.

#### Example - 0001.do.initial.js

```js
import { db, createCollection, createEdgeCollection } from 'arangrate2'
import { getLogger } from 'logade'

export default async function setup () {
  const log = getLogger('0001')

  log.info('Migrating')

  const documentCollections = [
    'notifications',
    'profiles',
    'sessions',
    'users'
  ]
  const edgeCollections = ['hasPrivilege', 'hasRole']

  for (const localName of documentCollections) {
    await createCollection({ name: localName })
  }

  for (const localName of edgeCollections) {
    await createEdgeCollection({ name: localName })
  }

  /**
   * Sessions Indexes
   */
  const sessions = await db.collection('sessions')

  await sessions.ensureIndex({
    type: 'hash',
    unique: false,
    fields: ['uid']
  })

  await sessions.ensureIndex({
    type: 'hash',
    unique: false,
    fields: ['expires']
  })

  /**
   * Users Indexes
   */
  const users = await db.collection('users')

  await users.ensureIndex({
    type: 'hash',
    unique: true,
    fields: ['username']
  })

  await users.ensureIndex({
    type: 'hash',
    unique: true,
    fields: ['email']
  })

  /**
   * Notifications
   */
  const notifications = await db.collection('notifications')

  await notifications.ensureIndex({
    type: 'hash',
    unique: false,
    fields: ['userId']
  })
}
```

#### Migrate

```js
import { migrate } from '.../path/to/src/migrate.js'

await migrate('max') // can be target version instead of 'max'
```

```none
2021-10-03 16:56:09 [info][arangrate] Performing migration to max!
2021-10-03 16:56:09 [info][arangrate] Total migrations: 1
2021-10-03 16:56:09 [info][0001] Migrating
2021-10-03 16:56:09 [info][arangrate] Migration 0001 - 0001.initial complete!
2021-10-03 16:56:09 [info][arangrate] Migration target completed!
```

#### Example - 0001.undo.initial.js

```js
import { dropCollection } from 'arangrate2'
import { getLogger } from 'logade'

export default async function setup () {
  const log = getLogger('0001')

  log.info('Reverting')

  const documentCollections = [
    'notifications',
    'profiles',
    'sessions',
    'users'
  ]
  const edgeCollections = ['hasPrivilege', 'hasRole']

  for (const localName of documentCollections) {
    await dropCollection({ name: localName })
  }

  for (const localName of edgeCollections) {
    await dropCollection({ name: localName })
  }
}
```

#### Revert a Migration

To revert, simply provide the migration identifier you would to revert to. If you are on migration `6`, you can revert to any identifier before `6`, such as entering `5` to revert just migration `6`, with `0` being to revert all.

```javascript
import { migrate } from '.../path/to/src/migrate.js'

await migrate(0)
```

```none
2021-10-03 16:59:52 [info][arangrate] Performing migration to 0!
2021-10-03 16:59:52 [info][arangrate] Total migrations: 1
2021-10-03 16:59:52 [info][0001] Reverting
2021-10-03 16:59:52 [info][arangrate] Reverted 0001 - 0001.initial complete!
2021-10-03 16:59:52 [info][arangrate] Migration target completed!
```

### File Structure

The examples used here would fall under the following file structure:

```
- /src
  - migrate.js
- /migrations
  - 0001.do.initial.js
  - 0001.undo.initial.js
```

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