NAME

Rose::DB::Object::Metadata - Database object metadata.

SYNOPSIS

  use Rose::DB::Object::Metadata;

  $meta = Rose::DB::Object::Metadata->new(class => 'Product');
  # ...or...
  # $meta = Rose::DB::Object::Metadata->for_class('Product');

  $meta->table('products');

  $meta->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' },
  );

  $meta->add_unique_key('name');

  $meta->foreign_keys
  (
    category =>
    {
      class       => 'Category',
      key_columns =>
      {
        category_id => 'id',
      }
    },
  );

  ...

DESCRIPTION

Rose::DB::Object::Metadata objects store information about a single table in a database: the name of the table, the names and types of columns, any foreign keys, etc. These metadata objects are also responsible for supplying information to, and creating object methods for the Rose::DB::Object-derived objects to which they belong.

Rose::DB::Object::Metadata objects objects are per-class singletons; there is one Rose::DB::Object::Metadata object for each Rose::DB::Object-derived class.

CLASS METHODS

for_class CLASS: Returns (or creates, if needed) the single Rose::DB::Object::Metadata object associated with CLASS, where CLASS is the name of a Rose::DB::Object-derived class.

CONSTRUCTOR

new PARAMS

Returns (or creates, if needed) the single Rose::DB::Object::Metadata associated with a particular Rose::DB::Object-derived class, modifying or initializing it according to PARAMS, where PARAMS are name/value pairs.

Any object method is a valid parameter name, but PARAMS must include a value for the class parameter, since that's how Rose::DB::Object::Metadata objects are mapped to their corresponding Rose::DB::Object-derived class.

OBJECT METHODS

add_column ARGS

This is an alias for the add_columns() method.

add_columns ARGS

Add the columns specified by ARGS to the list of columns for the table. Columns can be specified in ARGS in several ways.

If an argument is a subclass of Rose::DB::Object::Metadata::Column, it is added as-is.

If an argument is a plain scalar, it is taken as the name of a scalar column. A column object of the class returned by the method call column_type_class('scalar') is constructed and then added.

Otherwise, only name/value pairs are considered, where the name is taken as the column name and the value must be a reference to a hash.

If the hash contains the key "primary_key", it is deleted. If the value of the "primary_key" key is true, then the column name is added as a primary key by calling the add_primary_key_column() method with the column name as its argument.

Then the column_type_class() method is called with the value of the "type" hash key as its argument (or "scalar" if that key is missing), returning the name of a column class. Finally, a new column object of that class is constructed and is passed all the remaining pairs in the hash reference, along with the name and type of the column. That column object is then added to the list of columns.

This is done until there are no more arguments to be processed, or until an argument does not conform to one of the required formats, in which case a fatal error occurs.

Example:

    $meta->add_columns
    (
      # Add a scalar column
      'name', 
      #
      # which is roughly equivalent to:
      #
      # $class = $meta->column_type_class('scalar');
      # $col = $class->new(name => 'name');
      # (then add $col to the list of columns)

      # Add by name/hashref pair
      age => { type => 'int', default => 5 },
      #
      # which is roughly equivalent to:
      #
      # $class = $meta->column_type_class('int');
      # $col = $class->new(name    => 'age',
      #                    type    => 'int', 
      #                    default => 5, );
      # (then add $col to the list of columns)

      # Add a column object directly
      Rose::DB::Object::Metadata::Column::Date->new(
        name => 'start_date'),
    );

add_foreign_keys ARGS

Add foreign keys as specified by ARGS. Foreign keys can be specified in ARGS in several ways.

If an argument is a subclass of Rose::DB::Object::Metadata::ForeignKey, it is added as-is.

Otherwise, only name/value pairs are considered, where the name is taken as the foreign key name and the value must be a reference to a hash.

