NAME¶

DBD::Cassandra - DBI database backend for Cassandra

VERSION¶

version 0.57

DESCRIPTION¶

DBD::Cassandra is a Perl5 Database Interface driver for Cassandra, using the CQL3 query language.

EXAMPLE¶

    use DBI;
    my $dbh = DBI->connect("dbi:Cassandra:host=localhost;keyspace=test", $user, $password, { RaiseError => 1 });
    my $rows = $dbh->selectall_arrayref("SELECT id, field_one, field_two FROM some_table");
    for my $row (@$rows) {
        # Do something with your row
    }
    $dbh->do("INSERT INTO some_table (id, field_one, field_two) VALUES (?, ?, ?)",
        { Consistency => "quorum" },
        1, "String value", 38962986
    );
    $dbh->disconnect;

COLLECTION TYPES¶

Cassandra supports collection types natively, eg. "list" and "map". DBD::Cassandra translates them to native Perl types, eg. hashes and arrays.

When doing queries, placeholders can be substituted by these collections. For example, inserting a map into a table is done by passing a Perl hash.

    my $sth= $dbh->prepare('INSERT INTO some_table (id, value) VALUES (?,?);');
    $sth->execute(5, { days => 15 });

This will also work for "IN" queries, which accept an array.

    my $sth= $dbh->prepare('SELECT id, value FROM some_table WHERE id IN ?');
    $sth->execute([1, 2, 3]);
    my $rows= $sth->fetchall_arrayref();

ASYNCHRONOUS QUERIES¶

    my $sth= $dbh->prepare("SELECT id FROM some_table WHERE x=?",
        { async => 1 });
    $sth->execute(5);
    some_other_function();
    while (my $row = $sth->fetchrow_arrayref()) {
        print "$row->[0]\n";
    }

DBD::Cassandra supports asynchronous queries in an easy to use form. When "async =" 1> is passed to "prepare()", any subsequent executes on the handle are not read back immediately. Instead, these are delayed until the result is actually needed.

For inserts and other writes, a convenience method "x_finish_async" is provided, which returns an approximation to what "execute()" would have returned in an non-asynchronous context. This method also raises errors, if needed.

    my $sth= $dbh->prepare("INSERT INTO table (a, b) VALUES (?, ?)",
        { async => 1 });
    $sth->execute(5, 6);
    some_other_function_that_takes_a_while();
    $sth->x_finish_async;

    my @dataset_to_insert= ([1, 2, 3, 4], [5, 6, 7, 8]);
    my (@pending, @reusable);
    while (my $row= shift @dataset_to_insert) {
        my $sth= (shift @reusable) || $dbh->prepare(
            "INSERT INTO some_table (a, b, c, d) VALUES (?, ?, ?, ?)"
        );
        $sth->execute(@$row);
        push @pending, $sth;
        if (@pending > 500) { # Tune this number!
            my $pending_sth= shift @pending;
            $pending_sth->x_finish_async;
            push @reusable, $pending_sth;
        }
    }
    $_->x_finish_async for @pending;

CONSISTENCY LEVELS¶

    $dbh->do("INSERT INTO some_table (id, field_name) VALUES (?, ?)",
        { Consistency => "quorum" },
        @values
    );

DBD::Cassandra accepts a Consistency attribute for statements. Supported consistency levels are "any", "one", "two", "three", "quorum", "all", "local_quorum", "each_quorum", "serial", "local_serial" and "local_one".

This attribute is ignored on statements that do not support it, such as "CREATE".

A global consistency level can be defined as part of the DSN.

CAVEATS, BUGS, TODO¶

• There is currently no support for transactions. "begin_work" will die if you try to use it.
• Thread support is untested. Use at your own risk.
• The "timestamp" format is implemented naively by returning milliseconds since the UNIX epoch. In Perl you get this number through "time() * 1000". Trying to save times as "DateTime" objects or strings will not work, and will likely result in warnings and unexpected behavior.
• When using asynchronous queries, more functions than just execute() may throw errors. It is recommended that you enable RaiseError. If this is not possible, it should also suffice to call "$sth-"x_finish_async> and check its return value before reading any data from the handle.
• Cassandra/CQL3 is strict about the queries you write. When switching from other databases, such as MySQL, this may come as a surprise. This module supports "quote(..)", but try to use prepared statements instead. They will save you a lot of trouble.

UPGRADING¶

    my $good_float = unpack('f>', pack('f', $bad_float));
    my $good_double= unpack('d>', pack('d', $bad_double));

AUTHOR¶

Tom van der Woerdt <tvdw@cpan.org>

COPYRIGHT AND LICENSE¶

This software is copyright (c) 2017 by Tom van der Woerdt.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.