.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Jifty::DBI::Handle 3pm"
.TH Jifty::DBI::Handle 3pm "2014-05-29" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Jifty::DBI::Handle \- Perl extension which is a generic DBI handle
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Jifty::DBI::Handle;
\&
\&  my $handle = Jifty::DBI::Handle\->new();
\&  $handle\->connect( driver => \*(Aqmysql\*(Aq,
\&                    database => \*(Aqdbname\*(Aq,
\&                    host => \*(Aqhostname\*(Aq,
\&                    user => \*(Aqdbuser\*(Aq,
\&                    password => \*(Aqdbpassword\*(Aq);
\&  # now $handle isa Jifty::DBI::Handle::mysql
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class provides a wrapper for \s-1DBI\s0 handles that can also perform a
number of additional functions.
.SS "new"
.IX Subsection "new"
Generic constructor
.SS "connect \s-1PARAMHASH\s0"
.IX Subsection "connect PARAMHASH"
Takes a paramhash and connects to your \s-1DBI\s0 datasource, with the keys \f(CW\*(C`driver\*(C'\fR,
\&\f(CW\*(C`database\*(C'\fR, \f(CW\*(C`host\*(C'\fR, \f(CW\*(C`user\*(C'\fR and \f(CW\*(C`password\*(C'\fR.
.PP
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 \*(L"upgraded\*(R" into that subclass.
.PP
If there is an error, an exception will be thrown. If a connection has already
been established and is still active, \f(CW\*(C`undef\*(C'\fR will be returned (which is not
an error). Otherwise, if a new connection is made, a true value will be returned.
.SS "_upgrade_handle \s-1DRIVER\s0"
.IX Subsection "_upgrade_handle DRIVER"
This private internal method turns a plain Jifty::DBI::Handle into one
of the standard driver-specific subclasses.
.SS "build_dsn \s-1PARAMHASH\s0"
.IX Subsection "build_dsn PARAMHASH"
Builds a dsn suitable for handing to \s-1DBI\-\s0>connect.
.PP
Mandatory arguments:
.IP "driver" 4
.IX Item "driver"
.PD 0
.IP "database" 4
.IX Item "database"
.PD
.PP
Optional arguments:
.IP "host" 4
.IX Item "host"
.PD 0
.IP "port" 4
.IX Item "port"
.IP "sid" 4
.IX Item "sid"
.IP "requiressl" 4
.IX Item "requiressl"
.IP "and anything else your \s-1DBD\s0 lets you pass in" 4
.IX Item "and anything else your DBD lets you pass in"
.PD
.SS "dsn"
.IX Subsection "dsn"
Returns the dsn for this database connection.
.SS "raise_error [\s-1MODE\s0]"
.IX Subsection "raise_error [MODE]"
Turns on the Database Handle's RaiseError attribute.
.SS "print_error [\s-1MODE\s0]"
.IX Subsection "print_error [MODE]"
Turns on the Database Handle's PrintError attribute.
.SS "log \s-1MESSAGE\s0"
.IX Subsection "log MESSAGE"
Takes a single argument, a message to log.
.PP
Currently prints that message to \s-1STDERR\s0
.SS "log_sql_statements \s-1BOOL\s0"
.IX Subsection "log_sql_statements BOOL"
Takes a boolean argument. If the boolean is true, it will log all \s-1SQL\s0
statements, as well as their invocation times and execution times.
.PP
Returns whether we're currently logging or not as a boolean
.SS "log_sql_hook \s-1NAME\s0 [, \s-1CODE\s0]"
.IX Subsection "log_sql_hook NAME [, CODE]"
Used in instrumenting the \s-1SQL\s0 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.
.PP
The coderef is run in scalar context and (currently) receives no arguments.
.PP
If you don't pass \s-1CODE\s0 in, then the coderef currently assigned under
\&\s-1NAME\s0 is returned.
.SS "_log_sql_statement \s-1STATEMENT DURATION BINDINGS\s0"
.IX Subsection "_log_sql_statement STATEMENT DURATION BINDINGS"
add an \s-1SQL\s0 statement to our query log
.SS "clear_sql_statement_log"
.IX Subsection "clear_sql_statement_log"
Clears out the \s-1SQL\s0 statement log.
.SS "sql_statement_log"
.IX Subsection "sql_statement_log"
Returns the current \s-1SQL\s0 statement log as an array of arrays. Each entry is a list of:
.PP
(Time, Statement, [Bindings], Duration, {HookResults})
.PP
Bindings is an arrayref of the values of any placeholders. HookResults is a
hashref keyed by hook name.
.SS "auto_commit [\s-1MODE\s0]"
.IX Subsection "auto_commit [MODE]"
Turns on the Database Handle's Autocommit attribute.
.SS "disconnect"
.IX Subsection "disconnect"
disconnect from your \s-1DBI\s0 datasource
.SS "dbh [\s-1HANDLE\s0]"
.IX Subsection "dbh [HANDLE]"
Return the current \s-1DBI\s0 handle. If we're handed a parameter, make the database handle that.
.ie n .SS "delete $table_NAME @KEY_VALUE_PAIRS"
.el .SS "delete \f(CW$table_NAME\fP \f(CW@KEY_VALUE_PAIRS\fP"
.IX Subsection "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 \s-1DELETE\s0 statement and performs the delete. Returns the row_id of this row.
.ie n .SS "insert $table_NAME @KEY_VALUE_PAIRS"
.el .SS "insert \f(CW$table_NAME\fP \f(CW@KEY_VALUE_PAIRS\fP"
.IX Subsection "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 \s-1INSERT\s0 statement and performs the insert. Returns the row_id of this row.
.SS "update_record_value"
.IX Subsection "update_record_value"
Takes a hash with columns: \f(CW\*(C`table\*(C'\fR, \f(CW\*(C`column\*(C'\fR, \f(CW\*(C`value\*(C'\fR, \f(CW\*(C`primary_keys\*(C'\fR, and
\&\f(CW\*(C`is_sql_function\*(C'\fR.  The first two should be obvious; \f(CW\*(C`value\*(C'\fR is where you 
set the new value you want the column to have. The \f(CW\*(C`primary_keys\*(C'\fR column should 
be the lvalue of \fIJifty::DBI::Record::PrimaryKeys()\fR.  Finally ,
\&\f(CW\*(C`is_sql_function\*(C'\fR is set when the Value is a \s-1SQL\s0 function.  For example, you 
might have \f(CW\*(C`value => \*(AqPASSWORD(string)\*(Aq\*(C'\fR, by setting \f(CW\*(C`is_sql_function\*(C'\fR to true,
that string will be inserted into the query directly rather then as a binding.
.SS "update_table_value table \s-1COLUMN\s0 NEW_value \s-1RECORD_ID IS_SQL\s0"
.IX Subsection "update_table_value table COLUMN NEW_value RECORD_ID IS_SQL"
Update column \s-1COLUMN\s0 of table table where the record id = \s-1RECORD_ID.\s0
.PP
If \s-1IS_SQL\s0 is set, don't quote the \s-1NEW_VALUE.\s0
.SS "simple_query \s-1QUERY_STRING,\s0 [ \s-1BIND_VALUE, ... \s0]"
.IX Subsection "simple_query QUERY_STRING, [ BIND_VALUE, ... ]"
Execute the \s-1SQL\s0 string specified in \s-1QUERY_STRING\s0
.SS "fetch_result \s-1QUERY,\s0 [ \s-1BIND_VALUE, ... \s0]"
.IX Subsection "fetch_result QUERY, [ BIND_VALUE, ... ]"
Takes a \s-1SELECT\s0 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.
.SS "blob_params \s-1COLUMN_NAME COLUMN_TYPE\s0"
.IX Subsection "blob_params COLUMN_NAME COLUMN_TYPE"
Returns a hash ref for the bind_param call to identify \s-1BLOB\s0 types used
by the current database for a particular column type.
.SS "database_version"
.IX Subsection "database_version"
Returns the database's version.
.PP
If argument \f(CW\*(C`short\*(C'\fR is true returns short variant, in other
case returns whatever database handle/driver returns. By default
returns short version, e.g. \f(CW4.1.23\fR or \f(CW\*(C`8.0\-rc4\*(C'\fR.
.PP
Returns empty string on error or if database couldn't return version.
.PP
The base implementation uses a \f(CW\*(C`SELECT VERSION()\*(C'\fR
.SS "case_sensitive"
.IX Subsection "case_sensitive"
Returns 1 if the current database's searches are case sensitive by default
Returns undef otherwise
.SS "_make_clause_case_insensitive column operator \s-1VALUE\s0"
.IX Subsection "_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.
.PP
Returns a column operator value triple.
.SS "quote_value \s-1VALUE\s0"
.IX Subsection "quote_value VALUE"
Calls the database's \*(L"quote\*(R" in \s-1DBD\s0 method and returns the result.
Additionally, turns on perl's utf8 flag if the returned content is
\&\s-1UTF8.\s0
.SS "begin_transaction"
.IX Subsection "begin_transaction"
Tells Jifty::DBI to begin a new \s-1SQL\s0 transaction. This will
temporarily suspend Autocommit mode.
.PP
Emulates nested transactions, by keeping a transaction stack depth.
.SS "commit"
.IX Subsection "commit"
Tells Jifty::DBI to commit the current \s-1SQL\s0 transaction. 
This will turn Autocommit mode back on.
.SS "rollback [\s-1FORCE\s0]"
.IX Subsection "rollback [FORCE]"
Tells Jifty::DBI to abort the current \s-1SQL\s0 transaction. 
This will turn Autocommit mode back on.
.PP
If this method is passed a true argument, stack depth is blown away and the outermost transaction is rolled back
.SS "force_rollback"
.IX Subsection "force_rollback"
Force the handle to rollback. Whether or not we're deep in nested transactions
.SS "transaction_depth"
.IX Subsection "transaction_depth"
Return the current depth of the faked nested transaction stack.
.SS "apply_limits \s-1STATEMENTREF ROWS_PER_PAGE FIRST_ROW\s0"
.IX Subsection "apply_limits STATEMENTREF ROWS_PER_PAGE FIRST_ROW"
takes an \s-1SQL SELECT\s0 statement and massages it to return \s-1ROWS_PER_PAGE\s0 starting with \s-1FIRST_ROW\s0;
.SS "join { Paramhash }"
.IX Subsection "join { Paramhash }"
Takes a paramhash of everything Jifty::DBI::Collection's \f(CW\*(C`join\*(C'\fR method
takes, plus a parameter called \f(CW\*(C`collection\*(C'\fR that contains a ref to a
Jifty::DBI::Collection object'.
.PP
This performs the join.
.SS "may_be_null"
.IX Subsection "may_be_null"
Takes a \f(CW\*(C`collection\*(C'\fR and \f(CW\*(C`alias\*(C'\fR 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.
.PP
Works only for queries have been built with
\&\*(L"join\*(R" in Jifty::DBI::Collection and \*(L"limit\*(R" in Jifty::DBI::Collection
methods, for other cases return true value to avoid fault
optimizations.
.SS "distinct_query \s-1STATEMENTREF \s0"
.IX Subsection "distinct_query STATEMENTREF "
takes an incomplete \s-1SQL SELECT\s0 statement and massages it to return a \s-1DISTINCT\s0 result set.
.SS "distinct_count \s-1STATEMENTREF \s0"
.IX Subsection "distinct_count STATEMENTREF "
takes an incomplete \s-1SQL SELECT\s0 statement and massages it to return a \s-1DISTINCT\s0 result set.
.SS "canonical_true"
.IX Subsection "canonical_true"
This returns the canonical true value for this database. For example, in SQLite
it is 1 but in Postgres it is 't'.
.PP
The default is 1.
.SS "canonical_false"
.IX Subsection "canonical_false"
This returns the canonical false value for this database. For example, in SQLite
it is 0 but in Postgres it is 'f'.
.PP
The default is 0.
.SS "Schema manipulation methods"
.IX Subsection "Schema manipulation methods"
\fIrename_column\fR
.IX Subsection "rename_column"
.PP
Rename a column in a table. Takes 'table', 'column' and new name in 'to'.
.PP
\fIrename_table\fR
.IX Subsection "rename_table"
.PP
Renames a table in the \s-1DB.\s0 Takes 'table' and new name of it in 'to'.
.SS "supported_drivers"
.IX Subsection "supported_drivers"
Returns a list of the drivers Jifty::DBI supports.
.SS "available_drivers"
.IX Subsection "available_drivers"
Returns a list of the available drivers based on the presence of \f(CW\*(C`DBD::*\*(C'\fR
modules.
.SS "is_available_driver"
.IX Subsection "is_available_driver"
Returns a boolean indicating whether the provided driver is available.
.SS "\s-1DESTROY\s0"
.IX Subsection "DESTROY"
When we get rid of the Jifty::DBI::Handle, we need to disconnect
from the database
.SH "DIAGNOSIS"
.IX Header "DIAGNOSIS"
Setting \f(CW\*(C`JIFTY_DBQUERY_CALLER\*(C'\fR environment variable will make
Jifty::DBI dump the caller for the \s-1SQL\s0 queries matching it.  See
also \f(CW\*(C`DBI\*(C'\fR about setting \f(CW\*(C`DBI_PROFILE\*(C'\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Jesse Vincent, <jesse@bestpractical.com>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperl\fR\|(1), Jifty::DBI