package DBIx::Class::Storage::DBI::Replicated::Pool;
-use Moose;
-use MooseX::AttributeHelpers;
-use DBIx::Class::Storage::DBI::Replicated::Replicant;
-use List::Util qw(sum);
+use Moo;
+use Role::Tiny ();
+use List::Util ();
+use Scalar::Util qw(reftype);
+use DBI ();
+use Carp::Clan qw/^DBIx::Class/;
+use Try::Tiny;
+use DBIx::Class::Storage::DBI::Replicated::Types
+ qw(PositiveInteger Number DBICStorageDBI ClassName HashRef);
=head1 NAME
-DBIx::Class::Storage::DBI::Replicated::Pool; Manage a pool of replicants
+DBIx::Class::Storage::DBI::Replicated::Pool - Manage a pool of replicants
=head1 SYNOPSIS
This class is used internally by L<DBIx::Class::Storage::DBI::Replicated>. You
shouldn't need to create instances of this class.
-
+
=head1 DESCRIPTION
In a replicated storage type, there is at least one replicant to handle the
-read only traffic. The Pool class manages this replicant, or list of
+read-only traffic. The Pool class manages this replicant, or list of
replicants, and gives some methods for querying information about their status.
=head1 ATTRIBUTES
This class defines the following attributes.
-=head2 replicant_type
+=head2 maximum_lag ($num)
+
+This is a number which defines the maximum allowed lag returned by the
+L<DBIx::Class::Storage::DBI/lag_behind_master> method. The default is 0. In
+general, this should return a larger number when the replicant is lagging
+behind its master, however the implementation of this is database specific, so
+don't count on this number having a fixed meaning. For example, MySQL will
+return a number of seconds that the replicating database is lagging.
+
+=cut
+
+has 'maximum_lag' => (
+ is=>'rw',
+ isa=>Number,
+ lazy=>1,
+ default=>sub {0},
+);
+
+=head2 last_validated
+
+This is an integer representing a time since the last time the replicants were
+validated. It's nothing fancy, just an integer provided via the perl L<time|perlfunc/time>
+built-in.
+
+=cut
+
+has 'last_validated' => (
+ is=>'rw',
+ isa=>PositiveInteger,
+ lazy=>1,
+ default=>sub {0},
+);
+
+=head2 replicant_type ($classname)
Base class used to instantiate replicants that are in the pool. Unless you
need to subclass L<DBIx::Class::Storage::DBI::Replicated::Replicant> you should
=cut
has 'replicant_type' => (
- is=>'ro',
- isa=>'ClassName',
- required=>1,
- default=>'DBIx::Class::Storage::DBI::Replicated::Replicant',
- handles=>{
- 'create_replicant' => 'new',
- },
+ is=>'ro',
+ isa=>ClassName,
+ default=> sub{'DBIx::Class::Storage::DBI'},
+ handles=>{
+ 'create_replicant' => 'new',
+ },
);
-
=head2 replicants
-A hashref of replicant, with the key being the dsn and the value returning the
-actual replicant storage. For example if the $dsn element is something like:
+A hashref of replicants, with the key being the dsn and the value returning the
+actual replicant storage. For example, if the $dsn element is something like:
+
+ "dbi:SQLite:dbname=dbfile"
- "dbi:SQLite:dbname=dbfile"
-
You could access the specific replicant via:
- $schema->storage->replicants->{'dbname=dbfile'}
-
-This attributes also supports the following helper methods
+ $schema->storage->replicants->{'dbname=dbfile'}
-=over 4
+=cut
-=item set_replicant($key=>$storage)
+has 'replicants' => (
+ is => 'rw',
+ isa => HashRef,
+ default => sub { +{} },
+);
-Pushes a replicant onto the HashRef under $key
+has next_unknown_replicant_id => (
+ is => 'rw',
+ isa=>PositiveInteger
+ default => sub { 1 },
+);
-=item get_replicant($key)
+sub inc_unknown_replicant_id {
+ my $self = shift;
+ my $next = $self->next_unknown_replicant_id + 1;
+ $self->next_unknown_replicant_id($next);
+ return $next;
+}
-Retrieves the named replicant
+=head2 master
-=item has_replicants
+Reference to the master Storage.
-Returns true if the Pool defines replicants.
+=cut
-=item num_replicants
+has master => (
+ is => 'rw',
+ isa =>DBICStorageDBI,
+ weak_ref => 1,
+);
-The number of replicants in the pool
+=head1 METHODS
-=item delete_replicant ($key)
+This class defines the following methods.
-removes the replicant under $key from the pool
+=head2 connect_replicants ($schema, Array[$connect_info])
-=back
+Given an array of $dsn or connect_info structures suitable for connected to a
+database, create an L<DBIx::Class::Storage::DBI::Replicated::Replicant> object
+and store it in the L</replicants> attribute.
=cut
-has 'replicants' => (
- is=>'rw',
- metaclass => 'Collection::Hash',
- isa=>'HashRef[DBIx::Class::Storage::DBI::Replicated::Replicant]',
- default=>sub {{}},
- provides => {
- 'set' => 'set_replicant',
- 'get' => 'get_replicant',
- 'empty' => 'has_replicants',
- 'count' => 'num_replicants',
- 'delete' => 'delete_replicant',
- },
-);
+sub connect_replicants {
+ my $self = shift @_;
+ my $schema = shift @_;
+
+ my @newly_created = ();
+ foreach my $connect_info (@_) {
+ $connect_info = [ $connect_info ]
+ if reftype $connect_info ne 'ARRAY';
+
+ my $connect_coderef =
+ (reftype($connect_info->[0])||'') eq 'CODE' ? $connect_info->[0]
+ : (reftype($connect_info->[0])||'') eq 'HASH' &&
+ $connect_info->[0]->{dbh_maker};
+
+ my $dsn;
+ my $replicant = do {
+ ## yes this is evil, but it only usually happens once (for coderefs)
+ ## this will fail if the coderef does not actually DBI::connect
+ no warnings 'redefine';
+ my $connect = \&DBI::connect;
+ local *DBI::connect = sub {
+ $dsn = $_[1];
+ goto $connect;
+ };
+ $self->connect_replicant($schema, $connect_info);
+ };
+
+ my $key;
+
+ if (!$dsn) {
+ if (!$connect_coderef) {
+ $dsn = $connect_info->[0];
+ $dsn = $dsn->{dsn} if (reftype($dsn)||'') eq 'HASH';
+ }
+ else {
+ # all attempts to get the DSN failed
+ $key = "UNKNOWN_" . $self->next_unknown_replicant_id;
+ $self->inc_unknown_replicant_id;
+ }
+ }
+ if ($dsn) {
+ $replicant->dsn($dsn);
+ ($key) = ($dsn =~ m/^dbi\:.+\:(.+)$/i);
+ }
+ if($key) {
+ $replicant->id($key);
+ } else {
+ $replicant->debugobj->print("Could not create an ID for the replicant!");
+ }
-=head1 METHODS
+ ## Add the new replicant to the list
+ $self->replicants({
+ $key => $replicant,
+ %{$self->replicants},
+ });
-This class defines the following methods.
+ push @newly_created, $replicant;
+ }
-=head2 connect_replicants ($schema, Array[$connect_info])
+ return @newly_created;
+}
+
+=head2 connect_replicant ($schema, $connect_info)
-Given an array of $dsn suitable for connected to a database, create an
-L<DBIx::Class::Storage::DBI::Replicated::Replicant> object and store it in the
-L</replicants> attribute.
+Given a schema object and a hashref of $connect_info, connect the replicant
+and return it.
=cut
-sub connect_replicants {
- my $self = shift @_;
- my $schema = shift @_;
-
- my @newly_created = ();
- foreach my $connect_info (@_) {
- my $replicant = $self->create_replicant($schema);
- $replicant->connect_info($connect_info);
- $replicant->ensure_connected;
- my ($key) = ($connect_info->[0]=~m/^dbi\:.+\:(.+)$/);
- $self->set_replicant( $key => $replicant);
- push @newly_created, $replicant;
- }
-
- return @newly_created;
+sub connect_replicant {
+ my ($self, $schema, $connect_info) = @_;
+ my $replicant = $self->create_replicant($schema);
+ $replicant->connect_info($connect_info);
+
+## It is undesirable for catalyst to connect at ->connect_replicants time, as
+## connections should only happen on the first request that uses the database.
+## So we try to set the driver without connecting, however this doesn't always
+## work, as a driver may need to connect to determine the DB version, and this
+## may fail.
+##
+## Why this is necessary at all, is that we need to have the final storage
+## class to apply the Replicant role.
+
+ $self->_safely($replicant, '->_determine_driver', sub {
+ $replicant->_determine_driver
+ });
+
+ Role::Tiny->apply_roles_to_object($replicant, 'DBIx::Class::Storage::DBI::Replicated::Replicant');
+
+ # link back to master
+ $replicant->master($self->master);
+
+ return $replicant;
+}
+
+=head2 _safely_ensure_connected ($replicant)
+
+The standard ensure_connected method with throw an exception should it fail to
+connect. For the master database this is desirable, but since replicants are
+allowed to fail, this behavior is not desirable. This method wraps the call
+to ensure_connected in an eval in order to catch any generated errors. That
+way a slave can go completely offline (e.g. the box itself can die) without
+bringing down your entire pool of databases.
+
+=cut
+
+sub _safely_ensure_connected {
+ my ($self, $replicant, @args) = @_;
+
+ return $self->_safely($replicant, '->ensure_connected', sub {
+ $replicant->ensure_connected(@args)
+ });
}
+=head2 _safely ($replicant, $name, $code)
+
+Execute C<$code> for operation C<$name> catching any exceptions and printing an
+error message to the C<<$replicant->debugobj>>.
+
+Returns 1 on success and undef on failure.
+
+=cut
+
+sub _safely {
+ my ($self, $replicant, $name, $code) = @_;
+
+ return try {
+ $code->();
+ 1;
+ } catch {
+ $replicant->debugobj->print(sprintf(
+ "Exception trying to $name for replicant %s, error is %s",
+ $replicant->_dbi_connect_info->[0], $_)
+ );
+ undef;
+ };
+}
=head2 connected_replicants
Returns true if there are connected replicants. Actually is overloaded to
return the number of replicants. So you can do stuff like:
- if( my $num_connected = $storage->has_connected_replicants ) {
- print "I have $num_connected connected replicants";
- } else {
- print "Sorry, no replicants.";
- }
+ if( my $num_connected = $storage->has_connected_replicants ) {
+ print "I have $num_connected connected replicants";
+ } else {
+ print "Sorry, no replicants.";
+ }
This method will actually test that each replicant in the L</replicants> hashref
is actually connected, try not to hit this 10 times a second.
=cut
sub connected_replicants {
- my $self = shift @_;
- return sum( map {
- $_->connected ? 1:0
- } $self->all_replicants );
+ my $self = shift @_;
+ return List::Util::sum( map {
+ $_->connected ? 1:0
+ } $self->all_replicants );
}
=head2 active_replicants
=cut
sub active_replicants {
- my $self = shift @_;
- return ( grep {$_} map {
- $_->active ? $_:0
- } $self->all_replicants );
+ my $self = shift @_;
+ return ( grep {$_} map {
+ $_->active ? $_:0
+ } $self->all_replicants );
}
=head2 all_replicants
=cut
sub all_replicants {
- my $self = shift @_;
- return values %{$self->replicants};
+ my $self = shift @_;
+ return values %{$self->replicants};
}
+=head2 validate_replicants
+
+This does a check to see if 1) each replicate is connected (or reconnectable),
+2) that is ->is_replicating, and 3) that it is not exceeding the lag amount
+defined by L</maximum_lag>. Replicants that fail any of these tests are set to
+inactive, and thus removed from the replication pool.
+
+This tests L<all_replicants>, since a replicant that has been previous marked
+as inactive can be reactivated should it start to pass the validation tests again.
+
+See L<DBIx::Class::Storage::DBI> for more about checking if a replicating
+connection is not following a master or is lagging.
+
+Calling this method will generate queries on the replicant databases so it is
+not recommended that you run them very often.
+
+This method requires that your underlying storage engine supports some sort of
+native replication mechanism. Currently only MySQL native replication is
+supported. Your patches to make other replication types work are welcomed.
+
+=cut
+
+sub validate_replicants {
+ my $self = shift @_;
+ foreach my $replicant($self->all_replicants) {
+ if($self->_safely_ensure_connected($replicant)) {
+ my $is_replicating = $replicant->is_replicating;
+ unless(defined $is_replicating) {
+ $replicant->debugobj->print("Storage Driver ".ref($self)." Does not support the 'is_replicating' method. Assuming you are manually managing.\n");
+ next;
+ } else {
+ if($is_replicating) {
+ my $lag_behind_master = $replicant->lag_behind_master;
+ unless(defined $lag_behind_master) {
+ $replicant->debugobj->print("Storage Driver ".ref($self)." Does not support the 'lag_behind_master' method. Assuming you are manually managing.\n");
+ next;
+ } else {
+ if($lag_behind_master <= $self->maximum_lag) {
+ $replicant->active(1);
+ } else {
+ $replicant->active(0);
+ }
+ }
+ } else {
+ $replicant->active(0);
+ }
+ }
+ } else {
+ $replicant->active(0);
+ }
+ }
+ ## Mark that we completed this validation.
+ $self->last_validated(time);
+}
=head1 AUTHOR
-John Napiorkowski <john.napiorkowski@takkle.com>
+John Napiorkowski <jjnapiork@cpan.org>
=head1 LICENSE
=cut
-
-1;
\ No newline at end of file
+1;