1DBIx::Class::Storage::DUBsIeD:rB:IRCxeo:pn:ltCirlciaabstuset:de::dS:tIPonertrarlgoedD:uo:ccDtuBimIoe:nn:(tR3ae)tpiloincated::Introduction(3)
2
3
4

NAME

6       DBIx::Class::Storage::DBI::Replicated::Introduction - Minimum Need to
7       Know
8

SYNOPSIS

10       This is an introductory document for
11       DBIx::Class::Storage::DBI::Replicated.
12
13       This document is not an overview of what replication is or why you
14       should be using it. It is not a document explaining how to setup MySQL
15       native replication either. Copious external resources are available for
16       both. This document presumes you have the basics down.
17

DESCRIPTION

19       DBIx::Class supports a framework for using database replication. This
20       system is integrated completely, which means once it's setup you should
21       be able to automatically just start using a replication cluster without
22       additional work or changes to your code. Some caveats apply, primarily
23       related to the proper use of transactions (you are wrapping all your
24       database modifying statements inside a transaction, right ;) ) however
25       in our experience properly written DBIC will work transparently with
26       Replicated storage.
27
28       Currently we have support for MySQL native replication, which is
29       relatively easy to install and configure.  We also currently support
30       single master to one or more replicants (also called 'slaves' in some
31       documentation).  However the framework is not specifically tied to the
32       MySQL framework and supporting other replication systems or
33       topographies should be possible.  Please bring your patches and ideas
34       to the #dbix-class IRC channel or the mailing list.
35
36       For an easy way to start playing with MySQL native replication, see:
37       MySQL::Sandbox.
38
39       If you are using this with a Catalyst based application, you may also
40       want to see more recent updates to Catalyst::Model::DBIC::Schema, which
41       has support for replication configuration options as well.
42

REPLICATED STORAGE

44       By default, when you start DBIx::Class, your Schema
45       (DBIx::Class::Schema) is assigned a storage_type, which when fully
46       connected will reflect your underlying storage engine as defined by
47       your chosen database driver.  For example, if you connect to a MySQL
48       database, your storage_type will be DBIx::Class::Storage::DBI::mysql
49       Your storage type class will contain database specific code to help
50       smooth over the differences between databases and let DBIx::Class do
51       its thing.
52
53       If you want to use replication, you will override this setting so that
54       the replicated storage engine will 'wrap' your underlying storages and
55       present a unified interface to the end programmer.  This wrapper
56       storage class will delegate method calls to either a master database or
57       one or more replicated databases based on if they are read only (by
58       default sent to the replicants) or write (reserved for the master).
59       Additionally, the Replicated storage will monitor the health of your
60       replicants and automatically drop them should one exceed configurable
61       parameters.  Later, it can automatically restore a replicant when its
62       health is restored.
63
64       This gives you a very robust system, since you can add or drop
65       replicants and DBIC will automatically adjust itself accordingly.
66
67       Additionally, if you need high data integrity, such as when you are
68       executing a transaction, replicated storage will automatically delegate
69       all database traffic to the master storage.  There are several ways to
70       enable this high integrity mode, but wrapping your statements inside a
71       transaction is the easy and canonical option.
72

PARTS OF REPLICATED STORAGE

74       A replicated storage contains several parts.  First, there is the
75       replicated storage itself (DBIx::Class::Storage::DBI::Replicated).  A
76       replicated storage takes a pool of replicants
77       (DBIx::Class::Storage::DBI::Replicated::Pool) and a software balancer
78       (DBIx::Class::Storage::DBI::Replicated::Balancer).  The balancer does
79       the job of splitting up all the read traffic amongst the replicants in
80       the Pool. Currently there are two types of balancers, a Random one
81       which chooses a Replicant in the Pool using a naive randomizer
82       algorithm, and a First replicant, which just uses the first one in the
83       Pool (and obviously is only of value when you have a single replicant).
84

REPLICATED STORAGE CONFIGURATION

