--- name: "Jifty::DBI::Handle" section: "3pm" platform: "linux" package: "libjifty-dbi-perl" version: "0.78-3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Jifty::DBI::Handle" --- # Jifty::DBI::Handle(3pm) Perl extension which is a generic DBI handle ## 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, \ ## SEE ALSO [**perl**(1)](/perl/1.md), Jifty::DBI