Package list libexception-class-dbi-perl / fresh-snapshots/main
fresh-snapshots/main

Tree @fresh-snapshots/main (Download .tar.gz)

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
NAME

    Exception::Class::DBI - DBI Exception objects

VERSION

    version 1.04

Name

    Exception::Class::DBI - DBI Exception objects

Synopsis

      use DBI;
      use Exception::Class::DBI;
    
      my $dbh = DBI->connect($dsn, $user, $pass, {
          PrintError  => 0,
          RaiseError  => 0,
          HandleError => Exception::Class::DBI->handler,
      });
    
      eval { $dbh->do($sql) };
    
      if (my $ex = $@) {
          print STDERR "DBI Exception:\n";
          print STDERR "  Exception Type: ", ref $ex, "\n";
          print STDERR "  Error:          ", $ex->error, "\n";
          print STDERR "  Err:            ", $ex->err, "\n";
          print STDERR "  Errstr:         ", $ex->errstr, "\n";
          print STDERR "  State:          ", $ex->state, "\n";
          print STDERR "  Return Value:   ", ($ex->retval || 'undef'), "\n";
      }

Description

    This module offers a set of DBI-specific exception classes. They
    inherit from Exception::Class, the base class for all exception objects
    created by the Exception::Class module from the CPAN.
    Exception::Class::DBI itself offers a single class method, handler(),
    that returns a code reference appropriate for passing to the DBI
    HandleError attribute.

    The exception classes created by Exception::Class::DBI are designed to
    be thrown in certain DBI contexts; the code reference returned by
    handler() and passed to the DBI HandleError attribute determines the
    context and throws the appropriate exception.

    Each of the Exception::Class::DBI classes offers a set of object
    accessor methods in addition to those provided by Exception::Class.
    These can be used to output detailed diagnostic information in the
    event of an exception.

Interface

    Exception::Class::DBI inherits from Exception::Class, and thus its
    entire interface. Refer to the Exception::Class documentation for
    details.

 Class Method

    handler

        my $dbh = DBI->connect($data_source, $username, $auth, {
            PrintError  => 0,
            RaiseError  => 0,
            HandleError => Exception::Class::DBI->handler
        });

      This method returns a code reference appropriate for passing to the
      DBI HandleError attribute. When DBI encounters an error, it checks
      its PrintError, RaiseError, and HandleError attributes to decide what
      to do about it. When HandleError has been set to a code reference,
      DBI executes it, passing it the error string that would be printed
      for PrintError, the DBI handle object that was executing the method
      call that triggered the error, and the return value of that method
      call (usually undef). Using these arguments, the code reference
      provided by handler() determines what type of exception to throw.
      Exception::Class::DBI contains the subclasses detailed below, each
      relevant to the DBI handle that triggered the error.

