Morpheus Neo4j Migration Tool
raw JSON → 4.5.2 verified Thu Apr 23 auth: no javascript
Morpheus is a modern, open-source command-line interface (CLI) tool designed for managing database migrations in Neo4j graph databases. Currently at version 4.5.2, it follows a regular release cadence with several patch and minor updates typically occurring every few months, and major versions introducing significant architectural changes. Its core functionality involves executing pure Cypher queries from versioned `.cypher` files, ensuring a structured and reproducible migration process. Morpheus differentiates itself by providing a simple, intuitive, and CLI-centric workflow specifically tailored for Neo4j, taking inspiration from similar Java-based migration tools. It relies on environment variables or a configuration file (`morpheus.json`) for Neo4j connection details and does not provide traditional programmatic library imports as of version 4.0.0, shifting entirely to a CLI-first approach.
Common errors
error Morpheus requires Node.js version >= 18.0.0 ↓
cause The installed Node.js version is older than the minimum requirement specified in the package's engines field.
fix
Upgrade your Node.js installation to version 18.0.0 or higher. Use a version manager like
nvm (Node Version Manager) for easy switching (e.g., nvm install 18 && nvm use 18). error Checksum mismatch for migration V[VERSION]__[DESCRIPTION].cypher ↓
cause An existing migration file, which has already been applied to the database, was modified. Morpheus detected that the file's content no longer matches the recorded checksum.
fix
Do not modify migration files after they have been executed. If you need to make changes, create a new migration file (
morpheus create new-feature) that contains the necessary updates or corrections. error Neo4jError: ServiceUnavailable: WebSocket connection timed out ↓
cause Morpheus failed to establish a connection to the Neo4j database. This could be due to incorrect connection details, the Neo4j instance not running, or network issues.
fix
Verify your Neo4j connection settings in
morpheus.json or via environment variables (e.g., MORPHEUS_HOST, MORPHEUS_PORT, MORPHEUS_USERNAME, MORPHEUS_PASSWORD). Ensure your Neo4j database is running and accessible from the machine executing Morpheus. error Invalid input '\n': expected a statement terminator ';' (line X, column Y (offset Z)) ↓
cause A Cypher statement within a migration file is missing its required semicolon terminator.
fix
Review the indicated line and column in your
.cypher migration file and add a semicolon (;) at the end of each distinct Cypher statement. Warnings
breaking Version 4.0.0 introduced a major architectural change, migrating from a NestJS + Commander setup to OCLIF. This change explicitly removed previous programmatic APIs, including NestJS module registration (`register`, `registerAsync`) and the `runMigrationsFor` method. Morpheus is now primarily a CLI-driven tool. ↓
fix Users upgrading from v3.x must refactor their integration to use the `morpheus` CLI commands directly rather than programmatic imports. Consult the v4.0.0 release notes and documentation for new CLI flag syntax and usage.
gotcha Modifying a migration file that has already been executed will result in a 'Checksum mismatch' error during subsequent `morpheus migrate` runs. Morpheus tracks the checksums of applied migrations to prevent accidental tampering. ↓
fix Never modify existing migration files once they have been applied. If changes are needed, create a new migration file (`morpheus create new-changes`) to introduce the updates or rollbacks.
gotcha Every Cypher statement within a `.cypher` migration file must be terminated with a semicolon. Missing semicolons will lead to parsing errors during migration execution. ↓
fix Carefully review your `.cypher` migration files and ensure each individual Cypher query ends with a semicolon.
gotcha Morpheus relies on correct Neo4j connection details. Incorrect host, port, scheme, username, password, or database name will prevent successful connection and migration execution. ↓
fix Verify that your `morpheus.json` configuration or environment variables (MORPHEUS_HOST, MORPHEUS_PORT, MORPHEUS_SCHEME, MORPHEUS_USERNAME, MORPHEUS_PASSWORD, MORPHEUS_DATABASE) match your running Neo4j instance's settings. Ensure the Neo4j database is accessible from where Morpheus is being run.
deprecated The programmatic APIs for integrating Morpheus, such as the `runMigrationsFor` method and the NestJS module's `register` and `registerAsync` methods, were deprecated and subsequently removed in version 4.0.0. ↓
fix For versions 4.0.0 and above, transition to using the `morpheus` command-line interface directly for all migration operations. If programmatic control is still required, consider externalizing CLI calls.
Install
npm install morpheus4j yarn add morpheus4j pnpm add morpheus4j Imports
- morpheus init
morpheus init - morpheus create
morpheus create <migration-name> - morpheus migrate
morpheus migrate
Quickstart
npm install -g morpheus4j
# Ensure Neo4j is running and accessible.
# Configure connection either via morpheus.json or environment variables.
# For example, using environment variables (replace with your actual credentials):
export MORPHEUS_HOST='localhost'
export MORPHEUS_PORT='7687'
export MORPHEUS_SCHEME='neo4j'
export MORPHEUS_USERNAME='neo4j'
export MORPHEUS_PASSWORD='your_neo4j_password' # IMPORTANT: Change this in production!
export MORPHEUS_DATABASE='neo4j'
morpheus init # Creates morpheus.json in the current directory.
morpheus create initial-setup # Creates V1_0_0__initial-setup.cypher
# Open V1_0_0__initial-setup.cypher and add your Cypher statements, e.g.:
# CREATE CONSTRAINT user_email IF NOT EXISTS FOR (u:User) REQUIRE u.email IS UNIQUE;
# CREATE (u:User { email: 'test@example.com', name: 'Test User', created_at: datetime() });
morpheus migrate # Runs pending migrations against the Neo4j database.
morpheus info # View the status of your migrations.