Neo4j Configuration#

Supported URIs#

liquibase-neo4j accepts only URIs in the JDBC format.

Only connections through the Bolt protocol variants are supported. Connections through HTTP or embedded are not supported by the extension.

✅ jdbc:neo4j:bolt://host:port is supported
✅ jdbc:neo4j:bolt+s://host:port is supported
✅ jdbc:neo4j:bolt+ssc://host:port is supported
✅ jdbc:neo4j:neo4j://host:port is supported
✅ jdbc:neo4j:neo4j+s://host:port is supported
✅ jdbc:neo4j:neo4j+ssc://host:port is supported
❌ jdbc:neo4j:http://host:port is NOT supported
❌ jdbc:neo4j:https://host:port is NOT supported
❌ jdbc:neo4j:file:///path/to/neo4j is NOT supported

Read more about what each URI scheme means in the Neo4j driver manual.

JDBC connectivity#

For versions 4.18.0.1 and earlier, the Neo4j extension relied on a third-party JDBC connector. Configuration parameters for this connector can be found in this link.

Starting from version 4.19.0, the extension defines its own built-in JDBC connector.

The built-in connector is simpler and easier to reason about because Liquibase only needs one connection for a single execution and relies on a specific, finite set of JDBC APIs.

This new connector has a few key differences from the third-party connector.

The serialization and deserialization logic of the built-in connector is stricter.

Warning

This issue may arise if you try to use the third-party connector with recent versions of the extension.

Since it is tailored towards Liquibase use only, the new connector is not registered through the standard JDBC mechanisms.

import java.sql.Connection;
import java.sql.DriverManager;
// [...]
Connection connection = DriverManager.getConnection("jdbc:neo4j:neo4j://localhost", "neo4j", "<redacted>");
// this will not work! see below

If you need access to a JDBC Connection instance to programmatically configure Liquibase, the code to run is as follows:

Plain old JavaSpring Boot (properties)Spring Boot (Java Config)

import liquibase.ext.neo4j.database.jdbc.Neo4jDriver;

import java.sql.Connection;
import java.sql.SQLException;
import java.util.Properties;
// [...]
Properties properties = new Properties();
properties.setProperty("user", "neo4j");
properties.setProperty("password", "<redacted>");
Connection connection = new Neo4jDriver().connect(
    "jdbc:neo4j:neo4j://localhost",
    properties
);

spring.liquibase.driver-class-name=liquibase.ext.neo4j.database.jdbc.Neo4jDriver
spring.liquibase.url=jdbc:neo4j:bolt://localhost
spring.liquibase.user=neo4j
spring.liquibase.password=<redacted>

import javax.sql.DataSource;
import liquibase.ext.neo4j.database.jdbc.Neo4jDriver;
import org.springframework.boot.autoconfigure.liquibase.LiquibaseDataSource;
import org.springframework.context.annotation.Bean;
import org.springframework.jdbc.datasource.SimpleDriverDataSource;
// [...]

@LiquibaseDataSource
@Bean
public DataSource liquibaseNeo4jDataSource() {
    // SimpleDriverDataSource is a great fit for Liquibase
    // since it does not need any connection pooling
    // note: you can set properties instead of hardcoding credentials
    SimpleDriverDataSource dataSource = new SimpleDriverDataSource(
        new Neo4jDriver(),
        "jdbc:neo4j:bolt://localhost"
    );
    dataSource.setUsername("neo4j");
    dataSource.setPassword("<redacted>");
    return dataSource;
}

Configuration#

You can fine-tune the behavior of the JDBC driver or the underlying Java Bolt driver by configuring any of the settings below.

Important

Some settings supported by the third-party JDBC connector are not supported yet. If you happen to need one of them, please open an issue and describe why it is needed in your situation.

Setting	Description	Allowed values	URL?	Properties?	Remarks
`database`	Sets database name	Any valid database name	yes	yes	This setting is only available for Neo4j 4+ servers
`nossl`	Disables encryption	- [empty] - "true"	yes	yes	"false" has no effect. Using this setting in conjunction with `encryption` or with an incompatible URI scheme is unspecified. Favour the appropriate URL scheme instead (`bolt` or `neo4j`)
`encryption`	Sets whether the traffic should be encrypted	- [empty] - "true" - "false"	yes	yes	Using this setting in conjunction with `nossl` is unspecified. Favour the appropriate URL scheme instead
`trust.strategy`	Configures how the underlying driver handles certificates	- "TRUST_ALL_CERTIFICATES" - "TRUST_CUSTOM_CA_SIGNED_CERTIFICATES" - "TRUST_SYSTEM_CA_SIGNED_CERTIFICATES"	yes	yes	"TRUST_CUSTOM_CA_SIGNED_CERTIFICATES" requires the setting "trusted.certificate.file"
`trusted.certificate.file`	Custom certificate file name	A valid path	yes	yes	Only used in combination with the "TRUST_CUSTOM_CA_SIGNED_CERTIFICATES" trust strategy
`connection.acquisition.timeout`	Sets the maximum amount of time it takes for the full connection pool to acquire a connection	Any integer value	yes	yes	The value is in milliseconds.
`connection.liveness.check.timeout`	Sets the threshold after which idle connections are tested for liveness before they are acquired again	Any integer value	yes	yes	The value is in minutes.
`connection.timeout`	Sets the socket connection timeout	Any positive integer value	yes	yes
`leaked.sessions.logging`	Enables leaked sessions logging (i.e. sessions not properly closed, leaking underlying connections leading to OOM)	- [empty] - "true"	yes	yes	"false" has no effect
`max.connection.lifetime`	Sets the threshold after which a connection is not acquired again	Any integer value	yes	yes	The value is in milliseconds
`max.connection.poolsize`	Sets the maximum size of the underlying driver's connection pool	Any integer value	yes	yes	The extension now overrides the driver's default pool size to 1 (since `4.22.0.1`)
`max.transaction.retry.time`	Sets the maximum time transaction can be retried	Any positive integer value	yes	yes	The value is in milliseconds. This setting is currently ineffective since the purpose-built JDBC connector does not rely on transaction functions
`fetch.size`	Sets the number of records per batch to fetch	-1 or any strictly positive integer value	yes	yes	This setting is only available for Neo4j 4+ servers -1 disables batching (and lead to memory issues, use with caution)
`impersonated.user`	Sets the username to impersonate	Any valid username	yes	yes	This setting is only available for Neo4j 4.4+ servers
`driver.logging.console.level`	Sets the `java.util.logging.Level` by name or numeric value and redirects the driver logs to the standard error output stream	Any valid level name or numeric value	yes	yes	This setting is available since version `4.22.0.1` included
`driver.logging.jul.level`	Sets the `java.util.logging.Level` by name or numeric value to use by the built-in Java Util Logging system	Any valid level name or numeric value	yes	yes	This setting is available since version `4.22.0.1` included
`driver.logging.slf4j`	Sets the driver logging to SLF4J	- [empty] - "true"	yes	yes	This setting is available since version `4.22.0.1` included
`driver.logging.none`	Disables driver logging	- [empty] - "true"	yes	yes	This setting is available since version `4.22.0.1` included

Important

Setting names are normalized to lower case (per the English locale case rules).
If a setting is expressed both via URL and properties, the setting specified by URL has higher precedence.
URL settings without value are considered equivalent to boolean flags with value true.