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.