A new Rose::DB::Object::Metadata::ForeignKey object is constructed and is passed all the pairs in the hash reference, along with the name of the foreign key as the value of the "name" parameter. That foreign key object is then added to the list of foreign keys.

This is done until there are no more arguments to be processed, or until an argument does not conform to one of the required formats, in which case a fatal error occurs.

Example:

    $meta->add_foreign_keys
    (      
      # Add by name/hashref pair
      category => 
      {
        class       => 'Category', 
        key_columns => { category_id => 'id' },
      },
      #
      # which is roughly equivalent to:
      #
      # $fk = Rose::DB::Object::Metadata::ForeignKey->new(
      #         class       => 'Category', 
      #         key_columns => { category_id => 'id' },
      #         name        => 'category');
      # (then add $fk to the list of foreign keys)

      # Add a foreign key object directly
      Rose::DB::Object::Metadata::ForeignKey->new(...),
    );

add_primary_key_column COLUMN

This method is an alias for add_primary_key_columns().

add_primary_key_columns COLUMNS

Add COLUMNS to the list of columns that make up the primary key. COLUMNS can be a list or reference to an array of column names.

add_unique_key COLUMNS

Add a new unique key made up of COLUMNS, where COLUMNS is a list or a reference to an array of the column names that make up the key.

alias_column NAME, ALIAS

Use ALIAS instead of NAME as the accessor method name for column named NAME. Note that primary key columns cannot be aliased. If the column NAME is part of the primary key, a fatal error will occur.

It is sometimes necessary to use an alias for a column because the column name conflicts with an existing Rose::DB::Object method name.

For example, imagine a column named "save". The Rose::DB::Object API already defines a method named save(), so obviously that name can't be used for the accessor method for the "save" column. To solve this, make an alias:

    $meta->alias_column(save => 'save_flag');

See the Rose::DB::Object documentation or call the method_name_is_reserved() method to determine if a method name is reserved.

allow_inline_column_values [BOOL]

Get or set the boolean flag that indicates whether or not the associated Rose::DB::Object-derived class should try to inline column values that DBI does not handle correctly when they are bound to placeholders using bind_columns(). The default value is false.

Enabling this flag reduces the performance of the update() and insert() operations on the Rose::DB::Object-derived object. But it is sometimes necessary to enable the flag because some DBI drivers do not (or cannot) always do the right thing when binding values to placeholders in SQL statements. For example, consider the following SQL for the Informix database:

    CREATE TABLE test (d DATETIME YEAR TO SECOND);
    INSERT INTO test (d) VALUES (CURRENT);

This is valid Informix SQL and will insert a row with the current date and time into the "test" table.

Now consider the following attempt to do the same thing using DBI placeholders (assume the table was already created as per the CREATE TABLE statement above):

    $sth = $dbh->prepare('INSERT INTO test (d) VALUES (?)');
    $sth->execute('CURRENT'); # Error!

What you'll end up with is an error like this:

    DBD::Informix::st execute failed: SQL: -1262: Non-numeric 
    character in datetime or interval.

In other words, DBD::Informix has tried to quote the string "CURRENT", which has special meaning to Informix only when it is not quoted.

In order to make this work, the value "CURRENT" must be "inlined" rather than bound to a placeholder when it is the value of a "DATETIME YEAR TO SECOND" column in an Informix database.

class [CLASS]

Get or set the Rose::DB::object-derived class associated with this metadata object. This is the class where the accessor methods for each column will be created (by make_methods()).

column NAME [, COLUMN]

Get or set the column named NAME. If just NAME is passed, the Rose::DB::Object::Metadata::Column-derived column object for the column of that name is returned. If no such column exists, undef is returned.

If both NAME and COLUMN are passed, then COLUMN must be a Rose::DB::Object::Metadata::Column-derived object. COLUMN has its name() set to NAME, and is then stored as the column metadata object for NAME.

columns [ARGS]

Get or set the full list of columns. If ARGS are passed, the column list is cleared and then ARGS are passed to the add_columns() method.

