Skip to content

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:

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.