1DBIx::Simple(3) User Contributed Perl Documentation DBIx::Simple(3)
2
3
4
6 DBIx::Simple - Easy-to-use OO interface to DBI
7
9 DBIx::Simple
10 $db = DBIx::Simple->connect(...) # or ->new
11
12 $db->keep_statements = 16
13 $db->lc_columns = 1
14 $db->result_class = 'DBIx::Simple::Result';
15
16 $db->begin_work $db->commit
17 $db->rollback $db->disconnect
18 $db->func(...) $db->last_insert_id
19
20 $result = $db->query(...)
21
22 DBIx::SImple + SQL::Interp
23 $result = $db->iquery(...)
24
25 DBIx::Simple + SQL::Abstract
26 $db->abstract = SQL::Abstract->new(...)
27
28 $result = $db->select(...)
29 $result = $db->insert(...)
30 $result = $db->update(...)
31 $result = $db->delete(...)
32
33 DBIx::Simple::Result
34 @columns = $result->columns
35
36 $result->into($foo, $bar, $baz)
37 $row = $result->fetch
38
39 @row = $result->list @rows = $result->flat
40 $row = $result->array @rows = $result->arrays
41 $row = $result->hash @rows = $result->hashes
42
43 %map = $result->map_arrays(...)
44 %map = $result->map_hashes(...)
45 %map = $result->map
46
47 $rows = $result->rows
48
49 $dump = $result->text
50
51 $result->finish
52
53 DBIx::Simple::Result + DBIx::XHTML_Table
54 $html = $result->html(...)
55
56 $table_object = $result->xto(...)
57
58 Examples
59 Please read DBIx::Simple::Examples for code examples.
60
62 DBIx::Simple provides a simplified interface to DBI, Perl's powerful
63 database module.
64
65 This module is aimed at rapid development and easy maintenance. Query
66 preparation and execution are combined in a single method, the result
67 object (which is a wrapper around the statement handle) provides easy
68 row-by-row and slurping methods.
69
70 The "query" method returns either a result object, or a dummy object.
71 The dummy object returns undef (or an empty list) for all methods and
72 when used in boolean context, is false. The dummy object lets you
73 postpone (or skip) error checking, but it also makes immediate error
74 checking simply "$db->query(...) or die $db->error".
75
76 DBIx::Simple methods
77 "DBIx::Simple->connect($dbh)"
78 "DBIx::Simple->connect($dsn, $user, $pass, \%options)"
79 "DBIx::Simple->new($dbh)"
80 "DBIx::Simple->new($dsn, $user, $pass, \%options)"
81 The "connect" or "new" class method takes either an existing DBI
82 object ($dbh), or a list of arguments to pass to "DBI->connect".
83 See DBI for a detailed description.
84
85 You cannot use this method to clone a DBIx::Simple object: the $dbh
86 passed should be a DBI::db object, not a DBIx::Simple object.
87
88 This method is the constructor and returns a DBIx::Simple object on
89 success. On failure, it returns undef.
90
91 "lc_columns = $bool"
92 When true at time of query execution, makes "columns", "hash",
93 "hashes", and "map_hashes" use lower cased column names.
94 "lc_columns" is true by default.
95
96 "keep_statements = $integer"
97 Sets the number of statement objects that DBIx::Simple can keep for
98 reuse. This can dramatically speed up repeated queries (like when
99 used in a loop). "keep_statements" is 16 by default.
100
101 A query is only reused if it equals a previously used one
102 literally. This means that to benefit from this caching mechanism,
103 you must use placeholders and never interpolate variables yourself.
104
105 # Wrong:
106 $db->query("INSERT INTO foo VALUES ('$foo', '$bar', '$baz')");
107 $db->query("SELECT FROM foo WHERE foo = '$foo' OR bar = '$bar'");
108
109 # Right:
110 $db->query('INSERT INTO foo VALUES (??)', $foo, $bar, $baz);
111 $db->query('SELECT FROM foo WHERE foo = ? OR bar = ?', $foo, $baz);
112
113 Of course, automatic value escaping is a much better reason for
114 using placeholders.
115
116 "result_class = $string"
117 Class to use for result objects. Defaults to DBIx::Simple::Result.
118 A constructor is not used.
119
120 "error"
121 Returns the error string of the last DBI method. See the discussion
122 of ""err"" and ""errstr"" in DBI.
123
124 "query($query, @values)"
125 The "query" method prepares and executes the query and returns a
126 result object.
127
128 If the string "(??)" is present in the query, it is replaced with a
129 list of as many question marks as @values.
130
131 The database drivers substitute placeholders (question marks that
132 do not appear in quoted literals) in the query with the given
133 @values, after them escaping them. You should always use
134 placeholders, and never use raw user input in database queries.
135
136 On success, returns a DBIx::Simple::Result object.
137
138 On failure, returns a DBIx::Simple::Dummy object.
139
140 "iquery"
141 Uses SQL::Interp to interpolate values into a query, and uses the
142 resulting generated query and bind arguments with "query".
143
144 See SQL::Interp's documentation for usage information.
145
146 Requires that Mark Stosberg's SQL::Interp module be installed. It
147 is available from CPAN. SQL::Interp is a fork from David Manura's
148 SQL::Interpolate.
149
150 "select", "insert", "update", "delete"
151 Calls the respective method on "abstract", and uses the resulting
152 generated query and bind arguments with "query".
153
154 See SQL::Abstract's documentation for usage information. You can
155 override the object by assigning to the "abstract" property.
156
157 Obviously, calling "query" directly is faster for the computer and
158 using these abstracting methods is faster for the programmer.
159
160 "abstract = SQL::Abstract->new(...)"
161 Sets the object to use with the "select", "insert", "update" and
162 "delete" methods. On first access, will create one with
163 SQL::Abstract's default options.
164
165 Requires that Nathan Wiger's SQL::Abstract module be installed. It
166 is available from CPAN.
167
168 In theory, you can assign any object to this property, as long as
169 that object has these four methods, and they return a list suitable
170 for use with the "query" method.
171
172 "begin_work", "begin", "commit", "rollback"
173 These transaction related methods call the DBI respective methods
174 and Do What You Mean. See DBI for details.
175
176 "begin" is an alias for "begin_work".
177
178 "func(...)"
179 This calls the "func" method of DBI. See DBI for details.
180
181 "last_insert_id(...)"
182 This calls the "last_insert_id" method of DBI. See DBI for details.
183 Note that this feature requires DBI 1.38 or newer.
184
185 "dbh"
186 Exposes the internal database handle. Use this only if you know
187 what you are doing. Keeping a reference or doing queries can
188 interfere with DBIx::Simple's garbage collection and error
189 reporting.
190
191 "disconnect"
192 Destroys (finishes) active statements and disconnects. Whenever the
193 database object is destroyed, this happens automatically if
194 DBIx::Simple handled the connection (i.e. you didn't use an
195 existing DBI handle). After disconnecting, you can no longer use
196 the database object or any of its result objects.
197
198 DBIx::Simple::Dummy
199 The "query" method of DBIx::Simple returns a dummy object on failure.
200 Its methods all return an empty list or undef, depending on context.
201 When used in boolean context, a dummy object evaluates to false.
202
203 DBIx::Simple::Result methods
204 "columns" Returns a list of column names. In scalar context, returns
205 an array reference.
206
207 Column names are lower cased if "lc_columns" was true when
208 the query was executed.
209
210 "bind(LIST)"
211 Binds the given LIST to the columns. The elements of LIST
212 must be writable LVALUEs. In other words, use this method
213 as:
214
215 $result->bind(my ($foo, $bar));
216 $result->fetch;
217
218 Or, combined:
219
220 $result->into(my ($foo, $bar));
221
222 Unlike with DBI's "bind_columns", the "\" operator is not
223 needed.
224
225 Bound variables are very efficient. Binding a tied variable
226 doesn't work.
227
228 "fetch" Fetches a single row and returns a reference to the array
229 that holds the values. This is the same array every time.
230
231 Subsequent fetches (using any method) may change the values
232 in the variables passed and the returned reference's array.
233
234 "into(LIST)"
235 Combines "bind" with "fetch". Returns what "fetch" returns.
236
237 "list" Fetches a single row and returns a list of values. In
238 scalar context, returns only the last value.
239
240 "array" Fetches a single row and returns an array reference.
241
242 "hash" Fetches a single row and returns a hash reference.
243
244 Keys are lower cased if "lc_columns" was true when the
245 query was executed.
246
247 "flat" Fetches all remaining rows and returns a flattened list.
248
249 In scalar context, returns an array reference.
250
251 "arrays" Fetches all remaining rows and returns a list of array
252 references.
253
254 In scalar context, returns an array reference.
255
256 "hashes" Fetches all remaining rows and returns a list of hash
257 references.
258
259 In scalar context, returns an array reference.
260
261 Keys are lower cased if "lc_columns" was true when the
262 query was executed.
263
264 "map_arrays($column_number)"
265 Constructs a hash of array references keyed by the values
266 in the chosen column.
267
268 In scalar context, returns a hash reference.
269
270 In list context, returns interleaved keys and values.
271
272 "map_hashes($column_name)"
273 Constructs a hash of hash references keyed by the values in
274 the chosen column.
275
276 In scalar context, returns a hash reference.
277
278 In list context, returns interleaved keys and values.
279
280 "map" Constructs a simple hash, using the two columns as
281 key/value pairs. Should only be used with queries that
282 return two columns.
283
284 In scalar context, returns a hash reference.
285
286 In list context, returns interleaved keys and values.
287
288 "rows" Returns the number of rows affected by the last row
289 affecting command, or -1 if the number of rows is not known
290 or not available.
291
292 For SELECT statements, it is generally not possible to know
293 how many rows are returned. MySQL does provide this
294 information. See DBI for a detailed explanation.
295
296 "xto(%attr)"
297 Returns a DBIx::XHTML_Table object, passing the constructor
298 a reference to %attr.
299
300 Requires that Jeffrey Hayes Anderson's DBIx::XHTML_Table
301 module be installed. It is available from CPAN.
302
303 In general, using the "html" method (described below) is
304 much easier. "xto" is available in case you need more
305 flexibility.
306
307 This method ignores the "lc_columns" property.
308
309 "html(%attr)"
310 Returns an (X)HTML formatted table, using the
311 DBIx::XHTML_Table module. Passes a reference to %attr to
312 both the constructor and the "output" method.
313
314 Requires that Jeffrey Hayes Anderson's DBIx::XHTML_Table
315 module be installed. It is available from CPAN.
316
317 This method is a shortcut method. That means that
318
319 $result->html
320
321 $result->html(
322 tr => { bgcolor => [ 'silver', 'white' ] },
323 no_ucfirst => 1
324 )
325
326 do the same as:
327
328 $result->xto->output
329
330 $result->xto(
331 tr => { bgcolor => [ 'silver', 'white' ] }
332 )->output(
333 no_ucfirst => 1
334 );
335
336 "text($type)"
337 Returns a string with a simple text representation of the
338 data. $type can be any of: "neat", "table", "box". It
339 defaults to "table" if Text::Table is installed, to "neat"
340 if it is.
341
342 "table" and "box" require that Anno Siegel's Text::Table
343 module be installed. It is available from CPAN.
344
345 "attr(...)" Returns a copy of an sth attribute (property). See
346 "Statement Handle Attributes" in DBI for details.
347
348 "func(...)" This calls the "func" method of DBI. See DBI for details.
349
350 "finish" Finishes the statement. After finishing a statement, it can
351 no longer be used. When the result object is destroyed,
352 its statement handle is automatically finished and
353 destroyed. There should be no reason to call this method
354 explicitly; just let the result object go out of scope.
355
357 The mapping methods do not check whether the keys are unique. Rows that
358 are fetched later overwrite earlier ones.
359
360 PrintError is disabled by default. If you enable it, beware that it
361 will report line numbers in DBIx/Simple.pm.
362
364 There is no license. This software was released into the public domain.
365 Do with it what you want, but on your own risk. The author disclaims
366 any responsibility.
367
369 Juerd Waalboer <juerd@cpan.org> <http://juerd.nl/>
370
372 perl, perlref
373
374 DBI, DBIx::Simple::Examples, SQL::Abstract, DBIx::XHTML_Table
375
376
377
378perl v5.10.1 2007-09-17 DBIx::Simple(3)