1Rose::DB(3) User Contributed Perl Documentation Rose::DB(3)
2
6 Rose::DB - A DBI wrapper and abstraction layer.
7
9 package My::DB;
10 use Rose::DB;
12 our @ISA = qw(Rose::DB);
13 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 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 My::DB->default_domain('development');
37 My::DB->default_type('main');
38 ...
39 $db = My::DB->new;
41 my $dbh = $db->dbh or die $db->error;
43 $db->begin_work or die $db->error;
45 $dbh->do(...) or die $db->error;
46 $db->commit or die $db->error;
47 $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 $dt = $db->parse_timestamp('2001-03-05 12:34:56.123');
59 $val = $db->format_timestamp($dt);
60 $dt = $db->parse_datetime('2001-03-05 12:34:56');
62 $val = $db->format_datetime($dt);
63 $dt = $db->parse_date('2001-03-05');
65 $val = $db->format_date($dt);
66 $bit = $db->parse_bitfield('0x0AF', 32);
68 $val = $db->format_bitfield($bit);
69 ...
71
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 Please see the tutorial (perldoc Rose::DB::Tutorial) for an example
78 usage scenario that reflects "best practices" for this module.
79 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
86 Rose::DB currently supports the following DBI database drivers:
87 DBD::Pg (PostgreSQL)
89 DBD::mysql (MySQL)
90 DBD::MariaDB (MariaDB)
91 DBD::SQLite (SQLite)
92 DBD::Informix (Informix)
93 DBD::Oracle (Oracle)
94 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 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 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 This mapping can be changed using the driver_class class method.
113 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 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
124 The basic features of Rose::DB are as follows.
125 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 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 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 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 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 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 $main_db = Rose::DB->new(type => 'main');
160 $archive_db = Rose::DB->new(type => 'archive');
161 If there is only one database type, then all Rose::DB objects can be
163 instantiated with a bare constructor call like this:
164 $db = Rose::DB->new;
166 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 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 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 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 $main_dbh = Rose::DB->new(type => 'main')->retain_dbh
190 or die Rose::DB->error;
191 $aux_dbh = Rose::DB->new(type => 'aux')->retain_dbh
193 or die Rose::DB->error;
194 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 # WRONG: $dbh will be disconnected immediately after the assignment!
200 $dbh = Rose::DB->new(type => 'main')->dbh or die Rose::DB->error;
201 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 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 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 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 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
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 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 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 (These attributes use the inheritable_scalar method type as defined
257 in Rose::Class::MakeMethods::Generic.)
258 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 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 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 (These attributes use the inheritable_hash method type as defined
275 in Rose::Class::MakeMethods::Generic.)
276
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 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 Imagine that this is your Rose::DB-derived class:
292 package My::DB;
294 use Rose::DB;
296 our @ISA = qw(Rose::DB);
297 My::DB->register_db(
299 domain => 'dev',
300 type => 'main',
301 driver => 'Pg',
302 ...
303 );
304 My::DB->register_db(
306 domain => 'prod',
307 type => 'main',
308 driver => 'Pg',
309 ...
310 );
311 My::DB->default_domain('dev');
313 My::DB->default_type('main');
314 In one program, a "My::DB" object is frozen using Storable:
316 # my_freeze_script.pl
318 use My::DB;
320 use Storable qw(nstore);
321 # Create My::DB object
323 $db = My::DB->new(domain => 'dev', type => 'main');
324 # Do work...
326 $db->dbh->db('CREATE TABLE some_table (...)');
327 ...
328 # Serialize $db and store it in frozen_data_file
330 nstore($db, 'frozen_data_file');
331 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 # my_thaw_script.pl
338 # IMPORTANT: load db modules with all data sources registered before
340 # attempting to deserialize objects of this class.
341 use My::DB;
342 use Storable qw(retrieve);
344 # Retrieve frozen My::DB object from frozen_data_file
346 $db = retrieve('frozen_data_file');
347 # Do work...
349 $db->dbh->db('DROP TABLE some_table');
350 ...
351 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
359 There are two ways to alter the initial Rose::DB data source registry.
360 • The ROSEDB_DEVINIT file or module, which can add, modify, or remove
362 data sources and alter the default domain and type.
363 • The ROSEDBRC file, which can modify existing data sources.
365 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 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 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 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 Rose::DB->default_domain('development');
389 Rose::DB->modify_db(domain => 'development',
391 type => 'main_db',
392 database => 'main',
393 username => 'jdoe',
394 password => 'mysecret');
395 1;
397 Remember to end the file with a true value.
399 The "ROSEDB_DEVINIT" file or module must be read explicitly by calling
401 the auto_load_fixups class method.
402 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 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 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 The "ROSEDBRC" file's contents have the following structure:
419 ---
421 somedomain:
422 sometype:
423 somemethod: somevalue
424 ---
425 otherdomain:
426 othertype:
427 othermethod: othervalue
428 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 This file must be read explicitly by calling the auto_load_fixups class
434 method after setting up all your data sources. Example:
435 package My::DB;
437 use Rose::DB;
439 our @ISA = qw(Rose::DB);
440 __PACKAGE__->use_private_registry;
442 # 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 ...
455 # Load fix-up files, if any
457 __PACKAGE__->auto_load_fixups;
458
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 Rose::DB->alias_db(source => { domain => 'dev', type => 'main' },
467 alias => { domain => 'dev', type => 'aux' });
468 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 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 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 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 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 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 The default set of default connect options is:
505 AutoCommit => 1,
507 RaiseError => 1,
508 PrintError => 1,
509 ChopBlanks => 1,
510 Warn => 0,
511 See the connect_options object method for more information on how
513 the default connect options are used.
514 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 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 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 $class = Rose::DB->driver_class('Pg'); # get
529 Rose::DB->driver_class('pg' => 'MyDB::Pg'); # set
530 The default mapping of driver names to class names is as follows:
532 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 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 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 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 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 # 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 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 prepare_cache_for_apache_fork
572 This is a convenience method that is equivalent to the following
573 call:
574 Rose::DB->db_cache->prepare_for_apache_fork()
576 Any arguments passed to this method are passed on to the call to
578 the db_cache's prepare_for_apache_fork method.
579 Please read the Rose::DB::Cache documentation, particularly the
581 documentation for the use_cache_during_apache_startup method for
582 more information.
583 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 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 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 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 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 Database registration can be included directly in your Rose::DB
610 subclass. This is the recommended approach. Example:
611 package My::DB;
613 use Rose::DB;
615 our @ISA = qw(Rose::DB);
616 # Use a private registry for this class
618 __PACKAGE__->use_private_registry;
619 # 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 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 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 # File: MyCorp/DataSources.pm
648 package MyCorp::DataSources;
649 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 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 # File: /usr/local/apache/conf/startup.pl
672 use My::DB; # your Rose::DB subclass
674 use MyCorp::DataSources; # register all data sources
675 ...
676 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 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 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 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 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 package My::DB;
708 use Rose::DB;
710 our @ISA = qw(Rose::DB);
711 # 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 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 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 Rose::DB->unregister_db(type => 'main', domain => 'test');
733 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 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 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 Rose::DB->unregister_domain('test');
748 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 use_cache_during_apache_startup [BOOL]
755 This is a convenience method that is equivalent to the following
756 call:
757 Rose::DB->db_cache->use_cache_during_apache_startup(...)
759 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 Please read the Rose::DB::Cache's use_cache_during_apache_startup
764 documentation for more information.
765 use_private_registry
767 This method is used to give a class its own private registry. In
768 other words, this:
769 __PACKAGE__->use_private_registry;
771 is roughly equivalent to this:
773 use Rose::DB::Registry;
775 __PACKAGE__->registry(Rose::DB::Registry->new);
776
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 $db = Rose::DB->new(type => 'main', domain => 'qa');
784 If a single argument is passed to new, it is used as the "type"
786 value:
787 $db = Rose::DB->new(type => 'aux');
789 $db = Rose::DB->new('aux'); # same thing
790 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 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 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 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 # This is ok, even if no registered data sources exist
812 $db = Rose::DB->new(driver => 'sqlite');
813 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 The default driver-to-class mapping is as follows:
820 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 You can change this mapping with the driver_class class method.
829 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 See the Rose::DB::Cache documentation to learn about the cache API
839 and the default implementation.
840
842 begin_work
843 Attempt to start a transaction by calling the begin_work method on
844 the DBI database handle.
845 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 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 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 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 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 If any post_connect_sql statement failed to execute, the database
875 handle is disconnected and then discarded.
876 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 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 connect_option NAME [, VALUE]
889 Get or set a single connection option. Example:
890 $val = $db->connect_option('RaiseError'); # get
892 $db->connect_option(AutoCommit => 1); # set
893 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 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 Returns a reference to the connect options has in scalar context,
905 or a list of name/value pairs in list context.
906 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 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 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 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 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 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 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 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 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 # Transfer $100 from account id 5 to account id 9
958 $db->do_transaction(sub
959 {
960 my($amt, $id1, $id2) = @_;
961 my $dbh = $db->dbh or die $db->error;
963 # 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 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 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 has_dbh
981 Returns true if the object has a DBI database handle (dbh), false
982 if it does not.
983 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 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 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 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 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 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 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 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 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 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 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 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 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 See the "Database Handle Life-Cycle Management" section for more
1058 information on the retain/release system.
1059 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 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 See the "Database Handle Life-Cycle Management" section for more
1071 information on the retain/release system.
1072 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 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 Data Source Configuration
1082 Not all databases will use all of these values. Values that are not
1083 supported are simply ignored.
1084 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 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 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 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 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 Returns a reference to the hash of options in scalar context, or a
1112 list of name/value pairs in list context.
1113 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 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 # Rose::DB->default_connect_options are:
1135 #
1136 # AutoCommit => 1,
1137 # ChopBlanks => 1,
1138 # PrintError => 1,
1139 # RaiseError => 1,
1140 # Warn => 0,
1141 # 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 # $db->connect_options are:
1148 #
1149 # AutoCommit => 0,
1150 # ChopBlanks => 1,
1151 # PrintError => 1,
1152 # RaiseError => 0,
1153 # Warn => 0,
1154 $db->connect_options(TraceLevel => 2); # Add an option
1156 # $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 # 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 # $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 database [NAME]
1181 Get or set the database name used in the construction of the DSN
1182 used in the DBI connect call.
1183 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 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 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 The driver names for the currently supported database types are:
1201 pg
1203 mysql
1204 mariadb
1205 informix
1206 oracle
1207 sqlite
1208 Driver names should only use lowercase letters.
1210 dsn [DSN]
1212 Get or set the DBI DSN (Data Source Name) passed to the call to
1213 DBI's connect method.
1214 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 If the DSN is never set explicitly, it is built automatically based
1221 on the relevant object attributes.
1222 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 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 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 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 password [PASS]
1247 Get or set the password that will be passed to the DBI connect
1248 call.
1249 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 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 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 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 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 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 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 "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 "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 "table"
1298 The name of the table. This parameter is required.
1299 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 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 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 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 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 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 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 See the DateTime::TimeZone documentation for acceptable values of
1341 TZ.
1342 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 username [NAME]
1348 Get or set the username that will be passed to the DBI connect
1349 call.
1350 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 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 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 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 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 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 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 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 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 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 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 If BITS matches any of these regular expressions:
1418 /^0x/
1420 /^X'.*'$/
1421 /^[0-9a-f]+$/
1422 it is assumed to be a hexadecimal number and is converted to a
1424 bitfield as such.
1425 Otherwise, undef is returned.
1427 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 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 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 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 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 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 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 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 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 Valid modes are "wrap", "limit", and "preserve". See the
1481 documentation for DateTime::Duration for a full explanation.
1482 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 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 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 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 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 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 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 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 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 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 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 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
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
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 <http://groups.google.com/group/rose-db-object>
1566 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 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Rose-DB>
1572 There's also a wiki and other resources linked from the Rose project
1574 home page:
1575 <http://rosecode.org>
1577
1579 Kostas Chatzikokolakis, Peter Karman, Brian Duggan, Lucian Dragus, Ask
1580 Bjørn Hansen, Sergey Leschenko, Ron Savage
1581
1583 John C. Siracusa (siracusa@gmail.com)
1584
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.
1589perl v5.36.0 2022-07-22 Rose::DB(3)