NAME

Neo4j::Driver::Session - Context of work for database interactions

VERSION

version 0.12

SYNOPSIS

 use Neo4j::Driver;
 my $session = Neo4j::Driver->new->basic_auth(...)->session;
 
 # explicit transaction
 my $transaction = $session->begin_transaction;
 
 # autocommit transaction
 my $result = $session->run('MATCH (m:Movie) RETURN m.name, m.year');

DESCRIPTION

Provides a context of work for database interactions.

A Session hosts a series of transactions carried out against a database. Within the database, all statements are carried out within a transaction. Within application code, however, it is not always necessary to explicitly begin a transaction. If a statement is run directly against a Session, the server will automatically BEGIN and COMMIT that statement within its own transaction. This type of transaction is known as an autocommit transaction.

Explicit transactions allow multiple statements to be committed as part of a single atomic operation and can be rolled back if necessary.

Only one open transaction per session at a time is supported. To work with multiple concurrent transactions (also known as "nested transactions"), simply use more than one session.

METHODS

Neo4j::Driver::Session implements the following methods.

begin_transaction

 my $transaction = $session->begin_transaction;

Begin a new explicit Transaction.

run

 my $result = $session->run('...');

Run and commit a statement using an autocommit transaction and return the StatementResult.

This method is semantically exactly equivalent to the following code, but is faster because it doesn't require an extra server roundtrip to commit the transaction.

 my $transaction = $session->begin_transaction;
 my $result = $transaction->run('...');
 $transaction->commit;

EXPERIMENTAL FEATURES

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

Calling in list context

 my @records = $session->run('...');
 my @results = $session->run([...]);

The run method tries to Do What You Mean if called in list context.

Close method

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

ServerInfo

 my $host_port = $session->server->address;
 my $version_string = $session->server->version;
 say "Contacting $version_string at $host_port.";

For security reasons, ResultSummary cannot provide ServerInfo. Therefore, ServerInfo is available from the Session instead.

In future, an extra server round-trip just to obtain the Neo4j version number might be a way to get around this restriction and offer the ServerInfo strings through ResultSummary after all. However, I'm really not sure if the ensuing performance penalty is worth it.

Concurrent explicit transactions

 my $session = Neo4j::Driver->new('http://...')->basic_auth(...)->session;
 my $tx1 = $session->begin_transaction;
 my $tx2 = $session->begin_transaction;

Since HTTP is a stateless protocol, the Neo4j HTTP API effectively allows multiple concurrently open transactions without special client-side considerations. This driver exposes this feature to the client and will continue to do so, but the interface is not yet finalised.

The Bolt protocol does not support concurrent explicit transactions.

Concurrent autocommit transactions

 my $tx1 = $session->begin_transaction;
 my $tx2 = $session->run(...);

Sessions support autocommit transactions while an explicit transaction is open. Since it is not clear to me if this is intended behaviour when the Bolt protocol is used, this feature is listed as experimental.

BUGS

The implementation of sessions in this driver is incomplete. In particular, some of the official drivers implement restrictions on the count of transactions that can be used per session and offer additional methods to manage transactions.

See the TODO document and Github for details.

SECURITY CONSIDERATIONS

Both Session as well as Transaction objects internally hold references to the authentication credentials used to contact the Neo4j server. Objects of these classes should therefore not be passed to untrusted modules. However, objects of the StatementResult class do not contain a reference to these credentials and are safe in this regard.

SEE ALSO

Neo4j::Driver, Neo4j::Driver::Transaction, Neo4j::Driver::StatementResult, Neo4j Java Driver, Neo4j JavaScript Driver, Neo4j .NET Driver

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)

cpanm Neo4j::Driver

perl -MCPAN -e shell
install Neo4j::Driver