/ 
Neo4j-Driver-0.36
River stage one • 1 direct dependent • 2 total dependents
/ Neo4j::Driver

NAME

Neo4j::Driver - Neo4j community graph database driver for Bolt and HTTP

VERSION

version 0.36

SYNOPSIS

use Neo4j::Driver;
$uri = 'bolt://localhost';  # requires Neo4j::Bolt
$uri = 'http://localhost';
$driver = Neo4j::Driver->new($uri)->basic_auth('neo4j', 'password');

sub say_friends_of ($person) {
  $query = 'MATCH (a:Person)-[:KNOWS]->(f) '
            . 'WHERE a.name = $name RETURN f.name';
  @records = $driver->session->execute_read( sub ($tx) {
    $tx->run($query, { name => $person })->list;
  });
  foreach $record ( @records ) {
    say $record->get('f.name');
  }
}

say_friends_of 'Alice';

DESCRIPTION

This software is a community driver for the Neo4j graph database server. It is designed to follow the Neo4j Driver API, allowing clients to interact with a Neo4j server using the same classes and method calls as the official Neo4j drivers do. This extends the uniformity across languages, which is a stated goal of the Neo4j Driver API, to Perl.

This driver targets the Neo4j community edition, version 2.x, 3.x, 4.x, and 5.x. The Neo4j enterprise edition and AuraDB are only supported as far as practical, but patches will be accepted.

Two different network protocols exist for connecting to Neo4j. By default, Neo4j servers offer both, but this can be changed in neo4j.conf for each server; see "Configure connectors" in the Neo4j Operations Manual.

Bolt

Bolt is a Neo4j proprietary, binary protocol, available with Neo4j 3.0 and newer. Bolt communication may be encrypted or unencrypted. Because Bolt is faster than HTTP, it is generally the recommended protocol. However, Perl support for it may be lagging after major updates to Neo4j.

This driver supports Bolt, but doesn't bundle the necessary XS packages. You will need to install Neo4j::Bolt separately to enable Bolt for this driver.

HTTP / HTTPS

Support for HTTP is built into this driver, so it is always available. HTTP is still fast enough for many use cases and works even in a "Pure Perl" environment. It may also be quicker than Bolt to add support for future changes in Neo4j.

HTTP connections will use Jolt (JSON Bolt) when offered by the server. For older Neo4j servers (before version 4.2), the driver will automatically fall back to slower REST-style JSON.

The driver also supports encrypted communication using HTTPS, but doesn't bundle the necessary packages. You will need to install LWP::Protocol::https separately to enable HTTPS.

The protocol is automatically chosen based on the URI scheme. See "uri" for details.

This driver's development is not yet considered finalised.

As of version 0.36, the one major open item is:

  • Support for the neo4j: URI scheme in some fashion. (No first-party implementation of client-side routing is currently planned, but plug-ins might get a hook for it.)

Once the above item is implemented, this driver will move to version 1.00, removing deprecated functionality. There is an ongoing effort to work on this and other items, but there is no schedule for their completion.

METHODS

Neo4j::Driver implements the following methods.

basic_auth

$driver->basic_auth('neo4j', 'password');

Set basic auth credentials with a given user and password. This method returns the modified Neo4j::Driver object, so that method chaining is possible.

$session = $driver->basic_auth('neo4j', 'password')->session;

config

$driver->config({ option1 => 'foo', option2 => 'bar' });

Sets the specified configuration options on a Neo4j::Driver object. The options may be given as a hash or as a hash reference. This method returns the modified object, so that method chaining is possible.

$session = $driver->config(timeout => 60)->session;

See "CONFIGURATION OPTIONS" for a list of supported options. Setting configuration options on a driver is only allowed before creating the driver's first session.

Calling this method with just a single string parameter will return the current value of the config option named by the parameter.

$timeout = $driver->config('timeout');

new

$driver = Neo4j::Driver->new({ uri => 'http://localhost' });

Construct a new Neo4j::Driver object. This object holds the details required to establish connections with a Neo4j database, including server URIs, credentials and other configuration.

