1Rose::DB(3)           User Contributed Perl Documentation          Rose::DB(3)
2
3
4

NAME

6       Rose::DB - A DBI wrapper and abstraction layer.
7

SYNOPSIS

9         package My::DB;
10
11         use Rose::DB;
12         our @ISA = qw(Rose::DB);
13
14         My::DB->register_db(
15           domain   => 'development',
16           type     => 'main',
17           driver   => 'Pg',
18           database => 'dev_db',
19           host     => 'localhost',
20           username => 'devuser',
21           password => 'mysecret',
22           server_time_zone => 'UTC',
23         );
24
25         My::DB->register_db(
26           domain   => 'production',
27           type     => 'main',
28           driver   => 'Pg',
29           database => 'big_db',
30           host     => 'dbserver.acme.com',
31           username => 'dbadmin',
32           password => 'prodsecret',
33           server_time_zone => 'UTC',
34         );
35
36         My::DB->default_domain('development');
37         My::DB->default_type('main');
38         ...
39
40         $db = My::DB->new;
41
42         my $dbh = $db->dbh or die $db->error;
43
44         $db->begin_work or die $db->error;
45         $dbh->do(...)   or die $db->error;
46         $db->commit     or die $db->error;
47
48         $db->do_transaction(sub
49         {
50           $dbh->do(...);
51           $sth = $dbh->prepare(...);
52           $sth->execute(...);
53           while($sth->fetch) { ... }
54           $dbh->do(...);
55         })
56         or die $db->error;
57
58         $dt  = $db->parse_timestamp('2001-03-05 12:34:56.123');
59         $val = $db->format_timestamp($dt);
60
61         $dt  = $db->parse_datetime('2001-03-05 12:34:56');
62         $val = $db->format_datetime($dt);
63
64         $dt  = $db->parse_date('2001-03-05');
65         $val = $db->format_date($dt);
66
67         $bit = $db->parse_bitfield('0x0AF', 32);
68         $val = $db->format_bitfield($bit);
69
70         ...
71

DESCRIPTION

73       Rose::DB is a wrapper and abstraction layer for DBI-related
74       functionality.  A Rose::DB object "has a" DBI object; it is not a
75       subclass of DBI.
76
77       Please see the tutorial (perldoc Rose::DB::Tutorial) for an example
78       usage scenario that reflects "best practices" for this module.
79
80       Tip: Are you looking for an object-relational mapper (ORM)?  If so,
81       please see the Rose::DB::Object module.  Rose::DB::Object is an ORM
82       that uses this module to manage its database connections.  Rose::DB
83       alone is simply a data source abstraction layer; it is not an ORM.
84

DATABASE SUPPORT

86       Rose::DB currently supports the following DBI database drivers:
87
88           DBD::Pg       (PostgreSQL)
89           DBD::mysql    (MySQL)
90           DBD::MariaDB  (MariaDB)
91           DBD::SQLite   (SQLite)
92           DBD::Informix (Informix)
93           DBD::Oracle   (Oracle)
94
95       Rose::DB will attempt to service an unsupported database using a
96       generic implementation that may or may not work.  Support for more
97       drivers may be added in the future.  Patches are welcome.
98
99       All database-specific behavior is contained and documented in the
100       subclasses of Rose::DB.  Rose::DB's constructor method (new()) returns
101       a database-specific subclass of Rose::DB, chosen based on the driver
102       value of the selected data source.  The default mapping of databases to
103       Rose::DB subclasses is:
104
105           DBD::Pg       -> Rose::DB::Pg
106           DBD::mysql    -> Rose::DB::MySQL
107           DBD::MariaDB  -> Rose::DB::MariaDB
108           DBD::SQLite   -> Rose::DB::SQLite
109           DBD::Informix -> Rose::DB::Informix
110           DBD::Oracle   -> Rose::DB::Oracle
111
112       This mapping can be changed using the driver_class class method.
113
114       The Rose::DB object method documentation found here defines the purpose
115       of each method, as well as the default behavior of the method if it is
116       not overridden by a subclass.  You must read the subclass documentation
117       to learn about behaviors that are specific to each type of database.
118
119       Subclasses may also add methods that do not exist in the parent class,
120       of course.  This is yet another reason to read the documentation for
121       the subclass that corresponds to your data source's database software.
122

FEATURES

