NAME

Jifty::DBI::Handle - Perl extension which is a generic DBI handle

SYNOPSIS

use Jifty::DBI::Handle;

my $handle = Jifty::DBI::Handle->new();
$handle->connect( driver => 'mysql',
                  database => 'dbname',
                  host => 'hostname',
                  user => 'dbuser',
                  password => 'dbpassword');
# now $handle isa Jifty::DBI::Handle::mysql

DESCRIPTION

This class provides a wrapper for DBI handles that can also perform a number of additional functions.

new

Generic constructor

connect PARAMHASH

Takes a paramhash and connects to your DBI datasource, with the keys driver, database, host, user and password.

If you created the handle with Jifty::DBI::Handle->new and there is a Jifty::DBI::Handle::(Driver) subclass for the driver you have chosen, the handle will be automatically "upgraded" into that subclass.

_upgrade_handle DRIVER

This private internal method turns a plain Jifty::DBI::Handle into one of the standard driver-specific subclasses.

build_dsn PARAMHASH

Builds a dsn suitable for handing to DBI->connect.

Mandatory arguments:

driver
database

Optional arguments:

host
port
sid
requiressl
and anything else your DBD lets you pass in

dsn

Returns the dsn for this database connection.

raise_error [MODE]

Turns on the Database Handle's RaiseError attribute.

print_error [MODE]

Turns on the Database Handle's PrintError attribute.

log_sql_statements BOOL

Takes a boolean argument. If the boolean is true, it will log all SQL statements, as well as their invocation times and execution times.

Returns whether we're currently logging or not as a boolean

log_sql_hook NAME [, CODE]

Used in instrumenting the SQL logging. You can use this to, for example, get a stack trace for each query (so you can find out where the query is being made). The name is required so that multiple hooks can be installed without stepping on eachother's toes.

The coderef is run in scalar context and (currently) receives no arguments.

If you don't pass CODE in, then the coderef currently assigned under NAME is returned.

_log_sql_statement STATEMENT DURATION BINDINGS

add an SQL statement to our query log

clear_sql_statement_log

Clears out the SQL statement log.

sql_statement_log

Returns the current SQL statement log as an array of arrays. Each entry is a list of:

(Time, Statement, [Bindings], Duration, {HookResults})

Bindings is an arrayref of the values of any placeholders. HookResults is a hashref keyed by hook name.

auto_commit [MODE]

Turns on the Database Handle's Autocommit attribute.

disconnect

disconnect from your DBI datasource

dbh [HANDLE]

Return the current DBI handle. If we're handed a parameter, make the database handle that.

delete $table_NAME @KEY_VALUE_PAIRS

Takes a table name and a set of key-value pairs in an array. splits the key value pairs, constructs an DELETE statement and performs the delete. Returns the row_id of this row.

insert $table_NAME @KEY_VALUE_PAIRS

Takes a table name and a set of key-value pairs in an array. splits the key value pairs, constructs an INSERT statement and performs the insert. Returns the row_id of this row.

update_record_value

Takes a hash with columns: table, column, value, primary_keys, and is_sql_function. The first two should be obvious; value is where you set the new value you want the column to have. The primary_keys column should be the lvalue of Jifty::DBI::Record::PrimaryKeys(). Finally , is_sql_function is set when the Value is a SQL function. For example, you might have value => 'PASSWORD(string)', by setting is_sql_function to true, that string will be inserted into the query directly rather then as a binding.

update_table_value table COLUMN NEW_value RECORD_ID IS_SQL

Update column COLUMN of table table where the record id = RECORD_ID.

If IS_SQL is set, don't quote the NEW_VALUE.

simple_query QUERY_STRING, [ BIND_VALUE, ... ]

Execute the SQL string specified in QUERY_STRING

fetch_result QUERY, [ BIND_VALUE, ... ]

Takes a SELECT query as a string, along with an array of BIND_VALUEs If the select succeeds, returns the first row as an array. Otherwise, returns a Class::ResturnValue object with the failure loaded up.

blob_params COLUMN_NAME COLUMN_TYPE

Returns a hash ref for the bind_param call to identify BLOB types used by the current database for a particular column type.

database_version

Returns the database's version.

If argument short is true returns short variant, in other case returns whatever database handle/driver returns. By default returns short version, e.g. '4.1.23' or '8.0-rc4'.

Returns empty string on error or if database couldn't return version.

The base implementation uses a SELECT VERSION()

case_sensitive

Returns 1 if the current database's searches are case sensitive by default Returns undef otherwise

_make_clause_case_insensitive column operator VALUE

Takes a column, operator and value. performs the magic necessary to make your database treat this clause as case insensitive.

Returns a column operator value triple.

begin_transaction

Tells Jifty::DBI to begin a new SQL transaction. This will temporarily suspend Autocommit mode.

Emulates nested transactions, by keeping a transaction stack depth.

commit

Tells Jifty::DBI to commit the current SQL transaction. This will turn Autocommit mode back on.

rollback [FORCE]

Tells Jifty::DBI to abort the current SQL transaction. This will turn Autocommit mode back on.

If this method is passed a true argument, stack depth is blown away and the outermost transaction is rolled back

force_rollback

Force the handle to rollback. Whether or not we're deep in nested transactions

transaction_depth

Return the current depth of the faked nested transaction stack.

apply_limits STATEMENTREF ROWS_PER_PAGE FIRST_ROW

takes an SQL SELECT statement and massages it to return ROWS_PER_PAGE starting with FIRST_ROW;

join { Paramhash }

Takes a paramhash of everything Jifty::DBI::Collection's join method takes, plus a parameter called collection that contains a ref to a Jifty::DBI::Collection object'.

This performs the join.

may_be_null

Takes a collection and alias in a hash and returns true if restrictions of the query allow NULLs in a table joined with the alias, otherwise returns false value which means that you can use normal join instead of left for the aliased table.

Works only for queries have been built with "join" in Jifty::DBI::Collection and "limit" in Jifty::DBI::Collection methods, for other cases return true value to avoid fault optimizations.

distinct_query STATEMENTREF

takes an incomplete SQL SELECT statement and massages it to return a DISTINCT result set.

distinct_count STATEMENTREF