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.

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

    primaries => INT
            Optional. The number of primary node connections to maintain.
            Defaults to 1 if not specified.

    prefer_dc => STRING
            Optional. If set, prefer to pick primary nodes from the given
            data center, only falling back on others if there are not enough
            available.

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.

  $cass->connect( %args ) ==> ()
    Connects to the Cassandra node and starts up the connection. The
    returned Future will yield nothing on success.

    Takes the following named arguments:

    host => STRING
    service => STRING

    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.

  $cass->query( $cql, $consistency ) ==> ( $type, $result )
    Performs a CQL query. On success, the values returned from the Future
    will depend on the type of query.

    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.

  $cass->query_rows( $cql, $consistency ) ==> $result
    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

  $cass->prepare( $cql ) ==> $query
    Prepares a CQL query for later execution. On success, the returned
    Future yields an instance of a prepared query object (see below).

    Query objects stored internally cached by the CQL string; subsequent
    calls to `prepare' with the same exact CQL string will yield the same
    object immediately, saving a roundtrip.

  $cass->execute( $query, $data, $consistency ) ==> ( $type, $result )
    Executes a previously-prepared statement, given 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.

  $cass->schema_keyspaces ==> $result
    A shortcut to a `SELECT' query on `system.schema_keyspaces', which
    returns a result object listing all the keyspaces.

    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" )

  $cass->schema_columnfamilies( $keyspace ) ==> $result
    A shortcut to a `SELECT' query on `system.schema_columnfamilies', which
    returns a result object listing all the columnfamilies of the given
    keyspace.

    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" )

  $cass->schema_columns( $keyspace, $columnfamily ) ==> $result
    A shortcut to a `SELECT' query on `system.schema_columns', which returns
    a result object listing all the columns of the given columnfamily.

    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
    *       Allow storing multiple Cassandra seed node hostnames for
            startup.

    *       Allow other load-balancing strategies than roundrobin.

    *       Adjust connected primary nodes when changing `primaries'
            parameter.

    *       Allow backup nodes, for faster connection failover.

    *       Use `TOPOLOGY_CHANGE' events to keep the nodelist updated.

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>