124       The basic features of Rose::DB are as follows.
125
126   Data Source Abstraction
127       Instead of dealing with "databases" that exist on "hosts" or are
128       located via some vendor-specific addressing scheme, Rose::DB deals with
129       "logical" data sources.  Each logical data source is currently backed
130       by a single "physical" database (basically a single DBI connection).
131
132       Multiplexing, fail-over, and other more complex relationships between
133       logical data sources and physical databases are not part of Rose::DB.
134       Some basic types of fail-over may be added to Rose::DB in the future,
135       but right now the mapping is strictly one-to-one.  (I'm also currently
136       inclined to encourage multiplexing functionality to exist in a layer
137       above Rose::DB, rather than within it or in a subclass of it.)
138
139       The driver type of the data source determines the functionality of all
140       methods that do vendor-specific things (e.g., column value parsing and
141       formatting).
142
143       Rose::DB identifies data sources using a two-level namespace made of a
144       "domain" and a "type".  Both are arbitrary strings.  If left
145       unspecified, the default domain and default type (accessible via
146       Rose::DB's default_domain and default_type class methods) are assumed.
147
148       There are many ways to use the two-level namespace, but the most common
149       is to use the domain to represent the current environment (e.g.,
150       "development", "staging", "production") and then use the type to
151       identify the logical data source within that environment (e.g.,
152       "report", "main", "archive")
153
154       A typical deployment scenario will set the default domain using the
155       default_domain class method as part of the configure/install process.
156       Within application code, Rose::DB objects can be constructed by
157       specifying type alone:
158
159           $main_db    = Rose::DB->new(type => 'main');
160           $archive_db = Rose::DB->new(type => 'archive');
161
162       If there is only one database type, then all Rose::DB objects can be
163       instantiated with a bare constructor call like this:
164
165           $db = Rose::DB->new;
166
167       Again, remember that this is just one of many possible uses of domain
168       and type.  Arbitrarily complex scenarios can be created by nesting
169       namespaces within one or both parameters (much like how Perl uses "::"
170       to create a multi-level namespace from single strings).
171
172       The important point is the abstraction of data sources so they can be
173       identified and referred to using a vocabulary that is entirely
174       independent of the actual DSN (data source names) used by DBI behind
175       the scenes.
176
177   Database Handle Life-Cycle Management
178       When a Rose::DB object is destroyed while it contains an active DBI
179       database handle, the handle is explicitly disconnected before
180       destruction.  Rose::DB supports a simple retain/release reference-
181       counting system which allows a database handle to out-live its parent
182       Rose::DB object.
183
184       In the simplest case, Rose::DB could be used for its data source
185       abstractions features alone. For example, transiently creating a
186       Rose::DB and then retaining its DBI database handle before it is
187       destroyed:
188
189           $main_dbh = Rose::DB->new(type => 'main')->retain_dbh
190                         or die Rose::DB->error;
191
192           $aux_dbh  = Rose::DB->new(type => 'aux')->retain_dbh
193                         or die Rose::DB->error;
194
195       If the database handle was simply extracted via the dbh method instead
196       of retained with retain_dbh, it would be disconnected by the time the
197       statement completed.
198
199           # WRONG: $dbh will be disconnected immediately after the assignment!
200           $dbh = Rose::DB->new(type => 'main')->dbh or die Rose::DB->error;
201
202   Vendor-Specific Column Value Parsing and Formatting
203       Certain semantically identical column types are handled differently in
204       different databases.  Date and time columns are good examples.
205       Although many databases  store month, day, year, hours, minutes, and
206       seconds using a "datetime" column type, there will likely be
207       significant differences in how each of those databases expects to
208       receive such values, and how they're returned.
209
210       Rose::DB is responsible for converting the wide range of vendor-
211       specific column values for a particular column type into a single form
212       that is convenient for use within Perl code.  Rose::DB also handles the
213       opposite task, taking input from the Perl side and converting it into
214       the appropriate format for a specific database.  Not all column types
215       that exist in the supported databases are handled by Rose::DB, but
216       support will expand in the future.
217
218       Many column types are specific to a single database and do not exist
219       elsewhere.  When it is reasonable to do so, vendor-specific column
220       types may be "emulated" by Rose::DB for the benefit of other databases.
221       For example, an ARRAY value may be stored as a specially formatted
222       string in a VARCHAR field in a database that does not have a native
223       ARRAY column type.
224
225       Rose::DB does NOT attempt to present a unified column type system,
226       however.  If a column type does not exist in a particular kind of
227       database, there should be no expectation that Rose::DB will be able to
228       parse and format that value type on behalf of that database.
229
230   High-Level Transaction Support
231       Transactions may be started, committed, and rolled back in a variety of
232       ways using the DBI database handle directly.  Rose::DB provides
233       wrappers to do the same things, but with different error handling and
234       return values.  There's also a method (do_transaction) that will
235       execute arbitrary code within a single transaction, automatically
236       handling rollback on failure and commit on success.
237

SUBCLASSING

239       Subclassing is strongly encouraged and generally works as expected.
240       (See the tutorial for a complete example.)  There is, however, the
241       question of how class data is shared with subclasses.  Here's how it
242       works for the various pieces of class data.
243
244       alias_db, modify_db, register_db, unregister_db, unregister_domain
245           By default, all subclasses share the same data source "registry"
246           with Rose::DB.  To provide a private registry for your subclass
247           (the recommended approach), see the example in the documentation
248           for the registry method below.
249
250       default_domain, default_type
251           If called with no arguments, and if the attribute was never set for
252           this class, then a left-most, breadth-first search of the parent
253           classes is initiated.  The value returned is taken from first
254           parent class encountered that has ever had this attribute set.
255
256           (These attributes use the inheritable_scalar method type as defined
257           in Rose::Class::MakeMethods::Generic.)
258
259       driver_class, default_connect_options
260           These hashes of attributes are inherited by subclasses using a one-
261           time, shallow copy from a superclass.  Any subclass that accesses
262           or manipulates the hash in any way will immediately get its own
263           private copy of the hash as it exists in the superclass at the time
264           of the access or manipulation.
265
266           The superclass from which the hash is copied is the closest ("least
267           super") class that has ever accessed or manipulated this hash.  The
268           copy is a "shallow" copy, duplicating only the keys and values.
269           Reference values are not recursively copied.
270
271           Setting to hash to undef (using the 'reset' interface) will cause
272           it to be re-copied from a superclass the next time it is accessed.
273
274           (These attributes use the inheritable_hash method type as defined
275           in Rose::Class::MakeMethods::Generic.)
276

SERIALIZATION

278       A Rose::DB object may contain a DBI database handle, and DBI database
279       handles usually don't survive the serialize process intact.  Rose::DB
280       objects also hide database passwords inside closures, which also don't
281       serialize well.    In order for a Rose::DB object to survive
282       serialization, custom hooks are required.
283
284       Rose::DB has hooks for the Storable serialization module, but there is
285       an important caveat.  Since Rose::DB objects are blessed into a
286       dynamically generated class (derived from the driver class), you must
287       load your Rose::DB-derived class with all its registered data sources
288       before you can successfully thaw a frozen Rose::DB-derived object.
289       Here's an example.
290
291       Imagine that this is your Rose::DB-derived class:
292
293           package My::DB;
294
295           use Rose::DB;
296           our @ISA = qw(Rose::DB);
297
298           My::DB->register_db(
299             domain   => 'dev',
300             type     => 'main',
301             driver   => 'Pg',
302             ...
303           );
304
305           My::DB->register_db(
306             domain   => 'prod',
307             type     => 'main',
308             driver   => 'Pg',
309             ...
310           );
311
312           My::DB->default_domain('dev');
313           My::DB->default_type('main');
314
315       In one program, a "My::DB" object is frozen using Storable:
316
317           # my_freeze_script.pl
318
319           use My::DB;
320           use Storable qw(nstore);
321
322           # Create My::DB object
323           $db = My::DB->new(domain => 'dev', type => 'main');
324
325           # Do work...
326           $db->dbh->db('CREATE TABLE some_table (...)');
327           ...
328
329           # Serialize $db and store it in frozen_data_file
330           nstore($db, 'frozen_data_file');
331
332       Now another program wants to thaw out that "My::DB" object and use it.
333       To do so, it must be sure to load the My::DB module (which registers
334       all its data sources when loaded) before attempting to deserialize the
335       "My::DB" object serialized by "my_freeze_script.pl".
336
337           # my_thaw_script.pl
338
339           # IMPORTANT: load db modules with all data sources registered before
340           #            attempting to deserialize objects of this class.
341           use My::DB;
342
343           use Storable qw(retrieve);
344
345           # Retrieve frozen My::DB object from frozen_data_file
346           $db = retrieve('frozen_data_file');
347
348           # Do work...
349           $db->dbh->db('DROP TABLE some_table');
350           ...
351
352       Note that this rule about loading a Rose::DB-derived class with all its
353       data sources registered prior to deserializing such an object only
354       applies if the serialization was done in a different process.  If you
355       freeze and thaw within the same process, you don't have to worry about
356       it.
357

ENVIRONMENT

359       There are two ways to alter the initial Rose::DB data source registry.
360
361       •   The ROSEDB_DEVINIT file or module, which can add, modify, or remove
362           data sources and alter the default domain and type.
363
364       •   The ROSEDBRC file, which can modify existing data sources.
365
366   ROSEDB_DEVINIT
367       The "ROSEDB_DEVINIT" file or module is used during development, usually
368       to set up data sources for a particular developer's database or
369       project.  If the "ROSEDB_DEVINIT" environment variable is set, it
370       should be the name of a Perl module or file.  If it is a Perl module
371       and that module has a "fixup()" subroutine, it will be called as a
372       class method after the module is loaded.
373
374       If the "ROSEDB_DEVINIT" environment variable is not set, or if the
375       specified file does not exist or has errors, then it defaults to the
376       package name "Rose::DB::Devel::Init::username", where "username" is the
377       account name of the current user.
378
379       Note: if the getpwuid() function is unavailable (as is often the case
380       on Windows versions of perl) then this default does not apply and the
381       loading of the module named "Rose::DB::Devel::Init::username" is not
382       attempted.
383
384       The "ROSEDB_DEVINIT" file or module may contain arbitrary Perl code
385       which will be loaded and evaluated in the context of Rose::DB.
386       Example:
387
388           Rose::DB->default_domain('development');
389
390           Rose::DB->modify_db(domain   => 'development',
391                               type     => 'main_db',
392                               database => 'main',
393                               username => 'jdoe',
394                               password => 'mysecret');
395
396           1;
397
398       Remember to end the file with a true value.
399
400       The "ROSEDB_DEVINIT" file or module must be read explicitly by calling
401       the auto_load_fixups class method.
402
403   ROSEDBRC
404       The "ROSEDBRC" file contains configuration "fix-up" information.  This
405       file is most often used to dynamically set passwords that are too
406       sensitive to be included directly in the source code of a
407       Rose::DB-derived class.
408
409       The path to the fix-up file is determined by the "ROSEDBRC" environment
410       variable.  If this variable is not set, or if the file it points to
411       does not exist, then it defaults to "/etc/rosedbrc".
412
413       This file should be in YAML format.  To read this file, you must have
414       either YAML::Syck or some reasonably modern version of YAML installed
415       (0.66 or later recommended).  YAML::Syck will be preferred if both are
416       installed.
417
418       The "ROSEDBRC" file's contents have the following structure:
419
420           ---
421           somedomain:
422               sometype:
423                   somemethod: somevalue
424           ---
425           otherdomain:
426               othertype:
427                   othermethod: othervalue
428
429       Each entry modifies an existing registered data source.   Any valid
430       registry entry object method can be used (in place of "somemethod" and
431       "othermethod" in the YAML example above).
432
433       This file must be read explicitly by calling the auto_load_fixups class
434       method after setting up all your data sources.  Example:
435
436           package My::DB;
437
438           use Rose::DB;
439           our @ISA = qw(Rose::DB);
440
441           __PACKAGE__->use_private_registry;
442
443           # Register all data sources
444           __PACKAGE__->register_db(
445             domain   => 'development',
446             type     => 'main',
447             driver   => 'Pg',
448             database => 'dev_db',
449             host     => 'localhost',
450             username => 'devuser',
451             password => 'mysecret',
452           );
453
454           ...
455
456           # Load fix-up files, if any
457           __PACKAGE__->auto_load_fixups;
458

CLASS METHODS

460       alias_db PARAMS
461           Make one data source an alias for another by pointing them both to
462           the same registry entry.  PARAMS are name/value pairs that must
463           include domain and type values for both the source and alias
464           parameters.  Example:
465
466               Rose::DB->alias_db(source => { domain => 'dev', type => 'main' },
467                                  alias  => { domain => 'dev', type => 'aux' });
468
469           This makes the "dev/aux" data source point to the same registry
470           entry as the "dev/main" data source.  Modifications to either
471           registry entry (via modify_db) will be reflected in both.
472
473       auto_load_fixups
474           Attempt to load both the YAML-based ROSEDBRC and Perl-based
475           ROSEDB_DEVINIT fix-up files, if any exist, in that order.  The
476           ROSEDBRC file will modify the data source registry of the calling
477           class.  See the ENVIRONMENT section above for more information.
478
479       db_cache [CACHE]
480           Get or set the Rose::DB::Cache-derived object used to cache
481           Rose::DB objects on behalf of this class.  If no such object
482           exists, a new cache object of db_cache_class class will be created,
483           stored, and returned.
484
485       db_cache_class [CLASS]
486           Get or set the name of the Rose::DB::Cache-derived class used to
487           cache Rose::DB objects on behalf of this class.  The default value
488           is Rose::DB::Cache.
489
490       db_exists PARAMS
491           Returns true of the data source specified by PARAMS is registered,
492           false otherwise.  PARAMS are name/value pairs for "domain" and
493           "type".  If they are omitted, they default to default_domain and
494           default_type, respectively.  If default values do not exist, a
495           fatal error will occur.  If a single value is passed instead of
496           name/value pairs, it is taken as the value of the "type" parameter.
497
498       default_connect_options [HASHREF | PAIRS]
499           Get or set the default DBI connect options hash.  If a reference to
500           a hash is passed, it replaces the default connect options hash.  If
501           a series of name/value pairs are passed, they are added to the
502           default connect options hash.
503
504           The default set of default connect options is:
505
506               AutoCommit => 1,
507               RaiseError => 1,
508               PrintError => 1,
509               ChopBlanks => 1,
510               Warn       => 0,
511
512           See the connect_options object method for more information on how
513           the default connect options are used.
514
515       default_domain [DOMAIN]
516           Get or set the default data source domain.  See the "Data Source
517           Abstraction" section for more information on data source domains.
518
519       default_type [TYPE]
520           Get or set the default data source type.  See the "Data Source
521           Abstraction" section for more information on data source types.
522
523       driver_class DRIVER [, CLASS]
524           Get or set the subclass used for DRIVER.  The DRIVER argument is
525           automatically converted to lowercase.  (Driver names are
526           effectively case-insensitive.)
527
528               $class = Rose::DB->driver_class('Pg');      # get
529               Rose::DB->driver_class('pg' => 'MyDB::Pg'); # set
530
531           The default mapping of driver names to class names is as follows:
532
533               mysql    -> Rose::DB::MySQL
534               mariadb  -> Rose::DB::MariaDB
535               pg       -> Rose::DB::Pg
536               informix -> Rose::DB::Informix
537               sqlite   -> Rose::DB::SQLite
538               oracle   -> Rose::DB::Oracle
539               generic  -> Rose::DB::Generic
540
541           The class mapped to the special driver name "generic" will be used
542           for any driver name that does not have an entry in the map.
543
544           See the documentation for the new method for more information on
545           how the driver influences the class of objects returned by the
546           constructor.
547
548       default_keyword_function_calls [BOOL]
549           Get or set a boolean default value for the keyword_function_calls
550           object attribute.  Defaults to the value of the
551           "ROSE_DB_KEYWORD_FUNCTION_CALLS" environment variable, it set to a
552           defined value, or false otherwise.
553
554       modify_db PARAMS
555           Modify a data source, setting the attributes specified in PARAMS,
556           where PARAMS are name/value pairs.  Any Rose::DB object method that
557           sets a data source configuration value is a valid parameter name.
558
559               # Set new username for data source identified by domain and type
560               Rose::DB->modify_db(domain   => 'test',
561                                   type     => 'main',
562                                   username => 'tester');
563
564           PARAMS should include values for both the "type" and "domain"
565           parameters since these two attributes are used to identify the data
566           source.  If they are omitted, they default to default_domain and
567           default_type, respectively.  If default values do not exist, a
568           fatal error will occur.  If there is no data source defined for the
569           specified "type" and "domain", a fatal error will occur.
570
571       prepare_cache_for_apache_fork
572           This is a convenience method that is equivalent to the following
573           call:
574
575               Rose::DB->db_cache->prepare_for_apache_fork()
576
577           Any arguments passed to this method are passed on to the call to
578           the db_cache's prepare_for_apache_fork method.
579
580           Please read the Rose::DB::Cache documentation, particularly the
581           documentation for the use_cache_during_apache_startup method for
582           more information.
583
584       register_db PARAMS
585           Registers a new data source with the attributes specified in
586           PARAMS, where PARAMS are name/value pairs.  Any Rose::DB object
587           method that sets a data source configuration value is a valid
588           parameter name.
589
590           PARAMS must include a value for the "driver" parameter.  If the
591           "type" or "domain" parameters are omitted or undefined, they
592           default to the return values of the default_type and default_domain
593           class methods, respectively.
594
595           The "type" and "domain" are used to identify the data source.  If
596           either one is missing, a fatal error will occur.  See the "Data
597           Source Abstraction" section for more information on data source
598           types and domains.
599
600           The "driver" is used to determine which class objects will be
601           blessed into by the Rose::DB constructor, new.  The driver name is
602           automatically converted to lowercase.  If it is missing, a fatal
603           error will occur.
604
605           In most deployment scenarios, register_db is called early in the
606           compilation process to ensure that the registered data sources are
607           available when the "real" code runs.
608
609           Database registration can be included directly in your Rose::DB
610           subclass.  This is the recommended approach.  Example:
611
612               package My::DB;
613
614               use Rose::DB;
615               our @ISA = qw(Rose::DB);
616
617               # Use a private registry for this class
618               __PACKAGE__->use_private_registry;
619
620               # Register data sources
621               My::DB->register_db(
622                 domain   => 'development',
623                 type     => 'main',
624                 driver   => 'Pg',
625                 database => 'dev_db',
626                 host     => 'localhost',
627                 username => 'devuser',
628                 password => 'mysecret',
629               );
630
631               My::DB->register_db(
632                 domain   => 'production',
633                 type     => 'main',
634                 driver   => 'Pg',
635                 database => 'big_db',
636                 host     => 'dbserver.acme.com',
637                 username => 'dbadmin',
638                 password => 'prodsecret',
639               );
640               ...
641
642           Another possible approach is to consolidate data source
643           registration in a single module which is then "use"ed early on in
644           the code path.  For example, imagine a mod_perl web server
645           environment:
646
647               # File: MyCorp/DataSources.pm
648               package MyCorp::DataSources;
649
650               My::DB->register_db(
651                 domain   => 'development',
652                 type     => 'main',
653                 driver   => 'Pg',
654                 database => 'dev_db',
655                 host     => 'localhost',
656                 username => 'devuser',
657                 password => 'mysecret',
658               );
659
660               My::DB->register_db(
661                 domain   => 'production',
662                 type     => 'main',
663                 driver   => 'Pg',
664                 database => 'big_db',
665                 host     => 'dbserver.acme.com',
666                 username => 'dbadmin',
667                 password => 'prodsecret',
668               );
669               ...
670
671               # File: /usr/local/apache/conf/startup.pl
672
673               use My::DB; # your Rose::DB subclass
674               use MyCorp::DataSources; # register all data sources
675               ...
676
677           Data source registration can happen at any time, of course, but it
678           is most useful when all application code can simply assume that all
679           the data sources are already registered.  Doing the registration as
680           early as possible (e.g., directly in your Rose::DB subclass, or in
681           a "startup.pl" file that is loaded from an apache/mod_perl web
682           server's "httpd.conf" file) is the best way to create such an
683           environment.
684
685           Note that the data source registry serves as an initial source of
686           information for Rose::DB objects.  Once an object is instantiated,
687           it is independent of the registry.  Changes to an object are not
688           reflected in the registry, and changes to the registry are not
689           reflected in existing objects.
690
691       registry [REGISTRY]
692           Get or set the Rose::DB::Registry-derived object that manages and
693           stores the data source registry.  It defaults to an "empty"
694           Rose::DB::Registry object.  Remember that setting a new registry
695           will replace the existing registry and all the data sources
696           registered in it.
697
698           Note that Rose::DB subclasses will inherit the base class's
699           Rose::DB::Registry object and will therefore inherit all existing
700           registry entries and share the same registry namespace as the base
701           class.   This may or may not be what you want.
702
703           In most cases, it's wise to give your subclass its own private
704           registry if it inherits directly from Rose::DB.  To do that, just
705           set a new registry object in your subclass.  Example:
706
707               package My::DB;
708
709               use Rose::DB;
710               our @ISA = qw(Rose::DB);
711
712               # Create a private registry for this class:
713               #
714               # either explicitly:
715               # use Rose::DB::Registry;
716               # __PACKAGE__->registry(Rose::DB::Registry->new);
717               #
718               # or use the convenience method:
719               __PACKAGE__->use_private_registry;
720               ...
721
722           Further subclasses of "My::DB" may then inherit its registry
723           object, if desired, or may create their own private registries in
724           the manner shown above.
725
726       unregister_db PARAMS
727           Unregisters the data source having the "type" and "domain"
728           specified in  PARAMS, where PARAMS are name/value pairs.  Returns
729           true if the data source was unregistered successfully, false if it
730           did not exist in the first place.  Example:
731
732               Rose::DB->unregister_db(type => 'main', domain => 'test');
733
734           PARAMS must include values for both the "type" and "domain"
735           parameters since these two attributes are used to identify the data
736           source.  If either one is missing, a fatal error will occur.
737
738           Unregistering a data source removes all knowledge of it.  This may
739           be harmful to any existing Rose::DB objects that are associated
740           with that data source.
741
742       unregister_domain DOMAIN
743           Unregisters an entire domain.  Returns true if the domain was
744           unregistered successfully, false if it did not exist in the first
745           place.  Example:
746
747               Rose::DB->unregister_domain('test');
748
749           Unregistering a domain removes all knowledge of all of the data
750           sources that existed under it.  This may be harmful to any existing
751           Rose::DB objects that are associated with any of those data
752           sources.
753
754       use_cache_during_apache_startup [BOOL]
755           This is a convenience method that is equivalent to the following
756           call:
757
758               Rose::DB->db_cache->use_cache_during_apache_startup(...)
759
760           The boolean argument passed to this method is passed on to the call
761           to the db_cache's use_cache_during_apache_startup method.
762
763           Please read the Rose::DB::Cache's use_cache_during_apache_startup
764           documentation for more information.
765
766       use_private_registry
767           This method is used to give a class its own private registry.  In
768           other words, this:
769
770               __PACKAGE__->use_private_registry;
771
772           is roughly equivalent to this:
773
774               use Rose::DB::Registry;
775               __PACKAGE__->registry(Rose::DB::Registry->new);
776

CONSTRUCTORS

778       new PARAMS
779           Constructs a new object based on PARAMS, where PARAMS are
780           name/value pairs.  Any object method is a valid parameter name.
781           Example:
782
783               $db = Rose::DB->new(type => 'main', domain => 'qa');
784
785           If a single argument is passed to new, it is used as the "type"
786           value:
787
788               $db = Rose::DB->new(type => 'aux');
789               $db = Rose::DB->new('aux'); # same thing
790
791           Each Rose::DB object is associated with a particular data source,
792           defined by the type and domain values.  If these are not part of
793           PARAMS, then the default values are used.  If you do not want to
794           use the default values for the type and domain attributes, you
795           should specify them in the constructor PARAMS.
796
797           The default type and domain can be set using the default_type and
798           default_domain class methods.  See the "Data Source Abstraction"
799           section for more information on data sources.
800
801           Object attributes are set based on the registry entry specified by
802           the "type" and "domain" parameters.  This registry entry must exist
803           or a fatal error will occur (with one exception; see below).  Any
804           additional PARAMS will override the values taken from the registry
805           entry.
806
807           If "type" and "domain" parameters are not passed, but a "driver"
808           parameter is passed, then a new "empty" object will be returned.
809           Examples:
810
811               # This is ok, even if no registered data sources exist
812               $db = Rose::DB->new(driver => 'sqlite');
813
814           The object returned by new will be derived from a database-specific
815           driver class, chosen based on the driver value of the selected data
816           source.  If there is no registered data source for the specified
817           type and domain, a fatal error will occur.
818
819           The default driver-to-class mapping is as follows:
820
821               pg       -> Rose::DB::Pg
822               mysql    -> Rose::DB::MySQL
823               mariadb  -> Rose::DB::MariaDB
824               informix -> Rose::DB::Informix
825               oracle   -> Rose::DB::Oracle
826               sqlite   -> Rose::DB::SQLite
827
828           You can change this mapping with the driver_class class method.
829
830       new_or_cached PARAMS
831           Constructs or returns a Rose::DB object based on PARAMS, where
832           PARAMS are any name/value pairs that can be passed to the new
833           method.  If the db_cache's get_db method returns an existing
834           Rose::DB object that matches PARAMS, then it is returned.
835           Otherwise, a new  Rose::DB object is created, stored in the
836           db_cache, then returned.
837
838           See the Rose::DB::Cache documentation to learn about the cache API
839           and the default implementation.
840

OBJECT METHODS

842       begin_work
843           Attempt to start a transaction by calling the begin_work method on
844           the DBI database handle.
845
846           If necessary, the database handle will be constructed and connected
847           to the current data source.  If this fails, undef is returned.  If
848           there is no registered data source for the current "type" and
849           "domain", a fatal error will occur.
850
851           If the "AutoCommit" database handle attribute is false, the handle
852           is assumed to already be in a transaction and
853           Rose::DB::Constants::IN_TRANSACTION (-1) is returned.  If the call
854           to DBI's begin_work method succeeds, 1 is returned.  If it fails,
855           undef is returned.
856
857       commit
858           Attempt to commit the current transaction by calling the commit
859           method on the DBI database handle.  If the DBI database handle does
860           not exist or is not connected, 0 is returned.
861
862           If the "AutoCommit" database handle attribute is true, the handle
863           is assumed to not be in a transaction and
864           Rose::DB::Constants::IN_TRANSACTION (-1) is returned.  If the call
865           to DBI's commit method succeeds, 1 is returned.  If it fails, undef
866           is returned.
867
868       connect
869           Constructs and connects the DBI database handle for the current
870           data source, calling dbi_connect to create a new DBI database
871           handle if none exists.  If there is no registered data source for
872           the current type and domain, a fatal error will occur.
873
874           If any post_connect_sql statement failed to execute, the database
875           handle is disconnected and then discarded.
876
877           If the database handle returned by dbi_connect was originally
878           connected by another Rose::DB-derived object (e.g., if a subclass's
879           custom implementation of dbi_connect calls DBI's connect_cached
880           method) then the post_connect_sql statements will not be run, nor
881           will any custom DBI attributes be applied (e.g., Rose::DB::MySQL's
882           mysql_enable_utf8 attribute).
883
884           Returns true if the database handle was connected successfully and
885           all post_connect_sql statements (if any) were run successfully,
886           false otherwise.
887
888       connect_option NAME [, VALUE]
889           Get or set a single connection option.  Example:
890
891               $val = $db->connect_option('RaiseError'); # get
892               $db->connect_option(AutoCommit => 1);     # set
893
894           Connection options are name/value pairs that are passed in a hash
895           reference as the fourth argument to the call to DBI->connect().
896           See the DBI documentation for descriptions of the various options.
897
898       connect_options [HASHREF | PAIRS]
899           Get or set the DBI connect options hash.  If a reference to a hash
900           is passed, it replaces the connect options hash.  If a series of
901           name/value pairs are passed, they are added to the connect options
902           hash.
903
904           Returns a reference to the connect options has in scalar context,
905           or a list of name/value pairs in list context.
906
907       dbh [DBH]
908           Get or set the DBI database handle connected to the current data
909           source.  If the database handle does not exist or was created in
910           another process or thread, this method will discard the old
911           database handle (if any) and dbi_connect will be called to create a
912           new one.
913
914           Returns undef if the database handle could not be constructed and
915           connected.  If there is no registered data source for the current
916           "type" and "domain", a fatal error will occur.
917
918           Note: when setting this attribute, you must pass in a DBI database
919           handle that has the same driver as the object.  For example, if the
920           driver is "mysql" then the DBI database handle must be connected to
921           a MySQL database.  Passing in a mismatched database handle will
922           cause a fatal error.
923
924       dbi_connect [ARGS]
925           This method calls DBI->connect(...), passing all ARGS and returning
926           all values.  This method has no affect on the internal state of the
927           object.  Use the connect method to create and store a new database
928           handle in the object.
929
930           Override this method in your Rose::DB subclass if you want to use a
931           different method (e.g. DBI->connect_cached()) to create database
932           handles.
933
934       disconnect
935           Decrements the reference count for the database handle and
936           disconnects it if the reference count is zero and if the database
937           handle was originally connected by this object.  (This may not be
938           the case if, say, a subclass's custom implementation of dbi_connect
939           calls DBI's connect_cached method.)  Regardless of the reference
940           count, it sets the dbh attribute to undef.
941
942           Returns true if all pre_disconnect_sql statements (if any) were run
943           successfully and the database handle was disconnected successfully
944           (or if it was simply set to undef), false otherwise.
945
946           The database handle will not be disconnected if any
947           pre_disconnect_sql statement fails to execute, and the
948           pre_disconnect_sql is not run unless the handle is going to be
949           disconnected.
950
951       do_transaction CODE [, ARGS]
952           Execute arbitrary code within a single transaction, rolling back if
953           any of the code fails, committing if it succeeds.  CODE should be a
954           code reference.  It will be called with any arguments passed to
955           do_transaction after the code reference.  Example:
956
957               # Transfer $100 from account id 5 to account id 9
958               $db->do_transaction(sub
959               {
960                 my($amt, $id1, $id2) = @_;
961
962                 my $dbh = $db->dbh or die $db->error;
963
964                 # Transfer $amt from account id $id1 to account id $id2
965                 $dbh->do("UPDATE acct SET bal = bal - $amt WHERE id = $id1");
966                 $dbh->do("UPDATE acct SET bal = bal + $amt WHERE id = $id2");
967               },
968               100, 5, 9) or warn "Transfer failed: ", $db->error;
969
970           If the CODE block threw an exception or the transaction could not
971           be started and committed successfully, then undef is returned and
972           the exception thrown is available in the error attribute.
973           Otherwise, a true value is returned.
974
975       error [MSG]
976           Get or set the error message associated with the last failure.  If
977           a method fails, check this attribute to get the reason for the
978           failure in the form of a text message.
979
980       has_dbh
981           Returns true if the object has a DBI database handle (dbh), false
982           if it does not.
983
984       has_primary_key [ TABLE | PARAMS ]
985           Returns true if the specified table has a primary key (as
986           determined by the primary_key_column_names method), false
987           otherwise.
988
989           The arguments are the same as those for the
990           primary_key_column_names method: either a table name or name/value
991           pairs specifying "table", "catalog", and "schema".  The  "catalog"
992           and "schema" parameters are optional and default to the return
993           values of the catalog and schema methods, respectively.  See the
994           documentation for the primary_key_column_names for more
995           information.
996
997       in_transaction
998           Return true if the dbh is currently in the middle of a transaction,
999           false (but defined) if it is not.  If no dbh exists, then undef is
1000           returned.
1001
1002       init_db_info
1003           Initialize data source configuration information based on the
1004           current values of the type and domain attributes by pulling data
1005           from the corresponding registry entry.  If there is no registered
1006           data source for the current type and domain, a fatal error will
1007           occur.  init_db_info is called as part of the new and connect
1008           methods.
1009
1010       insertid_param
1011           Returns the name of the DBI statement handle attribute that
1012           contains the auto-generated unique key created during the last
1013           insert operation.  Returns undef if the current data source does
1014           not support this attribute.
1015
1016       keyword_function_calls [BOOL]
1017           Get or set a boolean value that indicates whether or not any string
1018           that looks like a function call (matches "/^\w+\(.*\)$/") will be
1019           treated as a "keyword" by the various format_* methods.  Defaults
1020           to the value returned by the default_keyword_function_calls class
1021           method.
1022
1023       last_insertid_from_sth STH
1024           Given a DBI statement handle, returns the value of the auto-
1025           generated unique key created during the last insert operation.
1026           This value may be undefined if this feature is not supported by the
1027           current data source.
1028
1029       list_tables
1030           Returns a list (in list context) or reference to an array (in
1031           scalar context) of tables in the database.  The current catalog and
1032           schema are honored.
1033
1034       quote_column_name NAME
1035           Returns the column name NAME appropriately quoted for use in an SQL
1036           statement.  (Note that "appropriate" quoting may mean no quoting at
1037           all.)
1038
1039       release_dbh
1040           Decrements the reference count for the DBI database handle, if it
1041           exists.  Returns 0 if the database handle does not exist.
1042
1043           If the reference count drops to zero, the database handle is
1044           disconnected.  Keep in mind that the Rose::DB object itself will
1045           increment the reference count when the database handle is
1046           connected, and decrement it when disconnect is called.
1047
1048           Returns true if the reference count is not 0 or if all
1049           pre_disconnect_sql statements (if any) were run successfully and
1050           the database handle was disconnected successfully, false otherwise.
1051
1052           The database handle will not be disconnected if any
1053           pre_disconnect_sql statement fails to execute, and the
1054           pre_disconnect_sql is not run unless the handle is going to be
1055           disconnected.
1056
1057           See the "Database Handle Life-Cycle Management" section for more
1058           information on the retain/release system.
1059
1060       retain_dbh
1061           Returns the connected DBI database handle after incrementing the
1062           reference count.  If the database handle does not exist or is not
1063           already connected, this method will do everything necessary to do
1064           so.
1065
1066           Returns undef if the database handle could not be constructed and
1067           connected.  If there is no registered data source for the current
1068           type and domain, a fatal error will occur.
1069
1070           See the "Database Handle Life-Cycle Management" section for more
1071           information on the retain/release system.
1072
1073       rollback
1074           Roll back the current transaction by calling the rollback method on
1075           the DBI database handle.  If the DBI database handle does not exist
1076           or is not connected, 0 is returned.
1077
1078           If the call to DBI's rollback method succeeds or if auto-commit is
1079           enabled, 1 is returned.  If it fails, undef is returned.
1080
1081   Data Source Configuration
1082       Not all databases will use all of these values.  Values that are not
1083       supported are simply ignored.
1084
1085       autocommit [VALUE]
1086           Get or set the value of the "AutoCommit" connect option and DBI
1087           handle attribute.  If a VALUE is passed, it will be set in both the
1088           connect options hash and the current database handle, if any.
1089           Returns the value of the "AutoCommit" attribute of the database
1090           handle if it exists, or the connect option otherwise.
1091
1092           This method should not be mixed with the connect_options method in
1093           calls to register_db or modify_db since connect_options will
1094           overwrite all the connect options with its argument, and neither
1095           register_db nor modify_db guarantee the order that its parameters
1096           will be evaluated.
1097
1098       catalog [CATALOG]
1099           Get or set the database catalog name.  This setting is only
1100           relevant to databases that support the concept of catalogs.
1101
1102       connect_options [HASHREF | PAIRS]
1103           Get or set the options passed in a hash reference as the fourth
1104           argument to the call to DBI->connect().  See the DBI documentation
1105           for descriptions of the various options.
1106
1107           If a reference to a hash is passed, it replaces the connect options
1108           hash.  If a series of name/value pairs are passed, they are added
1109           to the connect options hash.
1110
1111           Returns a reference to the hash of options in scalar context, or a
1112           list of name/value pairs in list context.
1113
1114           When init_db_info is called for the first time on an object (either
1115           in isolation or as part of the connect process), the connect
1116           options are merged with the default_connect_options.  The defaults
1117           are overridden in the case of a conflict.  Example:
1118
1119               Rose::DB->register_db(
1120                 domain   => 'development',
1121                 type     => 'main',
1122                 driver   => 'Pg',
1123                 database => 'dev_db',
1124                 host     => 'localhost',
1125                 username => 'devuser',
1126                 password => 'mysecret',
1127                 connect_options =>
1128                 {
1129                   RaiseError => 0,
1130                   AutoCommit => 0,
1131                 }
1132               );
1133
1134               # Rose::DB->default_connect_options are:
1135               #
1136               # AutoCommit => 1,
1137               # ChopBlanks => 1,
1138               # PrintError => 1,
1139               # RaiseError => 1,
1140               # Warn       => 0,
1141
1142               # The object's connect options are merged with default options
1143               # since new() will trigger the first call to init_db_info()
1144               # for this object
1145               $db = Rose::DB->new(domain => 'development', type => 'main');
1146
1147               # $db->connect_options are:
1148               #
1149               # AutoCommit => 0,
1150               # ChopBlanks => 1,
1151               # PrintError => 1,
1152               # RaiseError => 0,
1153               # Warn       => 0,
1154
1155               $db->connect_options(TraceLevel => 2); # Add an option
1156
1157               # $db->connect_options are now:
1158               #
1159               # AutoCommit => 0,
1160               # ChopBlanks => 1,
1161               # PrintError => 1,
1162               # RaiseError => 0,
1163               # TraceLevel => 2,
1164               # Warn       => 0,
1165
1166               # The object's connect options are NOT re-merged with the default
1167               # connect options since this will trigger the second call to
1168               # init_db_info(), not the first
1169               $db->connect or die $db->error;
1170
1171               # $db->connect_options are still:
1172               #
1173               # AutoCommit => 0,
1174               # ChopBlanks => 1,
1175               # PrintError => 1,
1176               # RaiseError => 0,
1177               # TraceLevel => 2,
1178               # Warn       => 0,
1179
1180       database [NAME]
1181           Get or set the database name used in the construction of the DSN
1182           used in the DBI connect call.
1183
1184       domain [DOMAIN]
1185           Get or set the data source domain.  See the "Data Source
1186           Abstraction" section for more information on data source domains.
1187
1188       driver [DRIVER]
1189           Get or set the driver name.  The driver name can only be set during
1190           object construction (i.e., as an argument to new) since it
1191           determines the object class.  After the object is constructed,
1192           setting the driver to anything other than the same value it already
1193           has will cause a fatal error.
1194
1195           Even in the call to new, setting the driver name explicitly is not
1196           recommended.  Instead, specify the driver when calling register_db
1197           for each data source and allow the driver to be set automatically
1198           based on the domain and type.
1199
1200           The driver names for the currently supported database types are:
1201
1202               pg
1203               mysql
1204               mariadb
1205               informix
1206               oracle
1207               sqlite
1208
1209           Driver names should only use lowercase letters.
1210
1211       dsn [DSN]
1212           Get or set the DBI DSN (Data Source Name) passed to the call to
1213           DBI's connect method.
1214
1215           An attempt is made to parse the new DSN.  Any parts successfully
1216           extracted are assigned to the corresponding Rose::DB attributes
1217           (e.g., host, port, database).  If no value could be extracted for
1218           an attribute, it is set to undef.
1219
1220           If the DSN is never set explicitly, it is built automatically based
1221           on the relevant object attributes.
1222
1223           If the DSN is set explicitly, but any of host, port, database,
1224           schema, or catalog are also provided, either in an object
1225           constructor or when the data source is registered, the explicit DSN
1226           may be ignored as a new DSN is constructed based on these
1227           attributes.
1228
1229       handle_error [VALUE]
1230           Get or set the value of the "HandleError" connect option and DBI
1231           handle attribute.  If a VALUE is passed, it will be set in both the
1232           connect options hash and the current database handle, if any.
1233           Returns the value of the "HandleError" attribute of the database
1234           handle if it exists, or the connect option otherwise.
1235
1236           This method should not be mixed with the connect_options method in
1237           calls to register_db or modify_db since connect_options will
1238           overwrite all the connect options with its argument, and neither
1239           register_db nor modify_db guarantee the order that its parameters
1240           will be evaluated.
1241
1242       host [NAME]
1243           Get or set the database server host name used in the construction
1244           of the DSN which is passed in the DBI connect call.
1245
1246       password [PASS]
1247           Get or set the password that will be passed to the DBI connect
1248           call.
1249
1250       port [NUM]
1251           Get or set the database server port number used in the construction
1252           of the DSN which is passed in the DBI connect call.
1253
1254       pre_disconnect_sql [STATEMENTS]
1255           Get or set the SQL statements that will be run immediately before
1256           disconnecting from the database.  STATEMENTS should be a list or
1257           reference to an array of SQL statements.  Returns a reference to
1258           the array of SQL statements in scalar context, or a list of SQL
1259           statements in list context.
1260
1261           The SQL statements are run in the order that they are supplied in
1262           STATEMENTS.  If any pre_disconnect_sql statement fails when
1263           executed, the subsequent statements are ignored.
1264
1265       post_connect_sql [STATEMENTS]
1266           Get or set the SQL statements that will be run immediately after
1267           connecting to the database.  STATEMENTS should be a list or
1268           reference to an array of SQL statements.  Returns a reference to
1269           the array of SQL statements in scalar context, or a list of SQL
1270           statements in list context.
1271
1272           The SQL statements are run in the order that they are supplied in
1273           STATEMENTS.  If any post_connect_sql statement fails when executed,
1274           the subsequent statements are ignored.
1275
1276       primary_key_column_names [ TABLE | PARAMS ]
1277           Returns a list (in list context) or reference to an array (in
1278           scalar context) of the names of the columns that make up the
1279           primary key for the specified table.  If the table has no primary
1280           key, an empty list (in list context) or reference to an empty array
1281           (in scalar context) will be returned.
1282
1283           The table may be specified in two ways.  If one argument is passed,
1284           it is taken as the name of the table.  Otherwise, name/value pairs
1285           are expected.  Valid parameter names are:
1286
1287           "catalog"
1288               The name of the catalog that contains the table.  This
1289               parameter is optional and defaults to the return value of the
1290               catalog method.
1291
1292           "schema"
1293               The name of the schema that contains the table.  This parameter
1294               is optional and defaults to the return value of the schema
1295               method.
1296
1297           "table"
1298               The name of the table.  This parameter is required.
1299
1300           Case-sensitivity of names is determined by the underlying database.
1301           If your database is case-sensitive, then you must pass names to
1302           this method with the expected case.
1303
1304       print_error [VALUE]
1305           Get or set the value of the "PrintError" connect option and DBI
1306           handle attribute.  If a VALUE is passed, it will be set in both the
1307           connect options hash and the current database handle, if any.
1308           Returns the value of the "PrintError" attribute of the database
1309           handle if it exists, or the connect option otherwise.
1310
1311           This method should not be mixed with the connect_options method in
1312           calls to register_db or modify_db since connect_options will
1313           overwrite all the connect options with its argument, and neither
1314           register_db nor modify_db guarantee the order that its parameters
1315           will be evaluated.
1316
1317       raise_error [VALUE]
1318           Get or set the value of the "RaiseError" connect option and DBI
1319           handle attribute.  If a VALUE is passed, it will be set in both the
1320           connect options hash and the current database handle, if any.
1321           Returns the value of the "RaiseError" attribute of the database
1322           handle if it exists, or the connect option otherwise.
1323
1324           This method should not be mixed with the connect_options method in
1325           calls to register_db or modify_db since connect_options will
1326           overwrite all the connect options with its argument, and neither
1327           register_db nor modify_db guarantee the order that its parameters
1328           will be evaluated.
1329
1330       schema [SCHEMA]
1331           Get or set the database schema name.  This setting is only useful
1332           to databases that support the concept of schemas (e.g.,
1333           PostgreSQL).
1334
1335       server_time_zone [TZ]
1336           Get or set the time zone used by the database server software.  TZ
1337           should be a time zone name that is understood by
1338           DateTime::TimeZone.  The default value is "floating".
1339
1340           See the DateTime::TimeZone documentation for acceptable values of
1341           TZ.
1342
1343       type [TYPE]
1344           Get or set the  data source type.  See the "Data Source
1345           Abstraction" section for more information on data source types.
1346
1347       username [NAME]
1348           Get or set the username that will be passed to the DBI connect
1349           call.
1350
1351   Value Parsing and Formatting
1352       format_bitfield BITS [, SIZE]
1353           Converts the Bit::Vector object BITS into the appropriate format
1354           for the "bitfield" data type of the current data source.  If a SIZE
1355           argument is provided, the bit field will be padded with the
1356           appropriate number of zeros until it is SIZE bits long.  If the
1357           data source does not have a native "bit" or "bitfield" data type, a
1358           character data type may be used to store the string of 1s and 0s
1359           returned by the default implementation.
1360
1361       format_boolean VALUE
1362           Converts VALUE into the appropriate format for the "boolean" data
1363           type of the current data source.  VALUE is simply evaluated in
1364           Perl's scalar context to determine if it's true or false.
1365
1366       format_date DATETIME
1367           Converts the DateTime object DATETIME into the appropriate format
1368           for the "date" (month, day, year) data type of the current data
1369           source.
1370
1371       format_datetime DATETIME
1372           Converts the DateTime object DATETIME into the appropriate format
1373           for the "datetime" (month, day, year, hour, minute, second) data
1374           type of the current data source.
1375
1376       format_interval DURATION
1377           Converts the DateTime::Duration object DURATION into the
1378           appropriate format for the interval (years, months, days, hours,
1379           minutes, seconds) data type of the current data source. If DURATION
1380           is undefined, a DateTime::Duration object, a valid interval keyword
1381           (according to validate_interval_keyword), or if it looks like a
1382           function call (matches "/^\w+\(.*\)$/") and keyword_function_calls
1383           is true, then it is returned unmodified.
1384
1385       format_time TIMECLOCK
1386           Converts the Time::Clock object TIMECLOCK into the appropriate
1387           format for the time (hour, minute, second, fractional seconds) data
1388           type of the current data source.  Fractional seconds are optional,
1389           and the useful precision may vary depending on the data source.
1390
1391       format_timestamp DATETIME
1392           Converts the DateTime object DATETIME into the appropriate format
1393           for the timestamp (month, day, year, hour, minute, second,
1394           fractional seconds) data type of the current data source.
1395           Fractional seconds are optional, and the useful precision may vary
1396           depending on the data source.
1397
1398       format_timestamp_with_time_zone DATETIME
1399           Converts the DateTime object DATETIME into the appropriate format
1400           for the timestamp with time zone (month, day, year, hour, minute,
1401           second, fractional seconds, time zone) data type of the current
1402           data source.  Fractional seconds are optional, and the useful
1403           precision may vary depending on the data source.
1404
1405       parse_bitfield BITS [, SIZE]
1406           Parse BITS and return a corresponding Bit::Vector object.  If SIZE
1407           is not passed, then it defaults to the number of bits in the parsed
1408           bit string.
1409
1410           If BITS is a string of "1"s and "0"s or matches "/^B'[10]+'$/",
1411           then the "1"s and "0"s are parsed as a binary string.
1412
1413           If BITS is a string of numbers, at least one of which is in the
1414           range 2-9, it is assumed to be a decimal (base 10) number and is
1415           converted to a bitfield as such.
1416
1417           If BITS matches any of these regular expressions:
1418
1419               /^0x/
1420               /^X'.*'$/
1421               /^[0-9a-f]+$/
1422
1423           it is assumed to be a hexadecimal number and is converted to a
1424           bitfield as such.
1425
1426           Otherwise, undef is returned.
1427
1428       parse_boolean STRING
1429           Parse STRING and return a boolean value of 1 or 0.  STRING should
1430           be formatted according to the data source's native "boolean" data
1431           type.  The default implementation accepts 't', 'true', 'y', 'yes',
1432           and '1' values for true, and 'f', 'false', 'n', 'no', and '0'
1433           values for false.
1434
1435           If STRING is a valid boolean keyword (according to
1436           validate_boolean_keyword) or if it looks like a function call
1437           (matches "/^\w+\(.*\)$/") and keyword_function_calls is true, then
1438           it is returned unmodified.  Returns undef if STRING could not be
1439           parsed as a valid "boolean" value.
1440
1441       parse_date STRING
1442           Parse STRING and return a DateTime object.  STRING should be
1443           formatted according to the data source's native "date" (month, day,
1444           year) data type.
1445
1446           If STRING is a valid date keyword (according to
1447           validate_date_keyword) or if it looks like a function call (matches
1448           "/^\w+\(.*\)$/") and keyword_function_calls is true, then it is
1449           returned unmodified.  Returns undef if STRING could not be parsed
1450           as a valid "date" value.
1451
1452       parse_datetime STRING
1453           Parse STRING and return a DateTime object.  STRING should be
1454           formatted according to the data source's native "datetime" (month,
1455           day, year, hour, minute, second) data type.
1456
1457           If STRING is a valid datetime keyword (according to
1458           validate_datetime_keyword) or if it looks like a function call
1459           (matches "/^\w+\(.*\)$/") and keyword_function_calls is true, then
1460           it is returned unmodified.  Returns undef if STRING could not be
1461           parsed as a valid "datetime" value.
1462
1463       parse_interval STRING [, MODE]
1464           Parse STRING and return a DateTime::Duration object.  STRING should
1465           be formatted according to the data source's native "interval"
1466           (years, months, days, hours, minutes, seconds) data type.
1467
1468           If STRING is a DateTime::Duration object, a valid interval keyword
1469           (according to validate_interval_keyword), or if it looks like a
1470           function call (matches "/^\w+\(.*\)$/") and keyword_function_calls
1471           is true, then it is returned unmodified.  Otherwise, undef is
1472           returned if STRING could not be parsed as a valid "interval" value.
1473
1474           This optional MODE argument determines how math is done on duration
1475           objects.  If defined, the "end_of_month" setting for each
1476           DateTime::Duration object created by this column will have its mode
1477           set to MODE.  Otherwise, the "end_of_month" parameter will not be
1478           passed to the DateTime::Duration constructor.
1479
1480           Valid modes are "wrap", "limit", and "preserve".  See the
1481           documentation for DateTime::Duration for a full explanation.
1482
1483       parse_time STRING
1484           Parse STRING and return a Time::Clock object.  STRING should be
1485           formatted according to the data source's native "time" (hour,
1486           minute, second, fractional seconds) data type.
1487
1488           If STRING is a valid time keyword (according to
1489           validate_time_keyword) or if it looks like a function call (matches
1490           "/^\w+\(.*\)$/") and keyword_function_calls is true, then it is
1491           returned unmodified.  Returns undef if STRING could not be parsed
1492           as a valid "time" value.
1493
1494       parse_timestamp STRING
1495           Parse STRING and return a DateTime object.  STRING should be
1496           formatted according to the data source's native "timestamp" (month,
1497           day, year, hour, minute, second, fractional seconds) data type.
1498           Fractional seconds are optional, and the acceptable precision may
1499           vary depending on the data source.
1500
1501           If STRING is a valid timestamp keyword (according to
1502           validate_timestamp_keyword) or if it looks like a function call
1503           (matches "/^\w+\(.*\)$/") and keyword_function_calls is true, then
1504           it is returned unmodified.  Returns undef if STRING could not be
1505           parsed as a valid "timestamp" value.
1506
1507       parse_timestamp_with_time_zone STRING
1508           Parse STRING and return a DateTime object.  STRING should be
1509           formatted according to the data source's native "timestamp with
1510           time zone" (month, day, year, hour, minute, second, fractional
1511           seconds, time zone) data type.  Fractional seconds are optional,
1512           and the acceptable precision may vary depending on the data source.
1513
1514           If STRING is a valid timestamp keyword (according to
1515           validate_timestamp_keyword) or if it looks like a function call
1516           (matches "/^\w+\(.*\)$/") and keyword_function_calls is true, then
1517           it is returned unmodified.  Returns undef if STRING could not be
1518           parsed as a valid "timestamp with time zone" value.
1519
1520       validate_boolean_keyword STRING
1521           Returns true if STRING is a valid keyword for the "boolean" data
1522           type of the current data source, false otherwise.  The default
1523           implementation accepts the values "TRUE" and "FALSE".
1524
1525       validate_date_keyword STRING
1526           Returns true if STRING is a valid keyword for the "date" (month,
1527           day, year) data type of the current data source, false otherwise.
1528           The default implementation always returns false.
1529
1530       validate_datetime_keyword STRING
1531           Returns true if STRING is a valid keyword for the "datetime"
1532           (month, day, year, hour, minute, second) data type of the current
1533           data source, false otherwise.  The default implementation always
1534           returns false.
1535
1536       validate_interval_keyword STRING
1537           Returns true if STRING is a valid keyword for the "interval"
1538           (years, months, days, hours, minutes, seconds) data type of the
1539           current data source, false otherwise.  The default implementation
1540           always returns false.
1541
1542       validate_time_keyword STRING
1543           Returns true if STRING is a valid keyword for the "time" (hour,
1544           minute, second, fractional seconds) data type of the current data
1545           source, false otherwise.  The default implementation always returns
1546           false.
1547
1548       validate_timestamp_keyword STRING
1549           Returns true if STRING is a valid keyword for the "timestamp"
1550           (month, day, year, hour, minute, second, fractional seconds) data
1551           type of the current data source, false otherwise.  The default
1552           implementation always returns false.
1553

