Debian Codegraph @

README

raw
1 DBIx::Connector
2
3 DBIx::Connector provides a simple interface for fast and safe DBI
4 connection and transaction management. Connecting to a database can be
5 expensive; you don't want your application to re-connect every time you
6 need to run a query. The efficient thing to do is to hang on to a
7 database handle to maintain a connection to the database in order to
8 minimize that overhead. DBIx::Connector lets you do that without having
9 to worry about dropped or corrupted connections.
10
11 You might be familiar with Apache::DBI and with the DBI's
12 "connect_cached()" constructor. DBIx::Connector serves a similar need,
13 but does a much better job. How is it different? I'm glad you asked!
14
15 * Fork Safety
16
17 Like Apache::DBI, but unlike "connect_cached()", DBIx::Connector
18 create a new database connection if a new process has been "fork"ed.
19 This happens all the time under mod_perl, in POE applications, and
20 elsewhere. Works best with DBI 1.614 and higher.
21
22 * Thread Safety
23
24 Unlike Apache::DBI or "connect_cached()", DBIx::Connector will
25 create a new database connection if a new thread has been spawned.
26 As with "fork"ing, spawning a new thread can break database
27 connections.
28
29 * Works Anywhere
30
31 Unlike Apache::DBI, DBIx::Connector runs anywhere -- inside of
32 mod_perl or not. Why limit yourself?
33
34 * Explicit Interface
35
36 DBIx::Connector has an explicit interface. There is none of the
37 magical action-at-a-distance crap that Apache::DBI is guilty of, and
38 no global caching. I've personally diagnosed a few issues with
39 Apache::DBI's magic, and killed it off in two different projects in
40 favor of "connect_cached()", only to be tripped up by other gotchas.
41 No more.
42
43 * Optimistic Execution
44
45 If you use "run()" and "txn()", the database handle will be passed
46 without first pinging the server. For the 99% or more of the time
47 when the database is just there, you'll save a ton of overhead
48 without the ping.
49
50 DBIx::Connector's other feature is transaction management. Borrowing an
51 interface from DBIx::Class, DBIx::Connector offers an API that
52 efficiently handles the scoping of database transactions so that you
53 needn't worry about managing the transaction yourself. Even better, it
54 offers an API for savepoints if your database supports them. Within a
55 transaction, you can scope savepoints to behave like subtransactions, so
56 that you can save some of your work in a transaction even if part of it
57 fails. See "txn()" and "svp()" for the goods.
58
59 INSTALLATION
60
61 This is a Perl module distribution. It should be installed with
62 whichever tool you use to manage your installation of Perl, e.g. any of
63
64 cpanm .
65 cpan .
66 cpanp -i .
67
68 Consult http://www.cpan.org/modules/INSTALL.html for further
69 instruction. Should you wish to install this module manually, the
70 procedure is
71
72 perl Makefile.PL
73 make
74 make test
75 make install
76
77 COPYRIGHT AND LICENSE
78
79 Copyright (c) 2009-2013 David E. Wheeler. Some Rights Reserved.
80
81 This module is free software; you can redistribute it and/or modify it
82 under the same terms as Perl itself.