Grant Street Group
and 1 contributors

NAME

DBIx::Connector::Retry - DBIx::Connector with block retry support

SYNOPSIS

    my $conn = DBIx::Connector::Retry->new(
        connect_info  => [ 'dbi:Driver:database=foobar', $user, $pass, \%args ],
        retry_debug   => 1,
        max_attempts  => 5,
    );

    # Keep retrying/reconnecting on errors
    my ($count) = $conn->run(ping => sub {
        $_->do('UPDATE foobar SET updated = 1 WHERE active = ?', undef, 'on');
        $_->selectrow_array('SELECT COUNT(*) FROM foobar WHERE updated = 1');
    });

    # Add a simple retry_handler for a manual timeout
    my $start_time = time;
    $conn->retry_handler(sub { time <= $start_time + 60 });

    my ($count) = $conn->txn(fixup => sub {
        $_->selectrow_array('SELECT COUNT(*) FROM barbaz');
    });
    $conn->clear_retry_handler;

    # Plus everything else in DBIx::Connector

DESCRIPTION

DBIx::Connector::Retry is a Moo-based subclass of DBIx::Connector that will retry on failures. Most of the interface was modeled after DBIx::Class::Storage::BlockRunner and adapted for use in DBIx::Connector.

ATTRIBUTES

connect_info

An arrayref that contains all of the connection details normally found in the DBI or DBIx::Connector call. This data can be changed, but won't take effect until the next $dbh re-connection cycle.

Obviously, this is required.

mode

This is just like "mode" in DBIx::Connector except that it can be set from within the constructor.

Unlike DBIx::Connector, the default is ping, not no_ping.

disconnect_on_destroy

This is just like "disconnect_on_destroy" in DBIx::Connector except that it can be set from within the constructor.

Default is on.

max_attempts

The maximum amount of block running attempts before the Connector gives up and dies.

Default is 10.

retry_debug

If enabled, any retries will output a debug warning with the error message and number of retries.

retry_handler

An optional handler that will be checked on each retry. It will be passed the Connector object as its only input. If the handler returns a true value, retries will continue. A false value will cause the retry loop to immediately rethrow the exception. You can also throw your own, if you prefer.

This check is independent of checks for "max_attempts".

The last exception can be inspected as part of the check by looking at "last_exception". This is recommended to make sure the failure is actually what you expect it to be. For example:

    $conn->retry_handler(sub {
        my $c = shift;
        my $err = $c->last_exception;
        $err = $err->error if blessed $err && $err->isa('DBIx::Connector::RollbackError');

        $err =~ /deadlock|timeout/i;  # only retry on deadlocks or timeouts
    });

Default is an always-true coderef.

This attribute has the following handles:

clear_retry_handler

Sets it back to the always-true default.

failed_attempt_count

The number of failed attempts so far. This can be used in the "retry_handler" or checked afterwards. It will be reset on each block run.

Not available for initialization.

exception_stack

The stack of exceptions received so far, as an arrayref. This can be used in the "retry_handler" or checked afterwards. It will be reset on each block run.

Not available for initialization.

This attribute has the following handles:

last_exception

The last exception on the stack.

CONSTRUCTORS

new

    my $conn = DBIx::Connector::Retry->new(
        connect_info => [ 'dbi:Driver:database=foobar', $user, $pass, \%args ],
        max_attempts => 5,
        # ...etc...
    );

    # Old-DBI syntax
    my $conn = DBIx::Connector::Retry->new(
        'dbi:Driver:database=foobar', $user, $pass, \%dbi_args,
        max_attempts => 5,
        # ...etc...
    );

As this is a Moo class, it uses the standard Moo constructor. The "connect_info" should be specified as its own key. The DBI/DBIx::Connector syntax is available, but only as a nicety for compatibility.

MODIFIED METHODS

run / txn

    my @result = $conn->run($mode => $coderef);
    my $result = $conn->run($mode => $coderef);
    $conn->run($mode => $coderef);

    my @result = $conn->txn($mode => $coderef);
    my $result = $conn->txn($mode => $coderef);
    $conn->txn($mode => $coderef);

