/ 
Neo4j-Driver-0.45
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.45

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" in Neo4j::Driver::Config for details.

This driver will soon move to version 1.00, removing deprecated functionality.

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 Neo4j::Driver::Config 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 Neo4j::Driver::Config 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.

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)

COPYRIGHT AND LICENSE

This software is Copyright (c) 2016-2024 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.