/ 
Neo4j-Driver-1.01-TRIAL
River stage one • 1 direct dependent • 2 total dependents
/ Neo4j::Driver::Transaction

NAME

Neo4j::Driver::Transaction - Logical container for an atomic unit of work

VERSION

version 1.01

SYNOPSIS

# Managed transaction function
$session->execute_write( sub ($transaction) {
  $transaction->run( ... );
  # Automatic commit upon subroutine return
  
  if ( my $failure = ... ) {
    die;   # any exception will cause a rollback
    $transaction->rollback;  # explicit rollback
  }
});

# Unmanaged explicit transaction
$transaction = $session->begin_transaction;
$transaction->run( ... );
if ( my $success = ... ) {
  $transaction->commit;
} else {
  $transaction->rollback;
}

# Query parameters
$query = "RETURN \$param";
$transaction->run( $query, { param => $value, ... } );
$transaction->run( $query,   param => $value, ...   );

# Neo4j v2 syntax for query parameters
$driver->config( cypher_params => v2 );
$query = "RETURN {param}";

DESCRIPTION

Logical container for an atomic unit of work that is either committed in its entirety or is rolled back on failure. A driver Transaction object corresponds to a server transaction.

Queries may be run lazily. Most of the time, you will not notice this, because the driver automatically waits for queries to complete at specific points to fulfill its contracts. If you require execution of a query to have completed (e. g. to check for query errors), you need to call any method in the Result, such as has_next().

Neo4j drivers allow the creation of different kinds of transactions. See Neo4j::Driver::Session for details.

METHODS

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

commit

$transaction->commit;

Commits an unmanaged transaction.

After committing, the transaction is closed and can no longer be used.

is_open

$bool = $transaction->is_open;

Report whether this transaction is still open, which means commit or rollback has not happened and the transaction has not timed out.

Bolt transactions by default have no timeout. If necessary, the timeout for idle HTTP transactions may be configured in the Neo4j server using the setting dbms.rest.transaction.idle_timeout or server.http.transaction_idle_timeout, depending on the version.

rollback

$transaction->rollback;

Rolls back a transaction.

After rolling back the transaction is closed and can no longer be used.

run

$result = $transaction->run($query);
$result = $transaction->run($query, \%params);

Run a query and return the Result. This method takes an optional set of parameters that will be injected into the Cypher query by Neo4j. Using parameters is highly encouraged: It helps avoid dangerous Cypher injection attacks and improves database performance as Neo4j can re-use query plans more often.

Parameters are given as Perl hashref. Alternatively, they may be given as a hash / balanced list.

# all of these are semantically equal
$result = $transaction->run('...', {key => 'value'});
$result = $transaction->run('...',  key => 'value' );
%hash = (key => 'value');
$result = $transaction->run('...', \%hash);
$result = $transaction->run('...',  %hash);

When used as parameters, Perl values are converted to Neo4j types as shown in the following example:

$parameters = {
  number =>  0 + $scalar,
  string => '' . $scalar,
  true   => builtin::true,   # or JSON::PP::true
  false  => builtin::false,  # or JSON::PP::false
  null   => undef,
  list   => [ ],
  map    => { },
};

For details and for known issues with type mapping see Neo4j::Driver::Types.

Running empty queries is supported. They yield an empty result (having zero records). With HTTP connections, the empty result is retrieved from the server, which resets the transaction timeout. This feature may also be used to test the connection to the server. For Bolt connections, the empty result is generated locally in the driver.

$result = $transaction->run;

Queries are usually strings, but may also be REST::Neo4p::Query or Neo4j::Cypher::Abstract objects. Such objects are automatically converted to strings before they are sent to the Neo4j server.

$transaction->run( REST::Neo4p::Query->new('RETURN 42') );
$transaction->run( Neo4j::Cypher::Abstract->new->return(42) );

ERROR HANDLING

This driver always reports all errors using die(). Error messages received from the Neo4j server are passed on as-is. See "error" in Neo4j::Driver::Plugin for accessing error details.

Query errors can occur when the query is executed on the server. This may not necessarily have happened by the time run() returns. If you use try/catch to handle errors, make sure you actually use the Result within the try block, for example by retrieving a record or calling the method has_next().

Transactions are rolled back and closed automatically if the Neo4j server encounters an error when running a query. However, if an error with the network connection to the server occurs, or if an internal error occurs in the driver or in one of its supporting modules, unmanaged transactions may remain open.

Typically, no particular handling of error conditions is required. But if you use try/catch, you intend to continue using the same session even after an error condition, and you want to be absolutely sure the session is in a defined state, you can roll back a failed transaction manually:

use Feature::Compat::Try;
$tx = $session->begin_transaction;
try {
  ...;
  $tx->commit;
}
catch ($e) {
  say "Database error: $e";
  ...;
  $tx->rollback if $tx->is_open;
}
# at this point, $session is safe to use

SEE ALSO

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.