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 Neo4j database by creating a DriverWithContext object and providing a URL and an authentication token.

package main

import (
    "context"
    "fmt"
    "github.com/neo4j/neo4j-go-driver/v5/neo4j"
)

func main() {
    ctx := context.Background() (2)
    dbUri := "<URI for Neo4j database>"
    dbUser := "<Username>"
    dbPassword := "<Password>"
    driver, err := neo4j.NewDriverWithContext(  (1)
        dbUri,
        neo4j.BasicAuth(dbUser, dbPassword, ""))
    if err != nil {
        panic(err)
    }
    defer driver.Close(ctx)  (4)

    err = driver.VerifyConnectivity(ctx)  (3)
    if err != nil {
        panic(err)
    }
    fmt.Println("Connection established.")
}

1	Creating a `DriverWithContext` 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	Most driver functions require a `context.Context` parameter, see the context package.
3	To verify immediately that the driver can connect to the database (valid credentials, compatible versions, etc), use the `.VerifyConnectivity(ctx)` method after initializing the driver.
4	Always close `DriverWithContext` objects to free up all allocated resources, even upon unsuccessful connection or runtime errors in subsequent querying. The safest practice is to `defer` the call to `DriverWithContext.Close(ctx)` after the object is successfully created. Note that there are corner cases in which `.Close()` might return an error, so you may want to catch that as well.

Driver objects are immutable, thread-safe, and expensive to create, so your application should create only one instance and pass it around (you may share Driver instances across threads). If you need to query the database through several different users, use impersonation without creating a new DriverWithContext instance. If you want to alter a DriverWithContext configuration, you 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 package godotenv for that purpose.

package main

import (
    "context"
    "os"
    "fmt"
    "github.com/joho/godotenv"
    "github.com/neo4j/neo4j-go-driver/v5/neo4j"
)

func main() {
    ctx := context.Background()
    err := godotenv.Load("Neo4j-a0a2fa1d-Created-2023-11-06.txt")
    if err != nil {
        panic(err)
    }
    dbUri := os.Getenv("NEO4J_URI")
    dbUser := os.Getenv("NEO4J_USERNAME")
    dbPassword := os.Getenv("NEO4J_PASSWORD")
    driver, err := neo4j.NewDriverWithContext(
        dbUri,
        neo4j.BasicAuth(dbUser, dbPassword, ""))
    if err != nil {
        panic(err)
    }
    defer driver.Close(ctx)

    err = driver.VerifyConnectivity(ctx)
    if err != nil {
        panic(err)
    }
    fmt.Println("Connection established.")
}

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.

Further connection parameters

For more DriverWithContext 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 or ExecuteWrite call. The driver automatically re-executes the callback in case of server failure.
DriverWithContext: A DriverWithContext object holds the details required to establish connections with a Neo4j database.