The new() method accepts one or more configuration options given as a hash reference. See "CONFIGURATION OPTIONS" below for a list of supported options. Alternatively, instead of the hash reference, the Neo4j server URI may be given as a scalar string.

$driver = Neo4j::Driver->new('http://localhost');

If new() is called with no arguments, a default configuration will be used for the driver.

session

$session = $driver->session;

Creates and returns a new Session, initiating a network connection with the Neo4j server.

Each session connects to a single database, which may be specified using the database option in a hash or hash reference passed to this method. If no defined value is given for this option, the driver will select the default database configured in neo4j.conf.

$session = $driver->session( database => 'system' );

The database option is silently ignored when used with Neo4j versions 2 and 3, which only support a single database.

EXPERIMENTAL FEATURES

Neo4j::Driver implements the following experimental features. These are subject to unannounced modification or removal in future versions. Expect your code to break if you depend upon these features.

Plug-in modules

$driver->plugin(  Local::MyPlugin->new );

The driver offers a simple plug-in interface. Plug-ins are modules providing handlers for events that may be triggered by the driver. Plug-ins are loaded by calling the plugin() method with the the blessed instance of a plug-in as parameter.

Details on the implementation of plug-ins including descriptions of individual events are provided in Neo4j::Driver::Plugin.

This feature is experimental because some parts of the plug-in API are still evolving.

Concurrent transactions in HTTP sessions

$session = Neo4j::Driver->new({
  concurrent_tx => 1,
  uri => 'http://...',
})->session;
$tx1 = $session->begin_transaction;
$tx2 = $session->begin_transaction;
$tx3 = $session->run(...);

The Neo4j Driver API officially doesn't allow multiple concurrent transactions (sometimes called "nested transactions") to be open within the same session. The standard way to work with multiple concurrent transactions is to simply use multiple sessions. However, since HTTP is a stateless protocol, concurrent transactions are still possible on connections which use the http: or https: protocol scheme.

This driver allows concurrent transactions on HTTP when the concurrent_tx config option is enabled. Trying to enable this option on a Bolt connection is a fatal error.

The default for HTTP connections is currently to enable concurrent transactions, but this will likely change in a future version. The driver will currently give warnings on a best-effort basis when using concurrent transactions on HTTP without enabling this option, but these warnings may become fatal errors in future.

When using HTTP, you should consider making a conscious choice regarding whether or not to use concurrent transactions, and configuring your driver accordingly. This can help to avoid surprising behaviour in case you switch to Bolt at a later point in time.

This config option is experimental because its name and semantics are still evolving.

CONFIGURATION OPTIONS

Neo4j::Driver implements the following configuration options.

auth

$driver->config(auth => {
  scheme      => 'basic',
  principal   => $user_id,   # 'neo4j' by default
  credentials => $password,
});

Specifies the authentication details for the Neo4j server. The authentication details are provided as a Perl reference that is made available to the network adapter. Typically, this is an unblessed hash reference with the authentication scheme declared in the hash entry scheme.

The Neo4j server uses the auth scheme 'basic' by default, which must be configured with a user id in the hash entry principal and a password in the entry credentials, as shown above. Alternatively, the method "basic_auth" can be used as a shortcut, or the basic auth details can be specified as userinfo in the URI.

The auth config option defaults to the value undef, which disables authentication.

cypher_params

$driver->config( cypher_params => v2 );
$foo = $driver->session->run('RETURN {bar}', bar => 'foo');

Enables conversion of the old Cypher parameter syntax {param} supported by Neo4j version 2 to the modern syntax $param supported by Neo4j version 3 and newer. The only allowed value for this config option is the unquoted literal v-string v2.

Cypher's modern $ parameter syntax unfortunately may cause string interpolations in Perl, which decreases database performance because Neo4j can re-use query plans less often. It is also a potential security risk (Cypher injection attacks). Using this config option enables your code to use the safer {} parameter syntax instead.

encrypted

$driver->config(encrypted => 1);

Specifies whether to use secure communication using TLS. This implies not just encryption, but also verification of the server's identity.

By default, a trust store on the local system will be used to verify the server's identity. This will fail unless your Neo4j installation uses a key pair that is trusted and verifiable through the global CA infrastructure. If that's not the case, you may need to additionally use the trust_ca option.

