Contact Us 1-800-596-4880
  1. Homepage
  2. Neo4j Connector (4.0)

  3. Upgrade and Migrate Neo4j Connector

All Connectors

Upgrading and Migrating Neo4j Connector to Version 4.0.0

Upgrade Anypoint Connector for Neo4j (Neo4j Connector) to version 4.0.0.

Supported Upgrade Paths

From Version To Version

3.0.x

4.0.0

Changes in This Release

This release contains significant changes:

  • Upgraded the Neo4j Java driver from version 1.7.6 to 5.28.8.

  • Updated Neo4j server requirements to version 4.4 and later (previously supported Neo4j 3.x).

  • Required minimum JDK 17 (upgraded from JDK 8).

  • Updated minimum Mule runtime engine (Mule) to 4.9.0 (upgraded from 4.1.x).

  • Removed the REST URL parameter from the connector configuration.

  • Overhauled input and output metadata resolution for a better Anypoint Studio experience.

  • Provided full compatibility with Neo4j 5.x and 2025.x server features.

  • Gained access to reactive APIs, multi-database support, and enhanced security.

  • Updated Docker configuration settings to use current Neo4j standards.

  • Changed the connector to only require a BOLT URL configuration.

  • Changed all metadata operations to use native Cypher queries through a BOLT connection instead of REST API calls.

Requirements

Ensure that you meet these requirements before you perform the upgrade.

Neo4j Server Requirements

  • The minimum Neo4j server version required is 4.4 LTS or later.

  • The recommended versions are Neo4j 5.26 LTS or Neo4j 2025.06+.

  • Neo4j 3.x servers are no longer supported.

Java Runtime Requirements

  • The minimum JDK version required is 17

  • The only supported JDK version is 17

  • JDK 8 and 11 are no longer supported

Mule Requirements

  • Minimum Mule version 4.9.0, required for JDK 17 support and unified connectors parent compatibility

  • Mule versions 4.1.x - 4.8.x not supported

Development Environment

  • Anypoint Studio latest version supporting Mule Runtime 4.9.0+

  • Maven version supporting JDK 17+

Considerations

Before you perform the upgrade, be aware of these known limitations:

  • Restore from backup to roll back after upgrading the connector.

  • Avoid using Neo4j 3.x servers with connector version 4.0.0.

  • Ensure Mule applications run on Mule 4.9.0+ and JDK 17+.

  • Update existing configurations that use the REST URL parameter.

  • Re-test all existing connections after upgrading the connector.

  • Refresh Studio metadata for the connector operations.

  • Upgrade test servers to Neo4j version 4.4+ before performing connector testing.

  • Use a JDK 17+ toolchain for Maven builds.

Upgrade Prerequisites

Before you perform the upgrade, you must complete the following.

Prepare Your Environment

  1. Create a backup of your Mule applications, data, and configurations

  2. Upgrade Neo4j Server to version 4.4 LTS or later (if currently using Neo4j 3.x)

  3. Upgrade Mule to version 4.9.0 or higher

  4. Upgrade JDK to version 17 or higher on all environments (development, test, production)

Asses Mule Application

  1. Review existing configurations to identify REST URL usage.

  2. Document current BOLT URL settings for post-upgrade validation.

  3. Test connectivity to make sure Neo4j servers are accessible via BOLT protocol.

  4. Identify custom error handling that references connector-specific error types.

Upgrade the Connector in Anypoint Code Builder

Follow these steps to perform the upgrade:

  1. In Explorer, right-click the configuration XML file in your integration project, and select Project Properties.

  2. In Project Properties, select Connectors.

  3. Select the latest version for the connector, and click Apply.

Upgrade the Connector in Studio

Follow these steps to perform the upgrade:

  1. In Anypoint Studio, open your existing Mule project.

  2. In Mule Palette, click Search in Exchange.

  3. In Add Dependencies to Project, enter neo4j in the search field.

  4. In Available modules, select Neo4j Connector and click Add.

  5. Click Finish.

  6. Verify that the Neo4j Connector <dependency> version is 4.0.0 in the pom.xml file in the Mule project:

    <dependency>
  <groupId>com.mulesoft.connectors</groupId>
  <artifactId>mule-neo4j-connector</artifactId>
  <version>4.0.0</version>
  <classifier>mule-plugin</classifier>
