1DBIx::Class::Storage::DUBsIe:r:RCeopnltirciabtuetde(d3D)PBeIrxl::DColcausmse:n:tSattoiroange::DBI::Replicated(3)
2
6 DBIx::Class::Storage::DBI::Replicated - BETA Replicated database
7 support
8
10 The Following example shows how to change an existing $schema to a
11 replicated storage type, add some replicated (read-only) databases, and
12 perform reporting tasks.
13 You should set the 'storage_type attribute to a replicated type. You
15 should also define your arguments, such as which balancer you want and
16 any arguments that the Pool object should get.
17 my $schema = Schema::Class->clone;
19 $schema->storage_type(['::DBI::Replicated', { balancer_type => '::Random' }]);
20 $schema->connection(...);
21 Next, you need to add in the Replicants. Basically this is an array of
23 arrayrefs, where each arrayref is database connect information. Think
24 of these arguments as what you'd pass to the 'normal' $schema->connect
25 method.
26 $schema->storage->connect_replicants(
28 [$dsn1, $user, $pass, \%opts],
29 [$dsn2, $user, $pass, \%opts],
30 [$dsn3, $user, $pass, \%opts],
31 );
32 Now, just use the $schema as you normally would. Automatically all
34 reads will be delegated to the replicants, while writes to the master.
35 $schema->resultset('Source')->search({name=>'etc'});
37 You can force a given query to use a particular storage using the
39 search attribute 'force_pool'. For example:
40 my $rs = $schema->resultset('Source')->search(undef, {force_pool=>'master'});
42 Now $rs will force everything (both reads and writes) to use whatever
44 was setup as the master storage. 'master' is hardcoded to always point
45 to the Master, but you can also use any Replicant name. Please see:
46 DBIx::Class::Storage::DBI::Replicated::Pool and the replicants
47 attribute for more.
48 Also see transactions and "execute_reliably" for alternative ways to
50 force read traffic to the master. In general, you should wrap your
51 statements in a transaction when you are reading and writing to the
52 same tables at the same time, since your replicants will often lag a
53 bit behind the master.
54 If you have a multi-statement read only transaction you can force it to
56 select a random server in the pool by:
57 my $rs = $schema->resultset('Source')->search( undef,
59 { force_pool => $db->storage->read_handler->next_storage }
60 );
61
63 Warning: This class is marked BETA. This has been running a production
64 website using MySQL native replication as its backend and we have some
65 decent test coverage but the code hasn't yet been stressed by a variety
66 of databases. Individual DBs may have quirks we are not aware of.
67 Please use this in first development and pass along your
68 experiences/bug fixes.
69 This class implements replicated data store for DBI. Currently you can
71 define one master and numerous slave database connections. All write-
72 type queries (INSERT, UPDATE, DELETE and even LAST_INSERT_ID) are
73 routed to master database, all read-type queries (SELECTs) go to the
74 slave database.
75 Basically, any method request that DBIx::Class::Storage::DBI would
77 normally handle gets delegated to one of the two attributes:
78 "read_handler" or to "write_handler". Additionally, some methods need
79 to be distributed to all existing storages. This way our storage class
80 is a drop in replacement for DBIx::Class::Storage::DBI.
81 Read traffic is spread across the replicants (slaves) occurring to a
83 user selected algorithm. The default algorithm is random weighted.
84
86 The consistency between master and replicants is database specific.
87 The Pool gives you a method to validate its replicants, removing and
88 replacing them when they fail/pass predefined criteria. Please make
89 careful use of the ways to force a query to run against Master when
90 needed.
91
93 Replicated Storage has additional requirements not currently part of
94 DBIx::Class. See DBIx::Class::Optional::Dependencies for more details.
95
97 This class defines the following attributes.
98 schema
100 The underlying DBIx::Class::Schema object this storage is attaching
101 pool_type
103 Contains the classname which will instantiate the "pool" object.
104 Defaults to: DBIx::Class::Storage::DBI::Replicated::Pool.
105 pool_args
107 Contains a hashref of initialized information to pass to the Balancer
108 object. See DBIx::Class::Storage::DBI::Replicated::Pool for available
109 arguments.
110 balancer_type
112 The replication pool requires a balance class to provider the methods
113 for choose how to spread the query load across each replicant in the
114 pool.
115 balancer_args
117 Contains a hashref of initialized information to pass to the Balancer
118 object. See DBIx::Class::Storage::DBI::Replicated::Balancer for
119 available arguments.
120 pool
122 Is a DBIx::Class::Storage::DBI::Replicated::Pool or derived class.
123 This is a container class for one or more replicated databases.
124 balancer
126 Is a DBIx::Class::Storage::DBI::Replicated::Balancer or derived class.
127 This is a class that takes a pool
128 (DBIx::Class::Storage::DBI::Replicated::Pool)
129 master
131 The master defines the canonical state for a pool of connected
132 databases. All the replicants are expected to match this databases
133 state. Thus, in a classic Master / Slaves distributed system, all the
134 slaves are expected to replicate the Master's state as quick as
135 possible. This is the only database in the pool of databases that is
136 allowed to handle write traffic.
137
139 The following methods are delegated all the methods required for the
140 DBIx::Class::Storage::DBI interface.
141 read_handler
143 Defines an object that implements the read side of
144 DBIx::Class::Storage::DBI.
145 write_handler
147 Defines an object that implements the write side of
148 DBIx::Class::Storage::DBI, as well as methods that don't write or read
149 that can be called on only one storage, methods that return a $dbh, and
150 any methods that don't make sense to run on a replicant.
151 around: connect_info
153 Preserves master's "connect_info" options (for merging with
154 replicants.) Also sets any Replicated-related options from
155 connect_info, such as "pool_type", "pool_args", "balancer_type" and
156 "balancer_args".
157
159 This class defines the following methods.
160 BUILDARGS
162 DBIx::Class::Schema when instantiating its storage passed itself as the
163 first argument. So we need to massage the arguments a bit so that all
164 the bits get put into the correct places.
165 _build_master
167 Lazy builder for the "master" attribute.
168 _build_pool
170 Lazy builder for the "pool" attribute.
171 _build_balancer
173 Lazy builder for the "balancer" attribute. This takes a Pool object so
174 that the balancer knows which pool it's balancing.
175 _build_write_handler
177 Lazy builder for the "write_handler" attribute. The default is to set
178 this to the "master".
179 _build_read_handler
181 Lazy builder for the "read_handler" attribute. The default is to set
182 this to the "balancer".
183 around: connect_replicants
185 All calls to connect_replicants needs to have an existing $schema
186 tacked onto top of the args, since DBIx::Class::Storage::DBI needs it,
187 and any connect_info options merged with the master, with replicant
188 opts having higher priority.
189 all_storages
191 Returns an array of all the connected storage backends. The first
192 element in the returned array is the master, and the rest are each of
193 the replicants.
194 execute_reliably ($coderef, ?@args)
196 Given a coderef, saves the current state of the "read_handler", forces
197 it to use reliable storage (e.g. sets it to the master), executes a
198 coderef and then restores the original state.
199 Example:
201 my $reliably = sub {
203 my $name = shift @_;
204 $schema->resultset('User')->create({name=>$name});
205 my $user_rs = $schema->resultset('User')->find({name=>$name});
206 return $user_rs;
207 };
208 my $user_rs = $schema->storage->execute_reliably($reliably, 'John');
210 Use this when you must be certain of your database state, such as when
212 you just inserted something and need to get a resultset including it,
213 etc.
214 set_reliable_storage
216 Sets the current $schema to be 'reliable', that is all queries, both
217 read and write are sent to the master
218 set_balanced_storage
220 Sets the current $schema to be use the </balancer> for all reads, while
221 all writes are sent to the master only
222 connected
224 Check that the master and at least one of the replicants is connected.
225 ensure_connected
227 Make sure all the storages are connected.
228 limit_dialect
230 Set the limit_dialect for all existing storages
231 quote_char
233 Set the quote_char for all existing storages
234 name_sep
236 Set the name_sep for all existing storages
237 set_schema
239 Set the schema object for all existing storages
240 debug
242 set a debug flag across all storages
243 debugobj
245 set a debug object
246 debugfh
248 set a debugfh object
249 debugcb
251 set a debug callback
252 disconnect
254 disconnect everything
255 cursor_class
257 set cursor class on all storages, or return master's
258 cursor
260 set cursor class on all storages, or return master's, alias for
261 "cursor_class" above.
262 unsafe
264 sets the "unsafe" in DBIx::Class::Storage::DBI option on all storages
265 or returns master's current setting
266 disable_sth_caching
268 sets the "disable_sth_caching" in DBIx::Class::Storage::DBI option on
269 all storages or returns master's current setting
270 lag_behind_master
272 returns the highest Replicant "lag_behind_master" in
273 DBIx::Class::Storage::DBI setting
274 is_replicating
276 returns true if all replicants return true for "is_replicating" in
277 DBIx::Class::Storage::DBI
278 connect_call_datetime_setup
280 calls "connect_call_datetime_setup" in DBIx::Class::Storage::DBI for
281 all storages
282 connect_call_rebase_sqlmaker
284 calls "connect_call_rebase_sqlmaker" in DBIx::Class::Storage::DBI for
285 all storages
286
288 Due to the fact that replicants can lag behind a master, you must take
289 care to make sure you use one of the methods to force read queries to a
290 master should you need realtime data integrity. For example, if you
291 insert a row, and then immediately re-read it from the database (say,
292 by doing $result->discard_changes) or you insert a row and then
293 immediately build a query that expects that row to be an item, you
294 should force the master to handle reads. Otherwise, due to the lag,
295 there is no certainty your data will be in the expected state.
296 For data integrity, all transactions automatically use the master
298 storage for all read and write queries. Using a transaction is the
299 preferred and recommended method to force the master to handle all read
300 queries.
301 Otherwise, you can force a single query to use the master with the
303 'force_pool' attribute:
304 my $result = $resultset->search(undef, {force_pool=>'master'})->find($pk);
306 This attribute will safely be ignored by non replicated storages, so
308 you can use the same code for both types of systems.
309 Lastly, you can use the "execute_reliably" method, which works very
311 much like a transaction.
312 For debugging, you can turn replication on/off with the methods
314 "set_reliable_storage" and "set_balanced_storage", however this
315 operates at a global level and is not suitable if you have a shared
316 Schema object being used by multiple processes, such as on a web
317 application server. You can get around this limitation by using the
318 Schema clone method.
319 my $new_schema = $schema->clone;
321 $new_schema->set_reliable_storage;
322 ## $new_schema will use only the Master storage for all reads/writes while
324 ## the $schema object will use replicated storage.
325
327 Check the list of additional DBIC resources.
328
330 This module is free software copyright by the DBIx::Class (DBIC)
331 authors. You can redistribute it and/or modify it under the same terms
332 as the DBIx::Class library.
333perl v5.36.0 2023-D0B1I-x2:0:Class::Storage::DBI::Replicated(3)