Connection
Once you have installed the driver and have a running Neo4j instance, you are ready to connect your application to the database.
Connect to the database
You connect to a database by creating a Driver object and providing a URL and an authentication token.
package demo;
import org.neo4j.driver.AuthTokens;
import org.neo4j.driver.GraphDatabase;
public class App {
public static void main(String... args) {
// URI examples: "neo4j://localhost", "neo4j+s://xxx.databases.neo4j.io"
final String dbUri = "<URI for Neo4j database>";
final String dbUser = "<Username>";
final String dbPassword = "<Password>";
try (var driver = GraphDatabase.driver(dbUri, AuthTokens.basic(dbUser, dbPassword))) { (1)
driver.verifyConnectivity(); (2)
}
}
}
1 | Creating a Driver instance only provides information on how to access the database, but does not actually establish a connection.
Connection is instead deferred to when the first query is executed. |
2 | To verify immediately that the driver can connect to the database (valid credentials, compatible versions, etc), use the .verifyConnectivity() method after initializing the driver. |
Both the creation of a Driver
object and the connection verification can raise a number of different exceptions.
Since a connection error is a blocker for any subsequent task, the most common choice is to let the program crash should an exception occur while estabilishing a connection.
Driver
objects are immutable, thread-safe, and fairly expensive to create.
You may share them across threads.
If you need to query the database through several different users, use impersonation without creating a new Driver
instance.
If you want to alter a Driver
configuration, you will need to create a new object.
Connect to an Aura instance
When you create an Aura instance, you may download a text file (a so-called Dotenv file) containing the connection information to the database in the form of environment variables.
The file has a name of the form Neo4j-a0a2fa1d-Created-2023-11-06.txt
.
You can either manually extract the URI and the credentials from that file, or use a third party-module to load them.
We recommend the module dotenv-java
for that purpose.
dotenv-java
to extract credentials from a Dotenv filepackage demo;
import io.github.cdimascio.dotenv.Dotenv;
import org.neo4j.driver.AuthTokens;
import org.neo4j.driver.GraphDatabase;
public class App {
public static void main(String... args) {
var dotenv = Dotenv.configure()
//.directory("/path/to/env/file")
.filename("Neo4j-a0a2fa1d-Created-2023-11-06.txt")
.load();
final String dbUri = dotenv.get("NEO4J_URI");
final String dbUser = dotenv.get("NEO4J_USERNAME");
final String dbPassword = dotenv.get("NEO4J_PASSWORD");
try (var driver = GraphDatabase.driver(dbUri, AuthTokens.basic(dbUser, dbPassword))) {
driver.verifyConnectivity();
}
}
}
An Aura instance is not conceptually different from any other Neo4j instance, as Aura is simply a deployment mode for Neo4j. When interacting with a Neo4j database through the driver, it doesn’t make a difference whether it is an Aura instance it is working with or a different deployment. |
Close connections
Always close Driver
objects to free up all allocated resources, even upon unsuccessful connection or runtime errors.
Either create the Driver
object using the try-with-resources
statement, or call the Driver.close()
method explicitly.
Further connection parameters
For more Driver
configuration parameters and further connection settings, see Advanced connection information.
Glossary
- LTS
-
A Long Term Support release is one guaranteed to be supported for a number of years. Neo4j 4.4 is LTS, and Neo4j 5 will also have an LTS version.
- Aura
-
Aura is Neo4j’s fully managed cloud service. It comes with both free and paid plans.
- Cypher
-
Cypher is Neo4j’s graph query language that lets you retrieve data from the database. It is like SQL, but for graphs.
- APOC
-
Awesome Procedures On Cypher (APOC) is a library of (many) functions that can not be easily expressed in Cypher itself.
- Bolt
-
Bolt is the protocol used for interaction between Neo4j instances and drivers. It listens on port 7687 by default.
- ACID
-
Atomicity, Consistency, Isolation, Durability (ACID) are properties guaranteeing that database transactions are processed reliably. An ACID-compliant DBMS ensures that the data in the database remains accurate and consistent despite failures.
- eventual consistency
-
A database is eventually consistent if it provides the guarantee that all cluster members will, at some point in time, store the latest version of the data.
- causal consistency
-
A database is causally consistent if read and write queries are seen by every member of the cluster in the same order. This is stronger than eventual consistency.
- NULL
-
The null marker is not a type but a placeholder for absence of value. For more information, see Cypher → Working with
null
. - transaction
-
A transaction is a unit of work that is either committed in its entirety or rolled back on failure. An example is a bank transfer: it involves multiple steps, but they must all succeed or be reverted, to avoid money being subtracted from one account but not added to the other.
- backpressure
-
Backpressure is a force opposing the flow of data. It ensures that the client is not being overwhelmed by data faster than it can handle.
- transaction function
-
A transaction function is a callback executed by an
executeRead
orexecuteWrite
call. The driver automatically re-executes the callback in case of server failure. - Driver
-
A
Driver
object holds the details required to establish connections with a Neo4j database.