1Rose::DB::Object(3) User Contributed Perl Documentation Rose::DB::Object(3)
2
6 Rose::DB::Object - Extensible, high performance object-relational
7 mapper (ORM).
8
10 ## For an informal overview of Rose::DB::Object, please
11 ## see the Rose::DB::Object::Tutorial documentation. The
12 ## reference documentation follows.
13 ## First, set up your Rose::DB data sources, otherwise you
15 ## won't be able to connect to the database at all. See
16 ## the Rose::DB documentation for more information. For
17 ## a quick start, see the Rose::DB::Tutorial documentation.
18 ##
20 ## Create classes - two possible approaches:
21 ##
22 #
24 # 1. Automatic configuration
25 #
26 package Category;
28 use base qw(Rose::DB::Object);
29 __PACKAGE__->meta->setup
30 (
31 table => 'categories',
32 auto => 1,
33 );
34 ...
36 package Price;
38 use base qw(Rose::DB::Object);
39 __PACKAGE__->meta->setup
40 (
41 table => 'prices',
42 auto => 1,
43 );
44 ...
46 package Product;
48 use base qw(Rose::DB::Object);
49 __PACKAGE__->meta->setup
50 (
51 table => 'products',
52 auto => 1,
53 );
54 #
56 # 2. Manual configuration
57 #
58 package Category;
60 use base qw(Rose::DB::Object);
62 __PACKAGE__->meta->setup
64 (
65 table => 'categories',
66 columns =>
68 [
69 id => { type => 'int', primary_key => 1 },
70 name => { type => 'varchar', length => 255 },
71 description => { type => 'text' },
72 ],
73 unique_key => 'name',
75 );
76 ...
78 package Price;
80 use base qw(Rose::DB::Object);
82 __PACKAGE__->meta->setup
84 (
85 table => 'prices',
86 columns =>
88 [
89 id => { type => 'int', primary_key => 1 },
90 price => { type => 'decimal' },
91 region => { type => 'char', length => 3 },
92 product_id => { type => 'int' }
93 ],
94 unique_key => [ 'product_id', 'region' ],
96 );
97 ...
99 package Product;
101 use base qw(Rose::DB::Object);
103 __PACKAGE__->meta->setup
105 (
106 table => 'products',
107 columns =>
109 [
110 id => { type => 'int', primary_key => 1 },
111 name => { type => 'varchar', length => 255 },
112 description => { type => 'text' },
113 category_id => { type => 'int' },
114 status =>
116 {
117 type => 'varchar',
118 check_in => [ 'active', 'inactive' ],
119 default => 'inactive',
120 },
121 start_date => { type => 'datetime' },
123 end_date => { type => 'datetime' },
124 date_created => { type => 'timestamp', default => 'now' },
126 last_modified => { type => 'timestamp', default => 'now' },
127 ],
128 unique_key => 'name',
130 foreign_keys =>
132 [
133 category =>
134 {
135 class => 'Category',
136 key_columns => { category_id => 'id' },
137 },
138 ],
139 relationships =>
141 [
142 prices =>
143 {
144 type => 'one to many',
145 class => 'Price',
146 column_map => { id => 'product_id' },
147 },
148 ],
149 );
150 ...
152 #
154 # Example usage
155 #
156 $product = Product->new(id => 123,
158 name => 'GameCube',
159 status => 'active',
160 start_date => '11/5/2001',
161 end_date => '12/1/2007',
162 category_id => 5);
163 $product->save;
165 ...
167 $product = Product->new(id => 123);
169 $product->load;
170 # Load foreign object via "one to one" relationship
172 print $product->category->name;
173 $product->end_date->add(days => 45);
175 $product->save;
177 ...
179 $product = Product->new(id => 456);
181 $product->load;
182 # Load foreign objects via "one to many" relationship
184 print join ' ', $product->prices;
185 ...
187
189 Rose::DB::Object is a base class for objects that encapsulate a single
190 row in a database table. Rose::DB::Object-derived objects are
191 sometimes simply called "Rose::DB::Object objects" in this
192 documentation for the sake of brevity, but be assured that derivation
193 is the only reasonable way to use this class.
194 Rose::DB::Object inherits from, and follows the conventions of,
196 Rose::Object. See the Rose::Object documentation for more information.
197 For an informal overview of this module distribution, consult the
199 Rose::DB::Object::Tutorial.
200 Restrictions
202 Rose::DB::Object objects can represent rows in almost any database
203 table, subject to the following constraints.
204 • The database server must be supported by Rose::DB.
206 • The database table must have a primary key.
208 • The primary key must not allow null values in any of its columns.
210 Although the list above contains the only hard and fast rules, there
212 may be other realities that you'll need to work around.
213 The most common example is the existence of a column name in the
215 database table that conflicts with the name of a method in the
216 Rose::DB::Object API. There are two possible workarounds: either
217 explicitly alias the column, or define a mapping function. See the
218 alias_column and column_name_to_method_name_mapper methods in the
219 Rose::DB::Object::Metadata documentation for more details.
220 There are also varying degrees of support for data types in each
222 database server supported by Rose::DB. If you have a table that uses a
223 data type not supported by an existing
224 Rose::DB::Object::Metadata::Column-derived class, you will have to
225 write your own column class and then map it to a type name using
226 Rose::DB::Object::Metadata's column_type_class method, yada yada. (Or,
227 of course, you can map the new type to an existing column class.)
228 The entire framework is extensible. This module distribution contains
230 straight-forward implementations of the most common column types, but
231 there's certainly more that can be done. Submissions are welcome.
232 Features
234 Rose::DB::Object provides the following functions:
235 • Create a row in the database by saving a newly constructed object.
237 • Initialize an object by loading a row from the database.
239 • Update a row by saving a modified object back to the database.
241 • Delete a row from the database.
243 • Fetch an object referred to by a foreign key in the current object.
245 (i.e., "one to one" and "many to one" relationships.)
246 • Fetch multiple objects that refer to the current object, either
248 directly through foreign keys or indirectly through a mapping
249 table. (i.e., "one to many" and "many to many" relationships.)
250 • Load an object along with "foreign objects" that are related
252 through any of the supported relationship types.
253 Objects can be loaded based on either a primary key or a unique key.
255 Since all tables fronted by Rose::DB::Objects must have non-null
256 primary keys, insert, update, and delete operations are done based on
257 the primary key.
258 In addition, its sibling class, Rose::DB::Object::Manager, can do the
260 following:
261 • Fetch multiple objects from the database using arbitrary query
263 conditions, limits, and offsets.
264 • Iterate over a list of objects, fetching from the database in
266 response to each step of the iterator.
267 • Fetch objects along with "foreign objects" (related through any of
269 the supported relationship types) in a single query by
270 automatically generating the appropriate SQL join(s).
271 • Count the number of objects that match a complex query.
273 • Update objects that match a complex query.
275 • Delete objects that match a complex query.
277 Rose::DB::Object::Manager can be subclassed and used separately (the
279 recommended approach), or it can create object manager methods within a
280 Rose::DB::Object subclass. See the Rose::DB::Object::Manager
281 documentation for more information.
282 Rose::DB::Object can parse, coerce, inflate, and deflate column values
284 on your behalf, providing the most convenient possible data
285 representations on the Perl side of the fence, while allowing the
286 programmer to completely forget about the ugly details of the data
287 formats required by the database. Default implementations are included
288 for most common column types, and the framework is completely
289 extensible.
290 Finally, the Rose::DB::Object::Loader can be used to automatically
292 create a suite of Rose::DB::Object and Rose::DB::Object::Manager
293 subclasses based on the contents of the database.
294 Configuration
296 Before Rose::DB::Object can do any useful work, you must register at
297 least one Rose::DB data source. By default, Rose::DB::Object
298 instantiates a Rose::DB object by passing no arguments to its
299 constructor. (See the db method.) If you register a Rose::DB data
300 source using the default type and domain, this will work fine.
301 Otherwise, you must override the meta method in your Rose::DB::Object
302 subclass and have it return the appropriate Rose::DB-derived object.
303 To define your own Rose::DB::Object-derived class, you must describe
305 the table that your class will act as a front-end for. This is done
306 through the Rose::DB::Object::Metadata object associated with each
307 Rose::DB::Object-derived class. The metadata object is accessible via
308 Rose::DB::Object's meta method.
309 Metadata objects can be populated manually or automatically. Both
311 techniques are shown in the synopsis above. The automatic mode works
312 by asking the database itself for the information. There are some
313 caveats to this approach. See the auto-initialization section of the
314 Rose::DB::Object::Metadata documentation for more information.
315 Serial and Auto-Incremented Columns
317 Most databases provide a way to use a series of arbitrary integers as
318 primary key column values. Some support a native "SERIAL" column data
319 type. Others use a special auto-increment column attribute.
320 Rose::DB::Object supports at least one such serial or auto-incremented
322 column type in each supported database. In all cases, the
323 Rose::DB::Object-derived class setup is the same:
324 package My::DB::Object;
326 ...
327 __PACKAGE__->meta->setup
328 (
329 columns =>
330 [
331 id => { type => 'serial', primary_key => 1, not_null => 1 },
332 ...
333 ],
334 ...
335 );
336 (Note that the column doesn't have to be named "id"; it can be named
338 anything.)
339 If the database column uses big integers, use "bigserial" column "type"
341 instead.
342 Given the column metadata definition above, Rose::DB::Object will
344 automatically generate and/or retrieve the primary key column value
345 when an object is save()d. Example:
346 $o = My::DB::Object->new(name => 'bud'); # no id specified
348 $o->save; # new id value generated here
349 print "Generated new id value: ", $o->id;
351 This will only work, however, if the corresponding column definition in
353 the database is set up correctly. The exact technique varies from
354 vendor to vendor. Below are examples of primary key column definitions
355 that provide auto-generated values. There's one example for each of
356 the databases supported by Rose::DB.
357 • PostgreSQL
359 CREATE TABLE mytable
361 (
362 id SERIAL PRIMARY KEY,
363 ...
364 );
365 • MySQL
367 CREATE TABLE mytable
369 (
370 id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
371 ...
372 );
373 • SQLite
375 CREATE TABLE mytable
377 (
378 id INTEGER PRIMARY KEY AUTOINCREMENT,
379 ...
380 );
381 • Informix
383 CREATE TABLE mytable
385 (
386 id SERIAL NOT NULL PRIMARY KEY,
387 ...
388 );
389 • Oracle
391 Since Oracle does not natively support a serial or auto-incremented
393 column data type, an explicit sequence and trigger must be created
394 to simulate the behavior. The sequence should be named according
395 to this convention: "<table>_<column>_seq". For example, if the
396 table is named "mytable" and the column is named "id", then the
397 sequence should be named "mytable_id_seq". Here's an example
398 database setup.
399 CREATE TABLE mytable
401 (
402 id INT NOT NULL PRIMARY KEY,
403 ...
404 );
405 CREATE SEQUENCE mytable_id_seq;
407 CREATE TRIGGER mytable_insert BEFORE INSERT ON mytable
409 FOR EACH ROW
410 BEGIN
411 IF :new.id IS NULL THEN
412 :new.id := mytable_id_seq.nextval;
413 END IF;
414 END;
415 Note the conditional that checks if ":new.id" is null, which allows
417 the value of the "id" column to be set explicitly. If a non-NULL
418 value for the "id" column is provided, then a new value is not
419 pulled from the sequence.
420 If the sequence is not named according to the
422 "<table>_<column>_seq" convention, you can specify the sequence
423 name explicitly in the column metadata. Example:
424 columns =>
426 [
427 id => { type => 'serial', primary_key => 1, not_null => 1,
428 sequence => 'some_other_seq' },
429 ...
430 If the table has a multi-column primary key or does not use a column
432 type that supports auto-generated values, you can define a custom
433 primary key generator function using the primary_key_generator method
434 of the Rose::DB::Object::Metadata-derived object that contains the
435 metadata for this class. Example:
436 package MyDBObject;
438 use base qw(Rose::DB::Object);
440 __PACKAGE__->meta->setup
442 (
443 table => 'mytable',
444 columns =>
446 [
447 k1 => { type => 'int', not_null => 1 },
448 k2 => { type => 'int', not_null => 1 },
449 name => { type => 'varchar', length => 255 },
450 ...
451 ],
452 primary_key_columns => [ 'k1', 'k2' ],
454 primary_key_generator => sub
456 {
457 my($meta, $db) = @_;
458 # Generate primary key values somehow
460 my $k1 = ...;
461 my $k2 = ...;
462 return $k1, $k2;
464 },
465 );
466 See the Rose::DB::Object::Metadata documentation for more information
468 on custom primary key generators.
469 Inheritance
471 Simple, single inheritance between Rose::DB::Object-derived classes is
472 supported. (Multiple inheritance is not currently supported.) The
473 first time the metadata object for a given class is accessed, it is
474 created by making a one-time "deep copy" of the base class's metadata
475 object (as long that the base class has one or more columns set). This
476 includes all columns, relationships, foreign keys, and other metadata
477 from the base class. From that point on, the subclass may add to or
478 modify its metadata without affecting any other class.
479 Tip: When using perl 5.8.0 or later, the Scalar::Util::Clone module is
481 highly recommended. If it's installed, it will be used to more
482 efficiently clone base-class metadata objects.
483 If the base class has already been initialized, the subclass must
485 explicitly specify whether it wants to create a new set of column and
486 relationship methods, or merely inherit the methods from the base
487 class. If the subclass contains any metadata modifications that affect
488 method creation, then it must create a new set of methods to reflect
489 those changes.
490 Finally, note that column types cannot be changed "in-place." To
492 change a column type, delete the old column and add a new one with the
493 same name. This can be done in one step with the replace_column
494 method.
495 Example:
497 package BaseClass;
499 use base 'Rose::DB::Object';
500 __PACKAGE__->meta->setup
502 (
503 table => 'objects',
504 columns =>
506 [
507 id => { type => 'int', primary_key => 1 },
508 start => { type => 'scalar' },
509 ],
510 );
511 ...
513 package SubClass;
515 use base 'BaseClass';
516 # Set a default value for this column.
518 __PACKAGE__->meta->column('id')->default(123);
519 # Change the "start" column into a datetime column.
521 __PACKAGE__->meta->replace_column(start => { type => 'datetime' });
522 # Initialize, replacing any inherited methods with newly created ones
524 __PACKAGE__->meta->initialize(replace_existing => 1);
525 ...
527 $b = BaseClass->new;
529 $id = $b->id; # undef
531 $b->start('1/2/2003');
533 print $b->start; # '1/2/2003' (plain string)
534 $s = SubClass->new;
537 $id = $s->id; # 123
539 $b->start('1/2/2003'); # Value is converted to a DateTime object
541 print $b->start->strftime('%B'); # 'January'
542 To preserve all inherited methods in a subclass, do this instead:
544 package SubClass;
546 use base 'BaseClass';
547 __PACKAGE__->meta->initialize(preserve_existing => 1);
548 Error Handling
550 Error handling for Rose::DB::Object-derived objects is controlled by
551 the error_mode method of the Rose::DB::Object::Metadata object
552 associated with the class (accessible via the meta method). The
553 default setting is "fatal", which means that Rose::DB::Object methods
554 will croak if they encounter an error.
555 PLEASE NOTE: The error return values described in the object method
557 documentation are only relevant when the error mode is set to something
558 "non-fatal." In other words, if an error occurs, you'll never see any
559 of those return values if the selected error mode dies or croaks or
560 otherwise throws an exception when an error occurs.
561
563 new PARAMS
564 Returns a new Rose::DB::Object constructed according to PARAMS,
565 where PARAMS are name/value pairs. Any object method is a valid
566 parameter name.
567
569 init_db
570 Returns the Rose::DB-derived object used to access the database in
571 the absence of an explicit db value. The default implementation
572 simply calls Rose::DB->new() with no arguments.
573 Override this method in your subclass in order to use a different
575 default data source. Note: This method must be callable as both an
576 object method and a class method.
577 meta
579 Returns the Rose::DB::Object::Metadata-derived object associated
580 with this class. This object describes the database table whose
581 rows are fronted by this class: the name of the table, its columns,
582 unique keys, foreign keys, etc.
583 See the Rose::DB::Object::Metadata documentation for more
585 information.
586 meta_class
588 Return the name of the Rose::DB::Object::Metadata-derived class
589 used to store this object's metadata. Subclasses should override
590 this method if they want to use a custom Rose::DB::Object::Metadata
591 subclass. (See the source code for Rose::DB::Object::Std for an
592 example of this.)
593
595 db [DB]
596 Get or set the Rose::DB object used to access the database that
597 contains the table whose rows are fronted by the
598 Rose::DB::Object-derived class.
599 If it does not already exist, this object is created with a simple,
601 argument-less call to "Rose::DB->new()". To override this default
602 in a subclass, override the init_db method and return the Rose::DB
603 to be used as the new default.
604 init_db
606 Returns the Rose::DB-derived object used to access the database in
607 the absence of an explicit db value. The default implementation
608 simply calls Rose::DB->new() with no arguments.
609 Override this method in your subclass in order to use a different
611 default data source. Note: This method must be callable as both an
612 object method and a class method.
613 dbh [DBH]
615 Get or set the DBI database handle contained in db.
616 delete [PARAMS]
618 Delete the row represented by the current object. The object must
619 have been previously loaded from the database (or must otherwise
620 have a defined primary key value) in order to be deleted. Returns
621 true if the row was deleted or did not exist, false otherwise.
622 PARAMS are optional name/value pairs. Valid PARAMS are:
624 cascade TYPE
626 Also process related rows. TYPE must be "delete", "null", or
627 "1". The value "1" is an alias for "delete". Passing an
628 illegal TYPE value will cause a fatal error.
629 For each "one to many" relationship, all of the rows in the
631 foreign ("many") table that reference the current object
632 ("one") will be deleted in "delete" mode, or will have the
633 column(s) that reference the current object set to NULL in
634 "null" mode.
635 For each "many to many" relationship, all of the rows in the
637 "mapping table" that reference the current object will deleted
638 in "delete" mode, or will have the columns that reference the
639 two tables that the mapping table maps between set to NULL in
640 "null" mode.
641 For each "one to one" relationship or foreign key with a "one
643 to one" relationship type, all of the rows in the foreign table
644 that reference the current object will deleted in "delete"
645 mode, or will have the column(s) that reference the current
646 object set to NULL in "null" mode.
647 In all modes, if the db is not currently in a transaction, a
649 new transaction is started. If any part of the cascaded delete
650 fails, the transaction is rolled back.
651 prepare_cached BOOL
653 If true, then DBI's prepare_cached method will be used (instead
654 of the prepare method) when preparing the SQL statement that
655 will delete the object. If omitted, the default value is
656 determined by the metadata object's dbi_prepare_cached class
657 method.
658 The cascaded delete feature described above plays it safe by only
660 deleting rows that are not referenced by any other rows (according
661 to the metadata provided by each Rose::DB::Object-derived class).
662 I strongly recommend that you implement "cascaded delete" in the
663 database itself, rather than using this feature. It will
664 undoubtedly be faster and more robust than doing it "client-side."
665 You may also want to cascade only to certain tables, or otherwise
666 deviate from the "safe" plan. If your database supports automatic
667 cascaded delete and/or triggers, please consider using these
668 features.
669 error
671 Returns the text message associated with the last error that
672 occurred.
673 insert [PARAMS]
675 Insert the current object to the database table. This method
676 should only be used when you're absolutely sure that you want to
677 force the current object to be inserted, rather than updated. It
678 is recommended that you use the save method instead of this one in
679 most circumstances. The save method will "do the right thing,"
680 executing an insert or update as appropriate for the current
681 situation.
682 PARAMS are optional name/value pairs. Valid PARAMS are:
684 changes_only BOOL
686 If true, then only the columns whose values have been modified
687 will be included in the insert query. Otherwise, all columns
688 will be included. Note that any column that has a default
689 value set in its column metadata is considered "modified"
690 during an insert operation.
691 If omitted, the default value of this parameter is determined
693 by the metadata object's default_insert_changes_only class
694 method, which returns false by default.
695 prepare_cached BOOL
697 If true, then DBI's prepare_cached method will be used (instead
698 of the prepare method) when preparing the SQL statement that
699 will insert the object. If omitted, the default value is
700 determined by the metadata object's dbi_prepare_cached class
701 method.
702 Returns true if the row was inserted successfully, false otherwise.
704 The true value returned on success will be the object itself. If
705 the object overloads its boolean value such that it is not true,
706 then a true value will be returned instead of the object itself.
707 load [PARAMS]
709 Load a row from the database table, initializing the object with
710 the values from that row. An object can be loaded based on either
711 a primary key or a unique key.
712 Returns true if the row was loaded successfully, undef if the row
714 could not be loaded due to an error, or zero (0) if the row does
715 not exist. The true value returned on success will be the object
716 itself. If the object overloads its boolean value such that it is
717 not true, then a true value will be returned instead of the object
718 itself.
719 When loading based on a unique key, unique keys are considered in
721 the order in which they were defined in the metadata for this
722 class. If the object has defined values for every column in a
723 unique key, then that key is used. If no such key is found, then
724 the first key for which the object has at least one defined value
725 is used.
726 PARAMS are optional name/value pairs. Valid PARAMS are:
728 for_update BOOL
730 If true, this parameter is translated to be the equivalent of
731 passing the lock parameter and setting the "type" to "for
732 update". For example, these are both equivalent:
733 $object->load(for_update => 1);
735 $object->load(lock => { type => 'for update' });
736 See the lock parameter below for more information.
738 lock [ TYPE | HASHREF ]
740 Load the object using some form of locking. These lock
741 directives have database-specific behavior and not all
742 directives are supported by all databases. The value should be
743 a reference to a hash or a TYPE string, which is equivalent to
744 setting the value of the "type" key in the hash reference form.
745 For example, these are both equivalent:
746 $object->load(lock => 'for update');
748 $object->load(lock => { type => 'for update' });
749 Valid hash keys are:
751 columns ARRAYREF
753 A reference to an array of column names to lock.
754 References to scalars will be de-referenced and used as-is,
755 included literally in the SQL locking clause.
756 "nowait BOOL"
758 If true, do not wait to acquire the lock. If supported,
759 this is usually by adding a "NOWAIT" directive to the SQL.
760 "type TYPE"
762 The lock type. Valid values for TYPE are "for update" and
763 "shared". This parameter is required unless the for_update
764 parameter was passed with a true value.
765 "wait TIME"
767 Wait for the specified TIME (generally seconds) before
768 giving up acquiring the lock. If supported, this is
769 usually by adding a "WAIT ..." clause to the SQL.
770 nonlazy BOOL
772 If true, then all columns will be fetched from the database,
773 even lazy columns. If omitted, the default is false.
774 prepare_cached BOOL
776 If true, then DBI's prepare_cached method will be used (instead
777 of the prepare method) when preparing the SQL query that will
778 load the object. If omitted, the default value is determined
779 by the metadata object's dbi_prepare_cached class method.
780 speculative BOOL
782 If this parameter is passed with a true value, and if the load
783 failed because the row was not found, then the error_mode
784 setting is ignored and zero (0) is returned. In the absence of
785 an explicitly set value, this parameter defaults to the value
786 returned my the metadata object's default_load_speculative
787 method.
788 use_key KEY
790 Use the unique key named KEY to load the object. This
791 overrides the unique key selection process described above.
792 The key must have a defined value in at least one of its
793 columns.
794 with OBJECTS
796 Load the object and the specified "foreign objects"
797 simultaneously. OBJECTS should be a reference to an array of
798 foreign key or relationship names.
799 SUBCLASS NOTE: If you are going to override the load method in your
801 subclass, you must pass an alias to the actual object as the first
802 argument to the method, rather than passing a copy of the object
803 reference. Example:
804 # This is the CORRECT way to override load() while still
806 # calling the base class version of the method.
807 sub load
808 {
809 my $self = $_[0]; # Copy, not shift
810 ... # Do your stuff
812 shift->SUPER::load(@_); # Call superclass
814 }
815 Now here's the wrong way:
817 # This is the WRONG way to override load() while still
819 # calling the base class version of the method.
820 sub load
821 {
822 my $self = shift; # WRONG! The alias to the object is now lost!
823 ... # Do your stuff
825 $self->SUPER::load(@_); # This won't work right!
827 }
828 This requirement exists in order to preserve some sneaky object-
830 replacement optimizations in the base class implementation of load.
831 At some point, those optimizations may change or go away. But if
832 you follow these guidelines, your code will continue to work no
833 matter what.
834 not_found
836 Returns true if the previous call to load failed because a row in
837 the database table with the specified primary or unique key did not
838 exist, false otherwise.
839 meta
841 Returns the Rose::DB::Object::Metadata object associated with this
842 class. This object describes the database table whose rows are
843 fronted by this class: the name of the table, its columns, unique
844 keys, foreign keys, etc.
845 See the Rose::DB::Object::Metadata documentation for more
847 information.
848 save [PARAMS]
850 Save the current object to the database table. In the absence of
851 PARAMS, if the object was previously loaded from the database, the
852 row will be updated. Otherwise, a new row will be inserted.
853 PARAMS are name/value pairs. Valid PARAMS are listed below.
854 Actions associated with sub-objects that were added or deleted
856 using one of the "*_on_save" relationship or foreign key method
857 types are also performed when this method is called. If there are
858 any such actions to perform, a new transaction is started if the db
859 is not already in one, and rollback() is called if any of the
860 actions fail during the save(). Example:
861 $product = Product->new(name => 'Sled');
863 $vendor = Vendor->new(name => 'Acme');
864 $product->vendor($vendor);
866 # Product and vendor records created and linked together,
868 # all within a single transaction.
869 $product->save;
870 See the "making methods" sections of the
872 Rose::DB::Object::Metadata::Relationship and
873 Rose::DB::Object::Metadata::ForeignKey documentation for a
874 description of the "method map" associated with each relationship
875 and foreign key. Only the actions initiated through one of the
876 "*_on_save" method types are handled when save() is called. See
877 the documentation for each individual "*_on_save" method type for
878 more specific information.
879 Valid parameters to save() are:
881 cascade BOOL
883 If true, then sub-objects related to this object through a
884 foreign key or relationship that have been previously loaded
885 using methods called on this object and that contain unsaved
886 changes will be saved after the parent object is saved. This
887 proceeds recursively through all sub-objects. (All other
888 parameters to the original call to save are also passed on when
889 saving sub-objects.)
890 All database operations are done within a single transaction.
892 If the db is not currently in a transaction, a new transaction
893 is started. If any part of the cascaded save fails, the
894 transaction is rolled back.
895 If omitted, the default value of this parameter is determined
897 by the metadata object's default_cascade_save class method,
898 which returns false by default.
899 Example:
901 $p = Product->new(id => 123)->load;
903 print join(', ', $p->colors); # related Color objects loaded
905 $p->colors->[0]->code('zzz'); # one Color object is modified
906 # The Product object and the modified Color object are saved
908 $p->save(cascade => 1);
909 changes_only BOOL
911 If true, then only the columns whose values have been modified
912 will be included in the insert or update query. Otherwise, all
913 eligible columns will be included. Note that any column that
914 has a default value set in its column metadata is considered
915 "modified" during an insert operation.
916 If omitted, the default value of this parameter is determined
918 by the metadata object's default_update_changes_only class
919 method on update, and the default_insert_changes_only class
920 method on insert, both of which return false by default.
921 insert BOOL
923 If set to a true value, then an insert is attempted, regardless
924 of whether or not the object was previously loaded from the
925 database.
926 prepare_cached BOOL
928 If true, then DBI's prepare_cached method will be used (instead
929 of the prepare method) when preparing the SQL statement that
930 will save the object. If omitted, the default value is
931 determined by the metadata object's dbi_prepare_cached class
932 method.
933 update BOOL
935 If set to a true value, then an update is attempted, regardless
936 of whether or not the object was previously loaded from the
937 database.
938 It is an error to pass both the "insert" and "update" parameters in
940 a single call.
941 Returns true if the row was inserted or updated successfully, false
943 otherwise. The true value returned on success will be the object
944 itself. If the object overloads its boolean value such that it is
945 not true, then a true value will be returned instead of the object
946 itself.
947 If an insert was performed and the primary key is a single column
949 that supports auto-generated values, then the object accessor for
950 the primary key column will contain the auto-generated value. See
951 the Serial and Auto-Incremented Columns section for more
952 information.
953 update [PARAMS]
955 Update the current object in the database table. This method
956 should only be used when you're absolutely sure that you want to
957 force the current object to be updated, rather than inserted. It
958 is recommended that you use the save method instead of this one in
959 most circumstances. The save method will "do the right thing,"
960 executing an insert or update as appropriate for the current
961 situation.
962 PARAMS are optional name/value pairs. Valid PARAMS are:
964 changes_only BOOL
966 If true, then only the columns whose values have been modified
967 will be updated. Otherwise, all columns whose values have been
968 loaded from the database will be updated. If omitted, the
969 default value of this parameter is determined by the metadata
970 object's default_update_changes_only class method, which
971 returns false by default.
972 prepare_cached BOOL
974 If true, then DBI's prepare_cached method will be used (instead
975 of the prepare method) when preparing the SQL statement that
976 will insert the object. If omitted, the default value of this
977 parameter is determined by the metadata object's
978 dbi_prepare_cached class method.
979 Returns true if the row was updated successfully, false otherwise.
981 The true value returned on success will be the object itself. If
982 the object overloads its boolean value such that it is not true,
983 then a true value will be returned instead of the object itself.
984
986 As described in the Rose::DB::Object::Metadata documentation, each
987 column in the database table has an associated get/set accessor method
988 in the Rose::DB::Object. Since the Rose::DB::Object API already
989 defines many methods (load, save, meta, etc.), accessor methods for
990 columns that share the name of an existing method pose a problem. The
991 solution is to alias such columns using Rose::DB::Object::Metadata's
992 alias_column method.
993 Here is a list of method names reserved by the Rose::DB::Object API.
995 If you have a column with one of these names, you must alias it.
996 db
998 dbh
999 delete
1000 DESTROY
1001 error
1002 init_db
1003 _init_db
1004 insert
1005 load
1006 meta
1007 meta_class
1008 not_found
1009 save
1010 update
1011 Note that not all of these methods are public. These methods do not
1013 suddenly become public just because you now know their names! Remember
1014 the stated policy of the Rose web application framework: if a method is
1015 not documented, it does not exist. (And no, the list of method names
1016 above does not constitute "documentation.")
1017
1019 The Rose development policy applies to this, and all "Rose::*" modules.
1020 Please install Rose from CPAN and then run ""perldoc Rose"" for more
1021 information.
1022
1024 For an informal overview of Rose::DB::Object, consult the
1025 Rose::DB::Object::Tutorial.
1026 perldoc Rose::DB::Object::Tutorial
1028 Any Rose::DB::Object questions or problems can be posted to the
1030 Rose::DB::Object mailing list. To subscribe to the list or view the
1031 archives, go here:
1032 <http://groups.google.com/group/rose-db-object>
1034 Although the mailing list is the preferred support mechanism, you can
1036 also email the author (see below) or file bugs using the CPAN bug
1037 tracking system:
1038 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Rose-DB-Object>
1040 There's also a wiki and other resources linked from the Rose project
1042 home page:
1043 <http://rosecode.org>
1045
1047 Bradley C Bailey, Graham Barr, Kostas Chatzikokolakis, David
1048 Christensen, Lucian Dragus, Justin Ellison, Perrin Harkins, Cees Hek,
1049 Benjamin Hitz, Dave Howorth, Peter Karman, Ed Loehr, Adam Mackler,
1050 Michael Reece, Thomas Whaples, Douglas Wilson, Teodor Zlatanov
1051
1053 John C. Siracusa (siracusa@gmail.com)
1054
1056 Copyright (c) 2010 by John C. Siracusa. All rights reserved. This
1057 program is free software; you can redistribute it and/or modify it
1058 under the same terms as Perl itself.
1059perl v5.38.0 2023-07-21 Rose::DB::Object(3)