Author: timbo
Date: Wed Feb 2 03:03:26 2005
New Revision: 853
Modified:
dbi/trunk/Changes
dbi/trunk/DBI.pm
dbi/trunk/lib/DBI/DBD.pm
Log:
Updated connect_cached() docs with issues and suggestions.
Modified: dbi/trunk/Changes
==============================================================================
--- dbi/trunk/Changes (original)
+++ dbi/trunk/Changes Wed Feb 2 03:03:26 2005
@@ -4,14 +4,13 @@
=cut
-=head2 Changes in DBI 1.47 (svn rev XXX), XXth January 2005
+=head2 Changes in DBI 1.47 (svn rev XXX), 2nd February 2005
Fixed DBI::ProxyServer to not create pid files by default.
References: Ubuntu Security Notice USN-70-1, CAN-2005-0077
Thanks to Javier Fern�ndez-Sanguino Pe�a from the
Debian Security Audit Project, and Jonathan Leffler.
Fixed some tests to work with older Test::More versions.
- Fixed setting $DBI::lasth where DESTROY calls other methods.
Fixed setting $DBI::err/errstr in DBI::PurePerl.
Fixed potential undef warning from connect_cached().
Fixed $DBI::lasth handling for DESTROY so lasth points to
@@ -29,6 +28,7 @@
Added $GetInfoType{SQL_DATABASE_NAME} thanks to Steffen Goeldner.
Updated docs to recommend some common DSN string attributes.
+ Updated connect_cached() docs with issues and suggestions.
Updated docs for NULL Value placeholders thanks to Brian Campbell.
Updated docs for primary_key_info and primary_keys.
Updated docs to clarify that the default fetchrow_hashref behaviour,
Modified: dbi/trunk/DBI.pm
==============================================================================
--- dbi/trunk/DBI.pm (original)
+++ dbi/trunk/DBI.pm Wed Feb 2 03:03:26 2005
@@ -332,7 +332,9 @@
sub dump_dbd_registry {
require Data::Dumper;
- print Data::Dumper::Dump($dbd_prefix_registry);
+ local $Data::Dumper::Sortkeys=1;
+ local $Data::Dumper::Indent=1;
+ print Data::Dumper->Dump([$dbd_prefix_registry],
[qw($dbd_prefix_registry)]);
}
# --- Dynamically create the DBI Standard Interface
@@ -2622,9 +2624,38 @@
Caching connections can be useful in some applications, but it can
also cause problems, such as too many connections, and so should
-be used with care.
+be used with care. In particular, avoid changing the attributes of
+a database handle created via connect_cached() because it will affect
+other code that may be using the same handle.
+
+Where multiple separate parts of a program are using connect_cached()
+to connect to the same database with the same (initial) attributes
+it is a good idea to add a private attribute to the connect_cached()
+call to effectively limit the scope of the caching. For example:
+
+ DBI->connect_cached(..., { private_foo_cachekey => "Bar", ... });
+
+Handles returned from that connect_cached() call will only be returned
+by other connect_cached() call elsewhere in the code if those other
+calls also pass in the same attribute values, including the private one.
+(I've used C<private_foo_cachekey> here as an example, you can use
+any attribute name with a C<private_> prefix.)
+
+Taking that one step further, you can limit a particular connect_cached()
+call to return handles unique to that one place in the code by setting the
+private attribute to a unique value for that place:
+
+ DBI->connect_cached(..., { private_foo_cachekey => __FILE__.__LINE__, ... });
+
+By using a private attribute you still get connection caching for
+the individual calls to connect_cached() but, by making separate
+database conections for separate parts of the code, the database
+handles are isolated from any attribute changes made to other handles.
-The cache can be accessed (and cleared) via the L</CachedKids> attribute.
+The cache can be accessed (and cleared) via the L</CachedKids> attribute:
+
+ my $CachedKids_hashref = $dbh->{Driver}->{CachedKids};
+ %$CachedKids_hashref = () if $CachedKids_hashref;
=item C<available_drivers>
Modified: dbi/trunk/lib/DBI/DBD.pm
==============================================================================
--- dbi/trunk/lib/DBI/DBD.pm (original)
+++ dbi/trunk/lib/DBI/DBD.pm Wed Feb 2 03:03:26 2005
@@ -142,7 +142,9 @@
Typically, the name is based on the name of the database software it
uses, and the prefix is a contraction of that.
Hence, DBD::Oracle has the name Oracle and the prefix 'ora_'.
-This information will be recorded in the DBI documentation.
+This information will be recorded in the DBI module.
+Apart from documentation purposes, registration is a prerequisite for
+L<installing private methods|DBI/install_method>.
This document assumes you are writing a driver called DBD::Driver, and
that the prefix 'drv_' is assigned to the driver.
@@ -657,6 +659,8 @@
for failure (in which case you must look at $DBI::err and $DBI::errstr
for the failure information, because you have no driver handle to use).
+=head4 The CLONE special subroutine
+
Also needed here, in the DBD::Driver package, is a CLONE() method
that will be called by perl when an intrepreter is cloned. All your
CLONE method needs to do, currently, is clear the cached $drh so
@@ -667,6 +671,9 @@
undef $drh;
}
+See
L<http://search.cpan.org/dist/perl/pod/perlmod.pod#Making_your_module_threadsafe>
+for details.
+
=head3 The DBD::Driver::dr package
=head4 The database handle constructor
@@ -2672,7 +2679,7 @@
Note that we cannot do a
- $srh->SUPER::connect($dbname, $user, $auth, $attr);
+ $drh->SUPER::connect($dbname, $user, $auth, $attr);
as we would usually do in a an OO environment, because $drh is an instance
of I<DBI::dr>. And note, that the I<connect> method of I<DBD::File> is
