NAME
Neo4j::Driver - Perl implementation of the Neo4j Driver API
VERSION
version 0.14
SYNOPSIS
use Neo4j::Driver;
my $uri = 'http://localhost';
my $driver = Neo4j::Driver->new($uri)->basic_auth('neo4j', 'password');
sub say_friends_of {
my $query = 'MATCH (a:Person)-[:KNOWS]->(f) '
. 'WHERE a.name = {name} RETURN f.name';
my $records = $driver->session->run($query, name => shift)->list;
foreach my $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.
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.
my $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.
my $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.
my $timeout = $driver->config('timeout');new
my $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. Only the http URI scheme is currently supported.
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
my $driver = Neo4j::Driver->new;
my $driver = Neo4j::Driver->new('http:');
my $driver = Neo4j::Driver->new('localhost');
my $driver = Neo4j::Driver->new('http://localhost');
my $driver = Neo4j::Driver->new('http://localhost:7474');session
my $session = $driver->session;Creates and returns a new Session.
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 support
my $driver = Neo4j::Driver->new('bolt://localhost');Thanks to Neo4j::Bolt, there is now skeletal support for the Bolt Protocol, which can be used as an alternative to HTTP to connect to the Neo4j server.
The design goal is for this driver to eventually offer equal support for Bolt and HTTP. At this time, using Bolt with this driver is not recommended, although it sorta-kinda works. The biggest issues include: Unicode is not supported in Neo4j::Bolt, the libneo4j-client backend currently doesn't support Neo4j 4, setting a custom timeout is not supported in Neo4j::Bolt, libneo4j-client error reporting is unreliable, summary information reported by Neo4j::Bolt is incomplete, and graph meta data supplied by Neo4j::Bolt is unreliable and has a different format than when the HTTP transport is used.
Additionally, there are incompatibilities with other "experimental" features of this driver, and parts of the documentation still assume that HTTP is the only option.
TLS encryption is disabled in early versions of Neo4j::Bolt. If you need remote access, consider using HTTPS instead of Bolt.
HTTPS support
my $driver = Neo4j::Driver->new('https://localhost');
$driver->config(ca_file => 'neo4j/certificates/neo4j.cert');Using HTTPS will result in an encrypted connection. In order to rule out a man-in-the-middle attack, the server's certificate must be verified. By default, this driver may be expected to use operating system default root certificates (not really tested yet). This will fail unless your Neo4j installation uses a key pair that is trusted and verifiable through the global CA infrastructure. For self-signed certificates (such as those automatically provided by some Neo4j versions), you need to specify the location of a local copy of the server certificate. The driver config option ca_file may be used for this; it corresponds to SSL_ca_file in LWP::UserAgent and IO::Socket::SSL.
See also the Neo4j Operations Manual for details on Neo4j network security.
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. Direct data structure access might also work, but is unsupported and discouraged because it makes your code prone to fail when any internals change in the implementation of Neo4j::Driver. For those objects that are implemented as blessed hash refs, clients may use any hash keys that beginn with two underscores (__) to store private data. All other hash keys are reserved for use by Neo4j::Driver.
CONFIGURATION OPTIONS
Neo4j::Driver implements the following configuration options.
timeout
$driver->config(timeout => 60); # secondsSpecifies 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.
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.
PERFORMANCE
Preliminary testing seems to indicate the two major bottlenecks are the HTTP transport to and from the Neo4j server, and the JSON parsing. Switching to the experimental Bolt protocol support may well increase the speed tenfold. You are encouraged to run your own tests for your specific application.
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
Neo4j::Driver::Session, Neo4j Drivers Manual, Neo4j HTTP API Docs, REST::Neo4p
AUTHOR
Arne Johannessen <ajnn@cpan.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2016-2019 by Arne Johannessen.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)