view release on metacpan or  search on metacpan

lib/Neo4j/Driver/Config.pod  view on Meta::CPAN

this is an unblessed hash reference with the authentication
scheme declared in the hash entry C<scheme>.

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

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

=head2 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 C<http:> or C<https:> protocol scheme.

This driver allows concurrent transactions on HTTP when the
C<concurrent_tx> config option is enabled. Trying to enable this
option on a Bolt connection is a fatal error.

Using concurrent transactions in new code is discouraged,
because it will make your code less portable.
This feature exists primarily to support legacy applications.

=head2 cypher_params

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

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

Cypher's modern C<$> 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 C<{}> parameter syntax instead.

=head2 encrypted

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

Specifies whether to use secure communication using TLS. This
L<implies|IO::Socket::SSL/"Essential Information About SSL/TLS">
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 C<trust_ca> option.

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

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

Before version 0.27, this option was named C<tls>. That name has since
been deprecated, matching a corresponding change in S<Neo4j 3.2>.

=head2 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 S<30 seconds>.

=head2 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.

=head2 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, S<i. e.> the S<"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 S<"CA bit"> is set.

Before version 0.27, this option was named C<tls_ca>. That name has
since been deprecated, as it didn't match Neo4j terminology.

=head2 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 C<bolt>, C<http>,
C<https>, and C<neo4j>.
Use of C<bolt> URIs requires L<Neo4j::Bolt> to be installed; use
of C<https> URIs requires L<IO::Socket::SSL> to be installed.

All URIs using the C<neo4j> scheme are interpreted either as C<bolt>
or as C<http>/C<https> URIs. The conditions that influence this
behaviour are unspecified for this driver and are subject to change.
Instead of relying on the C<neo4j> URI scheme, you should explicitly
select C<bolt> or C<http>/C<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
C<127.0.0.1> and the protocol C<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 C<localhost> when using HTTP. The connection may
appear to "hang". Literal IP addresses like C<127.0.0.1> are not
affected.

=head1 SEE ALSO

L<Neo4j::Driver>

=head1 AUTHOR

Arne Johannessen (L<AJNN|https://metacpan.org/author/AJNN>)

=head1 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.

=cut