Apache-LoggedAuthDBI
view release on metacpan or search on metacpan
Currently only the $dbh do() method and the $sth execute(), execute_array(),
and execute_for_fetch() methods set the C<Executed> attribute.
When it's set on a handle it is also set on the parent handle at the
same time. So calling execute() on a $sth also sets the C<Executed>
attribute on the parent $dbh.
The C<Executed> attribute for a database handle is cleared by the
commit() and rollback() methods. The C<Executed> attribute of a
statement handle is not cleared by the DBI under any circumstances
and so acts as a permanent record of whether the statement handle
was ever used.
The C<Executed> attribute was added in DBI 1.41.
=item C<Kids> (integer, read-only)
For a driver handle, C<Kids> is the number of currently existing database
handles that were created from that driver handle. For a database
handle, C<Kids> is the number of currently existing statement handles that
were created from that database handle.
For a statement handle, the value is zero.
=item C<ActiveKids> (integer, read-only)
Like C<Kids>, but only counting those that are C<Active> (as above).
=item C<CachedKids> (hash ref)
For a database handle, C<CachedKids> returns a reference to the cache (hash) of
statement handles created by the L</prepare_cached> method. For a
driver handle, returns a reference to the cache (hash) of
database handles created by the L</connect_cached> method.
=item C<CompatMode> (boolean, inherited)
The C<CompatMode> attribute is used by emulation layers (such as
Oraperl) to enable compatible behaviour in the underlying driver
(e.g., DBD::Oracle) for this handle. Not normally set by application code.
It also has the effect of disabling the 'quick FETCH' of attribute
values from the handles attribute cache. So all attribute values
are handled by the drivers own FETCH method. This makes them slightly
slower but is useful for special-purpose drivers like DBD::Multiplex.
=item C<InactiveDestroy> (boolean)
The C<InactiveDestroy> attribute can be used to disable the I<database
engine> related effect of DESTROYing a handle (which would normally
close a prepared statement or disconnect from the database etc).
The default value, false, means a handle will be fully destroyed
when it passes out of scope.
For a database handle, this attribute does not disable an I<explicit>
call to the disconnect method, only the implicit call from DESTROY
that happens if the handle is still marked as C<Active>.
Think of the name as meaning 'treat the handle as not-Active in the
DESTROY method'.
This attribute is specifically designed for use in Unix applications
that "fork" child processes. Either the parent or the child process,
but not both, should set C<InactiveDestroy> on all their shared handles.
Note that some databases, including Oracle, don't support passing a
database connection across a fork.
To help tracing applications using fork the process id is shown in
the trace log whenever a DBI or handle trace() method is called.
The process id also shown for I<every> method call if the DBI trace
level (not handle trace level) is set high enough to show the trace
from the DBI's method dispatcher, e.g. >= 9.
=item C<PrintWarn> (boolean, inherited)
The C<PrintWarn> attribute controls the printing of warnings recorded
by the driver. When set to a true value the DBI will check method
calls to see if a warning condition has been set. If so, the DBI
will effectively do a C<warn("$class $method warning: $DBI::errstr")>
where C<$class> is the driver class and C<$method> is the name of
the method which failed. E.g.,
DBD::Oracle::db execute warning: ... warning text here ...
By default, C<DBI-E<gt>connect> sets C<PrintWarn> "on" if $^W is true,
i.e., perl is running with warnings enabled.
If desired, the warnings can be caught and processed using a C<$SIG{__WARN__}>
handler or modules like CGI::Carp and CGI::ErrorWrap.
See also L</set_err> for how warnings are recorded and L</HandleSetErr>
for how to influence it.
Fetching the full details of warnings can require an extra round-trip
to the database server for some drivers. In which case the driver
may opt to only fetch the full details of warnings if the C<PrintWarn>
attribute is true. If C<PrintWarn> is false then these drivers should
still indicate the fact that there were warnings by setting the
warning string to, for example: "3 warnings".
=item C<PrintError> (boolean, inherited)
The C<PrintError> attribute can be used to force errors to generate warnings (using
C<warn>) in addition to returning error codes in the normal way. When set
"on", any method which results in an error occuring will cause the DBI to
effectively do a C<warn("$class $method failed: $DBI::errstr")> where C<$class>
is the driver class and C<$method> is the name of the method which failed. E.g.,
DBD::Oracle::db prepare failed: ... error text here ...
By default, C<DBI-E<gt>connect> sets C<PrintError> "on".
If desired, the warnings can be caught and processed using a C<$SIG{__WARN__}>
handler or modules like CGI::Carp and CGI::ErrorWrap.
=item C<RaiseError> (boolean, inherited)
The C<RaiseError> attribute can be used to force errors to raise exceptions rather
than simply return error codes in the normal way. It is "off" by default.
When set "on", any method which results in an error will cause
the DBI to effectively do a C<die("$class $method failed: $DBI::errstr")>,
where C<$class> is the driver class and C<$method> is the name of the method
$sth->execute($name, $phone);
}
close FH;
$dbh->commit;
$dbh->disconnect;
Here's how to convert fetched NULLs (undefined values) into empty strings:
while($row = $sth->fetchrow_arrayref) {
# this is a fast and simple way to deal with nulls:
foreach (@$row) { $_ = '' unless defined }
print "@$row\n";
}
The C<q{...}> style quoting used in these examples avoids clashing with
quotes that may be used in the SQL statement. Use the double-quote like
C<qq{...}> operator if you want to interpolate variables into the string.
See L<perlop/"Quote and Quote-like Operators"> for more details.
=head2 Threads and Thread Safety
Perl 5.7 and later support a new threading model called iThreads.
(The old "5.005 style" threads are not supported by the DBI.)
In the iThreads model each thread has it's own copy of the perl
interpreter. When a new thread is created the original perl
interpreter is 'cloned' to create a new copy for the new thread.
If the DBI and drivers are loaded and handles created before the
thread is created then it will get a cloned copy of the DBI, the
drivers and the handles.
However, the internal pointer data within the handles will refer
to the DBI and drivers in the original interpreter. Using those
handles in the new interpreter thread is not safe, so the DBI detects
this and croaks on any method call using handles that don't belong
to the current thread (except for DESTROY).
Because of this (possibly temporary) restriction, newly created
threads must make their own connctions to the database. Handles
can't be shared across threads.
But BEWARE, some underlying database APIs (the code the DBD driver
uses to talk to the database, often supplied by the database vendor)
are not thread safe. If it's not thread safe, then allowing more
than one thread to enter the code at the same time may cause
subtle/serious problems. In some cases allowing more than
one thread to enter the code, even if I<not> at the same time,
can cause problems. You have been warned.
Using DBI with perl threads is not yet recommended for production
environments. For more information see
L<http://www.perlmonks.org/index.pl?node_id=288022>
Note: There is a bug in perl 5.8.2 when configured with threads
and debugging enabled (bug #24463) which causes a DBI test to fail.
=head2 Signal Handling and Canceling Operations
[The following only applies to systems with unix-like signal handling.
I'd welcome additions for other systems, especially Windows.]
The first thing to say is that signal handling in Perl versions less
than 5.8 is I<not> safe. There is always a small risk of Perl
crashing and/or core dumping when, or after, handling a signal
because the signal could arrive and be handled while internal data
structures are being changed. If the signal handling code
used those same internal data structures it could cause all manner
of subtle and not-so-subtle problems. The risk was reduced with
5.4.4 but was still present in all perls up through 5.8.0.
Beginning in perl 5.8.0 perl implements 'safe' signal handling if
your system has the POSIX sigaction() routine. Now when a signal
is delivered perl just makes a note of it but does I<not> run the
%SIG handler. The handling is 'defered' until a 'safe' moment.
Although this change made signal handling safe, it also lead to
a problem with signals being defered for longer than you'd like.
If a signal arrived while executing a system call, such as waiting
for data on a network connection, the signal is noted and then the
system call that was executing returns with an EINTR error code
to indicate that it was interrupted. All fine so far.
The problem comes when the code that made the system call sees the
EINTR code and decides it's going to call it again. Perl doesn't
do that, but database code sometimes does. If that happens then the
signal handler doesn't get called untill later. Maybe much later.
Fortunately there are ways around this which we'll discuss below.
Unfortunately they make signals unsafe again.
The two most common uses of signals in relation to the DBI are for
canceling operations when the user types Ctrl-C (interrupt), and for
implementing a timeout using C<alarm()> and C<$SIG{ALRM}>.
=over 4
=item Cancel
The DBI provides a C<cancel> method for statement handles. The
C<cancel> method should abort the current operation and is designed
to be called from a signal handler. For example:
$SIG{INT} = sub { $sth->cancel };
However, few drivers implement this (the DBI provides a default
method that just returns C<undef>) and, even if implemented, there
is still a possibility that the statement handle, and even the
parent database handle, will not be usable afterwards.
If C<cancel> returns true, then it has successfully
invoked the database engine's own cancel function. If it returns false,
then C<cancel> failed. If it returns C<undef>, then the database
driver does not have cancel implemented.
=item Timeout
The traditional way to implement a timeout is to set C<$SIG{ALRM}>
to refer to some code that will be executed when an ALRM signal
arrives and then to call alarm($seconds) to schedule an ALRM signal
servers are stingy about which environment variables are available.
=head2 DBI_DSN
The DBI_DSN environment variable is used by DBI->connect if you do not
specify a data source when you issue the connect.
It should have a format such as "dbi:Driver:databasename".
=head2 DBI_DRIVER
The DBI_DRIVER environment variable is used to fill in the database
driver name in DBI->connect if the data source string starts "dbi::"
(thereby omitting the driver).
If DBI_DSN omits the driver name, DBI_DRIVER can fill the gap.
=head2 DBI_AUTOPROXY
The DBI_AUTOPROXY environment variable takes a string value that starts
"dbi:Proxy:" and is typically followed by "hostname=...;port=...".
It is used to alter the behaviour of DBI->connect.
For full details, see DBI::Proxy documentation.
=head2 DBI_USER
The DBI_USER environment variable takes a string value that is used as
the user name if the DBI->connect call is given undef (as distinct from
an empty string) as the username argument.
Be wary of the security implications of using this.
=head2 DBI_PASS
The DBI_PASS environment variable takes a string value that is used as
the password if the DBI->connect call is given undef (as distinct from
an empty string) as the password argument.
Be extra wary of the security implications of using this.
=head2 DBI_DBNAME (obsolete)
The DBI_DBNAME environment variable takes a string value that is used only when the
obsolescent style of DBI->connect (with driver name as fourth parameter) is used, and
when no value is provided for the first (database name) argument.
=head2 DBI_TRACE
The DBI_TRACE environment variable specifies the global default
trace settings for the DBI at startup. Can also be used to direct
trace output to a file. When the DBI is loaded it does:
DBI->trace(split /=/, $ENV{DBI_TRACE}, 2) if $ENV{DBI_TRACE};
So if C<DBI_TRACE> contains an "C<=>" character then what follows
it is used as the name of the file to append the trace to.
output appended to that file. If the name begins with a number
followed by an equal sign (C<=>), then the number and the equal sign are
stripped off from the name, and the number is used to set the trace
level. For example:
DBI_TRACE=1=dbitrace.log perl your_test_script.pl
On Unix-like systems using a Bourne-like shell, you can do this easily
on the command line:
DBI_TRACE=2 perl your_test_script.pl
See L</TRACING> for more information.
=head2 PERL_DBI_DEBUG (obsolete)
An old variable that should no longer be used; equivalent to DBI_TRACE.
=head2 DBI_PROFILE
The DBI_PROFILE environment variable can be used to enable profiling
of DBI method calls. See <DBI::Profile> for more information.
=head2 DBI_PUREPERL
The DBI_PUREPERL environment variable can be used to enable the
use of DBI::PurePerl. See <DBI::PurePerl> for more information.
=head1 WARNING AND ERROR MESSAGES
=head2 Fatal Errors
=over 4
=item Can't call method "prepare" without a package or object reference
The C<$dbh> handle you're using to call C<prepare> is probably undefined because
the preceding C<connect> failed. You should always check the return status of
DBI methods, or use the L</RaiseError> attribute.
=item Can't call method "execute" without a package or object reference
The C<$sth> handle you're using to call C<execute> is probably undefined because
the preceeding C<prepare> failed. You should always check the return status of
DBI methods, or use the L</RaiseError> attribute.
=item DBI/DBD internal version mismatch
The DBD driver module was built with a different version of DBI than
the one currently being used. You should rebuild the DBD module under
the current version of DBI.
(Some rare platforms require "static linking". On those platforms, there
may be an old DBI or DBD driver version actually embedded in the Perl
executable being used.)
=item DBD driver has not implemented the AutoCommit attribute
The DBD driver implementation is incomplete. Consult the author.
=item Can't [sg]et %s->{%s}: unrecognised attribute
You attempted to set or get an unknown attribute of a handle. Make
sure you have spelled the attribute name correctly; case is significant
(e.g., "Autocommit" is not the same as "AutoCommit").
=back
( run in 2.445 seconds using v1.01-cache-2.11-cpan-98e64b0badf )