Registry / database / neo4j-data-migrations

neo4j-data-migrations

library1.2.2jsnpmunverified

A Node.js library for managing data migrations on Neo4j graph databases, inspired by Django South. Version 1.2.2 supports Neo4j 3; for Neo4j 4 use version 2.x. Provides a CLI (`neo4j-data-migrate`) and programmatic API. Key differentiators: simple file-based migration scripts, automatic tracking via `__dm` nodes, and zero external dependencies beyond the Neo4j driver. Maintenance mode as Neo4j 3 is legacy.

database

npm install neo4j-data-migrations

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NEO4J-DATA-MIGRATI

neo4j-data-migrations

databasejavascriptv1.2.2

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.

Migrate

✓ import Migrate from 'neo4j-data-migrations'

✗ const { Migrate } = require('neo4j-data-migrations')

Default export is a class/object; named import will fail.

neo4j-data-migrate CLI

✓ npx neo4j-data-migrate myapp 0002

✗ node ./node_modules/.bin/neo4j-data-migrate myapp

CLI is installed alongside the package, use npx or local bin.

configuration

✓ const config = require('./datamigrations/configuration')

✗ import config from 'neo4j-data-migrations/configuration'

Configuration file is generated in your project, not imported from the package.

Complete setup and usage of neo4j-data-migrations with a sample migration file.

// 1. Install package // npm install neo4j-data-migrations // 2. Setup directory structure // npx neo4j-data-migrate --setup // 3. Configure connection in datamigrations/configuration.js // module.exports = { // connection: { uri: 'bolt://localhost:7687', user: 'neo4j', password: 'password' } // }; // 4. Create migration file: datamigrations/myapp/0001_add_users.js module.exports = { name: 'Add users', forward: async (driver) => { const session = driver.session(); await session.run( 'CREATE (user:User {name: $name, age: $age})', { name: 'Username', age: 30 } ); session.close(); }, backward: async (driver) => { const session = driver.session(); await session.run( 'MATCH (user:User {name: $name}) DELETE user', { name: 'Username' } ); session.close(); }, }; // 5. Run migration // npx neo4j-data-migrate myapp

Debug

Known issues

breakingVersion 1.x only supports Neo4j 3. For Neo4j 4+, use version 2.x.

fix

Upgrade to version 2.x if using Neo4j 4 or later.

affects: >=1.0.0 <2.0.0

deprecatedThe configuration file pattern uses `connection` object; in future versions it may change to `driver` instantiation.

fix

Check future changelog for configuration API changes.

affects: >=1.0.0

gotchaMigration scripts must export an object with `name`, `forward`, and `backward`; missing any will cause silent failures.

fix

Always include all three properties in each migration file.

affects: >=1.0.0

gotchaThe `session` object must be closed manually in migration functions; forgetting to close leads to connection leaks.

fix

Always call `session.close()` after running queries, or use driver.session() with a try-finally block.

affects: >=1.0.0

deprecatedThe library uses labels like `__dm` for tracking; these may conflict with user labels.

fix

Avoid using `__dm` label in your own graph.

affects: >=1.0.0

gotchaCLI command `neo4j-data-migrate` without arguments migrates all apps; ensure migrations are safe to run repeatedly.

fix

Check idempotency of forward and backward functions.

affects: >=1.0.0

gotchaMigrations are tracked by prefix (e.g., '0001'); gaps in numbering may cause unexpected ordering.

fix

Use sequential prefixes without gaps (0001, 0002, ...).

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'neo4j-data-migrations'

Package not installed or import path incorrect

fix

Run `npm install neo4j-data-migrations` and use `import Migrate from 'neo4j-data-migrations'`

TypeError: (intermediate value).forward is not a function

Migration file does not export an object with a forward function

fix

Ensure migration file exports `module.exports = { name: '...', forward: async (driver) => {...}, backward: async (driver) => {...} }`

Neo4jError: The client is unauthorized due to authentication failure.

Wrong credentials in configuration file

fix

Update `datamigrations/configuration.js` with correct `connection.user` and `connection.password`

Session is closed

Attempting to use a closed session object

fix

Create a new session per operation: `const session = driver.session();` and close after use

Error: Cannot find module 'neo4j-driver'

Neo4j driver not installed when using programmatic API

fix

Install peer dependency: `npm install neo4j-driver`

Upgrade

Version history

1.2.2latest on npm

Audit

Dependencies

neo4j-driverrequiredRequired to connect and run queries against Neo4j database

Agent activity

7 hits · last 30 days

node

Amazon

Resources

githubgit://github.com/abnamrocoesd/neo4j-data-migrations ↗

packageneo4j-data-migrations ↗

homepagehttps://github.com/abnamrocoesd/neo4j-data-migrations#readme ↗