</dependency>

Studio upgrades the connector automatically, but configuration changes are required.

Post Upgrade Steps

After you install the latest version of the connector, follow these steps to complete the upgrade:

Remove REST URL Parameter

The REST URL parameter is no longer supported in the connector configuration. Update your configurations:

Before (Version 3.x):

<neo4j:config name="Neo4j_Config" doc:name="Neo4j Config">
    <neo4j:connection username="${config.username}"
                     password="${config.password}"
                     boltUrl="${config.boltUrl}"
                     restUrl="${config.restUrl}" />
</neo4j:config>

After (Version 4.0.0):

<neo4j:config name="Neo4j_Config" doc:name="Neo4j Config">
    <neo4j:connection username="${config.username}"
                     password="${config.password}"
                     boltUrl="${config.boltUrl}" />
</neo4j:config>

Update Connection Properties

Remove the REST URL property from your configuration files:

Before:

config.username=<USERNAME>
config.password=<PASSWORD>
config.boltUrl=<BOLT_URL_ENDPOINT>
config.restUrl=<REST_URL_ENDPOINT>  <!-- Remove this line -->

After:

config.username=<USERNAME>
config.password=<PASSWORD>
config.boltUrl=<BOLT_URL_ENDPOINT>

Update Runtime Environment

  1. Make sure all environments are running on Mule 4.9.0+.

  2. Verify all environments are using JDK 17+.

  3. Make sure Neo4j servers are version 4.4+ or 5.x.

Refresh Metadata

  1. Regenerate metadata in Anypoint Studio for improved design-time experience.

  2. Test the connector operations to ensure metadata is properly resolved.

  3. Validate the DataWeave expressions benefit from enhanced type information.

Verify the Upgrade

After you install the latest version of the connector, verify the upgrade:

  1. Make sure no REST URL references remain in configurations.

  2. Verify the pom.xml file shows version 4.0.0 of the Neo4j Connector.

  3. Use the Test Connection feature to validate BOLT connectivity.

  4. Check that the operations show comprehensive field suggestions in Studio.

  5. Execute existing unit tests to ensure functionality is preserved.

  6. Verify no deprecation warnings appear during application startup.

Troubleshooting

If you encounter issues, perform these troubleshooting ste[s].

Troubleshoot Connection Failures After Upgrade

If the connector cannot connect to Neo4j server after upgrade, follow these steps:

  1. Verify that the Neo4j server is version 4.4+ (Neo4j 3.x is no longer supported).

  2. Make sure the BOLT protocol is enabled on Neo4j server.

  3. Remove any REST URL references from the configuration.

Error example:
Neo4j.ClientError.Security.Unauthorized

Therefore, verify credentials and server accessibility via BOLT port (default 7687).

Troubleshoot Metadata Not Displaying in Studio

If the connector operations show empty metadata or missing field suggestions, try these steps to solve the issue:

  1. Ensure sample data exists in your Neo4j database for the labels you’re using.

  2. Regenerate metadata by refreshing the connector in Studio.

  3. Verify the BOLT connection is working properly.

Troubleshoot Runtime Compatibility Issues

If the Mule application fails to start with JDK or Mule runtime errors, try these steps:

  1. Upgrade to JDK 17+ (JDK 8/11 no longer supported).

  2. Upgrade to Mule Runtime 4.9.0+ (earlier versions incompatible).

  3. Update Maven build configuration for JDK 17 compatibility.

Revert the Upgrade

If you need to revert to the previous version of Neo4j Connector, go to Anypoint Studio and in the project’s pom.xml file, change the mule-neo4j-connector dependency version 3.0.0 to the previous version.

Reverting requires restoring to environments compatible with version 3.x requirements.

See Also

Back to top
View on GitHub