Both run and txn are modified to run inside a retry loop. If the original Connector action dies, the exception is caught, and if "retry_handler" and "max_attempts" allows it, the action is retried. The database handle may be reset by the Connector action, according to its connection mode.

See "CAVEATS" for important behaviors/limitations.

CAVEATS

$dbh settings

Like DBIx::Connector, it's important that the "connect_info" properties have sane connection settings.

AutoCommit should be turned on. Otherwise, the connection is considered to be already in a transaction, and no retries will be attempted. Instead, use transactions via txn.

RaiseError should also be turned on, since exceptions are captured, and both Retry and Connector use them to determine if any of the $dbh calls failed.

Savepoints and nested transactions

The svp method is NOT modified to work inside of a retry loop, because retries are generally not possible for savepoints, and a disconnected connection will rollback any uncommited statements in most RDBMS. The same goes for any run/txn calls attempted inside of a transaction.

Consider the following:

    # If this dies, sub will retry
    $conn->txn(ping => sub {
        shift->do('UPDATE foobar SET updated = 1 WHERE active = ?', undef, 'on');

        # If this dies, it will not retry
        $conn->svp(sub {
            my $c = shift;
            $c->do('INSERT foobar (name, updated, active) VALUES (?, ?)', undef, 'barbaz', 0, 'off');
        });
    });

If the savepoint actually tried to retry, the UPDATE statement would get rolled back by virtue of database disconnection. However, the savepoint code would continue, possibly even succeeding. You would never know that the UPDATE statement was rolled back.

However, without savepoint retry support, as it is currently designed, the statements will work as expected. If the savepoint code dies, and if $conn is set up for retries, the transaction code is restarted, after a rollback or reconnection. Thus, the UPDATE and INSERT statements are both ran properly if they now succeed.

Obviously, this will not work if transactions are manually started outside of the main Connector interface:

    # Don't do this!  The whole transaction isn't compartmentalized properly!
    $conn->run(ping => sub {
        $_->begin_work;  # don't ever call this!
        $_->do('UPDATE foobar SET updated = 1 WHERE active = ?', undef, 'on');
    });

    # If this dies, the whole app will probably crash
    $conn->svp(sub {
        my $c = shift;
        $c->do('INSERT foobar (name, updated, active) VALUES (?, ?)', undef, 'barbaz', 0, 'off');
    });

    # Don't do this!
    $conn->run(ping => sub {
        $_->commit;  # no, let Connector handle this process!
    });

Fixup mode

Because of the nature of fixup mode, the block may be executed twice as often. Functionally, the code looks like this:

    # Very simplified example
    sub fixup_run {
        my ($self, $code) = @_;

        my (@ret, $run_err);
        do {
            eval {
                @ret = eval { $code->($dbh) };
                my $err = $@;

                if ($err) {
                    die $err if $self->connected;
                    # Not connected. Try again.
                    return $code->($dbh);
                }
            };
            $run_err = $@;

            if ($run_err) {
                # Push exception_stack, set/check attempts, check retry_handler
            }
        } while ($run_err);
        return @ret;
    }

If the first eval dies because of a connection failure, the code is ran twice before the retry loop finds it. This is only considered to be one attempt. If it dies because of some other fault, it's only ran once and continues the retry loop.

If this is behavior is undesirable, this can be worked around by using the "retry_handler" to change the mode after the first attempt:

    $conn->retry_handler(sub {
        my $c = shift;
        $c->mode('ping') if $c->mode eq 'fixup';
        1;
    });

Mode is localized outside of the retry loop, so even $conn->run(fixup => $code) calls work, and the default mode will return to normal after the block run.

SEE ALSO

DBIx::Connector, DBIx::Class

AUTHOR

Grant Street Group <developers@grantstreet.com>

LICENSE AND COPYRIGHT

Copyright 2018 Grant Street Group.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0