DBIx::SearchBuilder::Handle(3pm)

1SearchBuilder::Handle(3U)ser Contributed Perl DocumentatiSoenarchBuilder::Handle(3)
2
3
4

NAME

6       DBIx::SearchBuilder::Handle - Perl extension which is a generic DBI
7       handle
8

SYNOPSIS

10         use DBIx::SearchBuilder::Handle;
11
12         my $handle = DBIx::SearchBuilder::Handle->new();
13         $handle->Connect( Driver => 'mysql',
14                           Database => 'dbname',
15                           Host => 'hostname',
16                           User => 'dbuser',
17                           Password => 'dbpassword');
18         # now $handle isa DBIx::SearchBuilder::Handle::mysql
19

DESCRIPTION

21       This class provides a wrapper for DBI handles that can also perform a
22       number of additional functions.
23
24       new
25
26       Generic constructor
27
28       Connect PARAMHASH: Driver, Database, Host, User, Password
29
30       Takes a paramhash and connects to your DBI datasource.
31
32       You should _always_ set
33
34            DisconnectHandleOnDestroy => 1
35
36       unless you have a legacy app like RT2 or RT 3.0.{0,1,2} that depends on
37       the broken behaviour.
38
39       If you created the handle with
40            DBIx::SearchBuilder::Handle->new and there is a DBIx::Search‐
41       Builder::Handle::(Driver) subclass for the driver you have chosen, the
42       handle will be automatically "upgraded" into that subclass.
43
44       _UpgradeHandle DRIVER
45
46       This private internal method turns a plain DBIx::SearchBuilder::Handle
47       into one of the standard driver-specific subclasses.
48
49       BuildDSN PARAMHASH
50
51       Takes a bunch of parameters:
52
53       Required: Driver, Database, Optional: Host, Port and RequireSSL
54
55       Builds a DSN suitable for a DBI connection
56
57       DSN
58
59           Returns the DSN for this database connection.
60
61       RaiseError [MODE]
62
63       Turns on the Database Handle's RaiseError attribute.
64
65       PrintError [MODE]
66
67       Turns on the Database Handle's PrintError attribute.
68
69       LogSQLStatements BOOL
70
71       Takes a boolean argument. If the boolean is true, SearchBuilder will
72       log all SQL statements, as well as their invocation times and execution
73       times.
74
75       Returns whether we're currently logging or not as a boolean
76
77       _LogSQLStatement STATEMENT DURATION
78
79       add an SQL statement to our query log
80
81       ClearSQLStatementLog
82
83       Clears out the SQL statement log.
84
85       SQLStatementLog
86
87       Returns the current SQL statement log as an array of arrays. Each entry
88       is a triple of
89
90       (Time,  Statement, Duration)
91
92       AutoCommit [MODE]
93
94       Turns on the Database Handle's AutoCommit attribute.
95
96       Disconnect
97
98       Disconnect from your DBI datasource
99
100       dbh [HANDLE]
101
102       Return the current DBI handle. If we're handed a parameter, make the
103       database handle that.
104
105       Insert $TABLE_NAME @KEY_VALUE_PAIRS
106
107       Takes a table name and a set of key-value pairs in an array.  Splits
108       the key value pairs, constructs an INSERT statement and performs the
109       insert.
110
111       Base class return statement handle object, while DB specific subclass
112       should return row id.
113
114       InsertQueryString $TABLE_NAME @KEY_VALUE_PAIRS
115
116       Takes a table name and a set of key-value pairs in an array.  Splits
117       the key value pairs, constructs an INSERT statement and returns query
118       string and set of bind values.
119
120       This method is more useful for subclassing in DB specific handles.
121       "Insert" method is prefered for end users.
122
123       UpdateRecordValue
124
125       Takes a hash with fields: Table, Column, Value PrimaryKeys, and IsSQL‐
126       Function.  Table, and Column should be obvious, Value is where you set
127       the new value you want the column to have. The primary_keys field
128       should be the lvalue of DBIx::SearchBuilder::Record::PrimaryKeys().
129       Finally IsSQLFunction is set when the Value is a SQL function.  For
130       example, you might have ('Value'=>'PASSWORD(string)'), by setting
131       IsSQLFunction that string will be inserted into the query directly
132       rather then as a binding.
133
134       UpdateTableValue TABLE COLUMN NEW_VALUE RECORD_ID IS_SQL
135
136       Update column COLUMN of table TABLE where the record id = RECORD_ID.
137       if IS_SQL is set, don\'t quote the NEW_VALUE
138
139       SimpleQuery QUERY_STRING, [ BIND_VALUE, ... ]
140
141       Execute the SQL string specified in QUERY_STRING
142
143       FetchResult QUERY, [ BIND_VALUE, ... ]
144
145       Takes a SELECT query as a string, along with an array of BIND_VALUEs If
146       the select succeeds, returns the first row as an array.  Otherwise,
147       returns a Class::ResturnValue object with the failure loaded up.
148
149       BinarySafeBLOBs
150
151       Returns 1 if the current database supports BLOBs with embedded nulls.
152       Returns undef if the current database doesn't support BLOBs with embed‐
153       ded nulls
154
155       KnowsBLOBs
156
157       Returns 1 if the current database supports inserts of BLOBs automati‐
158       cally.  Returns undef if the current database must be informed of BLOBs
159       for inserts.
160
161       BLOBParams FIELD_NAME FIELD_TYPE
162
163       Returns a hash ref for the bind_param call to identify BLOB types used
164       by the current database for a particular column type.
165
166       DatabaseVersion [Short => 1]
167
168       Returns the database's version.
169
170       If argument "Short" is true returns short variant, in other case
171       returns whatever database handle/driver returns. By default returns
172       short version, e.g. '4.1.23' or '8.0-rc4'.
173
174       Returns empty string on error or if database couldn't return version.
175
176       The base implementation uses a "SELECT VERSION()"
177
178       CaseSensitive
179
180       Returns 1 if the current database's searches are case sensitive by
181       default Returns undef otherwise
182
183       _MakeClauseCaseInsensitive FIELD OPERATOR VALUE
184
185       Takes a field, operator and value. performs the magic necessary to make
186       your database treat this clause as case insensitive.
187
188       Returns a FIELD OPERATOR VALUE triple.
189
190       Transactions
191
192       DBIx::SearchBuilder::Handle emulates nested transactions, by keeping a
193       transaction stack depth.
194
195       NOTE: In nested transactions you shouldn't mix rollbacks and commits,
196       because only last action really do commit/rollback. For example next
197       code would produce desired results:
198
199         $handle->BeginTransaction;
200           $handle->BeginTransaction;
201           ...
202           $handle->Rollback;
203           $handle->BeginTransaction;
204           ...
205           $handle->Commit;
206         $handle->Commit;
207
208       Only last action(Commit in example) finilize transaction in DB.
209
210       BeginTransaction
211
212       Tells DBIx::SearchBuilder to begin a new SQL transaction.  This will
213       temporarily suspend Autocommit mode.
214
215       EndTransaction [Action => 'commit'] [Force => 0]
216
217       Tells to end the current transaction. Takes "Action" argument that
218       could be "commit" or "rollback", the default value is "commit".
219
220       If "Force" argument is true then all nested transactions would be com‐
221       mitted or rolled back.
222
223       If there is no transaction in progress then method throw warning unless
224       action is forced.
225
226       Method returns true on success or false if error occured.
227
228       Commit [FORCE]
229
230       Tells to commit the current SQL transaction.
231
232       Method uses "EndTransaction" method, read its description.
233
234       Rollback [FORCE]
235
236       Tells to abort the current SQL transaction.
237
238       Method uses "EndTransaction" method, read its description.
239
240       ForceRollback
241
242       Force the handle to rollback.  Whether or not we're deep in nested
243       transactions.
244
245       TransactionDepth
246
247       Returns the current depth of the nested transaction stack.  Returns
248       "undef" if there is no connection to database.
249
250       ApplyLimits STATEMENTREF ROWS_PER_PAGE FIRST_ROW
251
252       takes an SQL SELECT statement and massages it to return ROWS_PER_PAGE
253       starting with FIRST_ROW;
254
255       Join { Paramhash }
256
257       Takes a paramhash of everything Searchbuildler::Record does plus a
258       parameter called 'SearchBuilder' that contains a ref to a SearchBuilder
259       object'.
260
261       This performs the join.
262
263       MayBeNull
264
265       Takes a "SearchBuilder" and "ALIAS" in a hash and resturns true if
266       restrictions of the query allow NULLs in a table joined with the ALIAS,
267       otherwise returns false value which means that you can use normal join
268       instead of left for the aliased table.
269
270       Works only for queries have been built with "Join" in DBIx::Search‐
271       Builder and "Limit" in DBIx::SearchBuilder methods, for other cases
272       return true value to avoid fault optimizations.
273
274       DistinctQuery STATEMENTREF
275
276       takes an incomplete SQL SELECT statement and massages it to return a
277       DISTINCT result set.
278
279       DistinctCount STATEMENTREF
280
281       takes an incomplete SQL SELECT statement and massages it to return a
282       DISTINCT result set.
283
284       Log MESSAGE
285
286       Takes a single argument, a message to log.
287
288       Currently prints that message to STDERR
289
290       DESTROY
291
292       When we get rid of the Searchbuilder::Handle, we need to disconnect
293       from the database
294

AUTHOR

296       Jesse Vincent, jesse@fsck.com
297

NAME

SYNOPSIS

DESCRIPTION

AUTHOR

SEE ALSO