{"id":17819,"library":"morpheus4j","title":"Morpheus Neo4j Migration Tool","description":"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.","status":"active","version":"4.5.2","language":"javascript","source_language":"en","source_url":"https://github.com/marianozunino/morpheus","tags":["javascript","oclif","neo4j","migration","database","graph-database","cli","typescript"],"install":[{"cmd":"npm install morpheus4j","lang":"bash","label":"npm"},{"cmd":"yarn add morpheus4j","lang":"bash","label":"yarn"},{"cmd":"pnpm add morpheus4j","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for NestJS integration (though programmatic API was removed in v4).","package":"@nestjs/common","optional":true},{"reason":"Peer dependency for NestJS integration (though programmatic API was removed in v4).","package":"@nestjs/core","optional":true},{"reason":"Required for decorator metadata support, often used with NestJS.","package":"reflect-metadata","optional":true},{"reason":"Reactive programming library, a common dependency in NestJS environments.","package":"rxjs","optional":true}],"imports":[{"note":"Morpheus is primarily a CLI tool. This command initializes the `morpheus.json` configuration file in the current directory.","symbol":"morpheus init","correct":"morpheus init"},{"note":"This command generates a new versioned Cypher migration file (e.g., `V1_0_0__migration-name.cypher`) in your migrations directory.","symbol":"morpheus create","correct":"morpheus create <migration-name>"},{"note":"Executes all pending Cypher migration files against the configured Neo4j database, recording their application.","symbol":"morpheus migrate","correct":"morpheus migrate"}],"quickstart":{"code":"npm install -g morpheus4j\n\n# Ensure Neo4j is running and accessible.\n# Configure connection either via morpheus.json or environment variables.\n# For example, using environment variables (replace with your actual credentials):\nexport MORPHEUS_HOST='localhost'\nexport MORPHEUS_PORT='7687'\nexport MORPHEUS_SCHEME='neo4j'\nexport MORPHEUS_USERNAME='neo4j'\nexport MORPHEUS_PASSWORD='your_neo4j_password' # IMPORTANT: Change this in production!\nexport MORPHEUS_DATABASE='neo4j'\n\nmorpheus init         # Creates morpheus.json in the current directory.\nmorpheus create initial-setup # Creates V1_0_0__initial-setup.cypher\n\n# Open V1_0_0__initial-setup.cypher and add your Cypher statements, e.g.:\n# CREATE CONSTRAINT user_email IF NOT EXISTS FOR (u:User) REQUIRE u.email IS UNIQUE;\n# CREATE (u:User { email: 'test@example.com', name: 'Test User', created_at: datetime() });\n\nmorpheus migrate     # Runs pending migrations against the Neo4j database.\nmorpheus info        # View the status of your migrations.","lang":"bash","description":"Demonstrates global installation, setting up Neo4j connection via environment variables, initializing the configuration, creating a migration file, and finally running the migrations."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Carefully review your `.cypher` migration files and ensure each individual Cypher query ends with a semicolon.","message":"Every Cypher statement within a `.cypher` migration file must be terminated with a semicolon. Missing semicolons will lead to parsing errors during migration execution.","severity":"gotcha","affected_versions":"all"},{"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.","message":"Morpheus relies on correct Neo4j connection details. Incorrect host, port, scheme, username, password, or database name will prevent successful connection and migration execution.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"deprecated","affected_versions":"<4.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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`).","cause":"The installed Node.js version is older than the minimum requirement specified in the package's engines field.","error":"Morpheus requires Node.js version >= 18.0.0"},{"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.","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.","error":"Checksum mismatch for migration V[VERSION]__[DESCRIPTION].cypher"},{"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.","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.","error":"Neo4jError: ServiceUnavailable: WebSocket connection timed out"},{"fix":"Review the indicated line and column in your `.cypher` migration file and add a semicolon (`;`) at the end of each distinct Cypher statement.","cause":"A Cypher statement within a migration file is missing its required semicolon terminator.","error":"Invalid input '\\n': expected a statement terminator ';' (line X, column Y (offset Z))"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}