DBIx/Class/Storage/DBI/Replicated.pm

filter: Statementstmt 100% 4 / 4 Branchbran 50.0% 1 / 2 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 2 / 2 Podpod n/a totaltotal 87.5% 7 / 8 CC 2 SCAR 5.2
CC
2
Cov
83%
BEGIN
2.0
BEGIN
1.0
CRAP 1.7
« DBIx/Class/Admin.pm ↑ Summary DBIx/Class/SQLMaker/LimitDialects.pm »
1 package DBIx::Class::Storage::DBI::Replicated;
2  
3 3 ▶BEGIN {
Subroutine BEGIN: called CC=2 SCAR=7.0
4 3 ▶ use DBIx::Class;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 3 ▶ die('The following modules are required for Replication ' . DBIx::Class::Optional::Dependencies->req_missing_for ('replicated') . "\n" )
Branch: 1 branch
BranchTrueFalseTotal
unless "DBIx::Class::Optional::Dependencies"->req_ok_for("replicated") 3 0 3
6 unless DBIx::Class::Optional::Dependencies->req_ok_for ('replicated');
7 }
8  
9 use Moose;
10 use DBIx::Class::Storage::DBI;
11 use DBIx::Class::Storage::DBI::Replicated::Pool;
12 use DBIx::Class::Storage::DBI::Replicated::Balancer;
13 use DBIx::Class::Storage::DBI::Replicated::Types qw/BalancerClassNamePart DBICSchema DBICStorageDBI/;
14 use MooseX::Types::Moose qw/ClassName HashRef Object/;
15 use Scalar::Util 'reftype';
16 use Hash::Merge;
17 use List::Util ();
18 use Context::Preserve 'preserve_context';
19 use Try::Tiny;
20  
21 use namespace::clean -except => 'meta';
22  
23 =head1 NAME
24  
25 DBIx::Class::Storage::DBI::Replicated - BETA Replicated database support
26  
27 =head1 SYNOPSIS
28  
29 The Following example shows how to change an existing $schema to a replicated
30 storage type, add some replicated (read-only) databases, and perform reporting
31 tasks.
32  
33 You should set the 'storage_type attribute to a replicated type. You should
34 also define your arguments, such as which balancer you want and any arguments
35 that the Pool object should get.
36  
37 my $schema = Schema::Class->clone;
38 $schema->storage_type(['::DBI::Replicated', { balancer_type => '::Random' }]);
39 $schema->connection(...);
40  
41 Next, you need to add in the Replicants. Basically this is an array of
42 arrayrefs, where each arrayref is database connect information. Think of these
43 arguments as what you'd pass to the 'normal' $schema->connect method.
44  
45 $schema->storage->connect_replicants(
46 [$dsn1, $user, $pass, \%opts],
47 [$dsn2, $user, $pass, \%opts],
48 [$dsn3, $user, $pass, \%opts],
49 );
50  
51 Now, just use the $schema as you normally would. Automatically all reads will
52 be delegated to the replicants, while writes to the master.
53  
54 $schema->resultset('Source')->search({name=>'etc'});
55  
56 You can force a given query to use a particular storage using the search
57 attribute 'force_pool'. For example:
58  
59 my $rs = $schema->resultset('Source')->search(undef, {force_pool=>'master'});
60  
61 Now $rs will force everything (both reads and writes) to use whatever was setup
62 as the master storage. 'master' is hardcoded to always point to the Master,
63 but you can also use any Replicant name. Please see:
64 L<DBIx::Class::Storage::DBI::Replicated::Pool> and the replicants attribute for more.
65  
66 Also see transactions and L</execute_reliably> for alternative ways to
67 force read traffic to the master. In general, you should wrap your statements
68 in a transaction when you are reading and writing to the same tables at the
69 same time, since your replicants will often lag a bit behind the master.
70  
71 If you have a multi-statement read only transaction you can force it to select
72 a random server in the pool by:
73  
74 my $rs = $schema->resultset('Source')->search( undef,
75 { force_pool => $db->storage->read_handler->next_storage }
76 );
77  
78 =head1 DESCRIPTION
79  
80 Warning: This class is marked BETA. This has been running a production
81 website using MySQL native replication as its backend and we have some decent
82 test coverage but the code hasn't yet been stressed by a variety of databases.
83 Individual DBs may have quirks we are not aware of. Please use this in first
84 development and pass along your experiences/bug fixes.
85  
86 This class implements replicated data store for DBI. Currently you can define
87 one master and numerous slave database connections. All write-type queries
88 (INSERT, UPDATE, DELETE and even LAST_INSERT_ID) are routed to master
89 database, all read-type queries (SELECTs) go to the slave database.
90  
91 Basically, any method request that L<DBIx::Class::Storage::DBI> would normally
92 handle gets delegated to one of the two attributes: L</read_handler> or to
93 L</write_handler>. Additionally, some methods need to be distributed
94 to all existing storages. This way our storage class is a drop in replacement
95 for L<DBIx::Class::Storage::DBI>.
96  
97 Read traffic is spread across the replicants (slaves) occurring to a user
98 selected algorithm. The default algorithm is random weighted.
99  
100 =head1 NOTES
101  
102 The consistency between master and replicants is database specific. The Pool
103 gives you a method to validate its replicants, removing and replacing them
104 when they fail/pass predefined criteria. Please make careful use of the ways
105 to force a query to run against Master when needed.
106  
107 =head1 REQUIREMENTS
108  
109 Replicated Storage has additional requirements not currently part of
110 L<DBIx::Class>. See L<DBIx::Class::Optional::Dependencies> for more details.
111  
112 =head1 ATTRIBUTES
113  
114 This class defines the following attributes.
115  
116 =head2 schema
117  
118 The underlying L<DBIx::Class::Schema> object this storage is attaching
119  
120 =cut
121  
122 has 'schema' => (
123 is=>'rw',
124 isa=>DBICSchema,
125 weak_ref=>1,
126 required=>1,
127 );
128  
129 =head2 pool_type
130  
131 Contains the classname which will instantiate the L</pool> object. Defaults
132 to: L<DBIx::Class::Storage::DBI::Replicated::Pool>.
133  
134 =cut
135  
136 has 'pool_type' => (
137 is=>'rw',
138 isa=>ClassName,
139 default=>'DBIx::Class::Storage::DBI::Replicated::Pool',
140 handles=>{
141 'create_pool' => 'new',
142 },
143 );
144  
145 =head2 pool_args
146  
147 Contains a hashref of initialized information to pass to the Balancer object.
148 See L<DBIx::Class::Storage::DBI::Replicated::Pool> for available arguments.
149  
150 =cut
151  
152 has 'pool_args' => (
153 is=>'rw',
154 isa=>HashRef,
155 lazy=>1,
156 default=>sub { {} },
157 );
158  
159  
160 =head2 balancer_type
161  
162 The replication pool requires a balance class to provider the methods for
163 choose how to spread the query load across each replicant in the pool.
164  
165 =cut
166  
167 has 'balancer_type' => (
168 is=>'rw',
169 isa=>BalancerClassNamePart,
170 coerce=>1,
171 required=>1,
172 default=> 'DBIx::Class::Storage::DBI::Replicated::Balancer::First',
173 handles=>{
174 'create_balancer' => 'new',
175 },
176 );
177  
178 =head2 balancer_args
179  
180 Contains a hashref of initialized information to pass to the Balancer object.
181 See L<DBIx::Class::Storage::DBI::Replicated::Balancer> for available arguments.
182  
183 =cut
184  
185 has 'balancer_args' => (
186 is=>'rw',
187 isa=>HashRef,
188 lazy=>1,
189 required=>1,
190 default=>sub { {} },
191 );
192  
193 =head2 pool
194  
195 Is a L<DBIx::Class::Storage::DBI::Replicated::Pool> or derived class. This is a
196 container class for one or more replicated databases.
197  
198 =cut
199  
200 has 'pool' => (
201 is=>'ro',
202 isa=>'DBIx::Class::Storage::DBI::Replicated::Pool',
203 lazy_build=>1,
204 handles=>[qw/
205 connect_replicants
206 replicants
207 has_replicants
208 /],
209 );
210  
211 =head2 balancer
212  
213 Is a L<DBIx::Class::Storage::DBI::Replicated::Balancer> or derived class. This
214 is a class that takes a pool (L<DBIx::Class::Storage::DBI::Replicated::Pool>)
215  
216 =cut
217  
218 has 'balancer' => (
219 is=>'rw',
220 isa=>'DBIx::Class::Storage::DBI::Replicated::Balancer',
221 lazy_build=>1,
222 handles=>[qw/auto_validate_every/],
223 );
224  
225 =head2 master
226  
227 The master defines the canonical state for a pool of connected databases. All
228 the replicants are expected to match this databases state. Thus, in a classic
229 Master / Slaves distributed system, all the slaves are expected to replicate
230 the Master's state as quick as possible. This is the only database in the
231 pool of databases that is allowed to handle write traffic.
232  
233 =cut
234  
235 has 'master' => (
236 is=> 'ro',
237 isa=>DBICStorageDBI,
238 lazy_build=>1,
239 );
240  
241 =head1 ATTRIBUTES IMPLEMENTING THE DBIx::Storage::DBI INTERFACE
242  
243 The following methods are delegated all the methods required for the
244 L<DBIx::Class::Storage::DBI> interface.
245  
246 =cut
247  
248 my $method_dispatch = {
249 writer => [qw/
250 on_connect_do
251 on_disconnect_do
252 on_connect_call
253 on_disconnect_call
254 connect_info
255 _connect_info
256 throw_exception
257 sql_maker
258 sqlt_type
259 create_ddl_dir
260 deployment_statements
261 datetime_parser
262 datetime_parser_type
263 build_datetime_parser
264 last_insert_id
265 insert
266 update
267 delete
268 dbh
269 txn_begin
270 txn_do
271 txn_commit
272 txn_rollback
273 txn_scope_guard
274 _exec_txn_rollback
275 _exec_txn_begin
276 _exec_txn_commit
277 deploy
278 with_deferred_fk_checks
279 dbh_do
280 _prep_for_execute
281 is_datatype_numeric
282 _count_select
283 svp_rollback
284 svp_begin
285 svp_release
286 relname_to_table_alias
287 _dbh_last_insert_id
288 _default_dbi_connect_attributes
289 _dbi_connect_info
290 _dbic_connect_attributes
291 auto_savepoint
292 _query_start
293 _query_end
294 _format_for_trace
295 _dbi_attrs_for_bind
296 bind_attribute_by_data_type
297 transaction_depth
298 _dbh
299 _select_args
300 _dbh_execute_for_fetch
301 _sql_maker
302 _dbh_execute_inserts_with_no_binds
303 _select_args_to_query
304 _gen_sql_bind
305 _svp_generate_name
306 _normalize_connect_info
307 _parse_connect_do
308 savepoints
309 _sql_maker_opts
310 _use_multicolumn_in
311 _conn_pid
312 _dbh_autocommit
313 _native_data_type
314 _get_dbh
315 sql_maker_class
316 insert_bulk
317 _insert_bulk
318 _execute
319 _do_query
320 _dbh_execute
321 /, Class::MOP::Class->initialize('DBIx::Class::Storage::DBIHacks')->get_method_list ],
322 reader => [qw/
323 select
324 select_single
325 columns_info_for
326 _dbh_columns_info_for
327 _select
328 /],
329 unimplemented => [qw/
330 _arm_global_destructor
331 _verify_pid
332  
333 _seems_connected
334 _ping
335  
336 get_use_dbms_capability
337 set_use_dbms_capability
338 get_dbms_capability
339 set_dbms_capability
340 _dbh_details
341 _dbh_get_info
342  
343 _determine_connector_driver
344 _extract_driver_from_connect_info
345 _describe_connection
346 _warn_undetermined_driver
347  
348 sql_limit_dialect
349 sql_quote_char
350 sql_name_sep
351  
352 _prefetch_autovalues
353 _perform_autoinc_retrieval
354 _autoinc_supplied_for_op
355  
356 _resolve_bindattrs
357  
358 _max_column_bytesize
359 _is_lob_type
360 _is_binary_lob_type
361 _is_binary_type
362 _is_text_lob_type
363  
364 _prepare_sth
365 _bind_sth_params
366 /,(
367 # the capability framework
368 # not sure if CMOP->initialize does evil things to DBIC::S::DBI, fix if a problem
369 grep
370 { $_ =~ /^ _ (?: use | supports | determine_supports ) _ /x and $_ ne '_use_multicolumn_in' }
371 ( Class::MOP::Class->initialize('DBIx::Class::Storage::DBI')->get_all_method_names )
372 )],
373 };
374  
375 if (DBIx::Class::_ENV_::DBICTEST) {
376  
377 my $seen;
378 for my $type (keys %$method_dispatch) {
379 for (@{$method_dispatch->{$type}}) {
380 push @{$seen->{$_}}, $type;
381 }
382 }
383  
384 if (my @dupes = grep { @{$seen->{$_}} > 1 } keys %$seen) {
385 die(join "\n", '',
386 'The following methods show up multiple times in ::Storage::DBI::Replicated handlers:',
387 (map { "$_: " . (join ', ', @{$seen->{$_}}) } sort @dupes),
388 '',
389 );
390 }
391  
392 if (my @cant = grep { ! DBIx::Class::Storage::DBI->can($_) } keys %$seen) {
393 die(join "\n", '',
394 '::Storage::DBI::Replicated specifies handling of the following *NON EXISTING* ::Storage::DBI methods:',
395 @cant,
396 '',
397 );
398 }
399 }
400  
401 for my $method (@{$method_dispatch->{unimplemented}}) {
402 __PACKAGE__->meta->add_method($method, sub {
403 my $self = shift;
404 $self->throw_exception("$method() must not be called on ".(blessed $self).' objects');
405 });
406 }
407  
408 =head2 read_handler
409  
410 Defines an object that implements the read side of L<DBIx::Class::Storage::DBI>.
411  
412 =cut
413  
414 has 'read_handler' => (
415 is=>'rw',
416 isa=>Object,
417 lazy_build=>1,
418 handles=>$method_dispatch->{reader},
419 );
420  
421 =head2 write_handler
422  
423 Defines an object that implements the write side of L<DBIx::Class::Storage::DBI>,
424 as well as methods that don't write or read that can be called on only one
425 storage, methods that return a C<$dbh>, and any methods that don't make sense to
426 run on a replicant.
427  
428 =cut
429  
430 has 'write_handler' => (
431 is=>'ro',
432 isa=>Object,
433 lazy_build=>1,
434 handles=>$method_dispatch->{writer},
435 );
436  
437  
438  
439 has _master_connect_info_opts =>
440 (is => 'rw', isa => HashRef, default => sub { {} });
441  
442 =head2 around: connect_info
443  
444 Preserves master's C<connect_info> options (for merging with replicants.)
445 Also sets any Replicated-related options from connect_info, such as
446 C<pool_type>, C<pool_args>, C<balancer_type> and C<balancer_args>.
447  
448 =cut
449  
450 around connect_info => sub {
451 my ($next, $self, $info, @extra) = @_;
452  
453 $self->throw_exception(
454 'connect_info can not be retrieved from a replicated storage - '
455 . 'accessor must be called on a specific pool instance'
456 ) unless defined $info;
457  
458 my $merge = Hash::Merge->new('LEFT_PRECEDENT');
459  
460 my %opts;
461 for my $arg (@$info) {
462 next unless (reftype($arg)||'') eq 'HASH';
463 %opts = %{ $merge->merge($arg, \%opts) };
464 }
465 delete $opts{dsn};
466  
467 if (@opts{qw/pool_type pool_args/}) {
468 $self->pool_type(delete $opts{pool_type})
469 if $opts{pool_type};
470  
471 $self->pool_args(
472 $merge->merge((delete $opts{pool_args} || {}), $self->pool_args)
473 );
474  
475 ## Since we possibly changed the pool_args, we need to clear the current
476 ## pool object so that next time it is used it will be rebuilt.
477 $self->clear_pool;
478 }
479  
480 if (@opts{qw/balancer_type balancer_args/}) {
481 $self->balancer_type(delete $opts{balancer_type})
482 if $opts{balancer_type};
483  
484 $self->balancer_args(
485 $merge->merge((delete $opts{balancer_args} || {}), $self->balancer_args)
486 );
487  
488 $self->balancer($self->_build_balancer)
489 if $self->balancer;
490 }
491  
492 $self->_master_connect_info_opts(\%opts);
493  
494 return preserve_context {
495 $self->$next($info, @extra);
496 } after => sub {
497 # Make sure master is blessed into the correct class and apply role to it.
498 my $master = $self->master;
499 $master->_determine_driver;
500 Moose::Meta::Class->initialize(ref $master);
501  
502 DBIx::Class::Storage::DBI::Replicated::WithDSN->meta->apply($master);
503  
504 # link pool back to master
505 $self->pool->master($master);
506 };
507 };
508  
509 =head1 METHODS
510  
511 This class defines the following methods.
512  
513 =head2 BUILDARGS
514  
515 L<DBIx::Class::Schema> when instantiating its storage passed itself as the
516 first argument. So we need to massage the arguments a bit so that all the
517 bits get put into the correct places.
518  
519 =cut
520  
521 sub BUILDARGS {
522 my ($class, $schema, $storage_type_args, @args) = @_;
523  
524 return {
525 schema=>$schema,
526 %$storage_type_args,
527 @args
528 }
529 }
530  
531 =head2 _build_master
532  
533 Lazy builder for the L</master> attribute.
534  
535 =cut
536  
537 sub _build_master {
538 my $self = shift @_;
539 my $master = DBIx::Class::Storage::DBI->new($self->schema);
540 $master
541 }
542  
543 =head2 _build_pool
544  
545 Lazy builder for the L</pool> attribute.
546  
547 =cut
548  
549 sub _build_pool {
550 my $self = shift @_;
551 $self->create_pool(%{$self->pool_args});
552 }
553  
554 =head2 _build_balancer
555  
556 Lazy builder for the L</balancer> attribute. This takes a Pool object so that
557 the balancer knows which pool it's balancing.
558  
559 =cut
560  
561 sub _build_balancer {
562 my $self = shift @_;
563 $self->create_balancer(
564 pool=>$self->pool,
565 master=>$self->master,
566 %{$self->balancer_args},
567 );
568 }
569  
570 =head2 _build_write_handler
571  
572 Lazy builder for the L</write_handler> attribute. The default is to set this to
573 the L</master>.
574  
575 =cut
576  
577 sub _build_write_handler {
578 return shift->master;
579 }
580  
581 =head2 _build_read_handler
582  
583 Lazy builder for the L</read_handler> attribute. The default is to set this to
584 the L</balancer>.
585  
586 =cut
587  
588 sub _build_read_handler {
589 return shift->balancer;
590 }
591  
592 =head2 around: connect_replicants
593  
594 All calls to connect_replicants needs to have an existing $schema tacked onto
595 top of the args, since L<DBIx::Class::Storage::DBI> needs it, and any
596 L<connect_info|DBIx::Class::Storage::DBI/connect_info>
597 options merged with the master, with replicant opts having higher priority.
598  
599 =cut
600  
601 around connect_replicants => sub {
602 my ($next, $self, @args) = @_;
603  
604 for my $r (@args) {
605 $r = [ $r ] unless reftype $r eq 'ARRAY';
606  
607 $self->throw_exception('coderef replicant connect_info not supported')
608 if ref $r->[0] && reftype $r->[0] eq 'CODE';
609  
610 # any connect_info options?
611 my $i = 0;
612 $i++ while $i < @$r && (reftype($r->[$i])||'') ne 'HASH';
613  
614 # make one if none
615 $r->[$i] = {} unless $r->[$i];
616  
617 # merge if two hashes
618 my @hashes = @$r[$i .. $#{$r}];
619  
620 $self->throw_exception('invalid connect_info options')
621 if (grep { reftype($_) eq 'HASH' } @hashes) != @hashes;
622  
623 $self->throw_exception('too many hashrefs in connect_info')
624 if @hashes > 2;
625  
626 my $merge = Hash::Merge->new('LEFT_PRECEDENT');
627 my %opts = %{ $merge->merge(reverse @hashes) };
628  
629 # delete them
630 splice @$r, $i+1, ($#{$r} - $i), ();
631  
632 # make sure master/replicants opts don't clash
633 my %master_opts = %{ $self->_master_connect_info_opts };
634 if (exists $opts{dbh_maker}) {
635 delete @master_opts{qw/dsn user password/};
636 }
637 delete $master_opts{dbh_maker};
638  
639 # merge with master
640 %opts = %{ $merge->merge(\%opts, \%master_opts) };
641  
642 # update
643 $r->[$i] = \%opts;
644 }
645  
646 $self->$next($self->schema, @args);
647 };
648  
649 =head2 all_storages
650  
651 Returns an array of all the connected storage backends. The first element
652 in the returned array is the master, and the rest are each of the
653 replicants.
654  
655 =cut
656  
657 sub all_storages {
658 my $self = shift @_;
659 return grep {defined $_ && blessed $_} (
660 $self->master,
661 values %{ $self->replicants },
662 );
663 }
664  
665 =head2 execute_reliably ($coderef, ?@args)
666  
667 Given a coderef, saves the current state of the L</read_handler>, forces it to
668 use reliable storage (e.g. sets it to the master), executes a coderef and then
669 restores the original state.
670  
671 Example:
672  
673 my $reliably = sub {
674 my $name = shift @_;
675 $schema->resultset('User')->create({name=>$name});
676 my $user_rs = $schema->resultset('User')->find({name=>$name});
677 return $user_rs;
678 };
679  
680 my $user_rs = $schema->storage->execute_reliably($reliably, 'John');
681  
682 Use this when you must be certain of your database state, such as when you just
683 inserted something and need to get a resultset including it, etc.
684  
685 =cut
686  
687 sub execute_reliably {
688 my $self = shift;
689 my $coderef = shift;
690  
691 $self->throw_exception('Second argument must be a coderef')
692 unless( ref $coderef eq 'CODE');
693  
694 ## replace the current read handler for the remainder of the scope
695 local $self->{read_handler} = $self->master;
696  
697 &$coderef;
698 }
699  
700 =head2 set_reliable_storage
701  
702 Sets the current $schema to be 'reliable', that is all queries, both read and
703 write are sent to the master
704  
705 =cut
706  
707 sub set_reliable_storage {
708 my $self = shift @_;
709 my $schema = $self->schema;
710 my $write_handler = $self->schema->storage->write_handler;
711  
712 $schema->storage->read_handler($write_handler);
713 }
714  
715 =head2 set_balanced_storage
716  
717 Sets the current $schema to be use the </balancer> for all reads, while all
718 writes are sent to the master only
719  
720 =cut
721  
722 sub set_balanced_storage {
723 my $self = shift @_;
724 my $schema = $self->schema;
725 my $balanced_handler = $self->schema->storage->balancer;
726  
727 $schema->storage->read_handler($balanced_handler);
728 }
729  
730 =head2 connected
731  
732 Check that the master and at least one of the replicants is connected.
733  
734 =cut
735  
736 sub connected {
737 my $self = shift @_;
738 return
739 $self->master->connected &&
740 $self->pool->connected_replicants;
741 }
742  
743 =head2 ensure_connected
744  
745 Make sure all the storages are connected.
746  
747 =cut
748  
749 sub ensure_connected {
750 my $self = shift @_;
751 foreach my $source ($self->all_storages) {
752 $source->ensure_connected(@_);
753 }
754 }
755  
756 =head2 limit_dialect
757  
758 Set the limit_dialect for all existing storages
759  
760 =cut
761  
762 sub limit_dialect {
763 my $self = shift @_;
764 foreach my $source ($self->all_storages) {
765 $source->limit_dialect(@_);
766 }
767 return $self->master->limit_dialect;
768 }
769  
770 =head2 quote_char
771  
772 Set the quote_char for all existing storages
773  
774 =cut
775  
776 sub quote_char {
777 my $self = shift @_;
778 foreach my $source ($self->all_storages) {
779 $source->quote_char(@_);
780 }
781 return $self->master->quote_char;
782 }
783  
784 =head2 name_sep
785  
786 Set the name_sep for all existing storages
787  
788 =cut
789  
790 sub name_sep {
791 my $self = shift @_;
792 foreach my $source ($self->all_storages) {
793 $source->name_sep(@_);
794 }
795 return $self->master->name_sep;
796 }
797  
798 =head2 set_schema
799  
800 Set the schema object for all existing storages
801  
802 =cut
803  
804 sub set_schema {
805 my $self = shift @_;
806 foreach my $source ($self->all_storages) {
807 $source->set_schema(@_);
808 }
809 }
810  
811 =head2 debug
812  
813 set a debug flag across all storages
814  
815 =cut
816  
817 sub debug {
818 my $self = shift @_;
819 if(@_) {
820 foreach my $source ($self->all_storages) {
821 $source->debug(@_);
822 }
823 }
824 return $self->master->debug;
825 }
826  
827 =head2 debugobj
828  
829 set a debug object
830  
831 =cut
832  
833 sub debugobj {
834 my $self = shift @_;
835 return $self->master->debugobj(@_);
836 }
837  
838 =head2 debugfh
839  
840 set a debugfh object
841  
842 =cut
843  
844 sub debugfh {
845 my $self = shift @_;
846 return $self->master->debugfh(@_);
847 }
848  
849 =head2 debugcb
850  
851 set a debug callback
852  
853 =cut
854  
855 sub debugcb {
856 my $self = shift @_;
857 return $self->master->debugcb(@_);
858 }
859  
860 =head2 disconnect
861  
862 disconnect everything
863  
864 =cut
865  
866 sub disconnect {
867 my $self = shift @_;
868 foreach my $source ($self->all_storages) {
869 $source->disconnect(@_);
870 }
871 }
872  
873 =head2 cursor_class
874  
875 set cursor class on all storages, or return master's
876  
877 =cut
878  
879 sub cursor_class {
880 my ($self, $cursor_class) = @_;
881  
882 if ($cursor_class) {
883 $_->cursor_class($cursor_class) for $self->all_storages;
884 }
885 $self->master->cursor_class;
886 }
887  
888 =head2 cursor
889  
890 set cursor class on all storages, or return master's, alias for L</cursor_class>
891 above.
892  
893 =cut
894  
895 sub cursor {
896 my ($self, $cursor_class) = @_;
897  
898 if ($cursor_class) {
899 $_->cursor($cursor_class) for $self->all_storages;
900 }
901 $self->master->cursor;
902 }
903  
904 =head2 unsafe
905  
906 sets the L<DBIx::Class::Storage::DBI/unsafe> option on all storages or returns
907 master's current setting
908  
909 =cut
910  
911 sub unsafe {
912 my $self = shift;
913  
914 if (@_) {
915 $_->unsafe(@_) for $self->all_storages;
916 }
917  
918 return $self->master->unsafe;
919 }
920  
921 =head2 disable_sth_caching
922  
923 sets the L<DBIx::Class::Storage::DBI/disable_sth_caching> option on all storages
924 or returns master's current setting
925  
926 =cut
927  
928 sub disable_sth_caching {
929 my $self = shift;
930  
931 if (@_) {
932 $_->disable_sth_caching(@_) for $self->all_storages;
933 }
934  
935 return $self->master->disable_sth_caching;
936 }
937  
938 =head2 lag_behind_master
939  
940 returns the highest Replicant L<DBIx::Class::Storage::DBI/lag_behind_master>
941 setting
942  
943 =cut
944  
945 sub lag_behind_master {
946 my $self = shift;
947  
948 return List::Util::max( map { $_->lag_behind_master } $self->replicants );
949 }
950  
951 =head2 is_replicating
952  
953 returns true if all replicants return true for
954 L<DBIx::Class::Storage::DBI/is_replicating>
955  
956 =cut
957  
958 sub is_replicating {
959 my $self = shift;
960  
961 return (grep $_->is_replicating, $self->replicants) == ($self->replicants);
962 }
963  
964 =head2 connect_call_datetime_setup
965  
966 calls L<DBIx::Class::Storage::DBI/connect_call_datetime_setup> for all storages
967  
968 =cut
969  
970 sub connect_call_datetime_setup {
971 my $self = shift;
972 $_->connect_call_datetime_setup for $self->all_storages;
973 }
974  
975 =head2 connect_call_rebase_sqlmaker
976  
977 calls L<DBIx::Class::Storage::DBI/connect_call_rebase_sqlmaker> for all storages
978  
979 =cut
980  
981 sub connect_call_rebase_sqlmaker {
982 my( $self, $target_base ) = @_;
983 $_->connect_call_rebase_sqlmaker( $target_base ) for $self->all_storages;
984 }
985  
986 sub _populate_dbh {
987 my $self = shift;
988 $_->_populate_dbh for $self->all_storages;
989 }
990  
991 sub _connect {
992 my $self = shift;
993 $_->_connect for $self->all_storages;
994 }
995  
996 sub _rebless {
997 my $self = shift;
998 $_->_rebless for $self->all_storages;
999 }
1000  
1001 sub _determine_driver {
1002 my $self = shift;
1003 $_->_determine_driver for $self->all_storages;
1004 }
1005  
1006 sub _driver_determined {
1007 my $self = shift;
1008  
1009 if (@_) {
1010 $_->_driver_determined(@_) for $self->all_storages;
1011 }
1012  
1013 return $self->master->_driver_determined;
1014 }
1015  
1016 sub _init {
1017 my $self = shift;
1018  
1019 $_->_init for $self->all_storages;
1020 }
1021  
1022 sub _run_connection_actions {
1023 my $self = shift;
1024  
1025 $_->_run_connection_actions for $self->all_storages;
1026 }
1027  
1028 sub _do_connection_actions {
1029 my $self = shift;
1030  
1031 if (@_) {
1032 $_->_do_connection_actions(@_) for $self->all_storages;
1033 }
1034 }
1035  
1036 sub connect_call_do_sql {
1037 my $self = shift;
1038 $_->connect_call_do_sql(@_) for $self->all_storages;
1039 }
1040  
1041 sub disconnect_call_do_sql {
1042 my $self = shift;
1043 $_->disconnect_call_do_sql(@_) for $self->all_storages;
1044 }
1045  
1046 # not using the normalized_version, because we want to preserve
1047 # version numbers much longer than the conventional xxx.yyyzzz
1048 my $numify_ver = sub {
1049 my $ver = shift;
1050 my @numparts = split /\D+/, $ver;
1051 my $format = '%d.' . (join '', ('%06d') x (@numparts - 1));
1052  
1053 return sprintf $format, @numparts;
1054 };
1055 sub _server_info {
1056 my $self = shift;
1057  
1058 if (not $self->_dbh_details->{info}) {
1059 $self->_dbh_details->{info} = (
1060 reduce { $a->[0] < $b->[0] ? $a : $b }
1061 map [ $numify_ver->($_->{dbms_version}), $_ ],
1062 map $_->_server_info, $self->all_storages
1063 )->[1];
1064 }
1065  
1066 return $self->next::method;
1067 }
1068  
1069 sub _get_server_version {
1070 my $self = shift;
1071  
1072 return $self->_server_info->{dbms_version};
1073 }
1074  
1075 =head1 GOTCHAS
1076  
1077 Due to the fact that replicants can lag behind a master, you must take care to
1078 make sure you use one of the methods to force read queries to a master should
1079 you need realtime data integrity. For example, if you insert a row, and then
1080 immediately re-read it from the database (say, by doing
1081 L<< $result->discard_changes|DBIx::Class::Row/discard_changes >>)
1082 or you insert a row and then immediately build a query that expects that row
1083 to be an item, you should force the master to handle reads. Otherwise, due to
1084 the lag, there is no certainty your data will be in the expected state.
1085  
1086 For data integrity, all transactions automatically use the master storage for
1087 all read and write queries. Using a transaction is the preferred and recommended
1088 method to force the master to handle all read queries.
1089  
1090 Otherwise, you can force a single query to use the master with the 'force_pool'
1091 attribute:
1092  
1093 my $result = $resultset->search(undef, {force_pool=>'master'})->find($pk);
1094  
1095 This attribute will safely be ignored by non replicated storages, so you can use
1096 the same code for both types of systems.
1097  
1098 Lastly, you can use the L</execute_reliably> method, which works very much like
1099 a transaction.
1100  
1101 For debugging, you can turn replication on/off with the methods L</set_reliable_storage>
1102 and L</set_balanced_storage>, however this operates at a global level and is not
1103 suitable if you have a shared Schema object being used by multiple processes,
1104 such as on a web application server. You can get around this limitation by
1105 using the Schema clone method.
1106  
1107 my $new_schema = $schema->clone;
1108 $new_schema->set_reliable_storage;
1109  
1110 ## $new_schema will use only the Master storage for all reads/writes while
1111 ## the $schema object will use replicated storage.
1112  
1113 =head1 FURTHER QUESTIONS?
1114  
1115 Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
1116  
1117 =head1 COPYRIGHT AND LICENSE
1118  
1119 This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
1120 by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
1121 redistribute it and/or modify it under the same terms as the
1122 L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.
1123  
1124 =cut
1125  
1126 __PACKAGE__->meta->make_immutable;
1127  
1128 1;
« DBIx/Class/Admin.pm ↑ Summary DBIx/Class/SQLMaker/LimitDialects.pm »