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