Classes

    Exception::Class::DBI creates a number of exception classes, each one
    specific to a particular DBI error context. Most of the object methods
    described below correspond to like-named attributes in the DBI itself.
    Thus the documentation below summarizes the DBI attribute
    documentation, so you should refer to DBI itself for more in-depth
    information.

 Exception::Class::DBI

    All of the Exception::Class::DBI classes documented below inherit from
    Exception::Class::DBI. It offers the several object methods in addition
    to those it inherits from its parent, Exception::Class. These methods
    correspond to the DBI dynamic attributes, as well as to the values
    passed to the handler() exception handler via the DBI HandleError
    attribute. Exceptions of this base class are only thrown when there is
    no DBI handle object executing, e.g. in the DBI connect() method. Note:
    This functionality is not yet implemented in DBI -- see the discussion
    that starts here:
    http://archive.develooper.com/dbi-dev@perl.org/msg01438.html.

    error

        my $error = $ex->error;

      Exception::Class::DBI actually inherits this method from
      Exception::Class. It contains the error string that DBI prints when
      its PrintError attribute is enabled, or dies with when its
      <RaiseError> attribute is enabled.

    err

        my $err = $ex->err;

      Corresponds to the $DBI::err dynamic attribute. Returns the native
      database engine error code from the last driver method called.

    errstr

        my $errstr = $ex->errstr;

      Corresponds to the $DBI::errstr dynamic attribute. Returns the native
      database engine error message from the last driver method called.

    state

        my $state = $ex->state;

      Corresponds to the $DBI::state dynamic attribute. Returns an error
      code in the standard SQLSTATE five character format.

    retval

        my $retval = $ex->retval;

      The first value being returned by the DBI method that failed
      (typically undef).

    handle

        my $db_handle = $ex->handle;

      The DBI handle appropriate to the exception class. For
      Exception::Class::DBI::DRH, it will be a driver handle. For
      Exception::Class::DBI::DBH it will be a database handle. And for
      Exception::Class::DBI::STH it will be a statement handle. If there is
      no handle thrown in the exception (because, say, the exception was
      thrown before a driver handle could be created), the handle will be
      undef.

 Exception::Class::DBI::H

    This class inherits from Exception::Class::DBI, and is the base class
    for all DBI handle exceptions (see below). It will not be thrown
    directly. Its methods correspond to the DBI attributes common to all
    handles.

    warn

        my $warn = $ex->warn;

      Boolean value indicating whether DBI warnings have been enabled.
      Corresponds to the DBI Warn attribute.

    active

        my $active = $ex->active;

      Boolean value indicating whether the DBI handle that encountered the
      error is active. Corresponds to the DBI Active attribute.

    kids

        my $kids = $ex->kids;

      For a driver handle, Kids is the number of currently existing
      database handles that were created from that driver handle. For a
      database handle, Kids is the number of currently existing statement
      handles that were created from that database handle. Corresponds to
      the DBI Kids attribute.

    active_kids

        my $active_kids = $ex->active_kids;

      Like kids, but only counting those that are active (as above).
      Corresponds to the DBI ActiveKids attribute.

    compat_mode

        my $compat_mode = $ex->compat_mode;

      Boolean value indicating whether an emulation layer (such as Oraperl)
      enables compatible behavior in the underlying driver (e.g.,
      DBD::Oracle) for this handle. Corresponds to the DBI CompatMode
      attribute.

    inactive_destroy

        my $inactive_destroy = $ex->inactive_destroy;

      Boolean value indicating whether the DBI has disabled the database
      engine related effect of DESTROYing a handle. Corresponds to the DBI
      InactiveDestroy attribute.

    trace_level

        my $trace_level = $ex->trace_level;

      Returns the DBI trace level set on the handle that encountered the
      error. Corresponds to the DBI TraceLevel attribute.

    fetch_hash_key_name

        my $fetch_hash_key_name = $ex->fetch_hash_key_name;

      Returns the attribute name the DBI fetchrow_hashref() method should
      use to get the field names for the hash keys. Corresponds to the DBI
      FetchHashKeyName attribute.

    chop_blanks

        my $chop_blanks = $ex->chop_blanks;

      Boolean value indicating whether DBI trims trailing space characters
      from fixed width character (CHAR) fields. Corresponds to the DBI
      ChopBlanks attribute.

    long_read_len

        my $long_read_len = $ex->long_read_len;

      Returns the maximum length of long fields ("blob", "memo", etc.)
      which the DBI driver will read from the database automatically when
      it fetches each row of data. Corresponds to the DBI LongReadLen
      attribute.

    long_trunc_ok

        my $long_trunc_ok = $ex->long_trunc_ok;

      Boolean value indicating whether the DBI will truncate values it
      retrieves from long fields that are longer than the value returned by
      long_read_len(). Corresponds to the DBI LongTruncOk attribute.

    taint

        my $taint = $ex->taint;

      Boolean value indicating whether data fetched from the database is
      considered tainted. Corresponds to the DBI Taint attribute.

 Exception::Class::DBI::DRH

    DBI driver handle exceptions objects. This class inherits from
    Exception::Class::DBI::H, and offers no extra methods of its own.

 Exception::Class::DBI::DBH

    DBI database handle exceptions objects. This class inherits from
    Exception::Class::DBI::H Its methods correspond to the DBI database
    handle attributes.

    auto_commit

        my $auto_commit = $ex->auto_commit;

      Returns true if the database handle AutoCommit attribute is enabled.
      meaning that database changes cannot be rolled back. Corresponds to
      the DBI database handle AutoCommit attribute.

    db_name

        my $db_name = $ex->db_name;

      Returns the "name" of the database. Corresponds to the DBI database
      handle Name attribute.

    statement

        my $statement = $ex->statement;

      Returns the statement string passed to the most recent call to the
      DBI prepare() method in this database handle. If it was the prepare()
      method that encountered the error and triggered the exception, the
      statement string will be the statement passed to prepare().
      Corresponds to the DBI database handle Statement attribute.

    row_cache_size

        my $row_cache_size = $ex->row_cache_size;

      Returns the hint to the database driver indicating the size of the
      local row cache that the application would like the driver to use for
      future SELECT statements. Corresponds to the DBI database handle
      RowCacheSize attribute.

 Exception::Class::DBI::STH

    DBI statement handle exceptions objects. This class inherits from
    Exception::Class::DBI::H Its methods correspond to the DBI statement
    handle attributes.

    num_of_fields

        my $num_of_fields = $ex->num_of_fields;

      Returns the number of fields (columns) the prepared statement will
      return. Corresponds to the DBI statement handle NUM_OF_FIELDS
      attribute.

    num_of_params

        my $num_of_params = $ex->num_of_params;

      Returns the number of parameters (placeholders) in the prepared
      statement. Corresponds to the DBI statement handle NUM_OF_PARAMS
      attribute.

    field_names

        my $field_names = $ex->field_names;

      Returns a reference to an array of field names for each column.
      Corresponds to the DBI statement handle NAME attribute.

    type

        my $type = $ex->type;

      Returns a reference to an array of integer values for each column.
      The value indicates the data type of the corresponding column.
      Corresponds to the DBI statement handle TYPE attribute.

    precision

        my $precision = $ex->precision;

      Returns a reference to an array of integer values for each column.
      For non-numeric columns, the value generally refers to either the
      maximum length or the defined length of the column. For numeric
      columns, the value refers to the maximum number of significant digits
      used by the data type (without considering a sign character or
      decimal point). Corresponds to the DBI statement handle PRECISION
      attribute.

    scale

        my $scale = $ex->scale;

      Returns a reference to an array of integer values for each column.
      Corresponds to the DBI statement handle SCALE attribute.

    nullable

        my $nullable = $ex->nullable;

      Returns a reference to an array indicating the possibility of each
      column returning a null. Possible values are 0 (or an empty string) =
      no, 1 = yes, 2 = unknown. Corresponds to the DBI statement handle
      NULLABLE attribute.

    cursor_name

        my $cursor_name = $ex->cursor_name;

      Returns the name of the cursor associated with the statement handle,
      if available. Corresponds to the DBI statement handle CursorName
      attribute.

    param_values

        my $param_values = $ex->param_values;

      Returns a reference to a hash containing the values currently bound
      to placeholders. Corresponds to the DBI statement handle ParamValues
      attribute.

    statement

        my $statement = $ex->statement;

      Returns the statement string passed to the DBI prepare() method.
      Corresponds to the DBI statement handle Statement attribute.

    rows_in_cache

        my $rows_in_cache = $ex->rows_in_cache;

      the number of unfetched rows in the cache if the driver supports a
      local row cache for SELECT statements. Corresponds to the DBI
      statement handle RowsInCache attribute.

 Exception::Class::DBI::Unknown

    Exceptions of this class are thrown when the context for a DBI error
    cannot be determined. Inherits from Exception::Class::DBI, but
    implements no methods of its own.

