NAME

    AnyEvent::DBI::MySQL - Asynchronous MySQL queries

VERSION

    This document describes AnyEvent::DBI::MySQL version v2.1.0

SYNOPSIS

        use AnyEvent::DBI::MySQL;
    
        # get cached but not in use $dbh
        $dbh = AnyEvent::DBI::MySQL->connect(…);
    
        # async
        $dbh->do(…,                 sub { my ($rv, $dbh) = @_; … });
        $sth = $dbh->prepare(…);
        $sth->execute(…,            sub { my ($rv, $sth) = @_; … });
        $dbh->selectall_arrayref(…, sub { my ($ary_ref)  = @_; … });
        $dbh->selectall_hashref(…,  sub { my ($hash_ref) = @_; … });
        $dbh->selectcol_arrayref(…, sub { my ($ary_ref)  = @_; … });
        $dbh->selectrow_array(…,    sub { my (@row_ary)  = @_; … });
        $dbh->selectrow_arrayref(…, sub { my ($ary_ref)  = @_; … });
        $dbh->selectrow_hashref(…,  sub { my ($hash_ref) = @_; … });
    
        # sync
        $rv = $dbh->do('…');
        $dbh->do('…', {async=>0}, sub { my ($rv, $dbh) = @_; … });

DESCRIPTION

    This module is an AnyEvent user, you need to make sure that you use and
    run a supported event loop.

    This module implements asynchronous MySQL queries using "ASYNCHRONOUS
    QUERIES" in DBD::mysql feature. Unlike AnyEvent::DBI it doesn't spawn
    any processes.

    You shouldn't use {RaiseError=>1} with this module and should check
    returned values in your callback to detect errors. This is because with
    {RaiseError=>1} exception will be thrown instead of calling your
    callback function, which isn't what you want in most cases.

INTERFACE

    The API is trivial: use it just like usual DBI, but instead of
    expecting return value from functions which may block add one extra
    parameter: callback. That callback will be executed with usual returned
    value of used method in params (only exception is extra $dbh/$sth param
    in do() and execute() for convenience).

 SYNCHRONOUS QUERIES

    In most cases to make usual synchronous query it's enough to don't
    provide callback - use standard DBI params and it will work just like
    usual DBI. Only exception is prepare()/execute() pair: you should use
    {async=>0} attribute for prepare() to have synchronous execute().

    For convenience, you can quickly turn asynchronous query to synchronous
    by adding {async=>0} attribute - you don't have to rewrite code to
    remove callback function. In this case your callback will be called
    immediately after executing this synchronous query.

 SUPPORTED DBI METHODS

  connect

        $dbh = AnyEvent::DBI::MySQL->connect(...);

    DBD::mysql support only single asynchronous query per MySQL connection.
    To make it easier to overcome this limitation provided connect()
    constructor work using DBI->connect_cached() under the hood, but it
    reuse only inactive $dbh - i.e. one which you didn't use anymore. So,
    connect() guarantee to not return $dbh which is already in use in your
    code. For example, in FastCGI or Mojolicious app you can safely use
    connect() to get own $dbh per each incoming connection; after you send
    response and close this connection that $dbh should automatically go
    out of scope and become inactive (you can force this by $dbh=undef;);
    after that this $dbh may be returned by connect() when handling next
    incoming request. As result you should automatically get a pool of
    connected $dbh which size should match peak amount of simultaneously
    handled CGI requests. You can flush that $dbh cache as documented by
    DBI at any time.

    NOTE: To implement this caching behavior this module catch DESTROY()
    for $dbh and instead of destroying it (and calling $dbh->disconnect())
    make it available for next connect() call in cache. So, if you need to
    call $dbh->disconnect() - do it manually and don't expect it to happens
    automatically on $dbh DESTROY(), like it work in DBI.

    Also, usual limitations for cached connections apply as documented by
    DBI (read: don't change $dbh configuration).

  do

        $dbh->do(..., sub {
            my ($rv, $dbh) = @_;
            ...
        });

  execute

        $sth->execute(..., sub {
            my ($rv, $sth) = @_;
            ...
        });

  selectall_arrayref

        $dbh->selectall_arrayref(..., sub {
            my ($ary_ref) = @_;
            ...
        });

  selectall_hashref

        $dbh->selectall_hashref(..., sub {
            my ($hash_ref) = @_;
            ...
        });

  selectcol_arrayref

        $dbh->selectcol_arrayref(..., sub {
            my ($ary_ref) = @_;
            ...
        });

  selectrow_array

        $dbh->selectrow_array(..., sub {
            my (@row_ary) = @_;
            ...
        });

  selectrow_arrayref

        $dbh->selectrow_arrayref(..., sub {
            my ($ary_ref) = @_;
            ...
        });

  selectrow_hashref

        $dbh->selectrow_hashref(..., sub {
            my ($hash_ref) = @_;
            ...
        });

LIMITATIONS

    These DBI methods are not supported yet (i.e. they work as usually - in
    blocking mode), mostly because they internally run several queries and
    should be completely rewritten to support non-blocking mode.

    NOTE: You have to provide {async=>0} attribute to prepare() before
    using execute_array() or execute_for_fetch().

        $sth->execute_array
        $sth->execute_for_fetch
        $dbh->table_info
        $dbh->column_info
        $dbh->primary_key_info
        $dbh->foreign_key_info
        $dbh->statistics_info
        $dbh->primary_key
        $dbh->tables

SEE ALSO

    AnyEvent, DBI, AnyEvent::DBI

SUPPORT

 Bugs / Feature Requests

    Please report any bugs or feature requests through the issue tracker at
    https://github.com/powerman/perl-AnyEvent-DBI-MySQL/issues. You will be
    notified automatically of any progress on your issue.

 Source Code

    This is open source software. The code repository is available for
    public review and contribution under the terms of the license. Feel
    free to fork the repository and submit pull requests.

    https://github.com/powerman/perl-AnyEvent-DBI-MySQL

        git clone https://github.com/powerman/perl-AnyEvent-DBI-MySQL.git

 Resources

      * MetaCPAN Search

      https://metacpan.org/search?q=AnyEvent-DBI-MySQL

      * CPAN Ratings

      http://cpanratings.perl.org/dist/AnyEvent-DBI-MySQL

      * AnnoCPAN: Annotated CPAN documentation

      http://annocpan.org/dist/AnyEvent-DBI-MySQL

      * CPAN Testers Matrix

      http://matrix.cpantesters.org/?dist=AnyEvent-DBI-MySQL

      * CPANTS: A CPAN Testing Service (Kwalitee)

      http://cpants.cpanauthors.org/dist/AnyEvent-DBI-MySQL

AUTHOR

    Alex Efros <powerman@cpan.org>

COPYRIGHT AND LICENSE

    This software is Copyright (c) 2013- by Alex Efros <powerman@cpan.org>.

    This is free software, licensed under:

      The MIT (X11) License