Connecting to Neo4j Aura with Cypher Shell

In this page, we will learn how to connect to our Neo4j Aura database using the Cypher Shell command line tool.
We should have created and started a Neo4j Aura database instance. If we have not already, we can follow the instructions in the getting started guide to step through the process. We should also have installed the Cypher Shell command line tool.


Get database credentials

If we open our Neo4j Aura Console Dashboard, we’ll see a list of our databases.

We’ll need to use the Bolt URL, so let’s copy that onto our clipboard:

We’re now ready to connect to the Cypher Shell.

Connecting to Cypher Shell

If we have Neo4j installed locally we can find the Cypher Shell in the bin directory of the database.

In the following examples we’ll use the standalone version of the tool, which we can download from the Neo4j Download Center. Once we’ve downloaded the zip file, we’ll run the following commands:

cd cypher-shell

Let’s learn what arguments we need to pass to the tool to connect to our database.

./cypher-shell --help

If we run that command we’ll see the following output, which has been edited for brevity:

usage: cypher-shell [-h] [-a ADDRESS] [-u USERNAME] [-p PASSWORD] [--encryption {true,false}] [--format {auto,verbose,plain}] [--debug] [--non-interactive] [--sample-rows SAMPLE-ROWS] [--wrap {true,false}] [-v] [--driver-version] [--fail-fast | --fail-at-end] [cypher]

A command line shell where you can execute Cypher against an instance of Neo4j. By default the shell is interactive but you can use it for scripting by passing cypher directly on the command line or by piping a file with cypher statements (requires Powershell on Windows).

connection arguments:
  -a ADDRESS, --address ADDRESS
                         address and port to connect to (default: bolt://localhost:7687)
  -u USERNAME, --username USERNAME
                         username to connect as. Can also be specified using environment variable NEO4J_USERNAME (default: )
  -p PASSWORD, --password PASSWORD
                         password to connect with. Can also be specified using environment variable NEO4J_PASSWORD (default: )
  --encryption {true,false}
                         whether the connection to Neo4j should be encrypted; must be consistent with Neo4j's configuration (default: true)

We need to pass in our database URI to the -a argument. We can also optionally pass in user to the -u argument, and password to the -p argument, but we will be prompted for those values if we don’t provide them.

If we run the following command:

 ./cypher-shell -a bolt+routing://

We’ll then receive the following prompt:

username: neo4j
password: **********************************************

Once we’ve provided those details, we’ll see the following message:

Connected to Neo4j 3.5.0 at bolt+routing:// as user neo4j.
Type :help for a list of available commands or :exit to exit the shell.
Note that Cypher queries must end with a semicolon.

We can now run queries against our Cloud database. For example, we can run the following procedure to return the logged in user:

neo4j> CALL dbms.showCurrentUser();
userName roles flags




Importing data using the Cypher Shell

We could also pipe a file containing Cypher commands to the Cypher Shell command. This feature is useful for doing data import.

We have a file import.cypher that contains some of the Cypher statements from the Graph Model Refactoring developer guide. We can view the contents of that file by executing the following command from the terminal:

cat import.cypher
CREATE CONSTRAINT ON (airport:Airport)
ASSERT airport.code IS UNIQUE;

MERGE (origin:Airport {code: row.Origin})
MERGE (destination:Airport {code: row.Dest})
MERGE (origin)-[connection:CONNECTED_TO {
  airline: row.UniqueCarrier,
  flightNumber: row.FlightNum,
  date: date({year: toInteger(row.Year), month: toInteger(row.Month), day: toInteger(row.DayofMonth)}),
  cancelled: row.Cancelled,
  diverted: row.Diverted}]->(destination)
ON CREATE SET connection.departure = localtime(apoc.text.lpad(row.CRSDepTime, 4, "0")),
              connection.arrival = localtime(apoc.text.lpad(row.CRSArrTime, 4, "0"));

MATCH (:Airport)-[connectedTo:CONNECTED_TO]->(:Airport)
CALL apoc.refactor.normalizeAsBoolean(connectedTo, "diverted", ["1"], ["0"])
RETURN count(*)

Now we’re going to import this data into our Neo4j Cloud database, via the Cypher Shell command. We’ll do this by executing the following:

export NEO4J_PASSWORD="your password"
cat import.cypher | ./cypher-shell -a bolt+routing:// -u neo4j --format verbose

If we pipe a file into the Cypher Shell command, we won’t be prompted for our username and password, it will use default values if they aren’t provided.

If we run those commands, we’ll see the following output:

0 rows available after 1 ms, consumed after another 0 ms
0 rows available after 336 ms, consumed after another 0 ms
Added 62 nodes, Created 1000 relationships, Set 7062 properties, Added 62 labels

We can now execute a read query to see what data we’ve imported into our database:

./cypher-shell -a bolt+routing:// -u neo4j "MATCH path = ()-->() RETURN path LIMIT 10"

If we execute this command, we’ll see the following output:


(:Airport {code: "IAD"})-[:CONNECTED_TO {date: 2008-01-03, diverted: "0", arrival: 10:00, cancelled: "0", departure: 07:35, airline: "WN", flightNumber: "3231"}]→(:Airport {code: "TPA"})

(:Airport {code: "IAD"})-[:CONNECTED_TO {date: 2008-01-03, diverted: "0", arrival: 22:25, cancelled: "0", departure: 19:55, airline: "WN", flightNumber: "335"}]→(:Airport {code: "TPA"})

(:Airport {code: "IND"})-[:CONNECTED_TO {date: 2008-01-03, diverted: "0", arrival: 15:10, cancelled: "0", departure: 12:55, airline: "WN", flightNumber: "4"}]→(:Airport {code: "TPA"})

(:Airport {code: "IND"})-[:CONNECTED_TO {date: 2008-01-03, diverted: "0", arrival: 09:55, cancelled: "0", departure: 07:45, airline: "WN", flightNumber: "1144"}]→(:Airport {code: "PHX"})

(:Airport {code: "IND"})-[:CONNECTED_TO {date: 2008-01-03, diverted: "0", arrival: 16:25, cancelled: "0", departure: 14:25, airline: "WN", flightNumber: "675"}]→(:Airport {code: "PHX"})

(:Airport {code: "IND"})-[:CONNECTED_TO {date: 2008-01-03, diverted: "0", arrival: 10:10, cancelled: "0", departure: 10:20, airline: "WN", flightNumber: "2272"}]→(:Airport {code: "MDW"})

(:Airport {code: "IND"})-[:CONNECTED_TO {date: 2008-01-03, diverted: "0", arrival: 16:55, cancelled: "0", departure: 17:00, airline: "WN", flightNumber: "1827"}]→(:Airport {code: "MDW"})

(:Airport {code: "IND"})-[:CONNECTED_TO {date: 2008-01-03, diverted: "0", arrival: 07:10, cancelled: "0", departure: 07:15, airline: "WN", flightNumber: "1016"}]→(:Airport {code: "MDW"})

(:Airport {code: "IND"})-[:CONNECTED_TO {date: 2008-01-03, diverted: "0", arrival: 14:25, cancelled: "0", departure: 14:30, airline: "WN", flightNumber: "829"}]→(:Airport {code: "MDW"})

(:Airport {code: "IND"})-[:CONNECTED_TO {date: 2008-01-03, diverted: "0", arrival: 17:25, cancelled: "0", departure: 15:10, airline: "WN", flightNumber: "1333"}]→(:Airport {code: "MCO"})

Help and Questions

Helpful guides and support are available on the Aura support pages.

You can also ask questions and connect with other people launching Neo4j Aura at the cloud topic on the Community Site.