The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Neo4j-Driver-0.48
River stage one • 1 direct dependent • 2 total dependents
4 ++
/ Neo4j::Driver::Config

NAME

Neo4j::Driver::Config - Driver configuration options

VERSION

version 0.48

SYNOPSIS

 $driver = Neo4j::Driver->new({ option => 'value' });
 $driver->config( option => 'value' );
 $value = $driver->config( 'option' );
 
 $driver->config(
   
   # Authentication details for the Neo4j server
   auth => { scheme => 'basic', principal => $user,
             credentials => $password },
   
   # Concurrent transactions in HTTP sessions
   concurrent_tx => 1,
   
   # Enable both {param} and $param as Cypher parameter syntax
   cypher_params => v2,
   
   # Secure communication using TLS
   encrypted => 1,
   
   # Managed transaction timeout
   max_transaction_retry_time => 30,  # seconds
   
   # General network timeout
   timeout => 60,  # seconds
   
   # TLS certificate file
   trust_ca => 'neo4j/certificates/neo4j.cert',
   
   # Connection URI for the Neo4j server
   uri => 'https://[::1]',
 
 );

CONFIGURATION OPTIONS

Neo4j::Driver implements the following configuration options.

auth

 $driver->config(auth => {
   scheme      => 'basic',
   principal   => $user_id,   # 'neo4j' by default
   credentials => $password,
 });

Specifies the authentication details for the Neo4j server. The authentication details are provided as a Perl reference that is made available to the network adapter. Typically, this is an unblessed hash reference with the authentication scheme declared in the hash entry scheme.

The Neo4j server uses the auth scheme 'basic' by default, which must be configured with a user id in the hash entry principal and a password in the entry credentials, as shown above. Alternatively, the method "basic_auth" in Neo4j::Driver can be used as a shortcut, or the basic auth details can be specified as userinfo in the URI.

The auth config option defaults to the value undef, which disables authentication.

concurrent_tx

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

The Neo4j Driver API officially doesn't allow multiple concurrent transactions (sometimes called "nested transactions") to be open within the same session. The standard way to work with multiple concurrent transactions is to simply use multiple sessions. However, since HTTP is a stateless protocol, concurrent transactions are technically possible on connections which use the http: or https: protocol scheme.

This driver allows concurrent transactions on HTTP when the concurrent_tx config option is enabled. Trying to enable this option on a Bolt connection is a fatal error. The driver will currently give warnings when using concurrent transactions on HTTP without enabling this option, but these warnings will become fatal errors in driver version 1.xx.

Using concurrent transactions will make your code less portable. This feature exists primarily to support legacy applications.

cypher_params

 $driver->config( cypher_params => v2 );
 $foo = $driver->session->run('RETURN {bar}', bar => 'foo');

Enables conversion of the old Cypher parameter syntax {param} supported by Neo4j version 2 to the modern syntax $param supported by Neo4j version 3 and newer. The only allowed value for this config option is v2 (quoted or unquoted).

Cypher's modern $ parameter syntax unfortunately may cause string interpolations in Perl, which decreases database performance because Neo4j can re-use query plans less often. It is also a potential security risk (Cypher injection attacks). Using this config option enables your code to use the safer {} parameter syntax instead.

encrypted

 $driver->config(encrypted => 1);

Specifies whether to use secure communication using TLS. This implies not just encryption, but also verification of the server's identity.

By default, a trust store on the local system will be used to verify the server's identity. This will fail unless your Neo4j installation uses a key pair that is trusted and verifiable through the global CA infrastructure. If that's not the case, you may need to additionally use the trust_ca option.

This option defaults to 0 (no encryption). This is generally what you want if you connect to a server on localhost.

This option is only useful for Bolt connections. For HTTP connections, the use of TLS encryption is governed by the chosen URI scheme (http / https).

Before version 0.27, this option was named tls. Use of the former name is now discouraged.

max_transaction_retry_time

 $driver->config(max_transaction_retry_time => 6);  # seconds

Specifies the maximum amount of time that a managed transaction will retry before failing. The default value is 30 seconds.

timeout

 $driver->config(timeout => 60);  # seconds

Specifies the connection timeout. The semantics of this config option vary by network library. Its default value is therefore not defined here and is subject to change.

For details, see "timeout" in LWP::UserAgent when using HTTP or select(2) when using Bolt.

trust_ca

 $driver->config(trust_ca => 'neo4j/certificates/neo4j.cert');

Specifies the path to a file containing one or more trusted TLS certificates. When this option is given, encrypted connections will only be accepted if the server's identity can be verified using the certificates provided.

The certificates in the file must be PEM encoded. They are expected to be "root" certificates, i. e. the "CA bit" needs to be set and the certificate presented by the server must be signed by one of the certificates in this file (or by an intermediary).

Self-signed certificates (such as those automatically provided by some Neo4j versions) should also work if their "CA bit" is set.

Before version 0.27, this option was named tls_ca. Use of the former name is now discouraged.

uri

 $driver->config(uri => 'http://localhost:7474');

Specifies the Neo4j server connection URI. The URI scheme determines the type of driver created. Supported schemes are bolt, http, https, and neo4j. Use of bolt URIs requires Neo4j::Bolt to be installed; use of https URIs requires LWP::Protocol::https to be installed.

All URIs using the neo4j scheme are interpreted either as bolt or as http/https URIs. The conditions that influence this behaviour are unspecified for this driver and are subject to change. Instead of relying on the neo4j URI scheme, you should explicitly select bolt or http/https, as appropriate for your database setup. No first-party implementation of client-side routing is planned (but plug-ins might get a hook for it in a future version).

If a part of the URI or even the entire URI is missing, suitable default values will be substituted. In particular, the host name 127.0.0.1 and the protocol neo4j will be used as defaults; if no port is specified, the protocol's default port will be used.

 # all of these are semantically equal
 $driver->config(uri =>  undef );
 $driver->config(uri => '127.0.0.1');
 $driver->config(uri => 'neo4j:');
 $driver->config(uri => 'neo4j://127.0.0.1');
 
 # default ports for each protocol are optional
 $driver->config(uri => 'bolt://localhost');   # port 7687
 $driver->config(uri => 'http://localhost');   # port 7474
 $driver->config(uri => 'https://localhost');  # port 7473
 $driver->config(uri => 'neo4j://localhost');  # varies

Note that there sometimes are issues with IPv4/IPv6 dual-stack hostnames such as localhost when using HTTP. The connection may appear to "hang". Literal IP addresses like 127.0.0.1 are not affected. See "IPv6 / dual-stack support" in Neo4j::Driver::Net for further discussion.

SEE ALSO

Neo4j::Driver

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.