Note

    Note: Not all of the attributes offered by the DBI are exploited by
    these exception classes. For example, the PrintError and RaiseError
    attributes seemed redundant. But if folks think it makes sense to
    include the missing attributes for the sake of completeness, let me
    know. Enough interest will motivate me to get them in.

Subclassing

    It is possible to subclass Exception::Class::DBI. The trick is to
    subclass its subclasses, too. Similar to subclassing DBI itself, this
    means that the handle subclasses should exist as subnamespaces of your
    base subclass.

    It's easier to explain with an example. Say that you wanted to add a
    new method to all DBI exceptions that outputs a nicely formatted error
    message. You might do it like this:

      package MyApp::Ex::DBI;
      use base 'Exception::Class::DBI';
    
      sub full_message {
          my $self = shift;
          return $self->SUPER::full_message unless $self->can('statement');
          return $self->SUPER::full_message
              . ' [for Statement "'
              . $self->statement . '"]';
      }

    You can then use this subclass just like Exception::Class::DBI itself:

      my $dbh = DBI->connect($dsn, $user, $pass, {
          PrintError  => 0,
          RaiseError  => 0,
          HandleError => MyApp::Ex::DBI->handler,
      });

    And that's all well and good, except that none of
    Exception::Class::DBI's own subclasses inherit from your class, so most
    exceptions won't be able to use your spiffy new method.

    The solution is to create subclasses of both the Exception::Class::DBI
    subclasses and your own base subclass, as long as they each use the
    same package name as your subclass, plus "H", "DRH", "DBH", "STH", and
    "Unknown". Here's what it looks like:

      package MyApp::Ex::DBI::H;
      use base 'MyApp::Ex::DBI', 'Exception::Class::DBI::H';
    
      package MyApp::Ex::DBI::DRH;
      use base 'MyApp::Ex::DBI', 'Exception::Class::DBI::DRH';
    
      package MyApp::Ex::DBI::DBH;
      use base 'MyApp::Ex::DBI', 'Exception::Class::DBI::DBH';
    
      package MyApp::Ex::DBI::STH;
      use base 'MyApp::Ex::DBI', 'Exception::Class::DBI::STH';
    
      package MyApp::Ex::DBI::Unknown;
      use base 'MyApp::Ex::DBI', 'Exception::Class::DBI::Unknown';

    And then things should work just spiffy! Of course, you probably don't
    need the H subclass unless you want to add other methods for the DRH,
    DBH, and STH classes to inherit from.

To Do

      * I need to figure out a non-database specific way of testing STH
      exceptions. DBD::ExampleP works well for DRH and DBH exceptions, but
      not so well for STH exceptions.

Support

    This module is stored in an open GitHub repository
    <http://github.com/uperl/Exception-Class-DBI/>. Feel free to fork and
    contribute!

    Please file bug reports via GitHub Issues
    <http://github.com/uperl/Exception-Class-DBI/issues/>.

Author

    Original Author is David E. Wheeler <david@justatheory.com>

    Current maintainer is Graham Ollis <plicease@cpan.org>

See Also

    You should really only be using this module in conjunction with Tim
    Bunce's DBI, so it pays to be familiar with its documentation.

    See the documentation for Dave Rolsky's Exception::Class module for
    details on the methods this module's classes inherit from it. There's
    lots more information in these exception objects, so use them!

AUTHORS

      * David E. Wheeler <david@justatheory.com>

      * Graham Ollis <plicease@cpan.org>

COPYRIGHT AND LICENSE

    This software is copyright (c) 2002-2021 by David E. Wheeler.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.