NAME
DBIx::Async - use DBI with IO::Async
VERSION
version 0.003
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=:memory:',
'',
'', {
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";
})->on_fail(sub { warn "Failure: @_\n" })->get;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
Attempts to locate a suitable worker subclass, given a DSN.
For example:
$dbh->worker_class_from_dsn('dbi:SQLite:memory')should return 'DBIx::Async::Worker::SQLite'.
Note that this method will load the class if it is not already present.
Returns the class as a string.
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 yet.
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, adopt_future, can_event, children, configure, configure_unknown, debug_printf, get_loop, invoke_error, 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@perlsite.co.uk>
LICENSE
Copyright Tom Molesworth 2012-2015. Licensed under the same terms as Perl itself.