86       All the parts of replication can be altered dynamically at runtime,
87       which makes it possibly to create a system that automatically scales
88       under load by creating more replicants as needed, perhaps using a cloud
89       system such as Amazon EC2.  However, for common use you can setup your
90       replicated storage to be enabled at the time you connect the databases.
91       The following is a breakdown of how you may wish to do this.  Again, if
92       you are using Catalyst, I strongly recommend you use (or upgrade to)
93       the latest Catalyst::Model::DBIC::Schema, which makes this job even
94       easier.
95
96       First, you need to get a $schema object and set the storage_type:
97
98         my $schema = MyApp::Schema->clone;
99         $schema->storage_type([
100           '::DBI::Replicated' => {
101             balancer_type => '::Random',
102             balancer_args => {
103               auto_validate_every => 5,
104               master_read_weight => 1
105             },
106             pool_args => {
107               maximum_lag =>2,
108             },
109           }
110         ]);
111
112       Then, you need to connect your DBIx::Class::Schema.
113
114         $schema->connection($dsn, $user, $pass);
115
116       Let's break down the settings.  The method "storage_type" in
117       DBIx::Class::Schema takes one mandatory parameter, a scalar value, and
118       an option second value which is a Hash Reference of configuration
119       options for that storage.  In this case, we are setting the Replicated
120       storage type using '::DBI::Replicated' as the first value.  You will
121       only use a different value if you are subclassing the replicated
122       storage, so for now just copy that first parameter.
123
124       The second parameter contains a hash reference of stuff that gets
125       passed to the replicated storage.  "balancer_type" in
126       DBIx::Class::Storage::DBI::Replicated is the type of software load
127       balancer you will use to split up traffic among all your replicants.
128       Right now we have two options, "::Random" and "::First". You can review
129       documentation for both at:
130
131       DBIx::Class::Storage::DBI::Replicated::Balancer::First,
132       DBIx::Class::Storage::DBI::Replicated::Balancer::Random.
133
134       In this case we will have three replicants, so the ::Random option is
135       the only one that makes sense.
136
137       'balancer_args' get passed to the balancer when it's instantiated.  All
138       balancers have the 'auto_validate_every' option.  This is the number of
139       seconds we allow to pass between validation checks on a load balanced
140       replicant. So the higher the number, the more possibility that your
141       reads to the replicant may be inconsistent with what's on the master.
142       Setting this number too low will result in increased database loads, so
143       choose a number with care.  Our experience is that setting the number
144       around 5 seconds results in a good performance / integrity balance.
145
146       'master_read_weight' is an option associated with the ::Random
147       balancer. It allows you to let the master be read from.  I usually
148       leave this off (default is off).
149
150       The 'pool_args' are configuration options associated with the replicant
151       pool.  This object (DBIx::Class::Storage::DBI::Replicated::Pool)
152       manages all the declared replicants.  'maximum_lag' is the number of
153       seconds a replicant is allowed to lag behind the master before being
154       temporarily removed from the pool.  Keep in mind that the Balancer
155       option 'auto_validate_every' determines how often a replicant is tested
156       against this condition, so the true possible lag can be higher than the
157       number you set.  The default is zero.
158
159       No matter how low you set the maximum_lag or the auto_validate_every
160       settings, there is always the chance that your replicants will lag a
161       bit behind the master for the supported replication system built into
162       MySQL.  You can ensure reliable reads by using a transaction, which
163       will force both read and write activity to the master, however this
164       will increase the load on your master database.
165
166       After you've configured the replicated storage, you need to add the
167       connection information for the replicants:
168
169         $schema->storage->connect_replicants(
170           [$dsn1, $user, $pass, \%opts],
171           [$dsn2, $user, $pass, \%opts],
172           [$dsn3, $user, $pass, \%opts],
173         );
174
175       These replicants should be configured as slaves to the master using the
176       instructions for MySQL native replication, or if you are just learning,
177       you will find MySQL::Sandbox an easy way to set up a replication
178       cluster.
179
180       And now your $schema object is properly configured!  Enjoy!
181

FURTHER QUESTIONS?

183       Check the list of additional DBIC resources.
184
186       This module is free software copyright by the DBIx::Class (DBIC)
187       authors. You can redistribute it and/or modify it under the same terms
188       as the DBIx::Class library.
189
190
191
192perl v5.30.1            DBIx::Clas2s0:2:0S-t0o1r-a2g9e::DBI::Replicated::Introduction(3)
Impressum