Instance management

As mentioned, an instance in Desktop represents a DBMS, which is a Neo4j server installation that contains a minimum of the system database and a default user database.

Create instance

When you open Desktop for the first time, you can use the Create instance button in the middle of your screen to add a new instance to your local environment. If you already have an instance and want to create another, the button is located in the upper right corner instead.

create instance
Figure 1. Create a new instance

You need to give your instance a name and select a Neo4j version. Desktop 2.1 supports DBMS versions 5.1 and later and default is the latest version. Keep in mind that if you select any version other than the default, Desktop needs to download resources and therefore you must be connected to the internet.

You also need to create a database user and password. The credentials apply to all databases within that instance.

Once you are satisfied with the details, you finalize with the Create button. Your new DBMS is visible shortly thereafter and is ready to be started momentarily.

new instance
Figure 2. A running instance

Create from backup

Additionally, you can create a new instance from an existing .backup, .dump, or .tar file. The steps are the same as above, but you select a file to load into your new instance. The backup file will be loaded into the user database neo4j. A system database is created automatically. The version compatibility is the same as when creating an empty instance and likewise, if your backup is any other version than the default, you need to be connected to the internet.

Start/stop instance

You can only have one instance running in Desktop. Use the play/stop button to start/stop instances. If you start an instance, any already running instance will be stopped automatically. Some operations require that your instance is stopped, such as loading and exporting databases.

instance actions
Figure 3. Instance actions

Your Desktop instances can only run as long as the application is running. If you quit the application when you have a running local instance, a warning offers you to stop your instance or cancel your action.

You can turn off this warning in the Settings drawer.

Connect tools

The Connect dropdown on the instance card allows you to connect directly to either the Query, the Explore, or the Dashoards tool. The tools can only be connected to one database at the time and automatically selects the default database. You can switch both database and instance from inside the tool. See Query, Explore, and Dashboards for more information about the built-in tools.

Manage instances

The instance management menu […​] allows you to do a number of things:

  • Overview - View instance details such as Connection URI, version, and ID.

  • Plugins - Install one or more plugins.

  • Upgrade - Upgrade your instance to a later version of Neo4j.

  • Deploy to Aura - Deploy a database to Neo4j Aura. See Deploy to Aura

  • Load database from file - Load your .dump, .tar, and .backup files directly. See Load a database.

  • Export databases - Export databases in your instance as a .dump file. See Export databases.

  • Open - a dropdown to access:

    • Instance folder - View your instances and their related folders and files.

    • neo4j.log - View the log file in a new window.

    • neo4j.conf - Use your own editor/IDE to open and configure the neo4j.conf file.

  • Clone - Make a copy of your instance.

  • Delete - Delete your instance and the databases it contains.

Rename instance

Once you have opened the instance management menu, you can rename your instance by hovering on the instance name. Use the pen icon to edit the name.

rename instance
Figure 4. Rename instance

Upgrade instance

You can upgrade your local instances to a later version of Neo4j directly in from Desktop (i.e. this is not possible for remote instances). This action requires that the instance you want to upgrade is stopped.

From the instance management menu, select Upgrade and which version you want to upgrade to. Note that it is not possible to downgrade. Should the upgrade for some reason fail, a backup of the instance is taken and logs specific for the upgrade are provided.

upgrade process
Figure 5. Upgrade progress

Once the upgrade completes successfully, you can start the instance.

Install plugins

A plugin is additional functionality that can be enabled for a DBMS. With the latest version of Neo4j Desktop, the following plugins are available for installation for your local instance:

  • APOC - A library of user-defined procedures and functions to help with many different tasks in areas like data integration, graph algorithms or data conversion.

  • Bloom - The Bloom Enterprise plugin offers some extra functionality, such as features used for collaboration (e.g. persistent storage and sharing capabilities), but it requires a valid license key. Contact your Neo4j representative to register for a license. All other Bloom features are available in the Explore tool, without the plugin.

  • Gen AI integrations - A Gen AI plugin that enables creating vector embeddings in your data for use with vector indexes and vector functions.

  • GDS Library - Common graph algorithms for Neo4j.

Clone instance

Use the Clone option to make a copy of an instance. The instance you want to clone needs to be stopped and you need to give the copy a unique name. The operation will fail if an instance in Desktop already exists with the same name. Once the cloning is complete, the new copy is listed along with your other instances.

You can also clone instances you may have in a Desktop 1.x installation in order to access them in Desktop 2.x. See Clone instances from Desktop 1.x for more information.

Running instances simultaneously

As mentioned, you can only have one running instance in Desktop and you can only connect to a running instance. However, it is possible to connect to multiple instances as long as only one is local. In other words, you can connect to one local instance and multiple remote instances. In order to interact with the databases in your instances simultaneously, you need to have multiple Desktop windows open at the same time. This allows you to query and explore data in multiple databases without having to stop and start instances. To open new windows go to the File or Neoj Desktop 2 menu bar option and select New window. Keep in mind that you can only interact with one database per instance at a time.

Data path

Listed on your instance card, along with ID, Neo4j version, and connection URI, is the data path for your instance. You can open the path directly from the instance card. The location default is the users profile or home directory. It can be set to a custom location using the environment variable NEO4J_DESKTOP_DATA_PATH as described in Custom data path.

Desktop port conflicts

If you have any DBMS in an earlier version of Desktop running (Desktop 1.6 for example), you are not able to start any instance in Desktop 2. This is due to port conflicts and you have to stop any DBMS running locally before you can start your instance in Desktop 2. The only way to have multiple instances/DBMSs running simultaneously is as described in Running instances simultaneously above.