DEVELOPMENT POLICY

1555       The Rose development policy applies to this, and all "Rose::*" modules.
1556       Please install Rose from CPAN and then run ""perldoc Rose"" for more
1557       information.
1558

SUPPORT

1560       Any Rose::DB questions or problems can be posted to the
1561       Rose::DB::Object mailing list.  (If the volume ever gets high enough,
1562       I'll create a separate list for Rose::DB, but it isn't an issue right
1563       now.)  To subscribe to the list or view the archives, go here:
1564
1565       <http://groups.google.com/group/rose-db-object>
1566
1567       Although the mailing list is the preferred support mechanism, you can
1568       also email the author (see below) or file bugs using the CPAN bug
1569       tracking system:
1570
1571       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Rose-DB>
1572
1573       There's also a wiki and other resources linked from the Rose project
1574       home page:
1575
1576       <http://rosecode.org>
1577

CONTRIBUTORS

1579       Kostas Chatzikokolakis, Peter Karman, Brian Duggan, Lucian Dragus, Ask
1580       Bjørn Hansen, Sergey Leschenko, Ron Savage
1581

AUTHOR

1583       John C. Siracusa (siracusa@gmail.com)
1584

LICENSE

1586       Copyright (c) 2010 by John C. Siracusa.  All rights reserved.  This
1587       program is free software; you can redistribute it and/or modify it
1588       under the same terms as Perl itself.
1589
1590
1591
1592perl v5.36.0                      2022-07-22                       Rose::DB(3)
Impressum