NAME

DBIx::Async - use DBI with IO::Async

VERSION

version 0.002

SYNOPSIS

 #!/usr/bin/env perl 
 use strict;
 use warnings;
 use feature qw(say);
 use IO::Async::Loop;
 use DBIx::Async;
 my $loop = IO::Async::Loop->new;
 say 'Connecting to db';
 $loop->add(my $dbh = DBIx::Async->connect(
   'dbi:SQLite:dbname=test.sqlite3',
   '',
   '', {
     AutoCommit => 1,
     RaiseError => 1,
   }
 ));
 $dbh->do(q{CREATE TABLE tmp(id integer primary key autoincrement, content text)})
 # ... put some values in it
 ->then(sub { $dbh->do(q{INSERT INTO tmp(content) VALUES ('some text'), ('other text') , ('more data')}) })
 # ... and then read them back
 ->then(sub {
   # obviously you'd never really use * in a query like this...
   my $sth = $dbh->prepare(q{select * from tmp});
   $sth->execute;
   # the while($row = fetchrow_hashref) construct isn't a good fit
   # but we attempt to provide something reasonably close using the
   # ->iterate helper
   $sth->iterate(
     fetchrow_hashref => sub {
       my $row = shift;
       say "Row: " . join(',', %$row);
     }
   );
 })->on_done(sub {
   say "Query complete";
   $loop->stop;
 })->on_fail(sub { warn "Failure: @_\n" });
 $loop->run;

DESCRIPTION

Wrapper for DBI, for running queries much slower than usual but without blocking.

NOTE: This is an early release, please get in contact via email (see "AUTHOR" section) or RT before relying on it for anything.

PERFORMANCE

Greatly lacking. See examples/benchmark.pl, in one sample run the results looked like this:

               Rate DBIx::Async DBD::SQLite
 DBIx::Async 1.57/s          --        -89%
 DBD::SQLite 13.8/s        776%          --

If you're doing anything more than occasional light queries, you'd probably be better off with blocking DBI-based code running in a fork.

METHODS

Where possible, DBI method signatures are used.

connect

Constuctor. Sets up our instance with parameters that will be used when we attempt to connect to the given DSN.

Takes the following options:

• $dsn - the data source name, should be something like 'dbi:SQLite:dbname=:memory:'

• $user - username to connect as

• $pass - password to connect with

• $opt - any options

Options consist of:

• RaiseError - set this to 1

• AutoCommit - whether to run in AutoCommit mode by default, probably works better if this is set to 1 as well

NOTE: Despite the name, this method does not initiate a connection. This may change in a future version, but if this behaviour does change this method will still return $self.

Returns $self.

dsn

Returns the DSN used in the "connect" request.

user

Returns the username used in the "connect" request.

pass

Returns the password used in the "connect" request.

options

Returns any options that were set in the "connect" request.

do

Runs a query with optional bind parameters. Takes the following parameters:

• $sql - the query to run

• $options - any options to apply (can be undef)

• @params - the parameters to bind (can be empty)

Returns a Future which will resolve when this query completes.

begin_work

Starts a transaction.

Returns a Future which will resolve when this transaction has started.

commit

Commit the current transaction.

Returns a Future which will resolve when this transaction has been committed.

savepoint

Marks a savepoint. Takes a single parameter: the name to use for the savepoint.

 $dbh->savepoint('here');

Returns a Future which will resolve once the savepoint has been created.

release

Releases a savepoint. Takes a single parameter: the name to use for the savepoint.

 $dbh->release('here');

This is similar to "commit" for the work which has been completed since the savepoint, although the database state is not updated until the transaction itself is committed.

Returns a Future which will resolve once the savepoint has been released.

rollback

Rolls back this transaction. Takes an optional savepoint which can be used to roll back to the savepoint rather than cancelling the entire transaction.

Returns a Future which will resolve once the transaction has been rolled back.

prepare

Attempt to prepare a query.

Returns the statement handle as a DBIx::Async::Handle instance.

INTERNAL METHODS

These are unlikely to be of much use in application code.

queue

Queue a request. Used internally.

Returns a Future.

worker_class_from_dsn

Returns $self.

sth_ch

The channel used for prepared statements.

ret_ch

The channel which returns values.

_add_to_loop

Sets things up when we are added to a loop.

_remove_from_loop

Doesn't do anything.

TODO

• Much of the DBI API is not yet implemented. Fix this.

• Provide a nicer wrapper around transactions.

• Consider supporting Net::Async::PostgreSQL and Net::Async::MySQL natively, might lead to some performance improvements.

SEE ALSO

• DBI - the database framework that does all the real work

• Net::Async::PostgreSQL - nonblocking interaction with PostgreSQL, not DBI compatible

INHERITED METHODS

IO::Async::Notifier

add_child, can_event, children, configure, debug_printf, get_loop, invoke_event, loop, make_event_cb, maybe_invoke_event, maybe_make_event_cb, new, notifier_name, parent, remove_child, remove_from_parent

AUTHOR

Tom Molesworth <cpan@entitymodel.com>

LICENSE

Copyright Tom Molesworth 2012-2014. Licensed under the same terms as Perl itself.

cpanm DBIx::Async

perl -MCPAN -e shell
install DBIx::Async