.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "DBIx::Class::Storage::DBI::Replicated::Balancer 3pm"
.TH DBIx::Class::Storage::DBI::Replicated::Balancer 3pm "2018-04-19" "perl v5.26.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DBIx::Class::Storage::DBI::Replicated::Balancer \- A Software Load Balancer
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
This role is used internally by DBIx::Class::Storage::DBI::Replicated.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Given a pool (DBIx::Class::Storage::DBI::Replicated::Pool) of replicated
database's (DBIx::Class::Storage::DBI::Replicated::Replicant), defines a
method by which query load can be spread out across each replicant in the pool.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
This class defines the following attributes.
.SS "auto_validate_every ($seconds)"
.IX Subsection "auto_validate_every ($seconds)"
If auto_validate has some sort of value, run
\&\*(L"validate_replicants\*(R" in DBIx::Class::Storage::DBI::Replicated::Pool
every \f(CW$seconds\fR.  Be careful with this, because if you set it to 0 you
will end up validating every query.
.SS "master"
.IX Subsection "master"
The DBIx::Class::Storage::DBI object that is the master database all the
replicants are trying to follow.  The balancer needs to know it since it's the
ultimate fallback.
.SS "pool"
.IX Subsection "pool"
The DBIx::Class::Storage::DBI::Replicated::Pool object that we are trying to
balance.
.SS "current_replicant"
.IX Subsection "current_replicant"
Replicant storages (slaves) handle all read only traffic.  The assumption is
that your database will become readbound well before it becomes write bound
and that being able to spread your read only traffic around to multiple
databases is going to help you to scale traffic.
.PP
This attribute returns the next slave to handle a read request.  Your \*(L"pool\*(R"
attribute has methods to help you shuffle through all the available replicants
via its balancer object.
.SH "METHODS"
.IX Header "METHODS"
This class defines the following methods.
.SS "_build_current_replicant"
.IX Subsection "_build_current_replicant"
Lazy builder for the \*(L"current_replicant\*(R" attribute.
.SS "next_storage"
.IX Subsection "next_storage"
This method should be defined in the class which consumes this role.
.PP
Given a pool object, return the next replicant that will serve queries.  The
default behavior is to grab the first replicant it finds but you can write
your own subclasses of DBIx::Class::Storage::DBI::Replicated::Balancer to
support other balance systems.
.PP
This returns from the pool of active replicants.  If there are no active
replicants, then you should have it return the master as an ultimate fallback.
.SS "around: next_storage"
.IX Subsection "around: next_storage"
Advice on next storage to add the autovalidation.  We have this broken out so
that it's easier to break out the auto validation into a role.
.PP
This also returns the master in the case that none of the replicants are active
or just forgot to create them :)
.SS "increment_storage"
.IX Subsection "increment_storage"
Rolls the Storage to whatever is next in the queue, as defined by the Balancer.
.SS "around: select"
.IX Subsection "around: select"
Advice on the select attribute.  Each time we use a replicant
we need to change it via the storage pool algorithm.  That way we are spreading
the load evenly (hopefully) across existing capacity.
.SS "around: select_single"
.IX Subsection "around: select_single"
Advice on the select_single attribute.  Each time we use a replicant
we need to change it via the storage pool algorithm.  That way we are spreading
the load evenly (hopefully) across existing capacity.
.SS "before: columns_info_for"
.IX Subsection "before: columns_info_for"
Advice on the current_replicant_storage attribute.  Each time we use a replicant
we need to change it via the storage pool algorithm.  That way we are spreading
the load evenly (hopefully) across existing capacity.
.SS "_get_forced_pool ($name)"
.IX Subsection "_get_forced_pool ($name)"
Given an identifier, find the most correct storage object to handle the query.
.SH "FURTHER QUESTIONS?"
.IX Header "FURTHER QUESTIONS?"
Check the list of additional \s-1DBIC\s0 resources.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This module is free software copyright
by the DBIx::Class (\s-1DBIC\s0) authors. You can
redistribute it and/or modify it under the same terms as the
DBIx::Class library.