NAME

DBE - Database (Express) Engine for Perl

SYNOPSIS

  use DBE;
  
  $con = DBE->connect( %arg );
  $con = DBE->connect( $dsn );
  
  $res = $con->query( $sql );
  $res = $con->query( $sql, @bind_values );
  
  $rv = $con->do( $sql );
  $rv = $con->do( $sql, @bind_values );
  
  $con->prepare( $sql );
  $res = $con->execute( ... );
  
  $stmt = $con->prepare( $sql );
  $stmt->bind_param( $p_num, $value );
  $stmt->bind_param( $p_num, $value, $type );
  
  $res = $stmt->execute();
  $res = $stmt->execute( @bind_values );
  
  @row = $res->fetch_row();
  $res->fetch_row( \@row );
  $res->fetch_row( \%row );
  
  @row = $res->fetchrow_array();
  $row = $res->fetchrow_arrayref();
  $row = $res->fetchrow_hashref();
  
  $array = $res->fetchall_arrayref();
  $hash = $res->fetchall_hashref( $key );
  
  @name = $res->fetch_names();
  $num_rows = $res->num_rows();
  $num_fields = $res->num_fields();
  
  $rv = $con->auto_commit( $mode );
  $rv = $con->begin_work();
  $rv = $con->commit();
  $rv = $con->rollback();
  
  $str   = $con->error();
  $errno = $con->errno();
  
  $rv = $con->set_charset( $charset );
  $charset = $con->get_charset();
  
  $quoted = $db->quote( $arg );
  $quoted = $db->quote_id( ... );

DESCRIPTION

DBE provides an interface for high performance database communication.

The goal for this module is a fast and efficient database interface with the power of DBI.

The documentation uses different variable names for different classes. These variables are defined as follows. $con defines a connection class, $res defines a result set class, $stmt defines a statement class and $lob defines a class of a large object.

Uniform SQL

