1DBD::Multi(3) User Contributed Perl Documentation DBD::Multi(3)
2
6 DBD::Multi - Manage Multiple Data Sources with Failover and Load
7 Balancing
8
10 use DBI;
11 my $other_dbh = DBI->connect(...);
13 my $dbh = DBI->connect( 'dbi:Multi:', undef, undef, {
15 dsns => [ # in priority order
16 10 => [ 'dbi:SQLite:read_one.db', '', '' ],
17 10 => [ 'dbi:SQLite:read_two.db', '', '' ],
18 20 => [ 'dbi:SQLite:master.db', '', '' ],
19 30 => $other_dbh,
20 40 => sub { DBI->connect },
21 ],
22 # optional
23 failed_max => 1, # short credibility
24 failed_expire => 60*60, # long memory
25 timeout => 10, # time out connection attempts after 10 seconds.
26 });
27
29 This software manages multiple database connections for failovers and
30 also simple load balancing. It acts as a proxy between your code and
31 your database connections, transparently choosing a connection for each
32 query, based on your preferences and present availability of the DB
33 server.
34 This module is intended for read-only operations (where some other
36 application is being used to handle replication).
37 This software does not prevent write operations from being executed.
39 This is left up to the user. See "SUGGESTED USES" below for ideas.
40 The interface is nearly the same as other DBI drivers with one notable
42 exception.
43 Configuring DSNs
45 Specify an attribute to the "connect()" constructor, "dsns". This is a
46 list of DSNs to configure. The configuration is given in pairs. First
47 comes the priority of the DSN. Second is the DSN.
48 The priorities specify which connections should be used first (lowest
50 to highest). As long as the lowest priority connection is responding,
51 the higher priority connections will never be used. If multiple
52 connections have the same priority, then one connection will be chosen
53 randomly for each operation. Note that the random DB is chosen when
54 the statement is prepared. Therefore executing multiple queries on
55 the same prepared statement handle will always run on the same
56 connection.
57 The second parameter can a DBI object, a code ref which returns a DBI
59 object, or a list of parameters to pass to the DBI "connect()"
60 instructor. If a set of parameters or a code ref is given, then
61 DBD::Multi will be able to attempt re-connect in the event that the
62 connection is lost. If a DBI object is used, the DBD::Multi will give
63 up permanently once that connection is lost.
64 These connections are lazy loaded, meaning they aren't made until they
66 are actually used.
67 Configuring Failures
69 By default, after a data source fails three times, it will not be tried
70 again for 5 minutes. After that period, the data source will be tried
71 again for future requests until it reaches its three failure limit (the
72 cycle repeats forever).
73 To change the maximum number of failures allowed before a data source
75 is deemed failed, set the "failed_max" parameter. To change the amount
76 of time we remember a data source as being failed, set the
77 "failed_expire" parameter in seconds.
78 Timing out connections.
80 By default, if you attempt to connect to an IP that isn't answering,
81 DBI will hang for a very long period of time. This behavior is not
82 desirable in a multi database setup. Instead, it is better to give up
83 on slow connections and move on to other databases quickly.
84 DBD::Multi will give up on connection attempts after 5 seconds and then
86 try another connection. You may set the "timeout" parameter to change
87 the timeout time, or set it to 0 to disable the timeout feature
88 completely.
89
91 Here are some ideas on how to use this module effectively and safely.
92 It is important to remember that "DBD::Multi" is not intended for read-
94 write operations. One suggestion to prevent accidental write
95 operations is to make sure that the user you are connecting to the
96 databases with has privileges sufficiently restricted to prevent
97 updates.
98 Read-write operations should happen through a separate database handle
100 that will somehow trigger replication to all of your databases. For
101 example, your read-write handle might be connected to the master server
102 that replicates itself to all of the subordinate servers.
103 Read-only database calls within your application would be updated to
105 explicitly use the read-only (DBD::Multi) handle. It is not necessary
106 to find every single call that can be load balanced, since they can
107 safely be sent through the read/write handle as well.
108
110 There really isn't much of a TODO list for this module at this time.
111 Feel free to submit a bug report to rt.cpan.org if you think there is a
112 feature missing.
113 Although there is some code intended for read/write operations, this
115 should be considered not supported and not actively developed at this
116 time. The actual read/write code remains un-documented because in the
117 event that I ever do decide to work on supporting read/write
118 operations, the API is not guaranteed to stay the same. The focus of
119 this module is presently limited to read-only operations.
120
122 DBD::Multi has it's own suite of regression tests. But, suppose you
123 want to verify that you can slip DBD::Multi into whatever application
124 you already have written without breaking anything.
125 Thanks to a feature of DBI, you can regression test DBD::Multi using
127 any existing tests that already use DBI without having to update any of
128 your code. Simply set the environment variable DBI_AUTOPROXY to
129 'dbi:Multi:' and then run your tests. DBD::Multi should act as a
130 silent pipe between your application and whatever database driver you
131 were previously using. This will help you verify that you aren't
132 currently using some feature of the DBI that breaks DBD::Multi (If you
133 are, please do me a favor and submit a bug report so I can fix it).
134
136 CGI::Application::Plugin::DBH - A plugin for the CGI::Application
137 framework which makes it easy to support two database handles, and also
138 supports lazy-loading.
139 DBD::Multiplex, DBIx::HA - Two modules similar to DBD::Multi, but with
141 slightly different objectives.
142 DBI, perl - You should probably already know about these before using
144 this module.
145
147 Initially written by Casey West and Dan Wright for pair Networks, Inc.
148 (www.pair.com)
149 Maintained by Dan Wright. <DWRIGHT@CPAN.ORG>.
151perl v5.12.0 2008-03-03 DBD::Multi(3)