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.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>