Returns a list of column objects in list context, or a reference to an array of column objects in scalar context.

column_accessor_method COLUMN

Returns the name of the "get" method for COLUMN. This is currently just an alias for column_method() but should still be used for the sake of clarity when you're only interested in a method you can use to get the column value.

column_aliases [MAP]

Get or set the hash that maps column names to their aliases. If passed MAP (a list of name/value pairs or a reference to a hash) then MAP replaces the current alias mapping. Returns a reference to the hash that maps column names to their aliases.

Note that modifying this map has no effect if initialize() or make_methods() has already been called for the current class.

column_method COLUMN

Returns the name of the get/set accessor method for COLUMN. If the column is not aliased, then the accessor name is the same as the column name.

column_methods [MAP]

Get or set the hash that maps column names to their get/set accessor method names. If passed MAP (a list of name/value pairs or a reference to a hash) then MAP replaces the current method mapping.

Note that modifying this map has no effect if initialize() or make_methods() has already been called for the current class.

column_method_names

Returns a list (in list context) or a reference to an array (in scalar context) of method names for all columns, ordered according to the order that the column names are returned from the column_names() method.

column_mutator_method COLUMN

Returns the name of the "set" method for COLUMN. This is currently just an alias for column_method() but should still be used for the sake of clarity when you're only interested in a method you can use to set the column value.

column_names

Returns a list (in list context) or a reference to an array (in scalar context) of column names.

column_type_class TYPE

Given the column type string TYPE, return the name of the Rose::DB::Object::Metadata::Column-derived class used to store metadata and create the accessor method(s) for columns of that type.

column_type_classes [MAP]

Get or set the hash that maps column type strings to the names of the Rose::DB::Object::Metadata::Column-derived classes used to store metadata and create accessor method(s) for columns of that type.

If passed MAP (a list of type/class pairs or a reference to a hash of the same) then MAP replaces the current column type mapping. Returns a list of type/class pairs (in list context) or a reference to the hash of type/class mappings (in scalar context).

The default mapping of type names to class names is:

  scalar    => Rose::DB::Object::Metadata::Column::Scalar

  char      => Rose::DB::Object::Metadata::Column::Character
  character => Rose::DB::Object::Metadata::Column::Character
  varchar   => Rose::DB::Object::Metadata::Column::Varchar
  string    => Rose::DB::Object::Metadata::Column::Varchar

  text      => Rose::DB::Object::Metadata::Column::Text
  blob      => Rose::DB::Object::Metadata::Column::Blob

  bits      => Rose::DB::Object::Metadata::Column::Bitfield
  bitfield  => Rose::DB::Object::Metadata::Column::Bitfield

  bool      => Rose::DB::Object::Metadata::Column::Boolean
  boolean   => Rose::DB::Object::Metadata::Column::Boolean

  int       => Rose::DB::Object::Metadata::Column::Integer
  integer   => Rose::DB::Object::Metadata::Column::Integer

  serial    => Rose::DB::Object::Metadata::Column::Serial

  num       => Rose::DB::Object::Metadata::Column::Numeric
  numeric   => Rose::DB::Object::Metadata::Column::Numeric
  decimal   => Rose::DB::Object::Metadata::Column::Numeric
  float     => Rose::DB::Object::Metadata::Column::Float

  date      => Rose::DB::Object::Metadata::Column::Date
  datetime  => Rose::DB::Object::Metadata::Column::Datetime
  timestamp => Rose::DB::Object::Metadata::Column::Timestamp

  'datetime year to second' =>
    Rose::DB::Object::Metadata::Column::DatetimeYearToSecond

  'datetime year to minute' =>
    Rose::DB::Object::Metadata::Column::DatetimeYearToMinute

  array     => Rose::DB::Object::Metadata::Column::Array
  set       => Rose::DB::Object::Metadata::Column::Set

  chkpass   => Rose::DB::Object::Metadata::Column::Pg::Chkpass