Functions with SQL statements offer an extended notation of catalog, schema and table names. If a SQL statement starts with a percent (%) sign identities can be written uniformly. The identities stay in square brackets []. Within the notation points (.) are evaluated as separators for schema, table and field names. The catalog is identified by an AT (@) character. It must be the last part in the identity. The route (#) character is converted into a point.

Examples

MySQL Driver

  # uniform
  $con->query("% SELECT * FROM [table@db] WHERE [field] = '1'");
  # native
  $con->query("SELECT * FROM `db`.`table` WHERE `field` = '1'");

PostgreSQL Driver

  # uniform
  $con->query("% SELECT * FROM [schema.table] AS [t1] WHERE [t1.id] = 1");
  # native
  $con->query('SELECT * FROM "schema"."table" AS "t1" WHERE "t1"."id" = 1');

Text Driver

  # uniform
  $con->query('% SELECT * FROM [table#csv] WHERE [table.field] = 1');
  # native
  $con->query('SELECT * FROM "table.csv" WHERE "table"."field" = 1');

Parameter Names in Placeholders for All

Uniform SQL enables you to use parameter names in placeholders. A parameter name begins with a colon (:) character and may contain one or more of the following characters: 'a'-'z', 'A'-'Z', '0'-'9', '_'. The names are converted into question mark (?) characters before the statement is sent to the driver.

Examples

  # prepare, execute
  $stmt = $con->prepare( '% SELECT * FROM [table] WHERE [id] > :id' );
  $stmt->bind_param( ':id', 1000, 'i' );
  $res = $stmt->execute();
  
  # or as query
  $res = $con->query(
      '% SELECT * FROM [table] WHERE [id] > :id',
      { 'id' => 1000 }
  );

Functions by Category

Main Functions

affected_rows, bind_param, connect, disconnect, do, execute, get_charset, insert_id, param_count, prepare, query, set_charset

Accessing Result Data

bind_column, dump, fetch, fetch_col, fetch_row, fetchall_arrayref, fetchall_hashref, fetchrow_arrayref, fetchrow_hashref, num_rows, row_seek, row_tell

Accessing Fields in a Result Set

fetch_field, fetch_names, field_seek, field_tell, names, num_fields

Transactions

auto_commit, begin_work, commit, rollback

Combined Selects

selectall_arrayref, selectall_hashref, selectrow_array, selectrow_arrayref, selectrow_hashref

Information and Catalog Functions

columns, data_sources, foreign_keys, getinfo, primary_keys, installed_drivers, open_drivers, special_columns, tables, type_info

Misc Functions

attr_get, attr_set, driver_has, escape_pattern, name_convert, row_limit, quote, quote_id, ping

Error Handling

errno, error, set_error_handler, trace

Large Objects

close, eof, getc, read, print, seek, size, tell, write

Examples

Simple Query

  use DBE;
  
  $con = DBE->connect(
      'provider' => 'MySQL',
      'socket' => '/tmp/mysql.sock',
      'user' => 'root',
      'auth' => '',
      'db' => 'test',
      'charset' => 'utf8',
  );
  
  $res = $con->query( "SELECT * FROM table WHERE field = 'foo'" );
  
  print join( '|', $res->fetch_names() ), "\n";
  while( @row = $res->fetch_row() ) {
      print join( '|', @row ), "\n";
  }

Query with statements

  use DBE;
  
  $dsn = "Provider=MySQL;Host=localhost;User=root;Password=;Database=test";
  $con = DBE->connect( $dsn );
  $con->set_charset( 'utf8' );
  
  $stmt = $con->prepare( 'SELECT * FROM table WHERE field = ?' );
  # bind "foo" to parameter 1 and execute
  $res = $stmt->execute( 'foo' );
  
  print join( '|', $res->fetch_names() ), "\n";
  while( $row = $res->fetchrow_arrayref() ) {
      print join( '|', @$row ), "\n";
  }

METHODS

Connection Control Methods

$con = DBE -> connect ( %hash )

$con = DBE -> connect ( $dsn )

Opens a connection to a database.

Parameters

%hash

Following parameters are support by DBE:

PROVIDER | DRIVER [string]

Name of provider to connect with. Defaults to "Text".
WARN [1|0|Yes|No|True|False]

Warn on error. Defaults to $^W.
CROAK [1|0|Yes|No|True|False]

Croak on error. Defaults to TRUE.
RECONNECT [int]

Number of attempts to reconnect with a delay of 1 sec. Default value "0" disables reconnection.

$dsn

The connection string that includes the provider name, and other parameters needed to establish the initial connection.

The basic format of a connection string includes a series of keyword/value pairs separated by semicolons. The equal sign (=) connects each keyword and its value. To include values that contain a semicolon, single-quote character, or double-quote character, the value must be enclosed in double quotation marks. If the value contains both a semicolon and a double-quote character, the value can be enclosed in single quotation marks. The single quotation mark is also useful if the value starts with a double-quote character. Conversely, the double quotation mark can be used if the value starts with a single quotation mark. If the value contains both single-quote and double-quote characters, the quotation-mark character used to enclose the value must be doubled every time it occurs within the value. Parameters are listed below.

All parameters are case-insensitive. Additional parameters are documented in the drivers manual.

Return Values

Returns a connection object ($con) on success, or undef on failure.

Examples

  # parameters as hash
  $con = DBE->connect(
      'provider' => 'Text',
      'dbq' => '/path/to/csv-files/',
  );
  
  # parameters as dsn
  $dsn = 'Provider=Text;DBQ=.;Format="Delimited(;)";QuoteBy=""""';
  $con = DBE->connect( $dsn );

$con -> close ()

$con -> disconnect ()

Closes the connection explicitly and frees its resources. disconnect() is a synonym for close().

$con -> set_charset ( $charset )

Sets the default character set to be used when sending data from and to the database server.

Parameters

$charset: The character set to be set.

Return Values

Returns a TRUE value on success or undef on failure.

$con -> get_charset ()

Gets the default character set.

Return Values

Returns the default character set or undef on error.

DBE -> errno ()

$con -> errno ()

Returns the last error code for the most recent function call that can succeed or fail.

Return Values

An error code value for the last call, if it failed. Zero means no error occurred.

Examples

  # global error
  $con = DBE->connect( ... )
      or die 'Connect failed (' . DBE->errno . ') ' . DBE->error;
  
  # connection error
  $con->query( ... )
      or die 'Query failed (' . $con->errno . ') ' . $con->error;

DBE -> error ()

$con -> error ()

Returns the last error message for the most recent function call that can succeed or fail.

Return Values

A string that describes the error. An empty string if no error occurred.

Examples

  # global error
  $con = DBE->connect( ... )
      or die 'Connect failed ' . DBE->error;
  
  # connection error
  $con->query( ... )
      or die 'Query failed ' . $con->error;

$con -> set_error_handler ( [$fnc [, $arg]] )

Sets or removes a userdefined error handler.

Parameters

$fnc: Function name or code reference.
$arg: Argument can be used to pass a class reference.

Return Values

Resturns true on success, or undef on error.

Parameters passed to error function

$code: The error code.
$msg: The error message.
$provider: The description string of the provider.
$action: Performed action during the error occurred.
$obj_id: Either a value of "con", "res" or "stmt".
$obj: Depending on $obj_id, it can be a connection object, a result object or a statement object.

Examples

Error handler

  $con = DBE->connect ('Provider=Text');
  
  # set error handler to a function
  $con->set_error_handler (\&error_handler);
  
  # raise a syntax error
  $con->do ("SELECT * FROM");
  
  sub error_handler {
      # does allmost the same like internal croak
      my ($code, $msg, $provider, $action, $obj_id, $obj) = @_;
      my ($pkg, $file, $line) = caller ();
      print STDERR "[$provider] $action: $msg at $file line $line\n";
      exit;
  }

Error handler as class function

  $con = DBE->connect ('Provider=Text');
  
  $obj = MY->new ();
  
  # set error handler to an object
  $con->set_error_handler ('error_handler', $obj);
  # or
  # $con->set_error_handler ('MY::error_handler', $obj);
  # or
  # $con->set_error_handler (\&MY::error_handler, $obj);
  
  # raise a syntax error
  $con->do ("SELECT * FROM");
  
  1;
  
  package MY;
  
  require Carp;
  
  sub new {
      bless {}, shift;
  }
  
  sub error_handler {
      # does allmost the same like internal croak
      my ($this, $code, $msg, $provider, $action, $obj_id, $obj) = @_;
      &Carp::croak ("[$provider] $action: $msg");
  }

DBE -> trace ( [$level [, $iohandle]] )

$con -> trace ( [$level [, $iohandle]] )

Enables tracing support with a specified level. The levels are defined as follows:

  0 - DBE_TRACE_NONE - disable tracing
  1 - DBE_TRACE_SQL - trace sql statements only
  2 - DBE_TRACE_SQLFULL - trace sql statements inlcuding bind
      and execute calls
  3 - DBE_TRACE_ALL - trace all messages

Setting trace options to a connection object will overwrite global trace settings.

The $iohandle parameter can contain an io handle to write the messages there. The default handle is STDERR.

Examples

  # global tracing of all messages
  DBE->trace( 3 );
  
  # trace into a file
  open( $fh, "> trace.log" ) or die "can't open file: $!";
  DBE->trace( 3, $fh );
  
  # just trace the sql statements within a connection object
  $con->trace( 1 );
  
  # disable global tracing
  DBE->trace( 0 );

Command Execution Methods

$res = $con -> query ( $statement )

$res = $con -> query ( $statement, @bind_values )

$res = $con -> do ( $statement )

$res = $con -> do ( $statement, @bind_values )

Sends a SQL statement to the currently active database on the server. do() is a synonym for query().

Parameters

$statement: This parameter can include one or more parameter markers in the SQL statement by embedding question mark (?) characters at the appropriate positions.
@bind_values: An array of values to bind to the statement. Values bound in this way are usually treated as "string" types unless the driver can determine the correct type, or unless bind_param() has already been used to specify the type.

Return Values

For selective queries query() returns a result class ($res) on success, or FALSE on error.

For other type of SQL statements, UPDATE, DELETE, DROP, etc, query() returns TRUE on success or FALSE on error.

$stmt = $con -> prepare ( $statement )

Prepares the SQL query pointed to by the null-terminated string query, and returns a statement handle to be used for further operations on the statement. The query must consist of a single SQL statement.

Parameters

$statement

The query, as a string.

This parameter can include one or more parameter markers in the SQL statement by embedding question mark (?) characters at the appropriate positions.

Return Values

Returns a statement class ($stmt) or FALSE on failure.

Examples

With statement

  $stmt = $con->prepare( 'UPDATE table WHERE field = ?' );
  # bind 'foo' to 'field' as type 'string'
  $stmt->bind_param( 1, 'foo', 's' );
  # execute
  $res = $stmt->execute();

Without statement

  $con->prepare( 'UPDATE table WHERE field = ?' );
  # bind 'foo' to 'field' as type 'string'
  $con->bind_param( 1, 'foo', 's' );
  # execute
  $res = $con->execute();

See Also

execute(), bind_param()

$stmt -> param_count ()

Returns the number of parameters in the statement.

$stmt -> bind_param ( $p_num )

$stmt -> bind_param ( $p_num, $value )

$stmt -> bind_param ( $p_num, $value, $type )

Binds a value to a prepared statement as parameter

Parameters

$p_num

The number of parameter starting at 1.

$value

Any scalar value.

$type

A string that contains one character which specify the type for the corresponding bind value:

  Character Description
  ---------------------
  i   corresponding value has type integer 
  d   corresponding value has type double 
  s   corresponding value has type string 
  b   corresponding value has type binary

Return Values

Returns a true value on success, or undef on error.

Example

  $stmt = $con->prepare(
      'UPDATE table WHERE field1 = ? AND field2 = ?' );
  # bind '100' to 'field1' as type 'integer'
  $stmt->bind_param( 1, 100, 'i' );
  # bind 'foo' to 'field2'
  $stmt->bind_param( 2, 'foo' );

See Also

prepare(), execute()

$stmt -> bind ( @bind_values )

Values bound in this way are usually treated as "string" types unless the driver can determine the correct type.

Return Values

Returns a true value on success, or undef on error.

$res = $stmt -> execute ()

$res = $stmt -> execute ( @bind_values )

Executes a prepared statement.

Parameters

@bind_values: An array of values to bind. Values bound in this way are usually treated as "string" types unless the driver can determine the correct type.

Return Values

For SELECT, SHOW, DESCRIBE, EXPLAIN and other statements returning resultset, query returns a result class ($res) on success, or undef on error.

For other type of SQL statements, UPDATE, DELETE, DROP, etc, query returns a true value on success, or undef on error.

Example

  $stmt = $con->prepare( 'UPDATE table WHERE field = ?' );
  # bind 'foo' to 'field' and execute
  $res = $stmt->execute( 'foo' );

Note

Some drivers (like MySQL) do not support different result sets within the same statement. In this case each result set of the statement share the same data.

See Also

prepare(), bind_param()

$stmt -> close ()

Closes a statement explicitly.

Retrieving Query Result Information

$con -> affected_rows ()

Gets the number of affected rows in a previous SQL operation After executing a statement with query() or execute(), returns the number of rows changed (for UPDATE), deleted (for DELETE), or inserted (for INSERT). For SELECT statements, affected_rows() works like num_rows().

Return Values

An integer greater than zero indicates the number of rows affected or retrieved. Zero indicates that no records where updated for an UPDATE statement, no rows matched the WHERE clause in the query or that no query has yet been executed.

$con -> insert_id ()

$con -> insert_id ( $catalog )

$con -> insert_id ( $catalog, $schema )

$con -> insert_id ( $catalog, $schema, $table )

$con -> insert_id ( $catalog, $schema, $table, $column )

Returns the auto generated id used in the last query or statement.

Parameters

$catalog: The catalog where the table is located.
$schema: The schema where the table is located.
$table: The table where the column is located.
$column: The column to retrieve the generated id from.

Return Values

The value of an AUTO_INCREMENT (IDENDITY,SERIAL) field that was updated by the previous query. Returns NULL if there was no previous query on the connection or if the query did not update an AUTO_INCREMENT value.

Accessing Result Data

$res -> dump ( [$maxlen [, $lsep [, $fsep [, $fh [, $header]]]]] )

Fetches all the rows from the result set and prints the results to a handle. NULL fields are printed as undef. Fields with utf8 data are enclosed in double quotes. Other fields are enclosed in single quotes.

Parameters

$maxlen: The maximum length of a field value. Defaults to 35
$lsep: Line separator, printed after each row. Defaults to "\n"
$fsep: Field separator. Defaults to ", "
$fh: File handle to print the results there. Defaults to STDOUT
$header: Print the column names on the first line. Defaults to TRUE.

Note

This method is designed for testing purposes and should not be used to export data.

$res -> fetch ()

Fetches the next row into bound variables. See more at bind_column().

$res -> fetch_row ()

$res -> fetch_row ( \@row )

$res -> fetch_row ( \%row )

$res -> fetchrow_array ()

Get a result row as an array or a hash. fetchrow_array() is a synonym for fetch_row().

Paramters

\@row: A reference to an array which will be filled with the data of the next row.
\%row: A reference to a hash will be filled with the data of the next row, where each key in the hash represents the name of one of the result set columns.

Return Values

Without parameters it returns an array of values that is filled with the data of the next row. With parameters it returns TRUE. FALSE is returned if there are no more rows in result set.

Examples

  $res = $con->query( "SELECT prename, name FROM person" );
  
  $res->fetch_row( \%row );
  print "First person is $row{'prename'} $row{'name'}\n";
  
  $res->fetch_row( \@row );
  print "Second person is $row[0] $row[1]\n";
  
  @row = $res->fetch_row;
  print "Third person is $row[0] $row[1]\n";

$res -> fetch_col ()

$res -> fetch_col ( $num )

$res -> fetch_col ( \@col )

$res -> fetch_col ( \@col, $num )

$res -> fetch_col ( \%col )

$res -> fetch_col ( \%col, $num_key, $num_val )

Fetch all rows from the result set and return a column of it.

Paramters

\@col: A reference to an array to store the data into.
$num: A column number between 0 and num_fields() - 1. Defaults to 0.
\%col: A reference to a hash to store the data into. Each key in the hash contains the data of column $num_key and each value contains the data of column $num_val.
$num_key: Column number to fetch as key. Defaults to 0.
$num_val: Column number to fetch as value. Defaults to 1.

Return Values

Without \@col and \%col paramters it returns an array of values that corresponds to the specified column of each row in the result set, or TRUE on success, or FALSE if no data is available.

Examples

Fetch columns as array

  $res = $con->query( "SELECT name FROM color" );
  
  @colors = $res->fetch_col();
      or
  $res->fetch_col( \@colors );
  
  print "Available colors: ", join( ', ', @colors ), "\n";

Fetch columns as hash

  $res = $con->query( "SELECT id, name FROM color" );
  $res->fetch_col( \%color );
  
  $res = $con->query( "SELECT color_id, description FROM articles" );
  $res->bind( $color_id, $desc );
  while( $res->fetch ) {
      print "Article $desc has color ", $color{$color_id}, "\n";
  }

$res -> fetchrow_arrayref ()

Fetch a result row as an enumerated array.

Return Values

Returns a reference to an array of values that corresponds to the fetched row, or FALSE if there are no more rows in result set.

$res -> fetchrow_hashref ()

$res -> fetchrow_hashref ( $name )

Fetch a result row as an associative array (hash).

Paramters

$name: Name conversation. A value of "lc" convert names to lowercase and a value of "uc" convert names to uppercase.

Return Values

Returns a reference to a hash of values representing the fetched row in the result set, where each key in the hash represents the name of one of the result set columns or FALSE if there are no more rows in the resultset.

If two or more columns of the result have the same field names, the last column will take precedence. To access the other columns of the same name, you either need to access the result with numeric indices by using fetch_row(), fetchrow_arrayref() or add alias names.

$res -> fetchall_arrayref ()

$res -> fetchall_arrayref ( {} )

Fetch all data from the result as a reference to an array, which contains a reference to each row.

Paramters

{}: Fetch all fields of every row as a hash ref.

Return Values

Returns a reference to an array of references to all fetched rows, or FALSE if no data is available.

Examples

  $res = $con->query( "SELECT name, age FROM person" );
  
  $a_per = $res->fetchall_arrayref();
  foreach $row( @$a_per ) {
      print $row->[0], " is ", $row->[1], " years old\n";
  }
  
  # fetch as hashref
  $a_per = $res->fetchall_arrayref( {} );
  foreach $row( @$a_per ) {
      print $row->{'name'}, " is ", $row->{'age'}, " years old\n";
  }

$res -> fetchall_hashref ( $key1 )

$res -> fetchall_hashref ( $key1, $key2, ... )

$res -> fetchall_hashref ( [$key1, $key2, ...] )

Fetch all data from the result as a reference to hash containing a key for each distinct value of the $key(n) column that was fetched.

Parameters

$key(n): Column name to use their values as key in the hash.

Return Values

Returns a reference to a hash containing a key for each distinct value of the $key(n) column that was fetched. For each key the corresponding value is a reference to a hash containing all the selected columns and their values.

Examples

  $res = $con->query( 'SELECT ID, Name FROM Table' );
  $data = $res->fetchall_hashref( 'ID' );
  # print name of ID = 2
  print $data->{2}->{'Name'};
  
  $res = $con->query( 'SELECT ID1, ID2, Name FROM Table' );
  $data = $res->fetchall_hashref( 'ID1', 'ID2' );
  # print name of ID1 = 2 and ID2 = 10
  print $data->{2}->{10}->{'Name'};

$res -> bind_column ( $c_num, $c_var )

Binds a variable to a column in the result set.

Parameters

$c_num: Number of column starting at 1.
$c_var: A variable to bind. If it is a reference to a variable it will be dereferenced once.

Return Values

Returns a true value on succes, or undef on error.

Examples

  my ($article_id, $article_name);
  $res = $con->query( "SELECT ID, Name FROM Article" );
  $res->bind_column( 1, $article_id );
  $res->bind_column( 2, $article_name );
  
  while( $res->fetch ) {
      print "article $article_id: $article_name\n";
  }

$res -> bind ( @bind_variables )

Binds one or more variables to the columns in the result set. It is a shorthand version of bind_column().

Examples

  my ($prename, $name, $age);
  $res = $con->query( "SELECT Prename, Name, Age FROM Person" );
  $res->bind( $prename, $name, $age );
  while( $res->fetch ) {
      print "$name, $prename is $age years old\n";
  }

Bind a hash

  my %row;
  $res = $con->query( "SELECT Prename, Name, Age FROM Person" );
  $res->bind( @row{$res->names('lc')} );
  while( $res->fetch ) {
      print "$row{'name'}, $row{'prename'} is $row{'age'} years old\n";
  }

$res -> num_rows ()

Get the number of rows in a result.

Return Values

Returns number of rows in the result set.

$res -> row_tell ()

Get the actual position of row cursor in a result (Starting at 0).

Return Values

Returns the actual position of row cursor in a result.

$res -> row_seek ( $offset )

Set the actual position of row cursor in a result (Starting at 0).

Paramters

$offset: Absolute row position. Valid between 0 and num_rows() - 1.

Return Values

Returns the previous position of row cursor in a result.

Accessing Fields in a Result Set

$res -> names ()

$res -> names ( $name )

$res -> fetch_names ()

$res -> fetch_names ( $name )

Returns an array of field names representing in a result set. names is a synonym for fetch_names.

Paramters

$name: Name conversation. A value of "lc" convert names to lowercase and a value of "uc" convert names to uppercase.

Return Values

Returns an array of field names or FALSE if no field information is available.

$res -> num_fields ()

Gets the number of fields (columns) in a result.

Return Values

Returns number of fields in the result set.

$res -> fetch_field ()

Returns the next field in the result set.

Return Values

Returns a hash which contains field definition information or FALSE if no field information is available.

$res -> field_tell ()

Gets the actual position of field cursor in a result (Starting at 0).

Return Values

Returns the actual position of field cursor in the result.

$res -> field_seek ( $offset )

Sets the actual position of field cursor in the result (Starting at 0).

Paramters

$offset: Absolute field position. Valid between 0 and num_fields() - 1.

Return Values

Returns the previous position of field cursor in the result.

Transaction Methods

$con -> auto_commit ( $mode )

Turns on or off auto-commit mode on queries for the database connection.

Parameters

$mode: Whether to turn on auto-commit or not.

Return Values

Returns a true value on success, or undef on error.

$con -> begin_work ()

Turns off auto-commit mode for the database connection until transaction is finished.

Return Values

Returns a true value on success, or undef on error.

$con -> commit ()

Commits the current transaction for the database connection.

Return Values

Returns a true value on success, or undef on error.

$con -> rollback ()

Rollbacks the current transaction for the database.

Return Values

Returns a true value on success, or undef on error.

Simple Data Fetching

$con -> selectrow_array ( $statement )
$con -> selectrow_array ( $statement, @bind_values ): Combines various operations into a single call and returns an array with values of the first row, or undef on error. See fetchrow_array() for further information.
$con -> selectrow_arrayref ( $statement )
$con -> selectrow_arrayref ( $statement, @bind_values ): Combines various operations into a single call and returns a reference to an array with values of the first row, or undef on error. See fetchrow_arrayref() for further information.
$con -> selectrow_hashref ( $statement )
$con -> selectrow_hashref ( $statement, @bind_values ): Combines various operations into a single call and returns a reference to a hash with names and values of the first row, or undef on error. See fetchrow_hashref() for further information.
$db -> selectall_arrayref ( $statement )
$db -> selectall_arrayref ( $statement, {} )
$db -> selectall_arrayref ( $statement, undef, @bind_values )
$db -> selectall_arrayref ( $statement, {}, @bind_values ): Combines various operations into a single call. See fetchall_hashref() for a description. Returns undef on error.
$db -> selectall_hashref ( $statement, $key )
$db -> selectall_hashref ( $statement, $key, @bind_values ): Combines various operations into a single call. See fetchall_hashref() for a description. Returns undef on error.
$con -> select_col ( $statement, @bind_values )
$con -> select_col ( $statement, [$num], @bind_values )
$con -> select_col ( $statement, [\@col], @bind_values )
$con -> select_col ( $statement, [\@col, $num], @bind_values )
$con -> select_col ( $statement, [\%col], @bind_values )
$con -> select_col ( $statement, [\%col, $num_key, $num_val], @bind_values ): Combines various operations into a single call and returns an array with values of the first row, or undef on error. The @bind_values are optional. See fetch_col() for further information.

Information and Catalog Functions

DBE -> open_drivers ()

Returns a hash of open (loaded) drivers. The key field in the hash contains the name of the driver and the value field contains a description of the driver.

Example

  %drivers = DBE->open_drivers();

DBE -> installed_drivers ()

Returns a hash of installed drivers. The key field in the hash contains the name of the driver and the value field contains a description of the driver.

Example

  %drivers = DBE->installed_drivers();

$con -> data_sources ()

Returns a list of data sources (databases) available.

$con -> getinfo ( $id )

Returns general information, (including supported data conversions) about the DBMS that the application is currently connected to.

Example

  $pattern_escape = $con->getinfo( 14 );

$con -> type_info ()

$con -> type_info ( $sql_type )

Returns a result set that can be used to fetch information about the data types that are supported by the DBMS.

Parameters

$sql_type

The SQL data type being queried as string or number. Supported types are: (numeric values stay in parenthesis)

SQL_ALL_TYPES (0)
SQL_BIGINT (-5)
SQL_BINARY (-2)
SQL_VARBINARY (-3)
SQL_CHAR (1)
SQL_DATE (9)
SQL_DECIMAL (3)
SQL_DOUBLE (8)
SQL_FLOAT (6)
SQL_INTEGER (4)
SQL_NUMERIC (2)
SQL_REAL (7)
SQL_SMALLINT (5)
SQL_TIME (10)
SQL_TIMESTAMP (11)
SQL_VARCHAR (12)

If SQL_ALL_TYPES is specified, information about all supported data types would be returned in ascending order by TYPE_NAME. All unsupported data types would be absent from the result set.

Return Values

Returns a result set where each table is represented by one row. The result set contains the columns listed below in the order given.

1 TYPE_NAME

String representation of the SQL data type name.

2 DATA_TYPE

SQL data type code.

3 COLUMN_SIZE

If the data type is a character or binary string, then this column contains the maximum length in bytes.

For date, time, timestamp data types, this is the total number of characters required to display the value when converted to character.

For numeric data types, this is the total number of digits.

4 LITERAL_PREFIX

Character or characters used to prefix a literal; for example, a single quotation mark (') for character data types or 0x for binary data types; undef is returned for data types where a literal prefix is not applicable.

5 LITERAL_SUFFIX

Character or characters used to terminate a literal; for example, a single quotation mark (') for character data types; undef is returned for data types where a literal suffix is not applicable.

6 CREATE_PARAMS

A list of keywords, separated by commas, corresponding to each parameter that the application may specify in parentheses when using the name that is returned in the TYPE_NAME field. The keywords in the list can be any of the following: length, precision, or scale. They appear in the order that the syntax requires them to be used. For example, CREATE_PARAMS for DECIMAL would be "precision,scale"; CREATE_PARAMS for VARCHAR would equal "length." undef is returned if there are no parameters for the data type definition; for example, INTEGER.

7 NULLABLE

Whether the data type accepts a NULL value:

0 - if the data type does not accept NULL values.

1 - if the data type accepts NULL values.

2 - if it is not known whether the column accepts NULL values.

8 CASE_SENSITIVE

Indicates whether the data type can be treated as case sensitive for collation purposes; valid values are TRUE and FALSE.

9 SEARCHABLE

Indicates how the data type is used in a WHERE clause. Valid values are:

SQL_UNSEARCHABLE (0): The data type cannot be used in a WHERE clause.
SQL_LIKE_ONLY (1): The data type can be used in a WHERE clause only with the LIKE predicate.
SQL_ALL_EXCEPT_LIKE (2): The data type can be used in a WHERE clause with all comparison operators except LIKE.
SQL_SEARCHABLE (3): The data type can be used in a WHERE clause with any comparison operator.

10 UNSIGNED_ATTRIBUTE

Indicates where the data type is unsigned. The valid values are: TRUE, FALSE or undef. A undef indicator is returned if this attribute is not applicable to the data type.

11 FIXED_PREC_SCALE

Contains a TRUE value if the data type is exact numeric and always has the same precision and scale; otherwise, it contains FALSE.

12 AUTO_UNIQUE_VALUE

Contains TRUE if a column of this data type is automatically set to a unique value when a row is inserted; otherwise, contains FALSE.

13 LOCAL_TYPE_NAME

Localized version of the data source–dependent name of the data type. undef is returned if a localized name is not supported by the data source. This name is intended for display only.

14 MINIMUM_SCALE

The minimum scale of the SQL data type. If a data type has a fixed scale, the MINIMUM_SCALE and MAXIMUM_SCALE columns both contain the same value. undef is returned where scale is not applicable.

15 MAXIMUM_SCALE

The maximum scale of the SQL data type. undef is returned where scale is not applicable. If the maximum scale is not defined separately in the DBMS, but is defined instead to be the same as the maximum length of the column, then this column contains the same value as the COLUMN_SIZE column.

16 SQL_DATA_TYPE

The value of the SQL data type as it appears in the SQL_DESC_TYPE field of the descriptor. This column is the same as the DATA_TYPE column, except for interval and datetime data types.

For interval and datetime data types, the SQL_DATA_TYPE field in the result set will return SQL_INTERVAL or SQL_DATETIME, and the SQL_DATETIME_SUB field will return the subcode for the specific interval or datetime data type.

17 SQL_DATETIME_SUB

When the value of SQL_DATA_TYPE is SQL_DATETIME or SQL_INTERVAL, this column contains the datetime/interval subcode. For data types other than datetime and interval, this field is undef.

For interval or datetime data types, the SQL_DATA_TYPE field in the result set will return SQL_INTERVAL or SQL_DATETIME, and the SQL_DATETIME_SUB field will return the subcode for the specific interval or datetime data type.

18 NUM_PREC_RADIX

If the data type is an approximate numeric type, this column contains the value 2 to indicate that COLUMN_SIZE specifies a number of bits. For exact numeric types, this column contains the value 10 to indicate that COLUMN_SIZE specifies a number of decimal digits. Otherwise, this column is NULL.

19 INTERVAL_PRECISION

If the data type is an interval data type, then this column contains the value of the interval leading precision. Otherwise, this column is NULL.

$con -> tables ()

$con -> tables ( $catalog )

$con -> tables ( $catalog, $schema )

$con -> tables ( $catalog, $schema, $table )

$con -> tables ( $catalog, $schema, $table, $type )

Returns a result set that can be used to fetch information about tables and views that exist in the database.

Parameters

$catalog

String that may contain a pattern-value to qualify the result set. Catalog is the first part of a three-part table name.

$schema

String that may contain a pattern-value to qualify the result set by schema name.

$table

String that may contain a pattern-value to qualify the result set by table name.

$type

String that may contain a value list to qualify the result set by table type. The value is a list of values separated by commas for the types of interest. Valid table type identifiers may include: ALL, BASE TABLE, TABLE, VIEW, SYSTEM TABLE. If $table argument is empty, then this is equivalent to specifying all of the possibilities for the table type identifier.

If SYSTEM TABLE is specified, then both system tables and system views (if there are any) are returned.

Note

Since "_" is a pattern matching value, you may need to escape pattern-values by escape_pattern() first.

Return Values

Returns a result set where each table is represented by one row. The result set contains the columns listed below in the order given.

1 TABLE_CAT: The catalog identifier.
2 TABLE_SCHEM: The name of the schema containing TABLE_NAME.
3 TABLE_NAME: The name of the table, or view, or alias, or synonym.
4 TABLE_TYPE: Identifies the type given by the name in the TABLE_NAME column. It can have the string values 'TABLE', 'VIEW', 'BASE TABLE', or 'SYSTEM TABLE'.
5 REMARKS: Contains the descriptive information about the table.

$con -> columns ()

$con -> columns ( $catalog )

$con -> columns ( $catalog, $schema )

$con -> columns ( $catalog, $schema, $table )

$con -> columns ( $catalog, $schema, $table, $column )

Get a list of columns in the specified tables. The information is returned in a result set, which can be retrieved using the same functions that are used to fetch a result set generated by a SELECT statement.

Parameters

$catalog: String that may contain a pattern-value to qualify the result set. Catalog is the first part of a three-part table name.
$schema: String that may contain a pattern-value to qualify the result set by schema name.
$table: String that may contain a pattern-value to qualify the result set by table name.
$column: String that may contain a pattern-value to qualify the result set by column name.

Note

Since "_" is a pattern matching value, you may need to escape pattern-values by escape_pattern() first.

Return Values

Returns a result set class, with columns listed below in the order given.

1 TABLE_CAT

The catalog identifier.

2 TABLE_SCHEM

The name of the schema containing TABLE_NAME.

3 TABLE_NAME

The name of the table or view.

4 COLUMN_NAME

Column identifier. Name of the column of the specified table or view.

5 DATA_TYPE

Identifies the SQL data type of the column.

6 TYPE_NAME

String representing the name of the data type corresponding to DATA_TYPE.

7 COLUMN_SIZE

Defines the maximum length in characters for character data types, the number of digits for numeric data types or the length in the representation of temporal types.

8 BUFFER_LENGTH

The length in bytes of transferred data.

9 DECIMAL_DIGITS

The total number of significant digits to the right of the decimal point.

10 NUM_PREC_RADIX

The radix for numeric precision. The value is 10 or 2 for numeric data types and NULL (undef) if not applicable.

11 NULLABLE

FALSE if the column does not accept NULL values, or TRUE if the column accepts NULL values, or undef if unknown.

12 REMARKS

May contain descriptive information about the column.

13 COLUMN_DEF

The default value of the column. The value in this column should be interpreted as a string if it is enclosed in quotation marks.

14 SQL_DATA_TYPE

This column is the same as the DATA_TYPE column, except for datetime and interval data types.

15 SQL_DATETIME_SUB

The subtype code for datetime and interval data types. For other data types, this column returns a NULL.

16 CHAR_OCTET_LENGTH

The maximum length in bytes of a character or binary data type column. For all other data types, this column returns a NULL.

17 ORDINAL_POSITION

The ordinal position of the column in the table. The first column in the table is number 1.

18 IS_NULLABLE

"NO" if the column does not include NULLs.

"YES" if the column could include NULLs.

This column returns a zero-length string if nullability is unknown.

$con -> primary_keys ( $catalog, $schema, $table )

Returns a list of column names that comprise the primary key for a table. The information is returned in a result set, which can be retrieved using the same functions that are used to process a result set that is generated by a query.

Parameters

$catalog: Catalog qualifier of a 3 part table name.
$schema: Schema qualifier of table name.
$table: Table name.

Return Values

Returns the primary key columns from a single table, Search patterns cannot be used to specify the schema qualifier or the table name.

The result set contains the columns that are listed below, ordered by TABLE_CAT, TABLE_SCHEM, TABLE_NAME, and ORDINAL_POSITION.

1 TABLE_CAT: The catalog identifier.
2 TABLE_SCHEM: The name of the schema containing TABLE_NAME.
3 TABLE_NAME: Name of the specified table.
4 COLUMN_NAME: Primary Key column name.
5 KEY_SEQ: Column sequence number in the primary key, starting with 1.
6 PK_NAME: Primary key identifier. NULL if not applicable to the data source.

$con -> foreign_keys ( $pk_cat, $pk_schem, $pk_table, $fk_cat, $fk_schem, $fk_table )

Returns information about foreign keys for the specified table. The information is returned in a result set which can be processed using the same functions that are used to retrieve a result that is generated by a query.

Parameters

$pk_cat: Catalog qualifier of the primary key table.
$pk_schem: Schema qualifier of the primary key table.
$pk_table: Name of the table name containing the primary key.
$fk_cat: Catalog qualifier of the table containing the foreign key.
$fk_schem: Schema qualifier of the table containing the foreign key.
$fk_table: Name of the table containing the foreign key.

Usage

If $pk_table contains a table name, and $fk_table is empty, foreign_keys() returns a result set that contains the primary key of the specified table and all of the foreign keys (in other tables) that refer to it.

If $fk_table contains a table name, and $pk_table is empty, foreign_keys() returns a result set that contains all of the foreign keys in the specified table and the primary keys (in other tables) to which they refer.

If both $pk_table and $fk_table contain table names, foreign_keys() returns the foreign keys in the table specified in $fk_table that refer to the primary key of the table specified in $pk_table. This should be one key at the most.

Return Values

Returns a reference to a result set, or FALSE on failure. The columns of the result set are listed below in the order given.

1 PKTABLE_CAT

Primary key table catalog name; NULL if not applicable to the data source.

2 PKTABLE_SCHEM

Primary key table schema name; NULL if not applicable to the data source.

3 PKTABLE_NAME

Primary key table name.

3 PKCOLUMN_NAME

Primary key column name. The driver returns an empty string for a column that does not have a name.

4 FKTABLE_CAT

Foreign key table catalog name; NULL if not applicable to the data source.

5 FKTABLE_SCHEM

Foreign key table schema name; NULL if not applicable to the data source.

6 FKTABLE_NAME

Foreign key table name.

7 FKCOLUMN_NAME

Foreign key column name. The driver returns an empty string for a column that does not have a name.

8 KEY_SEQ

The ordinal position of the column in the key, starting at 1.

9 UPDATE_RULE

Action to be applied to the foreign key when the SQL operation is UPDATE:

  0  -  CASCADE
  1  -  RESTRICT
  2  -  SET NULL
  3  -  NO ACTION
  4  -  SET DEFAULT

10 DELETE_RULE

Action to be applied to the foreign key when the SQL operation is DELETE:

  0  -  CASCADE
  1  -  RESTRICT
  2  -  SET NULL
  3  -  NO ACTION
  4  -  SET DEFAULT

11 FK_NAME

Foreign key name. NULL if not applicable to the data source.

12 PK_NAME

Primary key name. NULL if not applicable to the data source.

$con -> statistics ( $catalog, $schema, $table )

$con -> statistics ( $catalog, $schema, $table, $unique_only )

Retrieve a list of statistics about a single table and the indexes associated with the table. The information is returned in a result set, which can be retrieved using the same functions that are used to fetch a result set generated by a SELECT statement.

Parameters

$catalog: Catalog is the first part of a three-part table name. It cannot contain a string search pattern.
$schema: Schema qualifier of the specified table. It cannot contain a string search pattern.
$table: Table name. This argument cannot be a empty. It cannot contain a string search pattern.
$unique_only: If TRUE, only unique indexes are returned. If FALSE, all indexes are returned.

Return Values

Returns a result set class, with columns listed below in the order given.

1 TABLE_CAT

Catalog name of the table to which the statistic or index applies; NULL if not applicable to the data source.

2 TABLE_SCHEM

Schema name of the table to which the statistic or index applies; NULL if not applicable to the data source.

3 TABLE_NAME

Table name of the table to which the statistic or index applies.

4 NON_UNIQUE

Indicates whether the index does not allow duplicate values:

TRUE if the index values can be nonunique.

FALSE if the index values must be unique.

NULL is returned if TYPE is 'table'.

5 INDEX_QUALIFIER

The identifier that is used to qualify the index name doing a DROP INDEX; NULL is returned if an index qualifier is not supported by the data source or if TYPE is 'table'.

6 INDEX_NAME

Index name; NULL is returned if TYPE is 'table'.

7 TYPE

Type of information being returned:

  'table'      indicates a statistic for the table (in the CARDINALITY
               or PAGES column). 
  'btree'      indicates a B-Tree index.
  'clustered'  indicates a clustered index. 
  'content'    indicates a content index.
  'hashed'     indicates a hashed index.
  'other'      indicates another type of index.

8 ORDINAL_POSITION

Column sequence number in index (starting with 1); NULL is returned if TYPE is 'table'.

9 COLUMN_NAME

Column name. If the column is based on an expression, such as SALARY + BENEFITS, the expression is returned; if the expression cannot be determined, an empty string is returned.

10 ASC_OR_DESC

Sort sequence for the column: "A" for ascending; "D" for descending; NULL is returned if column sort sequence is not supported by the data source or if TYPE is 'table'.

11 CARDINALITY

Cardinality of table or index; number of rows in table if TYPE is 'table'; number of unique values in the index if TYPE is not 'table'; NULL is returned if the value is not available from the data source.

12 PAGES

Number of pages used to store the index or table; number of pages for the table if TYPE is 'table'; number of pages for the index if TYPE is not 'table'; NULL is returned if the value is not available from the data source or if not applicable to the data source.

$con -> special_columns ( $type, $catalog, $schema, $table )

$con -> special_columns ( $type, $catalog, $schema, $table, $scope )

$con -> special_columns ( $type, $catalog, $schema, $table, $scope, $nullable )

special_columns retrieves the following information about columns within a specified table:

The optimal set of columns that uniquely identifies a row in the table.
Columns that are automatically updated when any value in the row is updated by a transaction.

The information is returned in a result set, which can be retrieved using the same functions that are used to fetch a result set generated by a SELECT statement.

Parameters

$type (integer)

Type of column to return. Must be one of the following values:

SQL_BEST_ROWID (1): Returns the optimal column or set of columns that, by retrieving values from the column or columns, allows any row in the specified table to be uniquely identified. A column can be either a pseudo-column specifically designed for this purpose (as in Oracle ROWID or Ingres TID) or the column or columns of any unique index for the table.
SQL_ROWVER (2): Returns the column or columns in the specified table, if any, that are automatically updated by the data source when any value in the row is updated by any transaction (as in SQLBase ROWID or Sybase TIMESTAMP).

$catalog

Catalog is the first part of a three-part table name. It cannot contain a string search pattern.

$schema

Schema qualifier of the specified table. It cannot contain a string search pattern.

$table

Table name. This argument cannot be a empty. It cannot contain a string search pattern.

$scope (integer)

Minimum required duration for which the unique row identifier is valid. $scope must be one of the following:

SQL_SCOPE_CURROW (0): The row identifier is guaranteed to be valid only while positioned on that row. A later reselect using the same row identifier values may not return a row if the row was updated or deleted by another transaction.
SQL_SCOPE_TRANSACTION (1): The row identifier is guaranteed to be valid for the duration of the current transaction.
SQL_SCOPE_SESSION (2): The row identifier is guaranteed to be valid for the duration of the connection.

$nullable (integer)

Determines whether to return special columns that can have a NULL value. Must be one of the following:

SQL_NO_NULLS (0): Exclude special columns that can have NULL values. Some drivers cannot support SQL_NO_NULLS, and these drivers will return an empty result set if SQL_NO_NULLS was specified. Applications should be prepared for this case and request SQL_NO_NULLS only if it is absolutely required.
SQL_NULLABLE (1): Return special columns even if they can have NULL values.

Return Values

Returns a result set class, with columns listed below in the order given.

1 SCOPE

Actual scope of the rowid. Contains one of the following values:

SQL_SCOPE_CURROW (0), SQL_SCOPE_TRANSACTION (1), SQL_SCOPE_SESSION (2)

NULL is returned when $type is SQL_ROWVER (2). For a description of each value, see the description of Scope in "Parameters," earlier in this section.

2 COLUMN_NAME

Column name. The driver returns an empty string for a column that does not have a name.

3 DATA_TYPE

SQL data type of the column.

4 TYPE_NAME

DBMS character string represented of the name associated with DATA_TYPE column value.

5 COLUMN_SIZE

The size of the column on the data source.

6 BUFFER_LENGTH

The length, in bytes, of the data returned in the default C type.

7 DECIMAL_DIGITS

The decimal digits of the column on the data source. NULL is returned for data types where decimal digits are not applicable.

8 PSEUDO_COLUMN

Indicates whether the column is a pseudo-column, such as Oracle ROWID:

SQL_PC_UNKNOWN (0), SQL_PC_NOT_PSEUDO (1), SQL_PC_PSEUDO (2)

Other Functions

$con -> escape_pattern ( $string )

Escape pattern matching characters for use in tables() and columns().

Example

  # since "_" matches any single character,
  # it must be escaped to match it as "_"
  $res = $con->tables( $con->escape_pattern( 'Database_Name' ) );

$con -> quote ( $value )

Quote a value for use as a literal value in an SQL statement, by escaping any special characters (such as quotation marks) contained within the string and adding the required type of outer quotation marks.

The quote() method should not be used with placeholders.

Parameters

$value: Value to be quoted.

Return Values

The quoted value with adding the required type of outer quotation marks.

Example

  print $con->quote( "Don't clash with quote chars" );
  # output: 'Don''t clash with quote chars'

$con -> quote_bin ( $value )

Quote a value for use as a binary value in an SQL statement,

The quote_bin() method should not be used with placeholders.

Parameters

$value: Value to be quoted as binary value.

Return Values

The quoted value to use as binary value in SQL statements, or undef if the driver does not support binary values directly in SQL statements.

Example

  print $con->quote_bin( "DBE" );
  
  # SQLite3:      X'444245'
  # MySQL:        0x444245
  # PostgreSQL:   '\104\102\105'

$con -> quote_id ( $field )

$con -> quote_id ( $table, $field )

$con -> quote_id ( $catalog, $schema, $table )

Quote an identifier (table name etc.) for use in an SQL statement, by escaping any special characters it contains and adding the required type of outer quotation marks.

Parameters

One or more identifiers to quote.

Return Values

The quoted string with adding the required type of outer quotation marks.

Examples

  # MySQL driver:
  
  $s = $con->quote_id( 'table' );
  # returns: `table`
  
  $s = $con->quote_id( 'table', 'field' );
  # returns: `table`.`field`
  
  $s = $con->quote_id( 'table', '*' );
  # returns: `table`.*

$con -> name_convert ()

$con -> name_convert ( $name )

Sets or returns the name conversion in result sets for subsequent queries.

Examples

  # read the actual state
  print "current name conversion: ", $con->name_convert() || "none", "\n";
  
  # convert names to uppercase
  $con->name_convert( "NAME_uc" );
  # run a query
  $res = $con->query( "SELECT ..." );
  $res->names; # uppercase
  
  # convert names to lowercase
  $con->name_convert( "lc" );
  # run a query
  $res = $con->query( "SELECT ..." );
  $res->fetchrow_hashref; # keys are in lowercase
  
  # disable name conversion
  $con->name_convert( "" );

$con -> row_limit ()

$con -> row_limit ( $limit )

$con -> row_limit ( $limit, $offset )

Adds a limit to SELECT statements. Setting this option affects subsequent calls to query() and prepare(). The driver holds $limit rows in the result set and calls internally SELECT again to give access to all rows.

Examples

Table "t1" should contain more then one row

  # set limit to 1 row
  $con->row_limit( 1 );
  
  # the driver holds one row in the result set
  $res = $con->query( "SELECT * FROM t1" );
  
  # num_rows returns the total number of rows available
  print $res->num_rows, "\n";
  
  # fetch the first row
  @row = $res->fetch_row;
  
  # fetch the second row
  # the driver now makes a new SELECT call to the dbms
  @row = $res->fetch_row;
  
  # disable row limit for further queries
  $con->row_limit( 0 );

Pagination Example

  $limit = 10;
  $offset = 0;
  
  $con->row_limit( $limit, $offset );
  $res->query( "SELECT * FROM t1" );
  
  $first_row = $offset + 1;
  $last_row = $res->num_rows - $offset;
  $last_row > $limit and $last_row = $limit;
  
  print "print rows $first_row to $last_row\n";
  for $row_pos( $first_row .. $last_row ) {
      $res->fetch_row( \@row ) or last;
      print "row $row_pos ", join( '|', @row ), "\n";
  }

Note

row_limit() must be supported by the driver. Known supporting drivers are MySQL, PostgreSQL and SQLite3.

$con -> attr_set ( $name, $value )

$con -> attr_get ( $name )

Sets or gets a connection attribute. Attribute names are given as string. Following attributes are available to DBE:

  croak, warn, reconnect

A description of these attributes can be found on connect().

Example

  $prv = $con->get_attr( 'croak' );
  # enable croak on error
  $con->set_attr( 'croak' => 1 );
  eval {
      # raise an error
      $con->do( "SELECT" );
  };
  # restore previous attribute
  $con->set_attr( 'croak' => $prv );
  if( $@ ) {
      print "SELECT failed: $@\n";
  }

$con -> ping ()

Determines if the connection is still working. Returns TRUE on success, or FALSE on failure.

$con -> driver_has ( $fnc_name )

Checks the driver for a function.

Parameters

$fnc_name: Name of the function.

Return Values

Return TRUE if the function exists, or FALSE if not.

Example

  if( ! $con->driver_has( 'prepare' ) ) {
      print "statements are not available!\n";
  }

Large Objects

Drivers with access to large objects would create this class which supports following methods.

$lob -> read ( $buffer, $length )

Reads a maximum of length bytes from the large object.

Parameters

$buffer: A variable to write the read bytes into.
$length: The maximum number of bytes read is specified by the length parameter.

Return Values

Returns number of bytes read, 0 on eof, or undef on error.

$lob -> write ( $buffer )

$lob -> write ( $buffer, $offset )

$lob -> write ( $buffer, $offset, $length )

Writes to the large object from the given buffer.

Parameters

$buffer: The buffer to be written.
$offset: The optional parameter $offset can specify an alternate offset in the buffer.
$length: The optional parameter $length can specify an alternate length of bytes written to the socket. If this length is greater then the buffer length, it is silently truncated to the length of the buffer.

Return Values

Returns the number of bytes successfully written, or undef on error.

$lob -> size ()

Returns the size of the large object, or undef on error.

$lob -> seek ( $position, $origin )

Moves the large object pointer to a specified location.

Parameters

$position

Number of bytes or characters from $origin.

$origin

Initial position. It must be one of the following values:

  0 - Beginning of large object. 
  1 - Current position of large object. 
  2 - End of large object.

Return Values

Returns a true value on success, or undef on error.

$lob -> tell ()

Returns the current position of the large object, or undef on error.

$lob -> print ( ... )

Writes to the large object from the given parameters.

Return Values

Returns a true value on success, or undef on error.

Example

  $lob->print( 'hello lob', "\n" );

$lob -> getc ()

Returns the character read as an integer, or -1 on end of large object, or undef on error.

$lob -> eof ()

Returns a true value if a read operation has attempted to read past the end of the large object, 0 otherwise, or undef on error.

$lob -> close ()

Closes the large object stream.

Return Values

Returns a true value on success, or undef on error.

THREADSAFETY

DBE was build for threads and should run properly with threads enabled. Objects are shared between threads. This means not that database connections are thread safe. It is never safe to use the same connection in two or more threads. You should make own connections for each thread. If you want share a database connection between threads you should use the lock() statement, which is a part of the threads::shared module.

AUTHORS

Navalla org., Christian Mueller, http://www.navalla.org/

COPYRIGHT

The DBE module is free software. You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 1766:: Non-ASCII character seen before =encoding in 'source–dependent'. Assuming CP1252

To install DBE, copy and paste the appropriate command in to your terminal.

cpanm

cpanm DBE

CPAN shell

perl -MCPAN -e shell
install DBE

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

Uniform SQL

Parameter Names in Placeholders for All

Functions by Category

Examples

Simple Query

Query with statements

METHODS

Connection Control Methods

Command Execution Methods

Retrieving Query Result Information

Accessing Result Data

Accessing Fields in a Result Set

Transaction Methods

Simple Data Fetching

Information and Catalog Functions

Other Functions

Large Objects

THREADSAFETY

AUTHORS

COPYRIGHT

Module Install Instructions