arango-migrate

library2.0.0jsnpmunverified

ArangoDb migration tool that applies migrations in transaction-safe manner, with support for before/after hooks and dry-run. Current stable version is 2.0.0. It uses arangojs v7.8.0+ and provides TypeScript types. Key differentiators: runs whole migration within a single ArangoDB transaction, auto-creates collections, and includes step-based upserts for fine-grained control. Release cadence is irregular, published 2022.

database

npm install arango-migrate

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ARANGO-MIGRATE

arango-migrate

databasejavascriptv2.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import migration from 'arango-migrate'

✗ const migration = require('arango-migrate')

Package is ESM-only, CommonJS require is not supported. TypeScript types included.

cli

✓ import { cli } from 'arango-migrate'

✗ import { cli } from 'arango-migrate/cli'

CLI function is a default export from main entry. Wrong path will not resolve.

migration template structure

✓ export default { description: '', collections: async () => [], up: async (db, step) => {} }

✗ module.exports = { ... }

Migration files are ES modules, must use export default. Down migration is optional.

Shows typical project setup: config file with dotenv, migration file example with step function, and CLI command.

// config.migrate.js import 'dotenv/config' export default { dbConfig: { databaseName: process.env.ARANGO_NAME, url: process.env.ARANGO_URL, auth: { username: process.env.ARANGO_USERNAME, password: process.env.ARANGO_PASSWORD || '' } }, autoCreateNewCollections: true, migrationHistoryCollection: 'migration_history', migrationsPath: './migrations' } // migrations/001-create-todos.js export default { description: 'Create todos collection', async collections() { return ['todos'] }, async up(db, step) { // step accepts a function that performs an operation within the transaction await step(async () => { // Use step for each operation that modifies data await db.collection('todos').save({ _key: '1', text: 'Buy milk' }) }) } } // Run via CLI: yarn arango-migrate -u

Debug

Known issues

breakingVersion 2.0.0 transitioned from CJS to ESM. Requires Node.js >= 12 and ES module configuration.

fix

Update package.json to include \"type\": \"module\" or use .mjs extension for config and migration files.

affects: >=2.0.0

breakingThe "arangojs" peer dependency was bumped to >=7.8.0 in v2.0.0. Older versions are incompatible.

fix

Install arangojs >=7.8.0 with: npm install arangojs@^7.8.0

affects: >=2.0.0

deprecatedIn v1 the config was exported via CommonJS. v2 uses ES module exports only.

fix

Change module.exports = {} to export default {} in config file.

affects: >=1.0.0 <2.0.0

gotchaAll migration operations must be wrapped in step() calls. Direct db operations outside step will not be rolled back on failure.

fix

Always wrap database writes in step() within the up/down functions.

affects: >=1.0.0

gotchaThe --no-history flag skips writing to migration history; can cause duplicate migrations if misused.

fix

Only use --no-history for testing or one-off scripts; prefer normal operation.

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/config.migrate.js from /path/to/node_modules/arango-migrate/... not supported.

Config file is ESM but package is imported via require() or node version too old.

fix

Use import syntax in config file and ensure Node >=12, or rename to .cjs and set \"type\": \"module\" appropriately.

TypeError: step is not a function

Migration up/down function not receiving step argument correctly, or migration exported as default but imported incorrectly.

fix

Ensure migration uses export default and up/down have two parameters: async up(db, step) {}

Collection 'migration_history' does not exist and autoCreateNewCollections is false

The migration history collection must be created manually if autoCreateNewCollections is set to false.

fix

Set autoCreateNewCollections to true or manually create the collection before running migrations.

ArangoError: cannot write from a read-only transaction

Trying to execute a write operation inside a read-only transaction (e.g., using db.query without step).

fix

Wrap write operations with step() as required by the package's transactional model.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

arangojsrequiredPeer dependency for interacting with ArangoDB

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/TimMikeladze/arango-migrate ↗

packagearango-migrate ↗

homepagehttps://github.com/TimMikeladze/arango-migrate#readme ↗