DBI Attributes Common to All Handles

These attributes provide information and can apply to all handles. The most common are those used for error handling, RaiseError and PrintError. For example, $h->{'RaiseError'} causes errors to that handle to raise exceptions.

Active

Active (boolean, read-only)

True if the handle object is active (connected to a database for a database handle or with more data to fetch for a statement handle).

ActiveKids (integer, read-only)

ActiveKids (integer, read-only)

The number of current active database handles (for a driver handle) or the number of current active statement handles for a database handle. Active means connected to a database for a database handle or with more data to fetch for a statement handle.

CachedKids (hash ref)

CachedKids (hash ref)

For a database handle this contains a reference to a hash of statement handles created by the prepare_cached() method. For a driver handle, it contains a hash of database handles created by connect_cached().

ChopBlanks

ChopBlanks (boolean, inherited)

Specifies whether the various fetch methods will chop leading and trailing blanks from CHAR fields. Set to true if they will and false (the default) if not.

CompatMode (boolean, inherited)

CompatMode (boolean, inherited)

Emulation layers ensure compatible behavior in the driver.

FetchHashKeyName

FetchHashKeyName (string, inherited)

Specifies which attribute name the fetchrow_hashref() method uses to get the fieldnames for the hash keys. It defaults to NAME, but you should instead set it to NAME_lc or NAME_uc for portability.

HandleError

HandleError (code ref, inherited)

Allows you to create your own way to handle errors. You can set it to a reference to a subroutine, which will be called when an error is detected (when RaiseError and PrintError would be called). If the subroutine returns false, then RaiseError and PrintError are checked, as normal. The subroutine is called with three parameters, the error message string (the same as RaiseError and PrintError would use), the DBI handle, and the first value returned by the failed method.

InactiveDestroy

InactiveDestroy (boolean)

Designed for Unix applications that fork child processes. False (the default) indicates that a handle is destroyed automatically when it passes out of scope. True indicates that the handle is not automatically destroyed.

Kids

Kids (integer, read-only)

Contains the number of current database handles (for a driver handle) or the number of current statement handles for a database handle.

LongReadLen

LongReadLen (unsigned integer, inherited) 

Controls the maximum length of long fields (BLOB and TEXT). It should be set to slightly more than the longest field. Setting it to 0 means long data will not automatically be fetched (in other words, fetch() will return undef—rather than the field's actual value—when processing long fields). Setting it too much larger is a waste of memory.

LongTruncOK

LongTruncOk (boolean, inherited)

False (the default) indicates that attempting to fetch long values longer than LongReadLen will cause the fetch to fail. True will return a truncated value.

PrintError

PrintError (boolean, inherited)

When set to true (the default), errors in a method generate a warning. Usually set to false when RaiseError is set to true.

private_*

private_*

You can store extra information of your own as a private attribute in a DBI handle by specifying a name beginning with private_. You should name it in the manner private_your_ module_name_description, and use just one attribute.

Because of the way the Perl tie mechanism works, you cannot reliably use the ||= operator directly to initialize the attribute.

To initialize, use a two-step approach like this:

my $descriptive_name = $dbh->{private_your_module_name_descriptive_name}; $descriptive_name ||= $dbh->{–  private_your_module_name_descriptive_name } = { ... };

You cannot use the following as you may expect:

my $descriptive_name = $dbh->{–  private_your_module_name_descriptive_name } ||= { ... };

Profile

Profile (inherited)

Allows method call timing statistics to be reported. See the DBI::Profile documentation for more details.

RaiseError

RaiseError (boolean, inherited) 

False by default; when set to true this will cause errors to raise exceptions rather than just returning error codes. Usually PrintError is set to false when RaiseError is true.

ShowErrorStatement

ShowErrorStatement (boolean, inherited)

When true, appends the statement text to the error messages from RaiseError and PrintError. It applies to statement handle errors and prepare(), do(), and select database handle methods.

Taint

Taint (boolean, inherited)

If set to true, and Perl is running in taint mode (–T), all data from the database is treated as being tainted as are arguments to most DBI methods. It defaults to false. More data may be treated as tainted at a later stage, so use Taint carefully!

TraceLevel

TraceLevel (integer, inherited)

Setting this is an alternative to using the trace() method to set the DBI trace level. The trace level can be from 0 to 9, with 0 disabling tracing, 1 best for a general overview, 2 being the most commonly used, and the other methods adding more and more driver and DBI detail.

Warn

Warn (boolean, inherited)

True by default, enables warnings. You can use $SIG{__WARN__} to catch warnings.