Apache-LoggedAuthDBI
view release on metacpan or search on metacpan
%EXPORT_TAGS = (
sql_types => [ qw(
SQL_GUID
SQL_WLONGVARCHAR
SQL_WVARCHAR
SQL_WCHAR
SQL_BIT
SQL_TINYINT
SQL_LONGVARBINARY
SQL_VARBINARY
SQL_BINARY
SQL_LONGVARCHAR
SQL_UNKNOWN_TYPE
SQL_ALL_TYPES
SQL_CHAR
SQL_NUMERIC
SQL_DECIMAL
SQL_INTEGER
SQL_SMALLINT
SQL_FLOAT
SQL_REAL
SQL_DOUBLE
SQL_DATETIME
SQL_DATE
SQL_INTERVAL
SQL_TIME
SQL_TIMESTAMP
SQL_VARCHAR
SQL_BOOLEAN
SQL_UDT
SQL_UDT_LOCATOR
SQL_ROW
SQL_REF
SQL_BLOB
SQL_BLOB_LOCATOR
SQL_CLOB
SQL_CLOB_LOCATOR
SQL_ARRAY
SQL_ARRAY_LOCATOR
SQL_MULTISET
SQL_MULTISET_LOCATOR
SQL_TYPE_DATE
SQL_TYPE_TIME
SQL_TYPE_TIMESTAMP
SQL_TYPE_TIME_WITH_TIMEZONE
SQL_TYPE_TIMESTAMP_WITH_TIMEZONE
SQL_INTERVAL_YEAR
SQL_INTERVAL_MONTH
SQL_INTERVAL_DAY
SQL_INTERVAL_HOUR
SQL_INTERVAL_MINUTE
SQL_INTERVAL_SECOND
SQL_INTERVAL_YEAR_TO_MONTH
SQL_INTERVAL_DAY_TO_HOUR
SQL_INTERVAL_DAY_TO_MINUTE
SQL_INTERVAL_DAY_TO_SECOND
SQL_INTERVAL_HOUR_TO_MINUTE
SQL_INTERVAL_HOUR_TO_SECOND
SQL_INTERVAL_MINUTE_TO_SECOND
) ],
sql_cursor_types => [ qw(
SQL_CURSOR_FORWARD_ONLY
SQL_CURSOR_KEYSET_DRIVEN
SQL_CURSOR_DYNAMIC
SQL_CURSOR_STATIC
SQL_CURSOR_TYPE_DEFAULT
) ], # for ODBC cursor types
utils => [ qw(
neat neat_list $neat_maxlen dump_results looks_like_number
data_string_diff data_string_desc data_diff
) ],
profile => [ qw(
dbi_profile dbi_profile_merge dbi_time
) ], # notionally "in" DBI::Profile and normally imported from there
);
$DBI::dbi_debug = 0;
$DBI::neat_maxlen = 400;
# If you get an error here like "Can't find loadable object ..."
# then you haven't installed the DBI correctly. Read the README
# then install it again.
if ( $ENV{DBI_PUREPERL} ) {
eval { bootstrap DBI } if $ENV{DBI_PUREPERL} == 1;
require DBI::PurePerl if $@ or $ENV{DBI_PUREPERL} >= 2;
$DBI::PurePerl ||= 0; # just to silence "only used once" warnings
}
else {
bootstrap DBI;
}
$EXPORT_TAGS{preparse_flags} = [ grep { /^DBIpp_\w\w_/ } keys %{__PACKAGE__."::"} ];
Exporter::export_ok_tags(keys %EXPORT_TAGS);
}
# Alias some handle methods to also be DBI class methods
for (qw(trace_msg set_err parse_trace_flag parse_trace_flags)) {
no strict;
*$_ = \&{"DBD::_::common::$_"};
}
use strict;
DBI->trace(split /=/, $ENV{DBI_TRACE}, 2) if $ENV{DBI_TRACE};
$DBI::connect_via = "connect";
# check if user wants a persistent database connection ( Apache + mod_perl )
if ($INC{'Apache/DBI.pm'} && $ENV{MOD_PERL}) {
$DBI::connect_via = "Apache::DBI::connect";
DBI->trace_msg("DBI connect via $DBI::connect_via in $INC{'Apache/DBI.pm'}\n");
}
%DBI::installed_drh = (); # maps driver names to installed driver handles
# Setup special DBI dynamic variables. See DBI::var::FETCH for details.
# These are dynamically associated with the last handle used.
tie $DBI::err, 'DBI::var', '*err'; # special case: referenced via IHA list
tie $DBI::state, 'DBI::var', '"state'; # special case: referenced via IHA list
tie $DBI::lasth, 'DBI::var', '!lasth'; # special case: return boolean
tie $DBI::errstr, 'DBI::var', '&errstr'; # call &errstr in last used pkg
tie $DBI::rows, 'DBI::var', '&rows'; # call &rows in last used pkg
sub DBI::var::TIESCALAR{ my $var = $_[1]; bless \$var, 'DBI::var'; }
sub DBI::var::STORE { Carp::croak("Can't modify \$DBI::${$_[0]} special variable") }
If C<$username> or C<$password> are undefined (rather than just empty),
then the DBI will substitute the values of the C<DBI_USER> and C<DBI_PASS>
environment variables, respectively. The DBI will warn if the
environment variables are not defined. However, the everyday use
of these environment variables is not recommended for security
reasons. The mechanism is primarily intended to simplify testing.
See below for alternative way to specify the username and password.
C<DBI-E<gt>connect> automatically installs the driver if it has not been
installed yet. Driver installation either returns a valid driver
handle, or it I<dies> with an error message that includes the string
"C<install_driver>" and the underlying problem. So C<DBI-E<gt>connect>
will die
on a driver installation failure and will only return C<undef> on a
connect failure, in which case C<$DBI::errstr> will hold the error message.
Use C<eval { ... }> if you need to catch the "C<install_driver>" error.
The C<$data_source> argument (with the "C<dbi:...:>" prefix removed) and the
C<$username> and C<$password> arguments are then passed to the driver for
processing. The DBI does not define any interpretation for the
contents of these fields. The driver is free to interpret the
C<$data_source>, C<$username>, and C<$password> fields in any way, and supply
whatever defaults are appropriate for the engine being accessed.
(Oracle, for example, uses the ORACLE_SID and TWO_TASK environment
variables if no C<$data_source> is specified.)
The C<AutoCommit> and C<PrintError> attributes for each connection
default to "on". (See L</AutoCommit> and L</PrintError> for more information.)
However, it is strongly recommended that you explicitly define C<AutoCommit>
rather than rely on the default. The C<PrintWarn> attribute defaults to
on if $^W is true, i.e., perl is running with warnings enabled.
The C<\%attr> parameter can be used to alter the default settings of
C<PrintError>, C<RaiseError>, C<AutoCommit>, and other attributes. For example:
$dbh = DBI->connect($data_source, $user, $pass, {
PrintError => 0,
AutoCommit => 0
});
The username and password can also be specified using the attributes
C<Username> and C<Password>, in which case they take precedence
over the C<$username> and C<$password> parameters.
You can also define connection attribute values within the C<$data_source>
parameter. For example:
dbi:DriverName(PrintWarn=>1,PrintError=>0,Taint=>1):...
Individual attributes values specified in this way take precedence over
any conflicting values specified via the C<\%attr> parameter to C<connect>.
The C<dbi_connect_method> attribute can be used to specify which driver
method should be called to establish the connection. The only useful
values are 'connect', 'connect_cached', or some specialized case like
'Apache::DBI::connect' (which is automatically the default when running
within Apache).
Where possible, each session (C<$dbh>) is independent from the transactions
in other sessions. This is useful when you need to hold cursors open
across transactions--for example, if you use one session for your long lifespan
cursors (typically read-only) and another for your short update
transactions.
For compatibility with old DBI scripts, the driver can be specified by
passing its name as the fourth argument to C<connect> (instead of C<\%attr>):
$dbh = DBI->connect($data_source, $user, $pass, $driver);
In this "old-style" form of C<connect>, the C<$data_source> should not start
with "C<dbi:driver_name:>". (If it does, the embedded driver_name
will be ignored). Also note that in this older form of C<connect>,
the C<$dbh-E<gt>{AutoCommit}> attribute is I<undefined>, the
C<$dbh-E<gt>{PrintError}> attribute is off, and the old C<DBI_DBNAME>
environment variable is
checked if C<DBI_DSN> is not defined. Beware that this "old-style"
C<connect> will soon be withdrawn in a future version of DBI.
=item C<connect_cached>
$dbh = DBI->connect_cached($data_source, $username, $password)
or die $DBI::errstr;
$dbh = DBI->connect_cached($data_source, $username, $password, \%attr)
or die $DBI::errstr;
C<connect_cached> is like L</connect>, except that the database handle
returned is also
stored in a hash associated with the given parameters. If another call
is made to C<connect_cached> with the same parameter values, then the
corresponding cached C<$dbh> will be returned if it is still valid.
The cached database handle is replaced with a new connection if it
has been disconnected or if the C<ping> method fails.
Note that the behaviour of this method differs in several respects from the
behaviour of persistent connections implemented by Apache::DBI.
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. 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
$sth = $dbh->prepare("select Id, Name from table");
$sth->execute;
@row = $sth->fetchrow_array;
print "Name $row[ $sth->{NAME_lc_hash}{name} ]\n";
=item C<TYPE> (array-ref, read-only)
Returns a reference to an array of integer values for each
column. The value indicates the data type of the corresponding column.
The values correspond to the international standards (ANSI X3.135
and ISO/IEC 9075) which, in general terms, means ODBC. Driver-specific
types that don't exactly match standard types should generally return
the same values as an ODBC driver supplied by the makers of the
database. That might include private type numbers in ranges the vendor
has officially registered with the ISO working group:
ftp://sqlstandards.org/SC32/SQL_Registry/
Where there's no vendor-supplied ODBC driver to be compatible with,
the DBI driver can use type numbers in the range that is now
officially reserved for use by the DBI: -9999 to -9000.
All possible values for C<TYPE> should have at least one entry in the
output of the C<type_info_all> method (see L</type_info_all>).
=item C<PRECISION> (array-ref, read-only)
Returns a reference to an array of integer values for each column.
For numeric columns, the value is the maximum number of digits
(without considering a sign character or decimal point). Note that
the "display size" for floating point types (REAL, FLOAT, DOUBLE)
can be up to 7 characters greater than the precision (for the
sign + decimal point + the letter E + a sign + 2 or 3 digits).
For any character type column the value is the OCTET_LENGTH,
in other words the number of bytes, not characters.
(More recent standards refer to this as COLUMN_SIZE but we stick
with PRECISION for backwards compatibility.)
=item C<SCALE> (array-ref, read-only)
Returns a reference to an array of integer values for each column.
NULL (C<undef>) values indicate columns where scale is not applicable.
=item C<NULLABLE> (array-ref, read-only)
Returns a reference to an array indicating the possibility of each
column returning a null. Possible values are C<0>
(or an empty string) = no, C<1> = yes, C<2> = unknown.
print "First column may return NULL\n" if $sth->{NULLABLE}->[0];
=item C<CursorName> (string, read-only)
Returns the name of the cursor associated with the statement handle, if
available. If not available or if the database driver does not support the
C<"where current of ..."> SQL syntax, then it returns C<undef>.
=item C<Database> (dbh, read-only)
Returns the parent $dbh of the statement handle.
=item C<ParamValues> (hash ref, read-only)
Returns a reference to a hash containing the values currently bound
to placeholders. The keys of the hash are the 'names' of the
placeholders, typically integers starting at 1. Returns undef if
not supported by the driver.
See L</ShowErrorStatement> for an example of how this is used.
If the driver supports C<ParamValues> but no values have been bound
yet then the driver should return a hash with placeholders names
in the keys but all the values undef, but some drivers may return
a ref to an empty hash.
It is possible that the values in the hash returned by C<ParamValues>
are not I<exactly> the same as those passed to bind_param() or execute().
The driver may have slightly modified values in some way based on the
TYPE the value was bound with. For example a floating point value
bound as an SQL_INTEGER type may be returned as an integer.
The values returned by C<ParamValues> can be passed to another
bind_param() method with the same TYPE and will be seen by the
database as the same value.
It is also possible that the keys in the hash returned by C<ParamValues>
are not exactly the same as those implied by the prepared statement.
For example, DBD::Oracle translates 'C<?>' placeholders into 'C<:pN>'
where N is a sequence number starting at 1.
The C<ParamValues> attribute was added in DBI 1.28.
=item C<Statement> (string, read-only)
Returns the statement string passed to the L</prepare> method.
=item C<RowsInCache> (integer, read-only)
If the driver supports a local row cache for C<SELECT> statements, then
this attribute holds the number of un-fetched rows in the cache. If the
driver doesn't, then it returns C<undef>. Note that some drivers pre-fetch
rows on execute, whereas others wait till the first fetch.
See also the L</RowCacheSize> database handle attribute.
=back
=head1 OTHER METHODS
=over 4
( run in 3.023 seconds using v1.01-cache-2.11-cpan-cdf2f3d4e48 )