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

NAME

Neo4j::Driver - Perl implementation of the Neo4j Driver API

VERSION

version 0.11

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;
  forach 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 more or less the same classes and method calls as the official Neo4j drivers do. Responses from the Neo4j server are passed through to the client as-is.

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 future Neo4j versions.

This software has pre-release quality. There is no schedule for further development. The interface is not yet stable.

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;

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 will be used as default, along with the default port of the selected protocol. The default protocol might change to https in future.

# all of these are semantically equal
my $driver = Neo4j::Driver->new;
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: Explicit transactions are not yet implemented, there is no proper error handling, and summary information is completely unavailable. Additionally, there are certain problems with Unicode, incompatibilities with other "experimental" features of this driver, and parts of the documentation still assume that HTTP is the only option.

Close method

$driver->close;  # no-op

This driver does not support persistent connections at present. All connections are closed automatically. There is no need for explicit calls to `close` at this time.

HTTP Timeout

$driver->{http_timeout} = 10;  # seconds

A timeout in seconds for making HTTP connections to the Neo4j server. If a connection cannot be established before timeout, a local error will be triggered by this client.

The default timeout currently is 6 seconds.

Mutability

my $session1 = $driver->basic_auth('user1', 'password')->session;
my $session2 = $driver->basic_auth('user2', 'password')->session;

my $session1 = $driver->session;
$driver->{http_timeout} = 30;
$driver->{die_on_error} = 0;
my $session2 = $driver->session;

The official Neo4j drivers are explicitly designed to be immutable. As this driver currently has a much simpler design, it can afford mutability, but applications shouldn't depend upon it.

The modifications will not be picked up by existing sessions. Only sessions that are newly created after making the changes will be affected.

Suppress exceptions

my $driver = Neo4j::Driver->new;
$driver->{die_on_error} = 0;
my $result = $driver->session->run('...');

The default value of the die_on_error attribute is 1. Setting this to 0 causes the driver to no longer die on server errors.

This is much less useful than it sounds. Not only is the StatementResult structure not well-defined for such situations, but also the internal state of the Transaction object may be corrupted. For example, when a minor server error occurs on the first request (which would normally establish the connection), the expected Location header may be missing from the error message and the transaction may therefore be marked as closed, even though it still is open.

Additionally, client errors (such as trying to call single() on a result with multiple result records) currently still will cause the driver to die.

This feature will likely be removed in a future version. Use eval, Try::Tiny or similar instead.

ENVIRONMENT

This software currently targets Neo4j versions 2.3, 3.x and 4.x. The latter doesn't exist yet, but is expected to continue support for the Transactional HTTP endpoint that this driver uses (as opposed to the Legacy Cypher HTTP endpoint, which is expected to be discontinued starting in Neo4j 4.0 along with direct REST access to the graph entities).

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.

BUGS

See the TODO.pod 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 Developer Manual: Drivers, Neo4j Transactional Cypher HTTP API, 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)