NAME

Protocol::CassandraCQL::Client - a minimal Cassandra CQL client

SYNOPSIS

 use Protocol::CassandraCQL::Client;
 use Protocol::CassandraCQL qw( CONSISTENCY_QUORUM );

 my $cass = Protocol::CassandraCQL::Client->new(
    PeerHost => "localhost",
    Keyspace => "my-keyspace",
 );

 my ( undef, $result ) = $cass->query( "SELECT v FROM numbers" );

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

DESCRIPTION

This subclass of IO::Socket::IP implements a client that can execute queries on a Cassandra CQL database. It is not intended as a complete client, is simply provides enough functionallity to test that the protocol handling is working, and is used to implement the bundled examples/cqlsh utility.

For a more complete client, see instead Net::Async::CassandraCQL.

CONSTRUCTOR

$cass = Protocol::CassandraCQL::Client->new( %args )

Takes the following arguments in addition to those accepted by IO::Socket::IP:

Username => STRING

Password => STRING

Authentication credentials if required by the server.

Keyspace => STRING

If defined, selects the keyspace to USE after connection.

CQLVersion => INT

If defined, sets the CQL protocol version that will be negotiated. If omitted will default to 1.

METHODS

( $result_op, $result_frame ) = $cass->send_message( $opcode, $frame )

Sends a message with the given opcode and Protocol::CassandraCQL::Frame for the message body. Waits for a response to be received, and returns it.

If the response opcode is OPCODE_ERROR then the error message string is thrown directly as an exception; this method will only return in non-error cases.

( $type, $result ) = $cass->query( $cql, $consistency )

Performs a CQL query and returns the result, as decoded by "parse_result_frame" in Protocol::CassandraCQL::Frames.

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

For CREATE, ALTER and DROP queries, the type is RESULT_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 RESULT_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 method returns RESULT_VOID and $result is undef.

( $type, $result ) = $cass->use_keyspace( $keyspace )

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

TODO

• Consider how the server's maximum supported CQL version can be detected on startup. This is made hard by the fact that the server closes the connection if the version is too high, so we'll have to reconnect it.

SPONSORS

This code was paid for by

• Perceptyx http://www.perceptyx.com/

• Shadowcat Systems http://www.shadow.cat

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>