Chapter 1. Get started

This section gives an overview of the official Neo4j drivers and how to connect to a Neo4j database with a "Hello World" example.

1.1. About the official drivers

Neo4j provides official drivers for many popular programming languages. These drivers are supported by Neo4j and come with full cluster routing support.

Community drivers also exist for many languages, but vary greatly in terms of feature sets, maturity, and support. To find out more about community drivers, visit https://neo4j.com/developer/language-guides/.

The following languages and frameworks are officially supported by Neo4j:

Table 1.1. Supported languages and frameworks for the 1.x driver series
Language/framework Versions supported

Java

Java 8+ (latest patch releases).

Python

CPython 2.7, 3.4, 3.5, 3.6 and 3.7 (latest patch releases).

Note that Python 2 support is deprecated and will be discontinued in the 2.x series drivers.

JavaScript

All LTS versions of Node.JS, specifically the 4.x and 6.x series runtimes (https://github.com/nodejs/LTS).

.NET

.NET standard 1.3 (https://github.com/dotnet/standard/blob/master/docs/versions.md) and .NET 4.5.2 and above.

Go

Go 1.10, 1.11 (latest patch releases).

The driver API is intended to be topologically agnostic. This means that the underlying database topology — single instance, Causal Cluster, etc. — can be altered without requiring a corresponding alteration to application code. In the general case, only the connection URI needs to be modified when changes are made to the topology.

The official drivers do not support HTTP communication. If you need an HTTP driver, choose one of the community drivers. See also the HTTP API documentation.

1.2. Driver versions and installation

The driver major.minor version number describes the feature set available within that driver. Across languages, drivers are generally released at similar times, although patches are driver-dependent. The 1.x series drivers have been built for Neo4j 3.x.

It is recommended to always use the latest driver release available. This will ensure that all server functionality is made available to client applications. To install a driver or to find out more about which driver versions are available, use the relevant language distribution system, described below.

Example 1.1. Acquire the driver

To find out the latest version of the driver, visit https://www.nuget.org/packages/Neo4j.Driver/.

To install the latest version of the driver using NuGet in Visual Studio:

PM> Install-Package Neo4j.Driver

You can also choose to install a certain version of the driver.

Below is the syntax for installing a certain version of the driver.

PM> Install-Package Neo4j.Driver -Version $DOTNET_DRIVER_VERSION

In the following example we are installing driver version 1.7.2.

PM> Install-Package Neo4j.Driver -Version 1.7.2

You can review the release notes for this driver here.

To find out the latest version of the driver, visit https://github.com/neo4j/neo4j-go-driver/releases.

In order to get go driver running, you need to install our C connector, seabolt, on your build and production environments. Follow instructions at https://github.com/neo4j-drivers/seabolt for installing seabolt through one of our binary packages or by building from scratch.

The go driver makes use of cgo and pkg-config to build against seabolt and thus requires a working cgo and pkg-config environment on your build environment.

To install the latest version of the driver using go get:

go get github.com/neo4j/neo4j-go-driver

To install the latest version of the driver using dep:

dep ensure github.com/neo4j/neo4j-go-driver

You can also choose to install a certain version of the driver. Below is the syntax for using a certain minor version of the driver. Visit https://golang.github.io/dep/docs/Gopkg.toml.html#version-rules for a detailed description of version rules that can be used.

dep ensure github.com/neo4j/neo4j-go-driver@1.7.x

You can review the release notes for this driver here.

To find out the latest version of the driver, visit the maven repository.

Example 1.2. Install the Java driver using Maven

When using Maven, add the following block to your pom.xml file. Note the placeholder for the driver version. You will have to find out the exact patch version that you wish to install.

<dependencies>
    <dependency>
        <groupId>org.neo4j.driver</groupId>
        <artifactId>neo4j-java-driver</artifactId>
        <version>$JAVA_DRIVER_VERSION</version>
    </dependency>
</dependencies>

In the following example we are adding driver version 1.7.5.

<dependencies>
    <dependency>
        <groupId>org.neo4j.driver</groupId>
        <artifactId>neo4j-java-driver</artifactId>
        <version>1.7.5</version>
    </dependency>
</dependencies>
Example 1.3. Add the dependency for the Java driver for Gradle or Grails

For Gradle or Grails, this is how to add the dependency. Again, note the placeholder for the driver version. You will have to find out the exact patch version that you wish to install.

compile 'org.neo4j.driver:neo4j-java-driver:$JAVA_DRIVER_VERSION'

In the following example we are adding driver version 1.7.5.

compile 'org.neo4j.driver:neo4j-java-driver:1.7.5'

You can review the release notes for this driver here.

Use npm to find out the latest version of the driver:

npm show neo4j-driver@* version

To install the latest version of the driver:

npm install neo4j-driver

You can also choose to install a certain version of the driver.

Below is the syntax for installing a certain version of the driver.

npm install neo4j-driver@$JAVASCRIPT-DRIVER-VERSION

In the following example we are installing driver version 1.7.6.

npm install neo4j-driver@1.7.6

You can review the release notes for this driver here.

To find out the latest version of the driver, visit https://pypi.python.org/pypi/neo4j-driver.

To install the latest version of the driver:

pip install neo4j-driver

You can also choose to install a certain version of the driver.

The following is the syntax for installing a certain version of the driver.

pip install neo4j-driver==$PYTHON_DRIVER_VERSION

In the following example we are installing driver version 1.7.4.

pip install neo4j-driver==1.7.4

You can review the release notes for this driver here.

1.3. A "Hello World" example

The example below shows the minimal configuration necessary to interact with Neo4j through a driver.

Example 1.4. Hello World
public class HelloWorldExample : IDisposable
{
    private readonly IDriver _driver;

    public HelloWorldExample(string uri, string user, string password)
    {
        _driver = GraphDatabase.Driver(uri, AuthTokens.Basic(user, password));
    }

    public void PrintGreeting(string message)
    {
        using (var session = _driver.Session())
        {
            var greeting = session.WriteTransaction(tx =>
            {
                var result = tx.Run("CREATE (a:Greeting) " +
                                    "SET a.message = $message " +
                                    "RETURN a.message + ', from node ' + id(a)",
                    new {message});
                return result.Single()[0].As<string>();
            });
            Console.WriteLine(greeting);
        }
    }

    public void Dispose()
    {
        _driver?.Dispose();
    }

    public static void Main()
    {
        using (var greeter = new HelloWorldExample("bolt://localhost:7687", "neo4j", "password"))
        {
            greeter.PrintGreeting("hello, world");
        }
    }
}
func helloWorld(uri, username, password string) (string, error) {
	var (
		err      error
		driver   neo4j.Driver
		session  neo4j.Session
		result   neo4j.Result
		greeting interface{}
	)

	driver, err = neo4j.NewDriver(uri, neo4j.BasicAuth(username, password, ""))
	if err != nil {
		return "", err
	}
	defer driver.Close()

	session, err = driver.Session(neo4j.AccessModeWrite)
	if err != nil {
		return "", err
	}
	defer session.Close()

	greeting, err = session.WriteTransaction(func(transaction neo4j.Transaction) (interface{}, error) {
		result, err = transaction.Run(
			"CREATE (a:Greeting) SET a.message = $message RETURN a.message + ', from node ' + id(a)",
			map[string]interface{}{"message": "hello, world"})
		if err != nil {
			return nil, err
		}

		if result.Next() {
			return result.Record().GetByIndex(0), nil
		}

		return nil, result.Err()
	})
	if err != nil {
		return "", err
	}

	return greeting.(string), nil
}
public class HelloWorldExample implements AutoCloseable
{
    private final Driver driver;

    public HelloWorldExample( String uri, String user, String password )
    {
        driver = GraphDatabase.driver( uri, AuthTokens.basic( user, password ) );
    }

    @Override
    public void close() throws Exception
    {
        driver.close();
    }

    public void printGreeting( final String message )
    {
        try ( Session session = driver.session() )
        {
            String greeting = session.writeTransaction( new TransactionWork<String>()
            {
                @Override
                public String execute( Transaction tx )
                {
                    StatementResult result = tx.run( "CREATE (a:Greeting) " +
                                                     "SET a.message = $message " +
                                                     "RETURN a.message + ', from node ' + id(a)",
                            parameters( "message", message ) );
                    return result.single().get( 0 ).asString();
                }
            } );
            System.out.println( greeting );
        }
    }

    public static void main( String... args ) throws Exception
    {
        try ( HelloWorldExample greeter = new HelloWorldExample( "bolt://localhost:7687", "neo4j", "password" ) )
        {
            greeter.printGreeting( "hello, world" );
        }
    }
}
const driver = neo4j.driver(uri, neo4j.auth.basic(user, password))
const session = driver.session()

const resultPromise = session.writeTransaction(tx =>
  tx.run(
    'CREATE (a:Greeting) SET a.message = $message RETURN a.message + ", from node " + id(a)',
    { message: 'hello, world' }
  )
)

resultPromise.then(result => {
  session.close()

  const singleRecord = result.records[0]
  const greeting = singleRecord.get(0)

  console.log(greeting)

  // on application exit:
  driver.close()
})
class HelloWorldExample(object):

    def __init__(self, uri, user, password):
        self._driver = GraphDatabase.driver(uri, auth=(user, password))

    def close(self):
        self._driver.close()

    def print_greeting(self, message):
        with self._driver.session() as session:
            greeting = session.write_transaction(self._create_and_return_greeting, message)
            print(greeting)

    @staticmethod
    def _create_and_return_greeting(tx, message):
        result = tx.run("CREATE (a:Greeting) "
                        "SET a.message = $message "
                        "RETURN a.message + ', from node ' + id(a)", message=message)
        return result.single()[0]

1.4. Driver API docs

For a comprehensive listing of all driver functionality, refer to the API documentation for the specific language driver.