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.

       If there is an error, an exception will be thrown. If a connection has already been
       established and is still active, "undef" will be returned (which is not an error).
       Otherwise, if a new connection is made, a true value will be returned.

   _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 MESSAGE
       Takes a single argument, a message to log.

       Currently prints that message to STDERR

   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, and inspected, by name.

       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.

   quote_value VALUE
       Calls the database's "quote" in DBD method and returns the result.  Additionally, turns on
       perl's utf8 flag if the returned content is UTF8.

   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
       takes an incomplete SQL SELECT statement and massages it to return a DISTINCT result set.

   canonical_true
       This returns the canonical true value for this database. For example, in SQLite it is 1
       but in Postgres it is 't'.

       The default is 1.

   canonical_false
       This returns the canonical false value for this database. For example, in SQLite it is 0
       but in Postgres it is 'f'.

       The default is 0.

   Schema manipulation methods
       rename_column

       Rename a column in a table. Takes 'table', 'column' and new name in 'to'.

       rename_table

       Renames a table in the DB. Takes 'table' and new name of it in 'to'.

   supported_drivers
       Returns a list of the drivers Jifty::DBI supports.

   available_drivers
       Returns a list of the available drivers based on the presence of "DBD::*" modules.

   is_available_driver
       Returns a boolean indicating whether the provided driver is available.

   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@bestpractical.com>

SEE ALSO

       perl(1), Jifty::DBI