Maven plugin

Liquigraph provides a Maven plugin. This plugin is a good fit for:

• standalone executions of Liquigraph in environments where JVM tooling is already in place (like CI/CD pipelines e.g.). You might want to have a look at the Liquigraph CLI otherwise
• the automation of migrations before some other Maven plugin executes (such as Maven Failsafe Plugin for integration tests)

Prerequisites

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

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

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

You will also need to install a recent version of Apache Maven.

As a simple sanity check, javac --version, java --version and mvn --version should display the same JDK version.

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.

A minimal POM file

For simplicity's sake, a standalone Maven build will be assumed. If that's not the case, simply copy the relevant sections of the following file:

Liquigraph 4.x

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>liquigraph-maven-example</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>jar</packaging>

    <name>liquigraph-maven-example</name>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>${project.build.sourceEncoding}</project.reporting.outputEncoding>
        <maven.compiler.release>11</maven.compiler.release>
    </properties>

    <build>
        <plugins>
            <plugin>
                <groupId>org.liquigraph</groupId>
                <artifactId>liquigraph-maven-plugin</artifactId>
                <version>4.0.3</version>
                <configuration>
                    <changelog>changelog.xml</changelog>
                    <jdbcUri>jdbc:neo4j:bolt://localhost</jdbcUri>
                    <username>neo4j</username>
                    <password>changeme</password>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Liquigraph 3.x

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>liquigraph-maven-example</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>jar</packaging>

    <name>liquigraph-maven-example</name>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>${project.build.sourceEncoding}</project.reporting.outputEncoding>
        <maven.compiler.source>8</maven.compiler.source>
        <maven.compiler.target>${maven.compiler.source}</maven.compiler.target>
    </properties>

    <build>
        <plugins>
            <plugin>
                <groupId>org.liquigraph</groupId>
                <artifactId>liquigraph-maven-plugin</artifactId>
                <version>3.1.2</version>
                <configuration>
                    <changelog>changelog.xml</changelog>
                    <jdbcUri>jdbc:neo4j:bolt://localhost</jdbcUri>
                    <username>neo4j</username>
                    <password>changeme</password>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Info

Please refer to the download section to learn how to retrieve a Liquigraph SNAPSHOT version.

Note

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

The following executions assumes that the current directory is the folder where pom.xml.

Dry run

It is a good practice to first execute a dry run.

A dry run does not alter your database. The database needs to be online, so that Liquigraph can properly detect which change sets are to be selected (based on whether they already ran, whether they match the execution context ...).

It helps you make sure that:

• your connection settings are correct
• the selected change sets are the ones you expect

Since the configuration is defined in the POM file, the execution is simply as follows:

mvn compile liquigraph:dry-run

This should result in a successful execution with a file named output.cypher in the generated target folder:

less target/output.cypher
//Liquigraph changeset[author: florent-biville, id: sentence-initialization]
//Liquigraph changeset[executionContexts: none declared]
CREATE (n:Sentence {text:"Hello monde!"}) RETURN n
//Liquigraph changeset[author: florent-biville, id: sentence-correction]
//Liquigraph changeset[executionContexts: none declared]
MATCH (n:Sentence {text:"Hello monde!"}) SET n.text="Hello world!" RETURN n

Note

• Contrary to Liquibase, Liquigraph only includes the queries of the matching change sets. Cypher queries executed for Liquigraph internal purposes are not included.
• Printing to the standard output is also currently unsupported.

Run

Once the dry run is successful, you can finally execute the migrations.

The invocation is very similar, only the plugin target goal changes:

mvn compile liquigraph: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.