/ 
DBIO-0.900004
/ DBIO::Replicated::Balancer

NAME

DBIO::Replicated::Balancer - Base class for replicated read balancing

VERSION

version 0.900004

DESCRIPTION

Base class for the read balancers of DBIO::Replicated::Storage. A balancer answers every read: it picks a replicant from the DBIO::Replicated::Pool (via the subclass's "next_storage"), falls back to the master when no replicant is usable, and sends reads to the master while a transaction is open there. auto_validate_every (seconds) and current_replicant are plain read/write accessors.

METHODS

new

my $balancer = $class->new(
  master              => $master_backend,
  pool                => $pool,
  auto_validate_every => 60,     # optional
);

When a pool is given, picks the first current_replicant right away.

master

Getter/setter for the master backend.

pool

Getter/setter for the DBIO::Replicated::Pool.

next_storage

Returns the next replicant to read from, or nothing if none is usable. The base class dies; every balancer subclass implements this.

next_storage_with_fallback

Re-validates the pool first if auto_validate_every seconds have passed since its last validation. Returns "next_storage" if that yields a replicant, else the master; each switch between replicant and master reads is noted once on the master's trace object.

increment_storage

Sets current_replicant to the result of "next_storage_with_fallback".

select

select_single

Route a read: with a force_pool key in the trailing attributes hashref (removed before the call) to that target -- a backend object, 'master', or the name of a replicant -- its DSN after dbi:Driver: without the password= part (throws for an unknown name); inside a master transaction, or when the attributes carry a lock (for with any defined value, 'update' and 'shared' among them), to the master; otherwise to the next replicant (see "increment_storage").

columns_info_for

Moves to the next replicant and asks it; unlike "select" it neither honours force_pool nor routes to the master during a transaction.

AUTHOR

DBIO & DBIx::Class Authors

COPYRIGHT AND LICENSE

Copyright (C) 2026 DBIO Authors Portions Copyright (C) 2005-2025 DBIx::Class Authors Based on DBIx::Class, heavily modified.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.