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

NAME

Neo4j::Driver - Perl Neo4j driver for Bolt and HTTP

VERSION

version 0.22

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 {
  $query = 'MATCH (a:Person)-[:KNOWS]->(f) '
            . 'WHERE a.name = {name} RETURN f.name';
  $records = $driver->session->run($query, name => shift)->list;
  foreach $record ( @$records ) {
    say $record->get('f.name');
  }
}

say_friends_of 'Alice';

DESCRIPTION

This is an unofficial Perl implementation of the Neo4j Driver API. It enables interacting with a Neo4j database server using the same classes and method calls as the official Neo4j drivers do.

This driver extends the uniformity across languages, which is a stated goal of the Neo4j Driver API, to Perl. The downside is that this driver doesn't offer fully-fledged object bindings like the existing REST::Neo4p module does. Nor does it offer any DBI integration. However, it avoids the legacy cypher endpoint, assuring compatibility with Neo4j versions 2.3, 3.x and 4.x.

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, 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.

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.

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 "new" for details.

As of version 0.13, the interface of this software may be considered stable.

However, bugs may still exist. Also, experimental features may be changed or deprecated at any time. If you find yourself reliant on an experimental feature, please file a new issue requesting that it be made stable.

There is an ongoing effort to clean up the experimental features. For each of them, the goal is to eventually either declare it stable or deprecate it. There is also ongoing work to further improve general stability and reliability of this software. However, there is no schedule for the completion of these efforts.

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 option or options on a Neo4j::Driver object. The options are given in hash syntax. This method returns the modified object, so that method chaining is possible.

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

See below for an explanation of all supported configuration options. Setting configuration options on a driver is only allowed before creating the driver's first session.

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

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

new

$driver = Neo4j::Driver->new('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 URI passed to this method determines the type of driver created. The http, https, and bolt URI schemes are supported. 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 = Neo4j::Driver->new;
$driver = Neo4j::Driver->new('http:');
$driver = Neo4j::Driver->new('localhost');
$driver = Neo4j::Driver->new('http://localhost');
$driver = Neo4j::Driver->new('http://localhost:7474');

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. 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.

Bolt version 3 and 4

There is now experimental support for Bolt protocol versions newer than 1 using Neo4j::Bolt version 0.40 or newer. This allows connecting to Neo4j 4 using Bolt.

This feature is currently undergoing testing. Until it becomes stable, please continue to use HTTP with Neo4j 4 in production environments.

Jolt

$d->config(jolt => undef);  # let the server decide
$d->config(jolt => 0);      # accept only JSON (the default)
$d->config(jolt => 1);      # accept only Jolt

There is experimental support for Neo4j HTTP responses that use the Jolt format (JSON Bolt). This new response format will soon become this driver's default for HTTP connections. For now, you'll have to request it explicitly using the jolt config option.

If you use the scalars 'sparse' or 'strict' instead of just 1, the driver will request that particular Jolt mode from the server. However, there is no advantage to manually selecting one of these modes. This feature is for testing purposes only.

Custom networking modules

use Local::MyNetworkAgent;
$driver->config(net_module => 'Local::MyNetworkAgent');

The module to be used for network communication may be specified using the net_module config option. The specified module must implement the API described in "EXTENSIONS" in Neo4j::Driver::Net. Your code must use or require the module it specifies here.

By default, the driver will try to auto-detect a suitable module. This will currently always result in the driver's built-in modules being used. Alternatively, you may specify the empty string to ask for the built-in modules explicitly, which will disable auto-detection.

$driver->config(net_module => undef);  # auto-detect (the default)
$driver->config(net_module => '');     # use the built-in modules

This config option is experimental because the API for custom networking modules is still evolving. See Neo4j::Driver::Net for details.

Parameter syntax conversion

$driver->config(cypher_filter => 'params');

When this option is set, the driver automatically uses a regular expression to convert the old Cypher parameter syntax {param} supported by Neo4j versions 2 and 3 to the new syntax $param supported by Neo4j versions 3 and 4.

Type system customisation

$driver->config(cypher_types => {
  node => 'Local::Node',
  relationship => 'Local::Relationship',
  path => 'Local::Path',
  point => 'Local::Point',
  temporal => 'Local::Temporal',
  init => sub { my $object = shift; ... },
});

The package names used for blessing objects in query results can be modified. This allows clients to add their own methods to such objects.

Clients must make sure their custom type packages are subtypes of the base type packages that this module provides (e. g. using @ISA):

Clients may only use the documented API to access the data in the base type. As an exception, clients may store private data by calling the _private() method, which returns a hashref. Within that hashref, clients may make free use of any hash keys that begin with two underscores (__). All other hash keys are reserved for use by Neo4j::Driver. Reading or modifying their values is unsupported and discouraged because it makes your code prone to fail when any internals change in the implementation of Neo4j::Driver.

The cypher_types config option will soon be deprecated and eventually be removed. The net_module option offers the same functionality and more (albeit somewhat less conveniently).

CONFIGURATION OPTIONS

Neo4j::Driver implements the following configuration options.

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.

The old $driver->{http_timeout} syntax remains supported for the time being in order to ensure backwards compatibility, but its use is discouraged and it may be deprecated in future.

tls

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

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

By default, the local system's trust store 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 tls_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).

tls_ca

$driver->config(tls_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.

ENVIRONMENT

This software currently targets Neo4j versions 2.3, 3.x and 4.x.

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

DIAGNOSTICS

Neo4j::Driver currently dies as soon as an error condition is discovered. Use eval, Try::Tiny or similar to catch this.

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.

Due to lack of resources, only the Neo4j community edition is targeted by this driver at present.

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 a far cry from what it is today.

AUTHOR

Arne Johannessen <ajnn@cpan.org>

COPYRIGHT AND LICENSE

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

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)