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: Driver, Database, Host, User, Password

Takes a paramhash and connects to your DBI datasource.

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_statement STATEMENT DURATION

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)

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.

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 PrimaryKeys, and IsSQLFunction. Table, and Column 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 IsSQLFunction is set when the Value is a SQL function. For example, you might have ('Value'=>'PASSWORD(string)'), by setting IsSQLFunction 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_depthh

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.

distinct_query STATEMENTREF

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

distinct_count STATEMENTREF