| DBIx::Class::ResultSource - Result source object |
DBIx::Class::ResultSource - Result source object
A ResultSource is a component of a schema from which results can be directly retrieved, most usually a table (see the DBIx::Class::ResultSource::Table manpage)
Basic view support also exists, see the <DBIx::Class::ResultSource::View manpage.
$source->add_columns(qw/col1 col2 col3/);
$source->add_columns('col1' => \%col1_info, 'col2' => \%col2_info, ...);
Adds columns to the result source. If supplied key => hashref pairs, uses the hashref as the column_info for that column. Repeated calls of this method will add more columns, not replace them.
The column names given will be created as accessor methods on your the DBIx::Class::Row manpage objects. You can change the name of the accessor by supplying an accessor in the column_info hash.
The contents of the column_info are not set in stone. The following keys are currently recognised/used by DBIx::Class:
Use this to set the name of the accessor method for this column. If unset, the name of the column will be used.
This contains the column type. It is automatically filled by the the SQL::Translator::Producer::DBIx::Class::File manpage producer, and the the DBIx::Class::Schema::Loader manpage module. If you do not enter a data_type, DBIx::Class will attempt to retrieve it from the database for you, using DBI's column_info method. The values of this key are typically upper-cased.
Currently there is no standard set of values for the data_type. Use whatever your database supports.
The length of your column, if it is a column type that can have a size restriction. This is currently only used by deploy in the DBIx::Class::Schema manpage.
Set this to a true value for a columns that is allowed to contain NULL values. This is currently only used by deploy in the DBIx::Class::Schema manpage.
Set this to a true value for a column whose value is somehow automatically set. This is used to determine which columns to empty when cloning objects using copy in the DBIx::Class::Row manpage. It is also used by deploy in the DBIx::Class::Schema manpage.
Set this to a true or false value (not undef) to explicitly specify
if this column contains numeric data. This controls how set_column
decides whether to consider a column dirty after an update: if
is_numeric is true a numeric comparison != will take place
instead of the usual eq
If not specified the storage class will attempt to figure this out on
first access to the column, based on the column data_type. The
result will be cached in this attribute.
Set this to a true value for a column that contains a key from a foreign table. This is currently only used by deploy in the DBIx::Class::Schema manpage.
Set this to the default value which will be inserted into a column
by the database. Can contain either a value or a function (use a
reference to a scalar e.g. \'now()' if you want a function). This
is currently only used by deploy in the DBIx::Class::Schema manpage.
See the note on new in the DBIx::Class::Row manpage for more information about possible issues related to db-side default values.
Set this on a primary key column to the name of the sequence used to generate a new key value. If not specified, the DBIx::Class::PK::Auto manpage will attempt to retrieve the name of the sequence from the database automatically.
Set this to a true value for a column whose value is retrieved automatically from an oracle sequence. If you do not use an Oracle trigger to get the nextval, you have to set sequence as well.
This is used by deploy in the DBIx::Class::Schema manpage and the SQL::Translator manpage
to add extra non-generic data to the column. For example: extra
=> { unsigned => 1} is used by the MySQL producer to set an integer
column to unsigned. For more details, see
the SQL::Translator::Producer::MySQL manpage.
$source->add_column('col' => \%info?);
Add a single column and optional column info. Uses the same column info keys as add_columns.
if ($source->has_column($colname)) { ... }
Returns true if the source has a column of this name, false otherwise.
my $info = $source->column_info($col);
Returns the column metadata hashref for a column, as originally passed to add_columns. See the description of add_columns for information on the contents of the hashref.
my @column_names = $source->columns;
Returns all column names in the order they were declared to add_columns.
$source->remove_columns(qw/col1 col2 col3/);
Removes the given list of columns by name, from the result source.
Warning: Removing a column that is also used in the sources primary key, or in one of the sources unique constraints, will result in a broken result source.
$source->remove_column('col');
Remove a single column by name from the result source, similar to remove_columns.
Warning: Removing a column that is also used in the sources primary key, or in one of the sources unique constraints, will result in a broken result source.
Defines one or more columns as primary key for this source. Should be called after add_columns.
Additionally, defines a unique constraint
named primary.
The primary key columns are used by the DBIx::Class::PK::Auto manpage to retrieve automatically created values from the database.
Read-only accessor which returns the list of primary keys, supplied by set_primary_key.
Declare a unique constraint on this source. Call once for each unique constraint.
# For UNIQUE (column1, column2) __PACKAGE__->add_unique_constraint( constraint_name => [ qw/column1 column2/ ], );
Alternatively, you can specify only the columns:
__PACKAGE__->add_unique_constraint([ qw/column1 column2/ ]);
This will result in a unique constraint named table_column1_column2, where
table is replaced with the table name.
Unique constraints are used, for example, when you call find in the DBIx::Class::ResultSet manpage. Only columns in the constraint are searched.
Throws an error if any of the given column names do not yet exist on the result source.
$source->table('mytable'); $source->name_unique_constraint('col1', 'col2'); # returns 'mytable_col1_col2'
Return a name for a unique constraint containing the specified columns. The name is created by joining the table name and each column name, using an underscore character.
For example, a constraint on a table named cd containing the columns
artist and title would result in a constraint name of cd_artist_title.
This is used by add_unique_constraint if you do not specify the optional constraint name.
$source->unique_constraints();
Read-only accessor which returns a hash of unique constraints on this source.
The hash is keyed by constraint name, and contains an arrayref of column names as values.
$source->unique_constraint_names();
Returns the list of unique constraint names defined on this source.
$source->unique_constraint_columns('myconstraint');
Returns the list of columns that make up the specified unique constraint.
__PACKAGE__->sqlt_deploy_callback('mycallbackmethod');
An accessor to set a callback to be called during deployment of the schema via create_ddl_dir in the DBIx::Class::Schema manpage or deploy in the DBIx::Class::Schema manpage.
The callback can be set as either a code reference or the name of a method in the current result class.
If not set, the default_sqlt_deploy_hook is called.
Your callback will be passed the $source object representing the ResultSource instance being deployed, and the the SQL::Translator::Schema::Table manpage object being created from it. The callback can be used to manipulate the table object or add your own customised indexes. If you need to manipulate a non-table object, use the sqlt_deploy_hook in the DBIx::Class::Schema manpage.
See Adding Indexes And Functions To Your SQL in the DBIx::Class::Manual::Cookbook manpage for examples.
This sqlt deployment callback can only be used to manipulate SQL::Translator objects as they get turned into SQL. To execute post-deploy statements which SQL::Translator does not currently handle, override deploy in the DBIx::Class::Schema manpage in your Schema class and call dbh_do.
This is the sensible default for sqlt_deploy_callback.
If a method named sqlt_deploy_hook exists in your Result class, it
will be called and passed the current $source and the
$sqlt_table being deployed.
Returns a resultset for the given source. This will initially be created on demand by calling
$self->resultset_class->new($self, $self->resultset_attributes)
but is cached from then on unless resultset_class changes.
package My::ResultSetClass; use base 'DBIx::Class::ResultSet'; ...
$source->resultset_class('My::ResultSet::Class');
Set the class of the resultset. This is useful if you want to create your own resultset methods. Create your own class derived from the DBIx::Class::ResultSet manpage, and set it here. If called with no arguments, this method returns the name of the existing resultset class, if one exists.
$source->resultset_attributes({ order_by => [ 'id' ] });
Store a collection of resultset attributes, that will be set on every the DBIx::Class::ResultSet manpage produced from this result source. For a full list see ATTRIBUTES in the DBIx::Class::ResultSet manpage.
Set an alternate name for the result source when it is loaded into a schema. This is useful if you want to refer to a result source by a name other than its class name.
package ArchivedBooks; use base qw/DBIx::Class/; __PACKAGE__->table('books_archive'); __PACKAGE__->source_name('Books');
# from your schema... $schema->resultset('Books')->find(1);
my $from_clause = $source->from();
Returns an expression of the source to be supplied to storage to specify retrieval from this source. In the case of a database, the required FROM clause contents.
my $schema = $source->schema();
Returns the the DBIx::Class::Schema manpage object that this result source belongs to.
$source->storage->debug(1);
Returns the storage handle for the current schema.
See also: the DBIx::Class::Storage manpage
$source->add_relationship('relname', 'related_source', $cond, $attrs);
the DBIx::Class::Relationship manpage describes a series of methods which create pre-defined useful types of relationships. Look there first before using this method directly.
The relationship name can be arbitrary, but must be unique for each relationship attached to this result source. 'related_source' should be the name with which the related result source was registered with the current schema. For example:
$schema->source('Book')->add_relationship('reviews', 'Review', { 'foreign.book_id' => 'self.id', });
The condition $cond needs to be an the SQL::Abstract manpage-style
representation of the join between the tables. For example, if you're
creating a relation from Author to Book,
{ 'foreign.author_id' => 'self.id' }
will result in the JOIN clause
author me JOIN book foreign ON foreign.author_id = me.id
You can specify as many foreign => self mappings as necessary.
Valid attributes are as follows:
Explicitly specifies the type of join to use in the relationship. Any
SQL join type is valid, e.g. LEFT or RIGHT. It will be placed in
the SQL command immediately before JOIN.
An arrayref containing a list of accessors in the foreign class to proxy in the main class. If, for example, you do the following:
CD->might_have(liner_notes => 'LinerNotes', undef, { proxy => [ qw/notes/ ], });
Then, assuming LinerNotes has an accessor named notes, you can do:
my $cd = CD->find(1); # set notes -- LinerNotes object is created if it doesn't exist $cd->notes('Notes go here');
Specifies the type of accessor that should be created for the
relationship. Valid values are single (for when there is only a single
related object), multi (when there can be many), and filter (for
when there is a single related object, but you also want the relationship
accessor to double as a column accessor). For multi accessors, an
add_to_* method is also created, which calls create_related for the
relationship.
Throws an exception if the condition is improperly supplied, or cannot be resolved.
my @relnames = $source->relationships();
Returns all relationship names for this source.
Returns a hash of relationship information for the specified relationship name. The keys/values are as specified for add_relationship.
Returns true if the source has a relationship of this name, false otherwise.
Looks through all the relationships on the source this relationship points to, looking for one whose condition is the reverse of the condition on this relationship.
A common use of this is to find the name of the belongs_to relation
opposing a has_many relation. For definition of these look in
the DBIx::Class::Relationship manpage.
The returned hashref is keyed by the name of the opposing relationship, and contains it's data in the same manner as relationship_info.
Returns the result source object for the given relationship.
Returns the class name for objects in the given relationship.
Obtain a new handle to this source. Returns an instance of a the DBIx::Class::ResultSourceHandle manpage.
See throw_exception in the DBIx::Class::Schema manpage.
Stores a hashref of per-source metadata. No specific key names have yet been standardized, the examples below are purely hypothetical and don't actually accomplish anything on their own:
__PACKAGE__->source_info({ "_tablespace" => 'fast_disk_array_3', "_engine" => 'InnoDB', });
$class->new();
$class->new({attribute_name => value});
Creates a new ResultSource object. Not normally called directly by end users.
__PACKAGE__->column_info_from_storage(1);
Enables the on-demand automatic loading of the above column metadata from storage as neccesary. This is *deprecated*, and should not be used. It will be removed before 1.0.
Matt S. Trout <mst@shadowcatsystems.co.uk>
You may distribute this code under the same terms as Perl itself.
| DBIx::Class::ResultSource - Result source object |