Run Cypher Without Leaving Your IDE With Neo4j VSCode Extension

The main features of the plugin: Manage connections to Neo4j instances in the Sidebar, manage query parameters and run Cypher from a file or text selection.

How did we get here?

As a developer building Neo4j Applications in VS Code, I often switch between my code editor and other tools like Neo4j Browser when writing more complex Cypher statements. Constantly switching between the code editor and other windows to write and execute queries can take a toll on productivity. Not only does it take up a lot of time, but I also find it also disrupts my workflow and productivity.

I started experimenting with custom VS Code extensions a few years ago but quickly got distracted by other things. The code sat dormant until recently when a colleague asked me what state it was in. That seeded an idea in my mind that others would really find this useful.

I got talking to a few others, partly fuelled by frustration while working to a tight deadline before the holiday break, and partly motivated by the brilliant Prisma extension. I decided I had to pick this up when I returned to my desk in January.

Introducing the Neo4j VS Code Extension 🎉

As a first release, I’ll target a few pain points that I commonly experience myself:

  • I often write Cypher queries in Neo4j Browser and then copy and paste the code into a Python, Node.js, or Typescript file.
  • If I get something wrong in the Cypher statement, it can be difficult to identify and debug.
  • Code highlighting packages for Cypher already exist but aren’t feature complete.
  • I don’t like having too many windows open at once.

The Neo4j VSCode Extension tackles these issues by providing a new Status bar menu that lists connections.

A quick command will allow you to copy and paste the URL of your Neo4j instance to add a connection.

Once you have added a connection, you can run a command to execute the currently highlighted text or the entire file contents against the database within a read or write transaction. The commands have a keybinding assigned to them, so you can even hit Ctrl+Alt+Space on Windows or Ctrl+Cmd+Space on Mac to execute the query.

The extension is configured to register Cypher as a language in its own right while at the same time adding highlighting and auto-closing bracket pairs. I have also included a quick subset of commonly used Cypher code snippets, and I plan to add more over time:

  • node pattern, relationship patterns — out, in
  • SET

Installation and Usage

You can install the extension within the IDE by searching for Neo4j or the from the Visual Studio Marketplace. Once installed, you can access a list of database connections by clicking the Neo4j logo in the Activity Bar on the left-hand side.

The Neo4j Status Bar, with database and Cypher parameters listed.

Adding a new Database Connection

You can add a database connection in three ways, all available through the Command Palette.

You can configure a new connection using the Neo4j: Add Connection command.

Add Neo4j Connection

To quickly add a connection to your local server at neo4j://localhost:7687you can use the Neo4j: Add Local Connection command.

Add Local Neo4j Connection

You can copy and paste the Connection URL directly from the Neo4j Aura console using the Neo4j: Add Aura Connection command.

AuraDB Console

You can switch your active database connection anytime using the Neo4j: Set Active Connection command or by clicking the connection URL in the status bar at the bottom of the screen.

Add Neo4j Aura Connection

Running Cypher Queries

Once an active connection is set, you can run a Cypher statement in a read transaction using the Neo4j: Run Cypher Statement in a Read Transaction command, or write to the database using the Neo4j: Run Cypher Statement in a Write Transaction command.

Run Statement

You can also use the multi-cursor functionality to execute multiple statements simultaneously. Each result will open in a new window so no data is lost.

Run Multiple Statements

If you have a Cypher statement within a larger file, such as a JavaScript module, you can highlight the Cypher you want to execute and run the command. If you are missing any $parameters, the extension will prompt you for the missing values.

Execute Highlighted Statement

If your query requires $parameters, you can set them using the Neo4j: Set Parameter command. If you no longer require the parameter, you can run the Neo4j: Remove Parameter command and select the key of the parameter you want to remove.

Remove Parameter

Bugs, Feedback & Suggestions

I would love to hear what you think about the extension. If you have any questions, comments, or feature requests you can contact me via Twitter, Mastodon, LinkedIn, or open an Issue on the Github repository. Pull requests are also welcome!

Repository and Marketplace Items

To learn more about Neo4j, head to Neo4j GraphAcademy for free online, hands-on, self-paced courses.

Run Cypher without leaving your IDE with Neo4j VSCode extension was originally published in Neo4j Developer Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.