NAME

       Rose::DB::Object::Std - Standardized object representation of a single row in a database table.

SYNOPSIS

         package Category;

         use base 'Rose::DB::Object::Std';

         __PACKAGE__->meta->setup
         (
           table => 'categories',

           columns =>
           [
             id          => { type => 'int', primary_key => 1 },
             name        => { type => 'varchar', length => 255 },
             description => { type => 'text' },
           ],

           unique_key => 'name',
         );

         ...

         package Product;

         use base 'Rose::DB::Object::Std';

         __PACKAGE__->meta->setup
         (
           table => 'products',

           columns =>
           [
             id          => { type => 'int', primary_key => 1 },
             name        => { type => 'varchar', length => 255 },
             description => { type => 'text' },
             category_id => { type => 'int' },

             status =>
             {
               type      => 'varchar',
               check_in  => [ 'active', 'inactive' ],
               default   => 'inactive',
             },

             start_date  => { type => 'datetime' },
             end_date    => { type => 'datetime' },

             date_created     => { type => 'timestamp', default => 'now' },
             last_modified    => { type => 'timestamp', default => 'now' },
           ],

           unique_key => 'name',

           foreign_keys =>
           [
             category =>
             {
               class       => 'Category',
               key_columns => { category_id => 'id' },
             },
           ],
         );

         ...

         $product = Product->new(name        => 'GameCube',
                                 status      => 'active',
                                 start_date  => '11/5/2001',
                                 end_date    => '12/1/2007',
                                 category_id => 5);

         $product->save or die $product->error;

         $id = $product->id; # auto-generated on save

         ...

         $product = Product->new(id => $id);
         $product->load or die $product->error;

         print $product->category->name;

         $product->end_date->add(days => 45);

         $product->save or die $product->error;

         ...

DESCRIPTION

       Rose::DB::Object::Std is a subclass of Rose::DB::Object that imposes a few more constraints on the tables
       it fronts.  In addition to the constraints described in the Rose::DB::Object documentation, tables
       fronted by Rose::DB::Object::Std objects must also fulfill the following requirements:

       •   The table must have a single primary key column named "id"

       •   The value of the "id" column must be auto-generated if absent.

       Different  databases  provide  for auto-generated column values in different ways.  Some provide a native
       "auto-increment" or "serial" data type, others use sequences behind the scenes.

       Rose::DB::Object::Std (in cooperation with Rose::DB and Rose::DB::Object::Std::Metadata) attempts to hide
       these details from you.  All you have to do is omit the value for the primary key  entirely.   After  the
       object is "save()"ed, you can retrieve the auto-selected primary key by calling the "id()" method.

       You  do  have to correctly define the "id" column in the database, however.  Here are examples of primary
       key column definitions that provide auto-generated values, one for each of  the  databases  supported  by
       Rose::DB.

       •   PostgreSQL

               CREATE TABLE mytable
               (
                 id   SERIAL NOT NULL PRIMARY KEY,
                 ...
               );

       •   MySQL

               CREATE TABLE mytable
               (
                 id   INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
                 ...
               );

       •   Informix

               CREATE TABLE mytable
               (
                 id   SERIAL NOT NULL PRIMARY KEY,
                 ...
               );

       Other  data  definitions  are  possible,  of  course,  but  the  three  definitions above are used in the
       Rose::DB::Object::Std test suite and are  therefore  guaranteed  to  work.   If  you  have  success  with
       alternative approaches, patches and/or new tests are welcome.

       To  achieve  much  of  this  functionality,  Rose::DB::Object::Std  uses  Rose::DB::Object::Std::Metadata
       objects.  The "meta()" method will create these form you.  You should not need to do anything special  if
       you use the idiomatic approach to defining metadata as shown in the synopsis.

METHODS

       Only the methods that are overridden are documented here.  See the Rose::DB::Object documentation for the
       rest.

       meta
           Returns the Rose::DB::Object::Std::Metadata object associated with this class.  This object describes
           the  database  table whose rows are fronted by this class: the name of the table, its columns, unique
           keys, foreign keys, etc.  See the Rose::DB::Object::Std::Metadata documentation for more information.

           This can be used as both a class method and an object method.

AUTHOR

       John C. Siracusa (siracusa@gmail.com)

LICENSE

       Copyright (c) 2010 by John C. Siracusa.  All rights reserved.  This program is  free  software;  you  can
       redistribute it and/or modify it under the same terms as Perl itself.

perl v5.36.0                                       2022-10-14                         Rose::DB::Object::Std(3pm)