delete_column_type_class TYPE

Delete the type/class mapping entry for the column type TYPE.

foreign_key NAME [, VALUE]

Get or set the foreign key named NAME. NAME should be the name of the thing being referenced by the foreign key, not the name of any of the columns that make up the foreign key. If called with just a NAME argument, the foreign key stored under that name is returned. Undef is returned if there is no such foreign key.

If passed a VALUE that is a reference to a hash, a new Rose::DB::Object::Metadata::ForeignKey object is constructed, with the name/value pairs in the hash passed to the constructor, along with the NAME as the value of the name parameter.

If VALUE is a Rose::DB::Object::Metadata::ForeignKey->derived object, it has its name set to NAME and then is stored under that name.

fq_table_sql

Returns the fully-qualified table name in a form suitable for use in an SQL statement.

generate_primary_key_values DB

Given the Rose::DB-derived object DB, generate new values for the primary key column(s) of the table described by this metadata object. If a primary_key_generator is defined, it will be called (passed this metadata object and the DB) and its value(s) returned. If not, a list of undef values is returned (one for each primary key column).

initialize [ARGS]

Initialize the Rose::DB::object-derived class associated with this metadata object by creating accessor methods for each column and foreign key. The table name and the primary_key must be defined or a fatal error will occur.

ARGS, if any, are passed to the call to make_methods() that actually creates the methods.

make_methods [ARGS]

Create accessor methods in class for each column and foreign key. ARGS are name/value pairs, and are all optional. Valid parameters are:

preserve_existing_methods

If set to a true value, a method will not be created if there is already an existing method with the same named.
override_existing_methods

If set to a true value, override any existing methods with the same name.

In the absence of one of these parameters, any method name that conflicts with an existing method name will cause a fatal error.

For each column, the corresponding accessor method name is determined by passing the column name to column_method(). If the method name is reserved (according to method_name_is_reserved(), a fatal error will occur. The accessor method is created by calling the column object's make_method() method.

For each foreign key, the corresponding accessor method name is determined by calling the method_name() method on the foreign key metadata object. If the method name is reserved (according to method_name_is_reserved()), a fatal error will occur. The accessor method is created by calling the foreign key metadata object's make_method() method.

method_column METHOD

Returns the name of the column manipulated by the get/set accessor method named METHOD. If the column is not aliased, then the accessor name is the same as the column name.

method_name_is_reserved NAME, CLASS

Given the method name NAME and the class name CLASS, returns true if the method name is reserved (i.e., is used by the CLASS API), false otherwise.

primary_key_columns [COLUMNS]

Get or set the list of of columns that make up the primary key. If COLUMNS are passed, the list is emptied and then COLUMNS are passed to the add_primary_key_columns() method. Returns a list of primary key column names (in list context) or a reference to the array of primary key column names (in scalar context).

primary_key_generator [CODE]

Get or set the subroutine used to generate new primary key values for the primary key columns of this table. The subroutine will be passed two arguments: the current metadata object and the Rose::DB-derived object that points to the current database.

The subroutine is expected to return a list of values, one for each primary key column. The values must be in the same order as the corresponding columns returned by primary_key_columns(). (i.e., the first value belongs to the first column returned by primary_key_columns(), the second value belongs to the second column, and so on.)

schema [SCHEMA]

Get or set the database schema name. This attribute is only applicable to PostgreSQL databases.

table [TABLE]

Get or set the database table name.

unique_keys

Returns the list (in list context) or reference to the array (in scalar context) of groups of column names for each unique key. Each group of column names is stored as a reference to an array of column names.

AUTHOR

John C. Siracusa (siracusa@mindspring.com)

COPYRIGHT

To install Rose::DB::Object, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Rose::DB::Object

CPAN shell

perl -MCPAN -e shell
install Rose::DB::Object

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)