/ 
Net-Async-CassandraCQL-0.05
River stage zero No dependents
/ Net::Async::CassandraCQL

NAME

Net::Async::CassandraCQL - use Cassandra databases with IO::Async using CQL

SYNOPSIS

use IO::Async::Loop;
use Net::Async::CassandraCQL;
use Protocol::CassandraCQL qw( CONSISTENCY_QUORUM );

my $loop = IO::Async::Loop->new;

my $cass = Net::Async::CassandraCQL->new(
   host => "localhost",
   keyspace => "my-keyspace",
   default_consistency => CONSISTENCY_QUORUM,
);
$loop->add( $cass );


$cass->connect->get;


my @f;
foreach my $number ( 1 .. 100 ) {
   push @f, $cass->query( "INSERT INTO numbers (v) VALUES $number" );
}
Future->needs_all( @f )->get;


my $get_stmt = $cass->prepare( "SELECT v FROM numbers" )->get;

my ( undef, $result ) = $get_stmt->execute( [] )->get;

foreach my $row ( $result->rows_hash ) {
   say "We have a number " . $row->{v};
}

DESCRIPTION

This module allows use of the CQL3 interface of a Cassandra database. It fully supports asynchronous operation via IO::Async, allowing both direct queries and prepared statements to be managed concurrently, if required. Alternatively, as the interface is entirely based on Future objects, it can be operated synchronously in a blocking fashion by simply awaiting each individual operation by calling the get method.

It is based on Protocol::CassandraCQL, which more completely documents the behaviours and limits of its ability to communicate with Cassandra.

EVENTS

on_event $name, @args

A registered event occurred. @args will depend on the event name. Each is also available as its own event, with the name in lowercase. If the event is not one of the types recognised below, @args will contain the actual Protocol::CassandraCQL::Frame object.

on_topology_change $type, $node

The cluster topology has changed. $node is a packed socket address.

on_status_change $status, $node

The node's status has changed. $node is a packed socket address.

on_schema_change $type, $keyspace, $table

A keyspace or table schema has changed.

PARAMETERS

The following named parameters may be passed to new or configure:

host => STRING

The hostname of the Cassandra node to connect to

service => STRING

Optional. The service name or port number to connect to.

username => STRING
password => STRING

Optional. Authentication details to use for PasswordAuthenticator.

keyspace => STRING

Optional. If set, a USE keyspace query will be issued as part of the connect method.

default_consistency => INT

Optional. Default consistency level to use if none is provided to query or execute.

METHODS

$str = $cass->quote( $str )

Quotes a string argument suitable for inclusion in an immediate CQL query string.

In general, it is better to use a prepared query and pass the value as an execute parameter though.

$str = $cass->quote_identifier( $str )

Quotes an identifier name suitable for inclusion in a CQL query string.

$f = $cass->connect( %args )

Connects to the Cassandra node an send the OPCODE_STARTUP message. The returned Future will yield nothing on success.

Takes the following named arguments:

host => STRING
service => STRING
keyspace => STRING

Optional. Overrides the configured values.

A host name is required, either as a named argument or as a configured value on the object. If the service name is missing, the default CQL port will be used instead.

$f = $cass->send_message( $opcode, $frame )

Sends a message with the given opcode and Protocol::CassandraCQL::Frame for the message body. The returned Future will yield the response opcode and frame.

( $reply_opcode, $reply_frame ) = $f->get

This is a low-level method; applications should instead use one of the wrapper methods below.

$f = $cass->startup

Sends the initial connection setup message. On success, the returned Future yields nothing.

Normally this is not required as the connect method performs it implicitly.

$f = $cass->options

Requests the list of supported options from the server node. On success, the returned Future yields a HASH reference mapping option names to ARRAY references containing valid values.

$f = $cass->query( $cql, $consistency )

Performs a CQL query. On success, the values returned from the Future will depend on the type of query.

( $type, $result ) = $f->get

For USE queries, the type is keyspace and $result is a string giving the name of the new keyspace.

For CREATE, ALTER and DROP queries, the type is schema_change and $result is a 3-element ARRAY reference containing the type of change, the keyspace and the table name.

For SELECT queries, the type is rows and $result is an instance of Protocol::CassandraCQL::Result containing the returned row data.

For other queries, such as INSERT, UPDATE and DELETE, the future returns nothing.

$f = $cass->query_rows( $cql, $consistency )

A shortcut wrapper for query which expects a rows result and returns it directly. Any other result is treated as an error. The returned Future returns a Protocol::CassandraCQL::Result directly

$result = $f->get

$f = $cass->prepare( $cql )

Prepares a CQL query for later execution. On success, the returned Future yields an instance of a prepared query object (see below).

( $query ) = $f->get

$f = $cass->execute( $id, $data, $consistency )

Executes a previously-prepared statement, given its ID and the binding data. On success, the returned Future will yield results of the same form as the query method. $data should contain a list of encoded byte-string values.

Normally this method is not directly required - instead, use the execute method on the query object itself, as this will encode the parameters correctly.

$f = $cass->register( $events )

Registers the connection's interest in receiving events of the types given in the ARRAY reference. Event names may be TOPOLOGY_CHANGE, STATUS_CHANGE or SCHEMA_CHANGE. On success, the returned Future yields nothing.

CONVENIENT WRAPPERS

The following wrapper methods all wrap the basic query operation.

$f = $cass->use_keyspace( $keyspace )

A convenient shortcut to the USE $keyspace query which escapes the keyspace name.

$f = $cass->schema_keyspaces

A shortcut to a SELECT query on system.schema_keyspaces, which returns a result object listing all the keyspaces.

( $result ) = $f->get

Exact details of the returned columns will depend on the Cassandra version, but the result should at least be keyed by the first column, called keyspace_name.

my $keyspaces = $result->rowmap_hash( "keyspace_name" )

$f = $cass->schema_columnfamilies( $keyspace )

A shortcut to a SELECT query on system.schema_columnfamilies, which returns a result object listing all the columnfamilies of the given keyspace.

( $result ) = $f->get

Exact details of the returned columns will depend on the Cassandra version, but the result should at least be keyed by the first column, called columnfamily_name.

my $columnfamilies = $result->rowmap_hash( "columnfamily_name" )

$f = $cass->schema_columns( $keyspace, $columnfamily )

A shortcut to a SELECT query on system.schema_columns, which returns a result object listing all the columns of the given columnfamily.

( $result ) = $f->get

Exact details of the returned columns will depend on the Cassandra version, but the result should at least be keyed by the first column, called column_name.

my $columns = $result->rowmap_hash( "column_name" )

TODO

  • Support frame compression

  • Allow storing multiple Cassandra node hostnames and perform some kind of balancing or failover of connections.

SPONSORS

This code was paid for by

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>