Spring Boot

Liquigraph provides a Spring Boot starter.

It is a good fit if your Spring Boot application owns (well-identified parts of) the data in Neo4j.

Prerequisites

Make sure a JDK is set up on the machine running the CLI.

For Neo4j 3.x, the minimal JDK version is 8.

For Neo4j 4.x, the minimal JDK version is 11.

Download

For this particular example, a simple Spring Boot application with a Maven build is assumed.

Info

You can bootstrap a project in a few clicks with Spring Initializr, the "second best place on the Internet". You do not need to add any dependencies.

Basic concepts

Liquigraph requires a single entry point, also known as a change log file. This file can include other change log files and/or define change sets.

Every change set is executed in a separate transaction. They define at least 1 Cypher query. These Cypher queries define the data (or indices/constraints) that will be created, modified or deleted from the target database.

Caution

Neo4j disallows mixing index/constraint with regular "data" operations within the same transaction. Such a transaction will always fail. As a consequence, index/constraint operations must be defined in separate Liquigraph change sets.

Change sets are uniquely identified by their ID and author name. By default, they also are:

• incremental: they are allowed to run only once.
• immutable: their queries are not allowed to change.

Learn how to change these defaults, and more, in the reference documentation.

First migrations

Change log creation

Save the following change log file:

<?xml version="1.0" encoding="UTF-8"?>
<changelog xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:noNamespaceSchemaLocation="https://www.liquigraph.org/schema/1.0/liquigraph.xsd">
    <changeset id="sentence-initialization" author="florent-biville">
        <query>CREATE (n:Sentence {text:"Hello monde!"}) RETURN n</query>
    </changeset>
    <changeset id="sentence-correction" author="florent-biville">
        <query>MATCH (n:Sentence {text:"Hello monde!"}) SET n.text="Hello world!" RETURN n</query>
    </changeset>
</changelog>

The change log defines two change sets, which are executed in order, in separate transactions:

1. The first change set defines a single query, which creates a node, with a Sentence label and a simple textual property called text.
2. The second change set defines a single Cypher query as well, which finds the node pattern and updates the text property accordingly.

If the Cypher syntax looks unfamiliar, feel free to follow this official tutorial.

Info

The location of this file will be called CHANGELOG_FILE throughout the rest of the tutorial.

Note

Contrary to Liquibase, Liquigraph only supports XML for defining change logs.

Connection URI

To keep things simple, we will assume a standalone Neo4j server is running on your machine, via Neo4j Desktop or Docker for instance.

The connection URI will be jdbc:neo4j:bolt://localhost, username neo4j and the password changeme.

Depending on Neo4j versions, Neo4j server typology and Liquigraph client, connection URI can vary greatly. The configuration is covered in much greater details in the reference documentation.

Configuration

Add the following dependencies to your POM file:

Liquigraph 4.x

<dependency>
    <groupId>org.liquigraph</groupId>
    <artifactId>liquigraph-spring-boot-starter</artifactId>
    <version>4.0.3</version>
</dependency>
<dependency>
    <groupId>org.neo4j</groupId>
    <!-- change this to neo4j-jdbc-http for HTTP connections to Neo4j -->
    <artifactId>neo4j-jdbc-bolt</artifactId>
    <version>4.0.1</version>
    <scope>runtime</scope>
</dependency>

Liquigraph 3.x

<dependency>
    <groupId>org.liquigraph</groupId>
    <artifactId>liquigraph-spring-boot-starter</artifactId>
    <version>3.1.2</version>
</dependency>
<dependency>
    <groupId>org.neo4j</groupId>
    <!-- change this to neo4j-jdbc-http for HTTP connections to Neo4j -->
    <artifactId>neo4j-jdbc-bolt</artifactId>
    <version>3.5.2</version>
    <scope>runtime</scope>
</dependency>

You also need to configure your application with the Neo4j connection settings required by Liquigraph (in src/main/resources/application.properties for instance):

spring.datasource.url=jdbc:neo4j:bolt://localhost
spring.datasource.driver-class-name=org.neo4j.jdbc.bolt.BoltDriver
spring.datasource.username=neo4j
spring.datasource.password=changeme

Run

Caution

The "dry run" mode is currently not supported by the Spring Boot starter, contrary to the CLI and Maven plugin.

Note

CHANGELOG_FILE should be stored in src/main/resources/db/liquigraph/changelog.xml for the example to work.

You just need to run:

mvn spring-boot:run

You can then check the data has been added in Neo4j Browser with the following Cypher query:

MATCH (sentence:Sentence) RETURN sentence.text AS text

The result should be "Hello world!".

You can re-run the same Liquigraph command several times and observe that the graph remains unchanged. In other words, the following Cypher query:

MATCH (sentence:Sentence) RETURN COUNT(sentence)

... should indeed always return 1.

Good to know

If you ever run a less specific Cypher query such as MATCH (n) RETURN n, you will see that more node and relationships are returned. This is normal: Liquigraph persists the change log history in the same database. The change log history graph structure is covered in much more details in the reference documentation.