Cypher-Shell: A Command Guide with Examples

Cypher-shell is a powerful command-line tool used to interact with a Neo4j database. It allows users to execute Cypher queries directly against a Neo4j instance, making it an essential tool for database administrators and developers who work with Neo4j. Beyond simple query execution, cypher-shell also supports various options for establishing secure connections, targeting specific databases, and logging query activity, providing a flexible and robust means to manage and interact with Neo4j databases.

Use case 1: Connect to a local instance on the default port

Code:

cypher-shell

Motivation: Often, the simplest use case for cypher-shell arises when developers or database administrators need to quickly connect to a local Neo4j instance to execute some queries or perform maintenance tasks. This command assumes that Neo4j is running on the default host (localhost) and port (7687).

Explanation:

• cypher-shell: This command initiates an interactive session with a Neo4j database running on the local machine at the default address (neo4j://localhost:7687). The assumption here is that the user has not set any custom host or port and is running Neo4j locally.

Example Output:

Connected to Neo4j using Bolt protocol version 4.1 at neo4j://localhost:7687
neo4j>

Use case 2: Connect to a remote instance

Code:

cypher-shell --address neo4j://host:port

Motivation: When working with remote server instances of Neo4j, it’s necessary to specify the particular host and port where the database is located. This situation often applies to production environments or cloud-based Neo4j services.

Explanation:

• cypher-shell: Starts the cypher-shell session.
• --address neo4j://host:port: The --address option is used to specify the full address of the Neo4j instance you are connecting to. You replace host with the remote server’s address and port with the appropriate port number used by the Neo4j instance.

Example Output:

Connected to Neo4j using Bolt protocol version 4.1 at neo4j://remote-host:7687
neo4j>

Use case 3: Connect and supply security credentials

Code:

cypher-shell --username username --password password

Motivation: For Neo4j instances that require user authentication, supplying the correct credentials at the point of connection is crucial. By including the username and password, users can authenticate themselves and gain access to the database.

Explanation:

• cypher-shell: Begins the session.
• --username username: Specifies the username required for logging into the Neo4j instance.
• --password password: This option supplies the associated password for the provided username to authenticate the session.

Example Output:

Connected to Neo4j using Bolt protocol version 4.1 at neo4j://localhost:7687 as user 'username'
neo4j>

Use case 4: Connect to a specific database

Code:

cypher-shell --database database_name

Motivation: In a multi-database environment, it’s essential to direct queries to the appropriate database. This option ensures you are connected to a specific database within your Neo4j instance.

Explanation:

• cypher-shell: Initiates the session.
• --database database_name: This option is used to specify the database you intend to connect to. Replace database_name with the actual name of your target database.

Example Output:

Connected to Neo4j using Bolt protocol version 4.1 at neo4j://localhost:7687 with database 'database_name'
neo4j>

Use case 5: Execute Cypher statements in a file and close

Code:

cypher-shell --file path/to/file.cypher

Motivation: When you have a set of pre-written Cypher queries saved in a file, and you want to execute them non-interactively (i.e., without manually entering commands in the shell), this option is highly convenient. It allows for batch processing of queries.

Explanation:

• cypher-shell: Begins the session.
• --file path/to/file.cypher: Specifies the file containing Cypher statements. On execution, cypher-shell reads from the file and executes the contents before closing the session.

Example Output:

Query results or confirmation of queries executed from file.cypher

Use case 6: Enable logging to a file

Code:

cypher-shell --log path/to/file.log

Motivation: Logging interactions and queries executed via cypher-shell can be beneficial for debugging, auditing, and keeping a record of database operations. It helps track what queries have been run and any issues that may have arisen during execution.

Explanation:

• cypher-shell: Starts the session.
• --log path/to/file.log: Directs the output and activity logs of the cypher-shell session to the specified log file path. path/to/file.log should be replaced with the desired logging file path.

Example Output:

Cypher-shell interactions are logged at path/to/file.log

Use case 7: Display help

Code:

cypher-shell --help

Motivation: When learning cypher-shell or in need of guidance on available options and usage, the help function is an excellent resource. It presents all command-line options and brief descriptions within the terminal.

Explanation:

• cypher-shell: Engages the tool.
• --help: Displays all the available options and their brief descriptions. It’s a quick reference guide for users.

Example Output:

Usage: cypher-shell [<options>]
Options:
  --address address       Address to connect to.
  --username username     User to connect with.
  --password password     Password to connect with.
  ...

Conclusion:

Cypher-shell is a versatile tool that provides various options for connecting and interacting with Neo4j databases. Whether you’re connecting locally, remotely, with security credentials, or aiming to automate query execution, cypher-shell serves as a powerful ally. This guide illustrated the different use cases, highlighting the benefits and contexts in which each command variation can be utilized, ultimately empowering you to leverage the full capabilities of your Neo4j ecosystem.