This option defaults to 0 (no encryption). This is generally what you want if you connect to a server on localhost.

This option is only useful for Bolt connections. For HTTP connections, the use of TLS encryption is governed by the chosen URI scheme (http / https).

Before version 0.27, this option was named tls. Use of the former name is now discouraged.

max_transaction_retry_time

$driver->config(max_transaction_retry_time => 6);  # seconds

Specifies the maximum amount of time that a managed transaction will retry before failing. The default value is 30 seconds.

timeout

$driver->config(timeout => 60);  # seconds

Specifies the connection timeout. The semantics of this config option vary by network library. Its default value is therefore not defined here and is subject to change.

For details, see "timeout" in LWP::UserAgent when using HTTP or select(2) when using Bolt.

trust_ca

$driver->config(trust_ca => 'neo4j/certificates/neo4j.cert');

Specifies the path to a file containing one or more trusted TLS certificates. When this option is given, encrypted connections will only be accepted if the server's identity can be verified using the certificates provided.

The certificates in the file must be PEM encoded. They are expected to be "root" certificates, i. e. the "CA bit" needs to be set and the certificate presented by the server must be signed by one of the certificates in this file (or by an intermediary).

Self-signed certificates (such as those automatically provided by some Neo4j versions) should also work if their "CA bit" is set.

Before version 0.27, this option was named tls_ca. Use of the former name is now discouraged.

uri

$driver->config(uri => 'http://localhost:7474');

Specifies the Neo4j server connection URI. The URI scheme determines the type of driver created. Supported schemes are bolt, http, and https. Use of bolt URIs requires Neo4j::Bolt to be installed; use of https URIs requires LWP::Protocol::https to be installed.

If a part of the URI or even the entire URI is missing, suitable default values will be substituted. In particular, the host name localhost and the protocol http will be used as defaults; if no port is specified, the protocol's default port will be used.

# all of these are semantically equal
$driver->config(uri =>  undef );
$driver->config(uri => 'http:');
$driver->config(uri => 'localhost');
$driver->config(uri => 'http://localhost');
$driver->config(uri => 'http://localhost:7474/');

The neo4j URI scheme is not yet implemented. Once it is added to a future version of this driver, the default URI scheme will likely change to neo4j.

Note that there sometimes are issues with IPv4/IPv6 dual-stack hostnames such as localhost when using HTTP. The connection may appear to "hang". Literal IP addresses like 127.0.0.1 are not affected. See "IPv6 / dual-stack support" in Neo4j::Driver::Net for further discussion.

ENVIRONMENT

This software requires at least Perl 5.10, though you should consider using Perl 5.26 or newer if you can.

DIAGNOSTICS

Neo4j::Driver triggers an "error" event as soon as an error condition is discovered. If unhandled, this event will cause the driver to die with an error string. See "ERROR HANDLING" in Neo4j::Driver::Transaction for further information.

Warnings are given when deprecated or ambiguous method calls are used. These warnings may be disabled if desired.

no warnings 'deprecated';
no warnings 'ambiguous';

BUGS

See the TODO document and Github for known issues and planned improvements. Please report new issues and other feedback on Github.

Just like the official Neo4j drivers, this driver has been designed to strike a balance between an idiomatic API for Perl and a uniform surface across all languages. Differences between this driver and the official Neo4j drivers in either the API or the behaviour are generally to be regarded as bugs unless there is a compelling reason for a different approach in Perl.

SEE ALSO

ACKNOWLEDGEMENT

Special thanks go to Mark A. Jensen (MAJENSEN). Without the inspiration of his REST::Neo4p, this driver project probably would never have been even gotten started. And without Mark's tremendous work on Neo4j::Bolt and libneo4j-client, this driver certainly would be in much worse shape than it is today.

AUTHOR

Arne Johannessen <ajnn@cpan.org>

If you contact me by email, please make sure you include the word "Perl" in your subject header to help beat the spam filters.

COPYRIGHT AND LICENSE

This software is Copyright (c) 2016-2023 by Arne Johannessen.

This is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0 or (at your option) the same terms as the Perl 5 programming language system itself.