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.

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.

    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
  $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->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.

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.

PREPARED QUERIES
    Prepared query objects are returned by `prepare', and have the following
    methods, in addition to those of its parent class,
    Protocol::CassandraCQL::ColumnMeta.

  $id = $query->id
    Returns the query ID.

  $f = $query->execute( $data, $consistency )
    Executes the query on the Cassandra connection object that created it,
    returning a future yielding the result the same way as the `query' or
    `execute' methods.

    The contents of the `$data' reference will be encoded according to the
    types given in the underlying column metadata. `$data' may be given as a
    positional ARRAY reference, or a named HASH reference where the keys
    give column names.

TODO
    *       Handle OPCODE_AUTHENTICATE and OPCODE_REGISTER

    *       Support frame compression

    *       Move Protocol::CassandraCQL to its own distribution

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

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>

