/ 
DBIO-0.900004
/ DBIO::Replicated

NAME

DBIO::Replicated - Replicated storage support for DBIO

VERSION

version 0.900004

SYNOPSIS

package MyApp::Schema;
use DBIO 'Schema', -pg;
__PACKAGE__->load_components('Replicated');

my $schema = __PACKAGE__->connect($dsn, $user, $pass, {
  balancer_type => 'DBIO::Replicated::Balancer::First',
});

$schema->storage->connect_replicants(
  [ $replica_dsn_1, $user, $pass ],
  [ $replica_dsn_2, $user, $pass ],
);

See t/test/08_replicated.t for a runnable example.

DESCRIPTION

DBIO::Replicated is the DBIO core component for replicated storage setups. It configures the schema to use DBIO::Replicated::Storage, which then coordinates a master backend plus optional replicant backends.

Writes, transactions, deploy operations, and other master-only work go through the master backend. Read-oriented operations are delegated to the configured balancer, which selects from the active replicants.

For shared test suites, DBIO::Test can wrap a requested backend storage in replicated mode with:

my $schema = DBIO::Test->init_schema(
  replicated   => 1,
  storage_type => 'DBIO::MySQL::Storage',
);

METHODS

connection

Overrides "connection" in DBIO::Schema to force +DBIO::Replicated::Storage as storage_type.

Replication runs on the driver the schema declares (ADR 0067): the master and every replicant are storages of that driver. connection reads the declared driver's storage class before it sets the replicated one and passes it on as backend_storage_class ("new" in DBIO::Replicated::Storage); a repeated connect keeps it. A backend_storage_class in the connect info wins over it. A schema that declares no driver, and gives no backend_storage_class, is refused before any storage is built.

The component is loaded after the driver component, so that the driver is declared when it connects and DBIO::Replicated::Storage is the storage class the schema ends up with:

__PACKAGE__->load_components(qw(PostgreSQL Replicated));

A schema whose connect leaves another storage class behind throws, naming that class and this order.

READING FROM THE MASTER AND THE REPLICANTS

A replicant answers with the data it has replicated so far; after a write on the master it may still show the earlier state for a short time (replication lag). Reads that tolerate this are balanced over the replicants.

Reads that go with a write are answered by the master, so they see what the writers see:

A force_pool in the attributes of a search names the pool for that one read ('master' or the name of a replicant). To run a whole block of reads on the master, wrap it in "execute_reliably" in DBIO::Replicated::Storage:

$schema->storage->execute_reliably(sub {
  my $artist = $schema->resultset('Artist')->find($id);
  ...
});

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.