Jifty::DBI::Handle(3p)

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_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.

  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.

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

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

  log MESSAGE
Takes a single argument, a message to log.

Currently prints that message to STDERR

  DESTROY
When we get rid of the Jifty::DBI::Handle, we need to disconnect from the database

DIAGNOSIS
Setting "JIFTY_DBQUERY_CALLER" environment variable will make Jifty::DBI dump the caller for the SQL queries matching it. See also "DBI" about setting "DBI_PROFILE".

AUTHOR
Jesse Vincent, jesse@fsck.com

SEE ALSO
perl(1), Jifty::DBI