.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Rose::DB::Object::Std 3pm"
.TH Rose::DB::Object::Std 3pm "2012-04-15" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Rose::DB::Object::Std \- Standardized object representation of a single row in a database table.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  package Category;
\&
\&  use base \*(AqRose::DB::Object::Std\*(Aq;
\&
\&  _\|_PACKAGE_\|_\->meta\->setup
\&  (
\&    table => \*(Aqcategories\*(Aq,
\&
\&    columns =>
\&    [
\&      id          => { type => \*(Aqint\*(Aq, primary_key => 1 },
\&      name        => { type => \*(Aqvarchar\*(Aq, length => 255 },
\&      description => { type => \*(Aqtext\*(Aq },
\&    ],
\&
\&    unique_key => \*(Aqname\*(Aq,
\&  );
\&
\&  ...
\&
\&  package Product;
\&
\&  use base \*(AqRose::DB::Object::Std\*(Aq;
\&
\&  _\|_PACKAGE_\|_\->meta\->setup
\&  (
\&    table => \*(Aqproducts\*(Aq,
\&
\&    columns =>
\&    [
\&      id          => { type => \*(Aqint\*(Aq, primary_key => 1 },
\&      name        => { type => \*(Aqvarchar\*(Aq, length => 255 },
\&      description => { type => \*(Aqtext\*(Aq },
\&      category_id => { type => \*(Aqint\*(Aq },
\&
\&      status => 
\&      {
\&        type      => \*(Aqvarchar\*(Aq, 
\&        check_in  => [ \*(Aqactive\*(Aq, \*(Aqinactive\*(Aq ],
\&        default   => \*(Aqinactive\*(Aq,
\&      },
\&
\&      start_date  => { type => \*(Aqdatetime\*(Aq },
\&      end_date    => { type => \*(Aqdatetime\*(Aq },
\&
\&      date_created     => { type => \*(Aqtimestamp\*(Aq, default => \*(Aqnow\*(Aq },  
\&      last_modified    => { type => \*(Aqtimestamp\*(Aq, default => \*(Aqnow\*(Aq },
\&    ],
\&
\&    unique_key => \*(Aqname\*(Aq,
\&
\&    foreign_keys =>
\&    [
\&      category =>
\&      {
\&        class       => \*(AqCategory\*(Aq,
\&        key_columns => { category_id => \*(Aqid\*(Aq },
\&      },
\&    ],
\&  );
\&
\&  ...
\&
\&  $product = Product\->new(name        => \*(AqGameCube\*(Aq,
\&                          status      => \*(Aqactive\*(Aq,
\&                          start_date  => \*(Aq11/5/2001\*(Aq,
\&                          end_date    => \*(Aq12/1/2007\*(Aq,
\&                          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;
\&
\&  ...
.Ve
.SH "DESCRIPTION"
.IX Header "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:
.IP "\(bu" 4
The table must have a single primary key column named \*(L"id\*(R"
.IP "\(bu" 4
The value of the \*(L"id\*(R" column must be auto-generated if absent.
.PP
Different databases provide for auto-generated column values in different ways.  Some provide a native \*(L"auto-increment\*(R" or \*(L"serial\*(R" data type, others use sequences behind the scenes.
.PP
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 \f(CW\*(C`save()\*(C'\fRed, you can retrieve the auto-selected primary key by calling the \f(CW\*(C`id()\*(C'\fR method.
.PP
You do have to correctly define the \*(L"id\*(R" 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.
.IP "\(bu" 4
PostgreSQL
.Sp
.Vb 5
\&    CREATE TABLE mytable
\&    (
\&      id   SERIAL NOT NULL PRIMARY KEY,
\&      ...
\&    );
.Ve
.IP "\(bu" 4
MySQL
.Sp
.Vb 5
\&    CREATE TABLE mytable
\&    (
\&      id   INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
\&      ...
\&    );
.Ve
.IP "\(bu" 4
Informix
.Sp
.Vb 5
\&    CREATE TABLE mytable
\&    (
\&      id   SERIAL NOT NULL PRIMARY KEY,
\&      ...
\&    );
.Ve
.PP
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.
.PP
To achieve much of this functionality, Rose::DB::Object::Std uses Rose::DB::Object::Std::Metadata objects.  The \f(CW\*(C`meta()\*(C'\fR method will create these form you.  You should not need to do anything special if you use the idimoatic approach to defining metadata as shown in the synopsis.
.SH "METHODS"
.IX Header "METHODS"
Only the methods that are overridden are documented here.  See the Rose::DB::Object documentation for the rest.
.IP "\fBmeta\fR" 4
.IX Item "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.
.Sp
This can be used as both a class method and an object method.
.SH "AUTHOR"
.IX Header "AUTHOR"
John C. Siracusa (siracusa@gmail.com)
.SH "LICENSE"
.IX Header "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.