DBD::Multiplex(3) User Contributed Perl Documentation DBD::Multiplex(3)NAMEDBD::Multiplex - A multiplexing driver for the DBI.
SYNOPSIS
use strict;
use DBI;
my ($dsn1, $dsn2, $dsn3, $dsn4, %attr);
# Define four databases, in this case, four Postgres databases.
$dsn1 = 'dbi:Pg:dbname=aaa;host=10.0.0.1;mx_id=dbaaa1';
$dsn2 = 'dbi:Pg:dbname=bbb;host=10.0.0.2;mx_id=dbbbb2';
$dsn3 = 'dbi:Pg:dbname=ccc;host=10.0.0.3;mx_id=dbccc3';
$dsn4 = 'dbi:Pg:dbname=ddd;host=10.0.0.4;mx_id=dbddd4';
# Define a callback error handler.
sub MyErrorProcedure {
my ($mx_id, $error_number, $error_string) = @_;
my ($filepath, $extension) = ('/tmp/', '.txt');
open (TFH, ">>$filepath$mx_id$extension");
print (TFH "$error_number\t$error_string\n");
close (TFH);
return 1;
}
# Define the pool of datasources.
%attr = (
'mx_dsns' => [$dsn1, $dsn2, $dsn3, $dsn4],
'mx_master_id' => 'dbaaa1',
'mx_connect_mode' => 'ignore_errors',
'mx_exit_mode' => 'first_success',
'mx_error_proc' => \&MyErrorProcedure,
);
# Connect to all four datasources.
$dbh = DBI->connect("dbi:Multiplex:", 'username', 'password', \%attr);
# See the DBI module documentation for full details.
DESCRIPTIONDBD::Multiplex is a Perl module which works with the DBI allowing you
to work with multiple datasources using a single DBI handle.
Basically, DBD::Multiplex database and statement handles are parents
that contain multiple child handles, one for each datasource. Method
calls on the parent handle trigger corresponding method calls on each
of the children.
One use of this module is to mirror the contents of one datasource
using a set of alternate datasources. For that scenario it can write
to all datasources, but read from only from one datasource.
Alternatively, where a database already supports replication, DBD::Mul‐
tiplex can be used to direct writes to the master and spread the
selects across multiple slaves.
COMPATIBILITY
A goal of this module is to be compatible with DBD::Proxy / DBI::Proxy‐
Server. Currently, the 'mx_error_proc' feature generates errors
regarding the storage of CODE references within the Storable module
used by RPC::PlClient which in turn is used by DBD::Proxy. Yet it
works.
CONNECTING TO THE DATASOURCES
Multiple datasources are specified in the either the DSN parameter of
the DBI->connect() function (separated by the '⎪' character), and/or in
the 'mx_dsns' key/value pair (as an array reference) of the \%attr
parameter.
SPECIFIC ATTRIBUTES
Multiplex attributes are specified in the either the DSN parameter of
the DBI->connect() function (separated from the DSNs by the '#' charac‐
ter), and/or in the the \%attr parameter. Attributes in the \%attr
parameter will overwrite attributes from the DSN parameter.
The following specific attributes can be set when connecting:
mx_dsns
An array reference of DSN strings.
mx_master_id
Specifies which mx_id will be used as the master server for a mas‐
ter/slave one-way replication scheme.
mx_connect_mode
Options available or under consideration:
report_errors
A failed connection to any of the data sources will generate a DBI
error. This is the default.
ignore_errors
Failed connections are ignored, forgotten, and therefore, unused.
mx_exit_mode
Options available or under consideration:
first_error
Execute the requested method against each child handle, stopping
after the first error, and returning the all of the results. This
is the default.
first_success
Execute the requested method against each child handle, stopping
after the first successful result, and returning only the success‐
ful result. Most appropriate when reading from a set of mirrored
datasources.
first_success_random
Randomly reorders the list of DSNs, and then connects to them in
that order. Then switches to first_success mode. You can redefine
mx_exit_mode after connecting.
$dbh->{'mx_exit_mode'} = 'last_result';
last_result
Execute the requested method against each child handle, not stop‐
ping after any errors, and returning all of the results.
last_result_most_common
Execute the requested method against each child handle, not stop‐
ping after the errors, and returning the most common result (eg
three-way-voting etc). Not yet implemented.
mx_error_proc
A reference to a subroutine which will be executed whenever a DBI
method generates an error when working with a specific datasource.
It will be passed the DSN and 'mx_id' of the datasource, and the
$DBI::err and $DBI::errstr.
Define your own subrouine and pass a reference to it, or pass a
reference to the default error_proc:
\&DBD::Multiplex::mx_error_subroutine
Remember that references to subroutines do not include the paren‐
theses.
In some cases, the exit mode will depend on the method being called.
For example, this module will always execute $dbh->disconnect() calls
against each child handle.
In others, the default will be used, unless the user of the DBI speci‐
fied the 'mx_exit_mode' when connecting, or later changed the
'mx_exit_mode' attribute of a database or statement handle.
USAGE EXAMPLE
Here's an example of using DBD::Multiplex with MySQL's replication
scheme.
MySQL supports one-way replication, which means we run a server as the
master server and others as slaves which catch up any changes made on
the master. Any READ operations then may be distributed among them
(master and slave(s)), whereas any WRITE operation must only be
directed toward the master. Any changes happened on slave(s) will
never get synchronized to other servers. More detailed instructions on
how to arrange such setup can be found at:
http://dev.mysql.com/doc/mysql/en/Replication.html
Now say we have two servers, one at 10.0.0.1 as a master, and one at
10.0.0.9 as a slave. The DSN for each server may be written like this:
my (@dsns) = qw{
dbi:mysql:database=test;host=10.0.0.1;mx_id=masterdb
dbi:mysql:database=test;host=10.0.0.9;mx_id=slavedb
};
Here we choose easy-to-remember "mx_id"s: masterdb and slavedb. You
are free to choose alternative names, for example: mst and slv. Then
we create the DSN for DBD::Multiplex by joining them, using the pipe
character as separator:
my ($dsn) = 'dbi:Multiplex:' . join('⎪', @dsns);
my ($user) = 'username';
my ($pass) = 'password';
As a more paranoid practice, configure the 'user's permissions to allow
only SELECTs on the slaves.
Next, we define the attributes which will affect DBD::Multiplex behav‐
iour:
my (%attr) = (
'mx_exit_mode' => 'first_success_random',
'mx_master_id' => 'masterdb',
);
These attributes are required for MySQL replication support:
We set "mx_exit_mode" to 'first_success_random' which will make
DBD::Multiplex shuffle the DSN list order prior to connect, and after‐
wards revert to 'first_success'.
The "mx_master_id" attribute specifies which "mx_id" will be recognized
as the master. In our example, this is set to 'masterdb'. This
attribute will ensure that every WRITE operation will be executed only
on the master server. Finally, we call DBI->connect():
$dbh = DBI->connect($dsn, $user, $pass, \%attr) or die $DBI::errstr;
AUTHORS AND COPYRIGHT
Copyright (c) 1999,2008, Tim Bunce & Thomas Kishel
While I defer to Tim Bunce regarding the majority of this module, feel
free to contact me for more information:
Thomas Kishel
tkishel + perl @ gmail . com
(remove spaces)
You may distribute under the terms of either the GNU General Public
License or the Artistic License, as specified in the Perl README file.
3rd Berkeley Distribution perl v5.6.1 DBD::Multiplex(3)
