DBIx::Simple(3pm)

1DBIx::Simple(3)       User Contributed Perl Documentation      DBIx::Simple(3)
2
3
4

NAME

6       DBIx::Simple - Easy-to-use OO interface to DBI
7

SYNOPSIS

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

DESCRIPTION

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

MISCELLANEOUS

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

LICENSE

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

AUTHOR

369       Juerd Waalboer <juerd@cpan.org> <http://juerd.nl/>
370

NAME

SYNOPSIS

DESCRIPTION

MISCELLANEOUS

LICENSE

AUTHOR

SEE ALSO