Rose::DB::Object::Metadata - Database object metadata.
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', } }, ); ...
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
Rose::DB::Object
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.
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.
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.
class
This is an alias for the add_columns() method.
add_columns()
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.
Rose::DB::Object::Metadata::Column
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.
column_type_class('scalar')
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.
add_primary_key_column()
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.
column_type_class()
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 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.
Rose::DB::Object::Metadata::ForeignKey
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.
$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(...), );
This method is an alias for add_primary_key_columns().
add_primary_key_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 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.
Use ALIAS instead of NAME as the accessor method name for column named NAME. It is sometimes necessary to use an alias for a column because the column name may conflict 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:
save()
$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.
method_name_is_reserved()
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.
DBI
bind_columns()
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:
update()
insert()
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.
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()).
Rose::DB::object
make_methods()
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.
name()
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.
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_method()
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.
initialize()
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.
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.
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_names()
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.
Returns a list (in list context) or a reference to an array (in scalar context) of column names.
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.
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 the type/class mapping entry for the column type TYPE.
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.
name
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.
Returns the fully-qualified table name in a form suitable for use in an SQL statement.
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).
Rose::DB
primary_key_generator
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.
table
primary_key
ARGS, if any, are passed to the call to make_methods() that actually creates the methods.
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.
make_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_name()
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.
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.
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).
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.)
primary_key_columns()
Get or set the database schema name. This attribute is only applicable to PostgreSQL databases.
Get or set the database table name.
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.
John C. Siracusa (siracusa@mindspring.com)
Copyright (c) 2005 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.
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.