failing (crashing, really) test for this strange pg thing. could not figure out...
[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / Storage / DBI / Replicated.pm
CommitLineData
2156bbdd 1package DBIx::Class::Storage::DBI::Replicated;
f5d3a5de 2
ecb65397 3BEGIN {
4 use Carp::Clan qw/^DBIx::Class/;
d4daee7b 5
ecb65397 6 ## Modules required for Replication support not required for general DBIC
7 ## use, so we explicitly test for these.
d4daee7b 8
ecb65397 9 my %replication_required = (
62eabf11 10 'Moose' => '0.87',
450a317d 11 'MooseX::AttributeHelpers' => '0.21',
62eabf11 12 'MooseX::Types' => '0.16',
bd5da369 13 'namespace::clean' => '0.11',
14 'Hash::Merge' => '0.11'
ecb65397 15 );
d4daee7b 16
ecb65397 17 my @didnt_load;
d4daee7b 18
ecb65397 19 for my $module (keys %replication_required) {
20 eval "use $module $replication_required{$module}";
21 push @didnt_load, "$module $replication_required{$module}"
22 if $@;
23 }
d4daee7b 24
ecb65397 25 croak("@{[ join ', ', @didnt_load ]} are missing and are required for Replication")
d4daee7b 26 if @didnt_load;
ecb65397 27}
28
b2e4d522 29use Moose;
26ab719a 30use DBIx::Class::Storage::DBI;
2bf79155 31use DBIx::Class::Storage::DBI::Replicated::Pool;
26ab719a 32use DBIx::Class::Storage::DBI::Replicated::Balancer;
6a151f58 33use DBIx::Class::Storage::DBI::Replicated::Types qw/BalancerClassNamePart DBICSchema DBICStorageDBI/;
41916570 34use MooseX::Types::Moose qw/ClassName HashRef Object/;
b2e4d522 35use Scalar::Util 'reftype';
36use Carp::Clan qw/^DBIx::Class/;
b88b85e7 37use Hash::Merge 'merge';
9901aad7 38
39use namespace::clean -except => 'meta';
2bf79155 40
41=head1 NAME
42
ecb65397 43DBIx::Class::Storage::DBI::Replicated - BETA Replicated database support
2bf79155 44
45=head1 SYNOPSIS
46
47The Following example shows how to change an existing $schema to a replicated
48storage type, add some replicated (readonly) databases, and perform reporting
955a6df6 49tasks.
2bf79155 50
3da4f736 51You should set the 'storage_type attribute to a replicated type. You should
d4daee7b 52also define your arguments, such as which balancer you want and any arguments
3da4f736 53that the Pool object should get.
54
64cdad22 55 $schema->storage_type( ['::DBI::Replicated', {balancer=>'::Random'}] );
d4daee7b 56
3da4f736 57Next, you need to add in the Replicants. Basically this is an array of
58arrayrefs, where each arrayref is database connect information. Think of these
59arguments as what you'd pass to the 'normal' $schema->connect method.
d4daee7b 60
64cdad22 61 $schema->storage->connect_replicants(
62 [$dsn1, $user, $pass, \%opts],
63 [$dsn2, $user, $pass, \%opts],
64 [$dsn3, $user, $pass, \%opts],
65 );
d4daee7b 66
3da4f736 67Now, just use the $schema as you normally would. Automatically all reads will
68be delegated to the replicants, while writes to the master.
69
7e38d850 70 $schema->resultset('Source')->search({name=>'etc'});
d4daee7b 71
3da4f736 72You can force a given query to use a particular storage using the search
73attribute 'force_pool'. For example:
d4daee7b 74
7e38d850 75 my $RS = $schema->resultset('Source')->search(undef, {force_pool=>'master'});
3da4f736 76
77Now $RS will force everything (both reads and writes) to use whatever was setup
78as the master storage. 'master' is hardcoded to always point to the Master,
79but you can also use any Replicant name. Please see:
212cc5c2 80L<DBIx::Class::Storage::DBI::Replicated::Pool> and the replicants attribute for more.
3da4f736 81
82Also see transactions and L</execute_reliably> for alternative ways to
83force read traffic to the master. In general, you should wrap your statements
84in a transaction when you are reading and writing to the same tables at the
85same time, since your replicants will often lag a bit behind the master.
212cc5c2 86
87See L<DBIx::Class::Storage::DBI::Replicated::Instructions> for more help and
88walkthroughs.
d4daee7b 89
2bf79155 90=head1 DESCRIPTION
91
7e38d850 92Warning: This class is marked BETA. This has been running a production
ccb3b897 93website using MySQL native replication as its backend and we have some decent
7e38d850 94test coverage but the code hasn't yet been stressed by a variety of databases.
95Individual DB's may have quirks we are not aware of. Please use this in first
96development and pass along your experiences/bug fixes.
2bf79155 97
98This class implements replicated data store for DBI. Currently you can define
99one master and numerous slave database connections. All write-type queries
100(INSERT, UPDATE, DELETE and even LAST_INSERT_ID) are routed to master
101database, all read-type queries (SELECTs) go to the slave database.
102
103Basically, any method request that L<DBIx::Class::Storage::DBI> would normally
bca099a3 104handle gets delegated to one of the two attributes: L</read_handler> or to
105L</write_handler>. Additionally, some methods need to be distributed
2bf79155 106to all existing storages. This way our storage class is a drop in replacement
107for L<DBIx::Class::Storage::DBI>.
108
109Read traffic is spread across the replicants (slaves) occuring to a user
110selected algorithm. The default algorithm is random weighted.
111
bca099a3 112=head1 NOTES
113
114The consistancy betweeen master and replicants is database specific. The Pool
faaba25f 115gives you a method to validate its replicants, removing and replacing them
7e38d850 116when they fail/pass predefined criteria. Please make careful use of the ways
ecb65397 117to force a query to run against Master when needed.
118
119=head1 REQUIREMENTS
120
121Replicated Storage has additional requirements not currently part of L<DBIx::Class>
122
62eabf11 123 Moose => '0.87',
124 MooseX::AttributeHelpers => '0.20',
125 MooseX::Types => '0.16',
126 namespace::clean => '0.11',
127 Hash::Merge => '0.11'
d4daee7b 128
ecb65397 129You will need to install these modules manually via CPAN or make them part of the
130Makefile for your distribution.
2bf79155 131
132=head1 ATTRIBUTES
133
134This class defines the following attributes.
135
2ce6e9a6 136=head2 schema
137
138The underlying L<DBIx::Class::Schema> object this storage is attaching
139
140=cut
141
142has 'schema' => (
143 is=>'rw',
6a151f58 144 isa=>DBICSchema,
2ce6e9a6 145 weak_ref=>1,
146 required=>1,
147);
148
26ab719a 149=head2 pool_type
2bf79155 150
26ab719a 151Contains the classname which will instantiate the L</pool> object. Defaults
152to: L<DBIx::Class::Storage::DBI::Replicated::Pool>.
2bf79155 153
154=cut
155
26ab719a 156has 'pool_type' => (
dcdf7b2c 157 is=>'rw',
41916570 158 isa=>ClassName,
2ce6e9a6 159 default=>'DBIx::Class::Storage::DBI::Replicated::Pool',
64cdad22 160 handles=>{
161 'create_pool' => 'new',
162 },
2bf79155 163);
164
f068a139 165=head2 pool_args
166
167Contains a hashref of initialized information to pass to the Balancer object.
212cc5c2 168See L<DBIx::Class::Storage::DBI::Replicated::Pool> for available arguments.
f068a139 169
170=cut
171
172has 'pool_args' => (
dcdf7b2c 173 is=>'rw',
41916570 174 isa=>HashRef,
64cdad22 175 lazy=>1,
64cdad22 176 default=>sub { {} },
f068a139 177);
178
179
26ab719a 180=head2 balancer_type
2bf79155 181
182The replication pool requires a balance class to provider the methods for
183choose how to spread the query load across each replicant in the pool.
184
185=cut
186
26ab719a 187has 'balancer_type' => (
dcdf7b2c 188 is=>'rw',
9901aad7 189 isa=>BalancerClassNamePart,
2ce6e9a6 190 coerce=>1,
191 required=>1,
192 default=> 'DBIx::Class::Storage::DBI::Replicated::Balancer::First',
64cdad22 193 handles=>{
194 'create_balancer' => 'new',
195 },
2bf79155 196);
197
17b05c13 198=head2 balancer_args
199
200Contains a hashref of initialized information to pass to the Balancer object.
212cc5c2 201See L<DBIx::Class::Storage::DBI::Replicated::Balancer> for available arguments.
17b05c13 202
203=cut
204
205has 'balancer_args' => (
dcdf7b2c 206 is=>'rw',
41916570 207 isa=>HashRef,
64cdad22 208 lazy=>1,
209 required=>1,
210 default=>sub { {} },
17b05c13 211);
212
26ab719a 213=head2 pool
2bf79155 214
26ab719a 215Is a <DBIx::Class::Storage::DBI::Replicated::Pool> or derived class. This is a
216container class for one or more replicated databases.
2bf79155 217
218=cut
219
26ab719a 220has 'pool' => (
64cdad22 221 is=>'ro',
222 isa=>'DBIx::Class::Storage::DBI::Replicated::Pool',
223 lazy_build=>1,
224 handles=>[qw/
225 connect_replicants
226 replicants
227 has_replicants
228 /],
2bf79155 229);
230
26ab719a 231=head2 balancer
2bf79155 232
26ab719a 233Is a <DBIx::Class::Storage::DBI::Replicated::Balancer> or derived class. This
234is a class that takes a pool (<DBIx::Class::Storage::DBI::Replicated::Pool>)
2bf79155 235
26ab719a 236=cut
2bf79155 237
26ab719a 238has 'balancer' => (
dcdf7b2c 239 is=>'rw',
64cdad22 240 isa=>'DBIx::Class::Storage::DBI::Replicated::Balancer',
241 lazy_build=>1,
242 handles=>[qw/auto_validate_every/],
26ab719a 243);
2bf79155 244
cb6ec758 245=head2 master
246
247The master defines the canonical state for a pool of connected databases. All
248the replicants are expected to match this databases state. Thus, in a classic
249Master / Slaves distributed system, all the slaves are expected to replicate
250the Master's state as quick as possible. This is the only database in the
251pool of databases that is allowed to handle write traffic.
252
253=cut
254
255has 'master' => (
64cdad22 256 is=> 'ro',
6a151f58 257 isa=>DBICStorageDBI,
64cdad22 258 lazy_build=>1,
cb6ec758 259);
260
cb6ec758 261=head1 ATTRIBUTES IMPLEMENTING THE DBIx::Storage::DBI INTERFACE
262
263The following methods are delegated all the methods required for the
264L<DBIx::Class::Storage::DBI> interface.
265
266=head2 read_handler
267
268Defines an object that implements the read side of L<BIx::Class::Storage::DBI>.
269
270=cut
271
272has 'read_handler' => (
64cdad22 273 is=>'rw',
41916570 274 isa=>Object,
64cdad22 275 lazy_build=>1,
276 handles=>[qw/
277 select
278 select_single
279 columns_info_for
280 /],
cb6ec758 281);
282
cb6ec758 283=head2 write_handler
284
285Defines an object that implements the write side of L<BIx::Class::Storage::DBI>.
286
287=cut
288
289has 'write_handler' => (
64cdad22 290 is=>'ro',
41916570 291 isa=>Object,
64cdad22 292 lazy_build=>1,
64cdad22 293 handles=>[qw/
294 on_connect_do
295 on_disconnect_do
296 connect_info
297 throw_exception
298 sql_maker
299 sqlt_type
300 create_ddl_dir
301 deployment_statements
302 datetime_parser
7fb60fb1 303 datetime_parser_type
304 build_datetime_parser
64cdad22 305 last_insert_id
306 insert
307 insert_bulk
308 update
309 delete
310 dbh
2ce6e9a6 311 txn_begin
64cdad22 312 txn_do
313 txn_commit
314 txn_rollback
2ce6e9a6 315 txn_scope_guard
64cdad22 316 sth
317 deploy
0180bef9 318 with_deferred_fk_checks
7fb60fb1 319 dbh_do
64cdad22 320 reload_row
7fb60fb1 321 with_deferred_fk_checks
2ce6e9a6 322 _prep_for_execute
7fb60fb1 323
324 backup
325 is_datatype_numeric
326 _count_select
327 _subq_count_select
328 _subq_update_delete
329 svp_rollback
330 svp_begin
331 svp_release
64cdad22 332 /],
cb6ec758 333);
334
b2e4d522 335has _master_connect_info_opts =>
336 (is => 'rw', isa => HashRef, default => sub { {} });
337
338=head2 around: connect_info
339
340Preserve master's C<connect_info> options (for merging with replicants.)
dcdf7b2c 341Also set any Replicated related options from connect_info, such as
342C<pool_type>, C<pool_args>, C<balancer_type> and C<balancer_args>.
b2e4d522 343
344=cut
345
346around connect_info => sub {
347 my ($next, $self, $info, @extra) = @_;
348
0ce2d0d5 349 my $wantarray = wantarray;
350
b2e4d522 351 my %opts;
352 for my $arg (@$info) {
353 next unless (reftype($arg)||'') eq 'HASH';
b88b85e7 354 %opts = %{ merge($arg, \%opts) };
b2e4d522 355 }
b2e4d522 356 delete $opts{dsn};
357
dcdf7b2c 358 if (@opts{qw/pool_type pool_args/}) {
359 $self->pool_type(delete $opts{pool_type})
360 if $opts{pool_type};
361
b88b85e7 362 $self->pool_args(
363 merge((delete $opts{pool_args} || {}), $self->pool_args)
364 );
dcdf7b2c 365
67c43863 366 $self->pool($self->_build_pool)
367 if $self->pool;
dcdf7b2c 368 }
369
370 if (@opts{qw/balancer_type balancer_args/}) {
371 $self->balancer_type(delete $opts{balancer_type})
372 if $opts{balancer_type};
373
b88b85e7 374 $self->balancer_args(
375 merge((delete $opts{balancer_args} || {}), $self->balancer_args)
376 );
dcdf7b2c 377
67c43863 378 $self->balancer($self->_build_balancer)
379 if $self->balancer;
dcdf7b2c 380 }
381
b2e4d522 382 $self->_master_connect_info_opts(\%opts);
383
0ce2d0d5 384 my (@res, $res);
385 if ($wantarray) {
386 @res = $self->$next($info, @extra);
387 } else {
388 $res = $self->$next($info, @extra);
389 }
390
fd4eb9c2 391 # Make sure master is blessed into the correct class and apply role to it.
392 my $master = $self->master;
393 $master->_determine_driver;
394 Moose::Meta::Class->initialize(ref $master);
395 DBIx::Class::Storage::DBI::Replicated::WithDSN->meta->apply($master);
0ce2d0d5 396
397 $wantarray ? @res : $res;
b2e4d522 398};
399
26ab719a 400=head1 METHODS
2bf79155 401
26ab719a 402This class defines the following methods.
2bf79155 403
c354902c 404=head2 BUILDARGS
2bf79155 405
faaba25f 406L<DBIx::Class::Schema> when instantiating its storage passed itself as the
2ce6e9a6 407first argument. So we need to massage the arguments a bit so that all the
408bits get put into the correct places.
2bf79155 409
410=cut
411
c354902c 412sub BUILDARGS {
413 my ($class, $schema, $storage_type_args, @args) = @_;
d4daee7b 414
c354902c 415 return {
416 schema=>$schema,
417 %$storage_type_args,
418 @args
419 }
420}
2bf79155 421
cb6ec758 422=head2 _build_master
2bf79155 423
cb6ec758 424Lazy builder for the L</master> attribute.
2bf79155 425
426=cut
427
cb6ec758 428sub _build_master {
2ce6e9a6 429 my $self = shift @_;
ee356d00 430 my $master = DBIx::Class::Storage::DBI->new($self->schema);
ee356d00 431 $master
106d5f3b 432}
433
26ab719a 434=head2 _build_pool
2bf79155 435
26ab719a 436Lazy builder for the L</pool> attribute.
2bf79155 437
438=cut
439
26ab719a 440sub _build_pool {
64cdad22 441 my $self = shift @_;
442 $self->create_pool(%{$self->pool_args});
2bf79155 443}
444
26ab719a 445=head2 _build_balancer
2bf79155 446
cb6ec758 447Lazy builder for the L</balancer> attribute. This takes a Pool object so that
448the balancer knows which pool it's balancing.
2bf79155 449
450=cut
451
26ab719a 452sub _build_balancer {
64cdad22 453 my $self = shift @_;
454 $self->create_balancer(
455 pool=>$self->pool,
456 master=>$self->master,
457 %{$self->balancer_args},
458 );
2bf79155 459}
460
cb6ec758 461=head2 _build_write_handler
2bf79155 462
cb6ec758 463Lazy builder for the L</write_handler> attribute. The default is to set this to
464the L</master>.
50336325 465
466=cut
467
cb6ec758 468sub _build_write_handler {
64cdad22 469 return shift->master;
cb6ec758 470}
50336325 471
cb6ec758 472=head2 _build_read_handler
2bf79155 473
cb6ec758 474Lazy builder for the L</read_handler> attribute. The default is to set this to
475the L</balancer>.
2bf79155 476
477=cut
478
cb6ec758 479sub _build_read_handler {
64cdad22 480 return shift->balancer;
cb6ec758 481}
50336325 482
cb6ec758 483=head2 around: connect_replicants
2bf79155 484
cb6ec758 485All calls to connect_replicants needs to have an existing $schema tacked onto
b2e4d522 486top of the args, since L<DBIx::Storage::DBI> needs it, and any C<connect_info>
487options merged with the master, with replicant opts having higher priority.
955a6df6 488
cb6ec758 489=cut
955a6df6 490
b2e4d522 491around connect_replicants => sub {
492 my ($next, $self, @args) = @_;
493
494 for my $r (@args) {
495 $r = [ $r ] unless reftype $r eq 'ARRAY';
496
497 croak "coderef replicant connect_info not supported"
498 if ref $r->[0] && reftype $r->[0] eq 'CODE';
499
500# any connect_info options?
501 my $i = 0;
502 $i++ while $i < @$r && (reftype($r->[$i])||'') ne 'HASH';
503
504# make one if none
505 $r->[$i] = {} unless $r->[$i];
506
507# merge if two hashes
b88b85e7 508 my @hashes = @$r[$i .. $#{$r}];
509
510 croak "invalid connect_info options"
511 if (grep { reftype($_) eq 'HASH' } @hashes) != @hashes;
512
513 croak "too many hashrefs in connect_info"
514 if @hashes > 2;
515
516 my %opts = %{ merge(reverse @hashes) };
517
518# delete them
b2e4d522 519 splice @$r, $i+1, ($#{$r} - $i), ();
520
521# merge with master
b88b85e7 522 %opts = %{ merge(\%opts, $self->_master_connect_info_opts) };
b2e4d522 523
524# update
525 $r->[$i] = \%opts;
526 }
527
528 $self->$next($self->schema, @args);
955a6df6 529};
2bf79155 530
2bf79155 531=head2 all_storages
532
533Returns an array of of all the connected storage backends. The first element
534in the returned array is the master, and the remainings are each of the
535replicants.
536
537=cut
538
539sub all_storages {
64cdad22 540 my $self = shift @_;
541 return grep {defined $_ && blessed $_} (
542 $self->master,
6412a592 543 values %{ $self->replicants },
64cdad22 544 );
2bf79155 545}
546
c4d3fae2 547=head2 execute_reliably ($coderef, ?@args)
548
549Given a coderef, saves the current state of the L</read_handler>, forces it to
550use reliable storage (ie sets it to the master), executes a coderef and then
551restores the original state.
552
553Example:
554
64cdad22 555 my $reliably = sub {
556 my $name = shift @_;
557 $schema->resultset('User')->create({name=>$name});
558 my $user_rs = $schema->resultset('User')->find({name=>$name});
559 return $user_rs;
560 };
c4d3fae2 561
64cdad22 562 my $user_rs = $schema->storage->execute_reliably($reliably, 'John');
c4d3fae2 563
564Use this when you must be certain of your database state, such as when you just
565inserted something and need to get a resultset including it, etc.
566
567=cut
568
569sub execute_reliably {
64cdad22 570 my ($self, $coderef, @args) = @_;
d4daee7b 571
64cdad22 572 unless( ref $coderef eq 'CODE') {
573 $self->throw_exception('Second argument must be a coderef');
574 }
d4daee7b 575
64cdad22 576 ##Get copy of master storage
577 my $master = $self->master;
d4daee7b 578
64cdad22 579 ##Get whatever the current read hander is
580 my $current = $self->read_handler;
d4daee7b 581
64cdad22 582 ##Set the read handler to master
583 $self->read_handler($master);
d4daee7b 584
64cdad22 585 ## do whatever the caller needs
586 my @result;
587 my $want_array = wantarray;
d4daee7b 588
64cdad22 589 eval {
590 if($want_array) {
591 @result = $coderef->(@args);
592 } elsif(defined $want_array) {
593 ($result[0]) = ($coderef->(@args));
ed213e85 594 } else {
64cdad22 595 $coderef->(@args);
596 }
597 };
d4daee7b 598
64cdad22 599 ##Reset to the original state
600 $self->read_handler($current);
d4daee7b 601
64cdad22 602 ##Exception testing has to come last, otherwise you might leave the
603 ##read_handler set to master.
d4daee7b 604
64cdad22 605 if($@) {
606 $self->throw_exception("coderef returned an error: $@");
607 } else {
608 return $want_array ? @result : $result[0];
609 }
c4d3fae2 610}
611
cb6ec758 612=head2 set_reliable_storage
613
614Sets the current $schema to be 'reliable', that is all queries, both read and
615write are sent to the master
d4daee7b 616
cb6ec758 617=cut
618
619sub set_reliable_storage {
64cdad22 620 my $self = shift @_;
621 my $schema = $self->schema;
622 my $write_handler = $self->schema->storage->write_handler;
d4daee7b 623
64cdad22 624 $schema->storage->read_handler($write_handler);
cb6ec758 625}
626
627=head2 set_balanced_storage
628
629Sets the current $schema to be use the </balancer> for all reads, while all
630writea are sent to the master only
d4daee7b 631
cb6ec758 632=cut
633
634sub set_balanced_storage {
64cdad22 635 my $self = shift @_;
636 my $schema = $self->schema;
bd5da369 637 my $balanced_handler = $self->schema->storage->balancer;
d4daee7b 638
bd5da369 639 $schema->storage->read_handler($balanced_handler);
cb6ec758 640}
2bf79155 641
642=head2 connected
643
644Check that the master and at least one of the replicants is connected.
645
646=cut
647
648sub connected {
64cdad22 649 my $self = shift @_;
650 return
651 $self->master->connected &&
652 $self->pool->connected_replicants;
2bf79155 653}
654
2bf79155 655=head2 ensure_connected
656
657Make sure all the storages are connected.
658
659=cut
660
661sub ensure_connected {
64cdad22 662 my $self = shift @_;
663 foreach my $source ($self->all_storages) {
664 $source->ensure_connected(@_);
665 }
2bf79155 666}
667
2bf79155 668=head2 limit_dialect
669
670Set the limit_dialect for all existing storages
671
672=cut
673
674sub limit_dialect {
64cdad22 675 my $self = shift @_;
676 foreach my $source ($self->all_storages) {
677 $source->limit_dialect(@_);
678 }
3fbe08e3 679 return $self->master->quote_char;
2bf79155 680}
681
2bf79155 682=head2 quote_char
683
684Set the quote_char for all existing storages
685
686=cut
687
688sub quote_char {
64cdad22 689 my $self = shift @_;
690 foreach my $source ($self->all_storages) {
691 $source->quote_char(@_);
692 }
3fbe08e3 693 return $self->master->quote_char;
2bf79155 694}
695
2bf79155 696=head2 name_sep
697
698Set the name_sep for all existing storages
699
700=cut
701
702sub name_sep {
64cdad22 703 my $self = shift @_;
704 foreach my $source ($self->all_storages) {
705 $source->name_sep(@_);
706 }
3fbe08e3 707 return $self->master->name_sep;
2bf79155 708}
709
2bf79155 710=head2 set_schema
711
712Set the schema object for all existing storages
713
714=cut
715
716sub set_schema {
64cdad22 717 my $self = shift @_;
718 foreach my $source ($self->all_storages) {
719 $source->set_schema(@_);
720 }
2bf79155 721}
722
2bf79155 723=head2 debug
724
725set a debug flag across all storages
726
727=cut
728
729sub debug {
64cdad22 730 my $self = shift @_;
3fbe08e3 731 if(@_) {
732 foreach my $source ($self->all_storages) {
733 $source->debug(@_);
734 }
64cdad22 735 }
3fbe08e3 736 return $self->master->debug;
2bf79155 737}
738
2bf79155 739=head2 debugobj
740
741set a debug object across all storages
742
743=cut
744
745sub debugobj {
64cdad22 746 my $self = shift @_;
3fbe08e3 747 if(@_) {
748 foreach my $source ($self->all_storages) {
749 $source->debugobj(@_);
750 }
64cdad22 751 }
3fbe08e3 752 return $self->master->debugobj;
2bf79155 753}
754
2bf79155 755=head2 debugfh
756
757set a debugfh object across all storages
758
759=cut
760
761sub debugfh {
64cdad22 762 my $self = shift @_;
3fbe08e3 763 if(@_) {
764 foreach my $source ($self->all_storages) {
765 $source->debugfh(@_);
766 }
64cdad22 767 }
3fbe08e3 768 return $self->master->debugfh;
2bf79155 769}
770
2bf79155 771=head2 debugcb
772
773set a debug callback across all storages
774
775=cut
776
777sub debugcb {
64cdad22 778 my $self = shift @_;
3fbe08e3 779 if(@_) {
780 foreach my $source ($self->all_storages) {
781 $source->debugcb(@_);
782 }
64cdad22 783 }
3fbe08e3 784 return $self->master->debugcb;
2bf79155 785}
786
2bf79155 787=head2 disconnect
788
789disconnect everything
790
791=cut
792
793sub disconnect {
64cdad22 794 my $self = shift @_;
795 foreach my $source ($self->all_storages) {
796 $source->disconnect(@_);
797 }
2bf79155 798}
799
b2e4d522 800=head2 cursor_class
801
802set cursor class on all storages, or return master's
803
804=cut
805
806sub cursor_class {
807 my ($self, $cursor_class) = @_;
808
809 if ($cursor_class) {
810 $_->cursor_class($cursor_class) for $self->all_storages;
811 }
812 $self->master->cursor_class;
813}
d4daee7b 814
7e38d850 815=head1 GOTCHAS
816
817Due to the fact that replicants can lag behind a master, you must take care to
818make sure you use one of the methods to force read queries to a master should
819you need realtime data integrity. For example, if you insert a row, and then
820immediately re-read it from the database (say, by doing $row->discard_changes)
821or you insert a row and then immediately build a query that expects that row
822to be an item, you should force the master to handle reads. Otherwise, due to
823the lag, there is no certainty your data will be in the expected state.
824
825For data integrity, all transactions automatically use the master storage for
826all read and write queries. Using a transaction is the preferred and recommended
827method to force the master to handle all read queries.
828
829Otherwise, you can force a single query to use the master with the 'force_pool'
830attribute:
831
832 my $row = $resultset->search(undef, {force_pool=>'master'})->find($pk);
833
834This attribute will safely be ignore by non replicated storages, so you can use
835the same code for both types of systems.
836
837Lastly, you can use the L</execute_reliably> method, which works very much like
838a transaction.
839
840For debugging, you can turn replication on/off with the methods L</set_reliable_storage>
841and L</set_balanced_storage>, however this operates at a global level and is not
842suitable if you have a shared Schema object being used by multiple processes,
843such as on a web application server. You can get around this limitation by
844using the Schema clone method.
845
846 my $new_schema = $schema->clone;
847 $new_schema->set_reliable_storage;
d4daee7b 848
7e38d850 849 ## $new_schema will use only the Master storage for all reads/writes while
850 ## the $schema object will use replicated storage.
851
f5d3a5de 852=head1 AUTHOR
853
64cdad22 854 John Napiorkowski <john.napiorkowski@takkle.com>
f5d3a5de 855
c4d3fae2 856Based on code originated by:
f5d3a5de 857
64cdad22 858 Norbert Csongrádi <bert@cpan.org>
859 Peter Siklósi <einon@einon.hu>
2156bbdd 860
f5d3a5de 861=head1 LICENSE
862
863You may distribute this code under the same terms as Perl itself.
864
865=cut
866
c354902c 867__PACKAGE__->meta->make_immutable;
868
f5d3a5de 8691;