DBI Methods

The following methods are available under DBI.

@drivers = DBI->available_drivers([nowarn]) 

Returns a list of available drivers by searching @INC for the presence of DBD::* modules.

• nowarn
• A Boolean value specifying whether to suppress warnings if some drivers are hidden by others of the same name in earlier directories. Default is false (don't suppress).

$result = $st_handle->bind_col(col, variable [, \%attr ]) 

Binds a field of a select statement to a variable, to be updated whenever the row is fetched.

• col
• The column number to bind
• \variable
• A reference to the variable to bind
• %attr
• Attributes to set for the statement handle

$result = $st_handle->bind_columns(\%attr, @reflist ) 

Runs bind_col on each column of the statement.

• %attr
• Attributes to set for the statement handle
• @reflist
• A list of references to the variables to bind

$result = $st_handle->bind_param(n, value [, type ]) 

Binds a value with a placeholder in a prepared statement.

• n
• The parameter number to bind.
• value
• The value to associate with parameter n.
• type
• The data type for the placeholder. The type can also be specified as an anonymous list ({TYPE => type}).

$result = $db_handle->commit 

Commits the most recent changes. See also the AutoCommit attribute.

$db_handle = DBI->connect(data_source, user, passwd,[\%attr]) 

Connects to the specified database, returning a database handle object. The connect method automatically installs the driver if it has not already been installed.

• data_source
• A string identifying the driver to connect to, and any other additional driver-specific information needed to identify the driver (e.g., a port number). The driver name is written in the form dbi:driver_name, e.g., dbi:mysql. (Default value is taken from the DBI_DSN environment variable.) For example, a connection string for the MySQL driver always starts with dbi:mysql:. The second colon should be followed by any information required by the driver to make the database connection. In the case of MySQL, you must supply a database name (tutorialdb in the following example), a hostname (localhost), and the port number of the database server ():

  DBI:$driver:database=$database;host=$hostname;port= $port
  

• user
• The username for the database connection. (Default value is taken from the DBI_USER environment variable.)
• passwd
• The password for the database connection. (Default value is taken from the DBI_PASS environment variable. Set this value at your own risk.)
• %attr
• A hash reference defining attributes for the database handle.

@drivers = DBI->data_sources(driver) 

Returns a list of all databases available for the named driver. (The database server must be running for data_sources to return any results.)

• driver
• The driver to list. If unspecified, the value of DBI_DRIVER is used.

$result = $db_handle->disconnect 

Disconnects the database.

$rows = $db_handle->do(statement [, \%attr, @bind_values ]) 

Prepares and executes a statement, returning the number of rows affected.

• statement
• The statement to execute
• %attr
• Attributes to set for the new statement
• @bind_values
• Bind values for placeholder substitution

$rows = DBI::dump_results(st_handle,maxlen,ldelim,fdelim,fileh) 

Runs DBI::neat( ) on all the rows of a statement handle and prints them for testing purposes.

• st_handle
• The statement handle to retrieve.
• maxlen
• The length at which to truncate with "...". Default is .
• ldelim
• The delimiter between rows. Default is n.
• fdelim
• The delimiter between individual fields. Default is .
• fileh
• The filehandle to print to. Default is STDOUT.

$handle->err 

Returns the error code from the last driver function called.

$handle->errstr 

Returns the error message from the last driver function called.

$result = $st_handle->execute([@bind_values]) 

Executes a prepared statement.

• @bind_values
• Binds values for placeholder substitution

$arrayref = $st_handle->fetch 

Fetches the next row of data, returning an array reference with the field values.

$arrayref = $st_handle->fetchall_arrayref 

Fetches all data from a prepared statement and returns a reference to an array of references.

$array = $st_handle->fetchrow_array 

Fetches the next row of data, returning an array with the field values.

$arrayref = $st_handle->fetchrow_arrayref 

Fetches the next row of data, returning an array reference with the field values. Synonym for fetch.

$hashref = $st_handle->fetchrow_hashref 

Fetches the next row of data, returning a hash reference containing the field values. The keys of the hash are the same as $st_handle->{NAME}.

$result = $st_handle->finish 

Disables further fetching from a statement.

$handle->func(@arguments, function) 

Calls a private nonportable method on the specific handle.

• @arguments
• The arguments to the function.
• function
• The function name. Note that the function name is specified last.

$newstring = DBI::neat(string, maxlength) 

Converts a string to one with quoted strings, null values shown as undef, and unprintable characters shown as ".".

• string
• The string to convert
• maxlength
• The length at which to truncate the string with "..."

$newstring = DBI::neat_list(\@list, maxlength, delim) 

Converts each element of a list with DBI::neat and returns it as a string.

• @list
• A reference to the list to convert.
• maxlength
• The length at which to truncate the string with "...".
• delim
• The delimiter to use between list elements in the new string. Default is .

$result = $db_handle->ping 

Determines if the database is still connected.

$st_handle = $db_handle->prepare(statement [, \%attr ]) 

Prepares a statement for execution and returns a reference to a statement handle object.

• statement
• The statement to prepare
• %attr
• Attributes to set for the assigned statement handle

$sql = $db_handle->quote(string) 

Escapes special characters in a string for use in a SQL statement.

• string
• The string to convert

$result = $db_handle->rollback 

Undoes the most recent database changes if not yet committed.

$rows = $st_handle->rows 

Returns the number of rows affected by the last change to the database.

$handle->state 

Returns an error code in a five-character format.

DBI->trace(n, filename) 

Traces the execution of DBI.

• n
• An integer indicating the level of trace/debugging information, as follows:
  • Disable the trace.
  • Trace the execution of the DBI.
  • Output detailed call trace information including parameters and return values.
• filename
• The file to append trace information to

$handle->trace(n, filename) 

Same as the class method DBI->trace, but for a specific database, statement, or driver handle.