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

NAME

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

VERSION

version 0.40

SYNOPSIS

use Neo4j::Driver;
$session = Neo4j::Driver->new->basic_auth(...)->session;

# managed transaction function
@records = $session->execute_read( sub ($transaction) {
  $transaction->run('MATCH (m:Movie) RETURN m')->list;
});

# unmanaged explicit transaction
$transaction = $session->begin_transaction;

# autocommit transaction
$result = $session->run('MATCH (m:Movie) RETURN m.name, m.year');

DESCRIPTION

Provides a context of work for database interactions.

A Session is a logical container hosting a series of transactions carried out against a database. Transactions can be either managed, unmanaged, or auto-commit transactions:

Managed transaction functions

A transaction function bundles an atomic unit of work that is either automatically committed when the function (subroutine) returns, or rolled back if an exception is thrown during query execution or by the user code. This means you don't have to think much about steps like begin or commit – the driver will do it all for you.

However, transaction functions must always be idempotent, because they might be retried (re-executed) multiple times in certain error conditions, for example if the connection breaks down during execution. See "execute_read" and "execute_write" below.

Unmanaged explicit transactions

Instead of using transaction functions, you can choose to handle begin, commit, rollback, and failures entirely yourself in an unmanaged transaction. This gives you more freedom in your interactions with the transaction, but it's also a bit more cumbersome. See "begin_transaction".

Auto-commit transactions

For simple one-off queries where you don't want to deal with explicit transactions at all, there is also a way to run queries directly on a session. Opening a transaction before and committing it afterwards happens implicitly on the server. However, unlike a managed transaction function, auto-commit queries will never be retried. See "run" below.

Only one open transaction per session at a time is supported. To work with multiple concurrent transactions, simply use more than one session. On http: and https: connections, you can alternatively enable concurrent transactions within the same session through a config option (currently experimental); see "Concurrent transactions in HTTP sessions" in Neo4j::Driver for details.

To create a new session, call "session" in Neo4j::Driver.

METHODS

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

begin_transaction

$transaction = $session->begin_transaction;

Begin a new explicit Transaction.

execute_read

@records = $session->execute_read( sub ($tx) {
  $tx->run('...')->list;
});

Exactly like execute_write(), except that it tries to route the request to a read-only server if one is available. This is a performance optimisation only and does not imply access control.

The effect of using this method to run queries that modify the database is unspecified.

execute_write

@records = $session->execute_write( sub ($tx) {
  $tx->run('...')->list;
});

Execute a unit of work as a single, managed transaction with retry behaviour. The transaction allows for one or more queries to be run.

The driver will automatically commit the transaction when the provided subroutine finishes execution. Any error raised during execution will result in a rollback attempt. For certain kinds of errors, the given subroutine will be retried with exponential backoff until "max_transaction_retry_time" in Neo4j::Driver::Config (see "is_retryable" in Neo4j::Error for the complete list). Because of this, the given subroutine needs to be idempotent (i. e., have the same effect regardless of how many times it is executed).

Note that Neo4j::Driver::Result objects may not be valid outside of the given subroutine. While the driver currently doesn't prevent you from returning such an object from the subroutine, the effect of doing so with results retrieved over a Bolt connection is unspecified. A simple solution might be to return the list of records from the subroutine instead, which is always safe to do.

run

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

Run and commit a statement using an auto-commit transaction and return the Result.

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.

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

server

$address = $session->server->address;
$version = $session->server->agent;

Obtain the ServerInfo, consisting of the host, port, protocol and Neo4j version.

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.

Concurrent transactions

%config = ( uri => 'http://...', concurrent_tx => 1 );
$session = Neo4j::Driver->new(\%config)->session;
$tx1 = $session->begin_transaction;
$tx2 = $session->begin_transaction;
$tx3 = $session->run(...);

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. See "Concurrent transactions in HTTP sessions" in Neo4j::Driver for further details.

The Bolt protocol does not support concurrent transactions (sometimes known as "nested transactions") within the same session.

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 ServerInfo class and the Result class (if detached) do not contain a reference to these credentials and are safe in this regard.

SEE ALSO

AUTHOR

Arne Johannessen <ajnn@cpan.org>

If you contact me by email, please make sure you include the word "Perl" in your subject header to help beat the spam filters.

COPYRIGHT AND LICENSE

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