File Coverage

blib/lib/Neo4j/Bolt/Cxn.pm

Criterion	Covered	Total	%
statement	8	39	20.5
branch	0	18	0.0
condition	0	16	0.0
subroutine	2	11	18.1
pod	8	9	88.8
total	18	93	19.3

package Neo4j::Bolt::Cxn;
use Carp qw/croak/;

BEGIN {
  our $VERSION = "0.4203";
  require Neo4j::Bolt::CTypeHandlers;
  require Neo4j::Bolt::ResultStream;
  require XSLoader;
  XSLoader::load();
}
sub default_db () { $Neo4j::Bolt::DEFAULT_DB // "" }

sub errnum { shift->errnum_ }
sub errmsg { shift->errmsg_ }
sub reset_cxn { shift->reset_ }

sub server_id { shift->server_id_ }
sub protocol_version { shift->protocol_version_ }

sub run_query {
  my $self = shift;
  my ($query, $parms, $db) = @_;
  unless ($query) {
    croak "Arg 1 should be Cypher query string";
  }
  if ($parms && !(ref $parms == 'HASH')) {
    croak "Arg 2 should be a hashref of { param => $value, ... }";
  }
  croak "No connection" unless $self->connected;
  utf8::upgrade($query);
  return $self->run_query_($query, $parms // {}, 0, $db // default_db);
}

sub send_query {
  my $self = shift;
  my ($query, $parms) = @_;
  unless ($query) {
    croak "Arg 1 should be Cypher query string";
  }
  if ($parms && !(ref $parms == 'HASH')) {
    croak "Arg 2 should be a hashref of { param => $value, ... }";
  }
  croak "No connection" unless $self->connected;
  utf8::upgrade($query);
  return $self->run_query_($query, $parms ? $parms : {}, 1, $db // default_db );
}

sub do_query {
  my $self = shift;
  my $stream = $self->run_query(@_);
  my @results;
  if ($stream->success_) {
    while (my @row = $stream->fetch_next_) {
      push @results, [@row];
    }
  }
  return wantarray ? ($stream, @results) : $stream;
}

=head1 NAME

Neo4j::Bolt::Cxn - Container for a Neo4j Bolt connection

=head1 SYNOPSIS

 use Neo4j::Bolt;
 $cxn = Neo4j::Bolt->connect("bolt://localhost:7687");
 unless ($cxn->connected) {
   die "Problem connecting: ".$cxn->errmsg;
 }
 $stream = $cxn->run_query(
   "MATCH (a) RETURN head(labels(a)) as lbl, count(a) as ct",
 );
 if ($stream->failure) {
   print STDERR "Problem with query run: ".
                 ($stream->client_errmsg || $stream->server_errmsg);
 }

=head1 DESCRIPTION

L is a container for a Bolt connection, instantiated by
a call to C<< Neo4j::Bolt->connect() >>.

=head1 METHODS

=over

=item connected()

True if server connected successfully. If not, see L and
L.

=item protocol_version()

Returns a string representing the major and minor Bolt protocol version of the
server, as ".", or the empty string if not connected.

=item run_query($cypher_query, [$param_hash])

Run a L query on
the server. Returns a L which can be iterated
to retrieve query results as Perl types and structures. [$param_hash]
is an optional hashref of the form C<{ param =E $value, ... }>.

=item send_query($cypher_query, [$param_hash])

Send a L query to
the server. All results (except error info) are discarded.

=item do_query($cypher_query, [$param_hash])

  ($stream, @rows) = do_query($cypher_query);
  $stream = do_query($cypher_query, $param_hash);

Run a L query on
the server, and iterate the stream to retrieve all result
rows. C is convenient for running write queries (e.g.,
C ), since it returns the $stream
with L ready for reading.

=item reset_cxn()

Send a RESET message to the Neo4j server. According to the L
protocol|https://boltprotocol.org/v1/>, this should force any currently
processing query to abort, forget any pending queries, clear any
failure state, dispose of outstanding result records, and roll back
the current transaction.

=item errnum(), errmsg()

Current error state of the connection. If

 $cxn->connected == $cxn->errnum == 0

then you have a virgin Cxn object that came from someplace other than
C<< Neo4j::Bolt->connect() >>, which would be weird.

=item server_id()

 print $cxn->server_id;  # "Neo4j/3.3.9"

Get the server ID string, including the version number. C if
connecting wasn't successful or the server didn't identify itself.

=back

=head1 SEE ALSO

L, L.

=head1 AUTHOR

 Mark A. Jensen
 CPAN: MAJENSEN
 majensen -at- cpan -dot- org

=head1 LICENSE

This software is Copyright (c) 2019-2021 by Mark A. Jensen.

This is free software, licensed under:

  The Apache License, Version 2.0, January 2004

=cut

1;