Repository files navigation

neo4rs is a driver for theNeo4j graph database, written in Rust.

neo4rs implements thebolt specification

This driver is compatible with Neo4j version 5.x and 4.4.Only the latest 5.x version is supported, following theNeo4j Version support policy.

// concurrent querieslet uri ="127.0.0.1:7687";let user ="neo4j";let pass ="neo";let graph =Graph::new(&uri, user, pass).unwrap();for _in1..=42{let graph = graph.clone();        tokio::spawn(asyncmove{letmut result = graph.execute(query("MATCH (p:Person {name: $name}) RETURN p").param("name","Mark")).await.unwrap();whileletSome(row) = result.next().await.unwrap(){let node:Node = row.get("p").unwrap();let name:String = node.get("name").unwrap();println!("{}", name);}});}//Transactionsletmut txn = graph.start_txn().await.unwrap();    txn.run_queries(["CREATE (p:Person {name: 'mark'})","CREATE (p:Person {name: 'jake'})","CREATE (p:Person {name: 'luke'})",]).await.unwrap();    txn.commit().await.unwrap();//or txn.rollback().await.unwrap();

The crate has a minimum supported Rust version (MSRV) of1.75.0 as of 0.9.x.The version0.8.x has an MSRV of1.63.0

A change in the MSRV innot considered a breaking change.For versions past 1.0.0, a change in the MSRV can be done in a minor version increment (1.1.3 -> 1.2.0)for versions before 1.0.0, a change in the MSRV can be done in a patch version increment (0.1.3 -> 0.1.4).

Only Bolt protocol versions 4.0 and 4.1 are supported.Support for later versions is planned and in progress.

This means, that certain features like bookmarks or element IDs are not supported yet.

This crate contains unit tests and integration tests.The unit tests are run withcargo test --lib and do not require a running Neo4j instance.The integration tests are run withcargo test and require a running Neo4j instance.

To run the tests, you need to have either docker or an existing Neo4j instance running.Docker is recommended since the tests don't necessarily clean up after themselves.

To run the tests with docker, you need to have docker installed and running.You can control the version of Neo4j that is used by setting theNEO4J_VERSION_TAG environment variable.The default version is4.2.The tests will use the officialneo4j docker image, with the provided version as tag.

You might run into panics or test failures with the message 'failed to start container'.In that case, try to pull the image first before running the tests withdocker pull neo4j:$NEO4J_VERSION_TAG.

This could happen if you are on a machine with an architecture that is not supported by the image, e.g.arm64 like the Apple silicon Macs.In that case, pulling the image will fail with a message like 'no matching manifest for linux/arm64/v8'.You need to use the--platform flag to pull the image for a different architecture, e.g.docker pull --platform linux/amd64 neo4j:$NEO4J_VERSION_TAG.There is an experimental option in docker to use Rosetta to run those images, so that tests don't take forever to run (please check the docker documentation).

You could also use a newer neo4j version like4.4 instead, which has support forarm64 architecture.

To run the tests with an existing Neo4j instance, you need to have theNEO4J_TEST_URI environment variable set to the connection string, e.g.neo4j+s://42421337thisisnotarealinstance.databases.neo4j.io.The default user isneo4j, but it can be changed with theNEO4J_TEST_USER environment variable.The default password isneo, but it can be changed with theNEO4J_TEST_PASS environment variable.

Some tests might run different queries depending on the Neo4j version.You can use theNEO4J_VERSION_TAG environment variable to set the version of the Neo4j instance.

It is recommended to only run a single integration test and manually clean up the database after the test.

env NEO4J_TEST_URI=bolt://localhost:7687 NEO4J_TEST_USER=neo4j NEO4J_TEST_PASS=supersecret NEO4J_VERSION_TAG=5.8 cargotest --test<name of the integration test, see the file namesin lib/tests/>

Running a test against an Aura instance can be done by setting the values as outlined above.However, the environment variables used do not match the names that are given in the connection file when an Aura instance is created.

By setting the environment variableNEO4RS_TEST_ON_AURA to1, the tests will look for the environment variables as they are used in the connection file.The tests can then also be run by using adotenv like tool, e.g.

dotenvx run -f .auraenv -e NEO4RS_TEST_ON_AURA=1 -- cargotest

We have CI tests that verify the MSRV as well as the minimal version of the dependencies.The minimal versions are the lowest version that still satisfies theCargo.toml entries, instead of the default of the highest version.

If you change anything in theCargo.toml, you need to update theCargo.lock files for CI.

This project usesxtasks to help with updating the lock files.

It is recommended to close all editors, or more specifically, all rust-analyzer instances for this project before running the commands below.

# If there are errors, update Cargo.toml to fix and try again from the top.# You might have to downgrade or remove certain crates to hit the MSRV.# A number of such downgrades are already defined in the `update_msrv_lock` function# in the xtask script.# Alternatively, you might suggest an increase of the MSRV.cargo xtask msrv

Usingxtask requires thatcurl andjq are available on the system.

# If there are errors, update Cargo.toml to fix and try again from the top.cargo xtask min

Usingxtask requires thatcurl andjq are available on the system.

Neo4rs is licensed under either of the following, at your option:

• Apache License, Version 2.0, (LICENSE-APACHE orhttp://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT orhttp://opensource.org/licenses/MIT)