morpheus4j

library4.5.2jsnpmunverified

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.

database

npm install morpheus4j

github ↗package ↗

INSTALL

IMPORT

SIG · MORPHEUS4J

morpheus4j

databasejavascriptv4.5.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

morpheus init

✓ morpheus init

Morpheus is primarily a CLI tool. This command initializes the `morpheus.json` configuration file in the current directory.

morpheus create

✓ morpheus create <migration-name>

This command generates a new versioned Cypher migration file (e.g., `V1_0_0__migration-name.cypher`) in your migrations directory.

morpheus migrate

✓ morpheus migrate

Executes all pending Cypher migration files against the configured Neo4j database, recording their application.

Demonstrates global installation, setting up Neo4j connection via environment variables, initializing the configuration, creating a migration file, and finally running the migrations.

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.

morpheus --version

Debug

Known issues

breakingVersion 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.

affects: >=4.0.0

gotchaModifying 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.

affects: all

gotchaEvery 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.

affects: all

gotchaMorpheus 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.

affects: all

deprecatedThe 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.

affects: <4.0.0

Errors

Common errors & fixes

Morpheus requires Node.js version >= 18.0.0

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`).

Checksum mismatch for migration V[VERSION]__[DESCRIPTION].cypher

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.

Neo4jError: ServiceUnavailable: WebSocket connection timed out

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.

Invalid input '\n': expected a statement terminator ';' (line X, column Y (offset Z))

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.

Upgrade

Version history

4.5.2latest on npm

Audit

Dependencies

@nestjs/commonoptionalPeer dependency for NestJS integration (though programmatic API was removed in v4).

@nestjs/coreoptionalPeer dependency for NestJS integration (though programmatic API was removed in v4).

reflect-metadataoptionalRequired for decorator metadata support, often used with NestJS.

rxjsoptionalReactive programming library, a common dependency in NestJS environments.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/marianozunino/morpheus ↗

packagehttps://www.npmjs.com/package/morpheus4j ↗