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 Connection URI, 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,default}] [-d DATABASE] [--format {auto,verbose,plain}] [-P PARAM] [--debug] [--non-interactive] [--sample-rows SAMPLE-ROWS] [--wrap {true,false}] [-v] [--driver-version] [-f FILE]
                    [--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).

example of piping a file:
  cat some-cypher.txt | cypher-shell

positional arguments:
  cypher                 an optional string of cypher to execute and then exit

optional arguments:
  -h, --help             show this help message and exit
  --fail-fast            exit and report failure on first error when reading from file (this is the default behavior)
  --fail-at-end          exit and report failures at end of input when reading from file
  --format {auto,verbose,plain}
                         desired output format, verbose displays results in tabular format and prints statistics, plain displays data with minimal formatting (default: auto)
  -P PARAM, --param PARAM
                         Add a parameter to this session. Example: `-P "number => 3"`. This argument can be specified multiple times.
  --debug                print additional debug information (default: false)
  --non-interactive      force non-interactive mode, only useful if auto-detection fails (like on Windows) (default: false)
  --sample-rows SAMPLE-ROWS
                         number of rows sampled to compute table widths (only for format=VERBOSE) (default: 1000)
  --wrap {true,false}    wrap table column values if column is too narrow (only for format=VERBOSE) (default: true)
  -v, --version          print version of cypher-shell and exit (default: false)
  --driver-version       print version of the Neo4j Driver used and exit (default: false)
  -f FILE, --file FILE   Pass a file with cypher statements to be executed. After the statements have been executed cypher-shell will be shutdown

connection arguments:
  -a ADDRESS, --address ADDRESS
                         address and port to connect to (default: neo4j://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,default}
                         whether the connection to Neo4j should be encrypted. This must be consistent with Neo4j's configuration. If  choosing  'default'  the  encryption  setting is deduced from the specified address. For example the 'neo4j+ssc' protocol would use encryption.
                         (default: default)
  -d DATABASE, --database DATABASE
                         database to connect to. Can also be specified using environment variable NEO4J_DATABASE (default: )

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 neo4j+s://

We’ll then receive the following prompt:

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

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

username: neo4j
password: *******************************************
Connected to Neo4j 4.1.0 at neo4j+s:// 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 neo4j+s:// -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 neo4j+s:// -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.