Verify Connectivity: How to Check the Neo4j Connection from a Spring Boot Application

- 8 minutes read - 1503 words
Photo credit

I have recently been working on a self-paced learning course for Spring Data Neo4j and wanted users to be able to test the database connection. Typically, in a Spring Boot application with Spring Data, you set the database credentials as properties in the application.properties file. You can run the application with just these details, but it only fails when the database URI has improper syntax. The application does not actually test the connection to see if it is valid and successfully connects.

In this blog post, I will show you how to test the connection to a Neo4j database from a Spring Boot application using the verifyConnectivity() method from the Driver class.

Ways to Test the Connection

You might ask, "why doesn’t the application test the connection?" This is because it isn’t a config property, so we have to test it at runtime. There are a few different ways to go about this.

  1. Use a CommandLineRunner with the driver and use the verifyConnectivity() method.

  2. Move the CommandLineRunner to its own config class (cleaner).

  3. Write a test for that uses the verifyConnectivity() method.

  4. Write application functionality (domain, repository, controller classes) that utilize the connection.

The last option has been what I have done in the past because I haven’t focused on only the connectivity step. However, it is not ideal for testing the connection because it requires you to write a lot of code that you don’t need. If the connection is wrong, then we have to troubleshoot a lot more code when something else might actually be causing the problem. We want to only deal with the database connection.

All three of the other options utilize the driver’s verifyConnectivity() method, but apply it in different places in the application. The first and second options were my next approach and are pretty good options, but require you to run the whole application. Once you have the test method, it either gets run along with the app every time, or you have to comment out/remove that piece of code.

The third option is the best because it is a test that you can run at any time. It doesn’t increase the overhead of the actual application, and you can run individual tests only when desired. This will be our goal, but I will show you how to write the first and second options, as well.

The verifyConnectivity() Method

First, let’s look at the verifyConnectivity() method. I didn’t realize this existed until now, so I had to do a bit of research. The info in the Java API docs says that it verifies the driver can connect to the database and throws an exception if it fails to connect. This is exactly what we want!

The method is part of the Driver class, which is part of the Neo4j Java Driver. So, in order to execute the verifyConnectivity() method, we will need to create a driver object.

Setup: Create a Spring Boot Project

Let’s start by creating a Spring Boot project. I like to do this through the Spring Initializr site. I will use the following settings:

  • Project: Maven Project

  • Language: Java

  • Spring Boot: Latest stable release (currently 3.1.3)

  • Project Metadata:

    • Group: com.jmhreif

    • Artifact: verify-connectivity

  • Dependencies:

    • Spring Data Neo4j

Spring Initializr settings

Once you have downloaded the project, open it in your preferred IDE. The first thing we will need to do is to set the database credentials in the application.properties file. This will give us something to test.

If you don’t already have an instance of Neo4j running, you can spin up a free cloud instance of Neo4j Aura in a few minutes. Neo4j Aura is a fully managed cloud database service. Once you have an instance, you can get the connection URI from the Aura console.

Next, open the application.properties file and add the following properties:

spring.neo4j.uri=neo4j+s://dbhash.databases.neo4j.io
spring.neo4j.authentication.username=neo4j
spring.neo4j.authentication.password=test
spring.data.neo4j.database=neo4j

Note that you will need to update at least the URI and password fields to match your instance (the username and database fields are defaulted unless you customize them later). Now, we can create a CommandLineRunner class to test the connection.

Each of the options we will cover in this post is in a separate branch in the accompanying Github project. You can follow along by checking out the branch for the option as we walk through each one. The main branch is the preferred solution using a test in the test class.

Option 1: Use CommandLineRunner

With our project ready, we can start adding code to test the database connection. Open the main application class (VerifyConnectivityApplication.java here) and add code so it matches the class below:

@SpringBootApplication
public class VerifyConnectivityApplication implements CommandLineRunner {

	public static void main(String[] args) {
		SpringApplication.run(VerifyConnectivityApplication.class, args);
	}

	final Driver driver;

	public VerifyConnectivityApplication(@Autowired Driver driver) {
		this.driver = driver;
	}

	public final void run(String... args) {
		driver.verifyConnectivity();
	}
}

We have our class implement the CommandLineRunner interface so that the bean we create to test our connection is run on application startup. Next, we inject the driver on line 17 and create a constructor that uses the driver on line 19.

Line 23 is where we actually test the connection. We implement the run() method, which uses the Driver object to call its verifyConnectivity() method. If the connection is successful, then we get a 0 success status code. If the connection fails, then the method will throw an exception and the application will exit.

We can test this by running the application. If the output returns the 0 status code, then it works as it’s supposed to. You can also test to make sure it fails by putting some bad data into the database properties in the application.properties file and running the app again.

Testing the connection in the main application class isn’t the best solution because we have cluttered up our main class with the test code. We can make this a bit cleaner by moving this code to its own config class.

Option 2: Set Up a Config Class

We are not really changing any functionality with this option, but are rather moving the configuration code to a separate class. This will allow us to keep our main application class focused on the application’s main functionality.

First, we need to create a new Java class. You can name it anything you like, but I called it Config.java. Open the class and copy/paste the code from the main application class so that your config class looks like the following:

@Configuration
public class Config implements CommandLineRunner {
    final Driver driver;

    public Config(@Autowired Driver driver) {
        this.driver = driver;
    }

    public final void run(String... args) {
        driver.verifyConnectivity();
    }
}

Ensure you remove the copied code from the main class, and then test the application again. It should still work the same as before where a 0 status code means success, but now we have put the connection test code into a configuration part of the application.

This solution also isn’t ideal because we still have to run the whole application to test the connection. We can do better by writing a test in the test class so that it only runs when we need to check that piece.

Option 3: Write a Test

The third option is the best one. It doesn’t increase the overhead of the application, and we can run an individual test as needed. To do this, we need to open the VerifyConnectivityApplicationTests.java file and match following code:

@SpringBootTest
class VerifyConnectivityApplicationTests {
    final Driver driver;
	public VerifyConnectivityApplicationTests(@Autowired Driver driver) {
		this.driver = driver;
	}

	@Test
	final void testConnection() {
		driver.verifyConnectivity();
	}
}

You will also need to remove the Config.java class, as we don’t need it anymore. Now, we can run the test, and it will verify the connection. If the connection is successful, then the test will pass. If the connection fails, then the test will fail. You can alter the values in the application.properties to verify results for both success and failure.

This version of the code is much cleaner, and since we want to test a connection, it makes sense to use the test class. For more comprehensive application testing, we could use a test suite such as Neo4j harness or Testcontainers, but that is out of scope for this post. In this case, it is sufficient to create a plain test that verifies our application can connect to the database.

Wrap Up!

In today’s post, we saw how to use the verifyConnectivity() method to test the connection to a Neo4j database from a Spring Boot application. We saw three different ways to do this, and the pros and cons of each. We also discussed why the best option is to utilize the test class and write a test. If the connection succeeds, the test passes. If the connection fails, the test fails, and we can troubleshoot connection details.

Happy debugging!

Resources