/ 
DBIx-Class-0.08118
River stage three • 349 direct dependents • 459 total dependents
/ DBIx::Class::ResultSource

NAME

DBIx::Class::ResultSource - Result source object

SYNOPSIS

# Create a table based result source, in a result class.

package MyDB::Schema::Result::Artist;
use base qw/DBIx::Class::Core/;

__PACKAGE__->table('artist');
__PACKAGE__->add_columns(qw/ artistid name /);
__PACKAGE__->set_primary_key('artistid');
__PACKAGE__->has_many(cds => 'MyDB::Schema::Result::CD');

1;

# Create a query (view) based result source, in a result class
package MyDB::Schema::Result::Year2000CDs;
use base qw/DBIx::Class::Core/;

__PACKAGE__->load_components('InflateColumn::DateTime');
__PACKAGE__->table_class('DBIx::Class::ResultSource::View');

__PACKAGE__->table('year2000cds');
__PACKAGE__->result_source_instance->is_virtual(1);
__PACKAGE__->result_source_instance->view_definition(
    "SELECT cdid, artist, title FROM cd WHERE year ='2000'"
    );

DESCRIPTION

A ResultSource is an object that represents a source of data for querying.

This class is a base class for various specialised types of result sources, for example DBIx::Class::ResultSource::Table. Table is the default result source type, so one is created for you when defining a result class as described in the synopsis above.

More specifically, the DBIx::Class::Core base class pulls in the DBIx::Class::ResultSourceProxy::Table component, which defines the table method. When called, table creates and stores an instance of DBIx::Class::ResultSoure::Table. Luckily, to use tables as result sources, you don't need to remember any of this.

Result sources representing select queries, or views, can also be created, see DBIx::Class::ResultSource::View for full details.

Finding result source objects

As mentioned above, a result source instance is created and stored for you when you define a Result Class.

You can retrieve the result source at runtime in the following ways:

From a Schema object:
$schema->source($source_name);
From a Row object:
$row->result_source;
From a ResultSet object:
$rs->result_source;

METHODS

add_columns

Arguments: @columns
Return value: The ResultSource object
$source->add_columns(qw/col1 col2 col3/);

$source->add_columns('col1' => \%col1_info, 'col2' => \%col2_info, ...);

Adds columns to the result source. If supplied colname => 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 DBIx::Class::Row 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:

accessor
{ accessor => '_name' }

# example use, replace standard accessor with one of your own:
sub name {
    my ($self, $value) = @_;

    die "Name cannot contain digits!" if($value =~ /\d/);
    $self->_name($value);

    return $self->_name();
}

Use this to set the name of the accessor method for this column. If unset, the name of the column will be used.

data_type
{ data_type => 'integer' }

This contains the column type. It is automatically filled if you use the SQL::Translator::Producer::DBIx::Class::File producer, or the DBIx::Class::Schema::Loader module.

Currently there is no standard set of values for the data_type. Use whatever your database supports.

size
{ size => 20 }

The length of your column, if it is a column type that can have a size restriction. This is currently only used to create tables from your schema, see "deploy" in DBIx::Class::Schema.

is_nullable
{ is_nullable => 1 }

Set this to a true value for a columns that is allowed to contain NULL values, default is false. This is currently only used to create tables from your schema, see "deploy" in DBIx::Class::Schema.

is_auto_increment
{ is_auto_increment => 1 }

Set this to a true value for a column whose value is somehow automatically set, defaults to false. This is used to determine which columns to empty when cloning objects using "copy" in DBIx::Class::Row. It is also used by "deploy" in DBIx::Class::Schema.

is_numeric
{ is_numeric => 1 }

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.

is_foreign_key
{ is_foreign_key => 1 }

Set this to a true value for a column that contains a key from a foreign table, defaults to false. This is currently only used to create tables from your schema, see "deploy" in DBIx::Class::Schema.

default_value
{ default_value => \'now()' }

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 to create tables from your schema, see "deploy" in DBIx::Class::Schema.

See the note on "new" in DBIx::Class::Row for more information about possible issues related to db-side default values.

sequence
{ sequence => 'my_table_seq' }

Set this on a primary key column to the name of the sequence used to generate a new key value. If not specified, DBIx::Class::PK::Auto will attempt to retrieve the name of the sequence from the database automatically.

auto_nextval

Set this to a true value for a column whose value is retrieved automatically from a sequence or function (if supported by your Storage driver.) For a sequence, if you do not use a trigger to get the nextval, you have to set the "sequence" value as well.

Also set this for MSSQL columns with the 'uniqueidentifier' "data_type" in DBIx::Class::ResultSource whose values you want to automatically generate using NEWID(), unless they are a primary key in which case this will be done anyway.

extra

This is used by "deploy" in DBIx::Class::Schema and SQL::Translator 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 SQL::Translator::Producer::MySQL.

add_column

Arguments: $colname, \%columninfo?
Return value: 1/0 (true/false)
$source->add_column('col' => \%info);

Add a single column and optional column info. Uses the same column info keys as "add_columns".

has_column

Arguments: $colname
Return value: 1/0 (true/false)
if ($source->has_column($colname)) { ... }

Returns true if the source has a column of this name, false otherwise.

column_info

Arguments: $colname
Return value: Hashref of info
my $info = $source->column_info($col);

Returns the column metadata hashref for a column, as originally passed to "add_columns". See "add_columns" above for information on the contents of the hashref.

columns

Arguments: None
Return value: Ordered list of column names
my @column_names = $source->columns;

Returns all column names in the order they were declared to "add_columns".

remove_columns

Arguments: @colnames
Return value: undefined
$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.

remove_column

Arguments: $colname
Return value: undefined
$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.

set_primary_key

Arguments: @cols
Return value: undefined

Defines one or more columns as primary key for this source. Must be called after "add_columns".

Additionally, defines a unique constraint named primary.

The primary key columns are used by DBIx::Class::PK::Auto to retrieve automatically created values from the database. They are also used as default joining columns when specifying relationships, see DBIx::Class::Relationship.

primary_columns

Arguments: None
Return value: Ordered list of primary column names

Read-only accessor which returns the list of primary keys, supplied by "set_primary_key".

add_unique_constraint

Arguments: $name?, \@colnames
Return value: undefined

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 pass the constraint name as the key attribute to "find" in DBIx::Class::ResultSet. Then 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.

name_unique_constraint

Arguments: @colnames
Return value: Constraint name
$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.

unique_constraints

Arguments: None
Return value: Hash of unique constraint data
$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.

unique_constraint_names

Arguments: None
Return value: Unique constraint names
$source->unique_constraint_names();

Returns the list of unique constraint names defined on this source.

unique_constraint_columns

Arguments: $constraintname
Return value: List of constraint columns
$source->unique_constraint_columns('myconstraint');

Returns the list of columns that make up the specified unique constraint.

sqlt_deploy_callback

Arguments: $callback
__PACKAGE__->sqlt_deploy_callback('mycallbackmethod');

An accessor to set a callback to be called during deployment of the schema via "create_ddl_dir" in DBIx::Class::Schema or "deploy" in DBIx::Class::Schema.

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 SQL::Translator::Schema::Table 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 DBIx::Class::Schema.

See "Adding Indexes And Functions To Your SQL" in DBIx::Class::Manual::Cookbook 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 DBIx::Class::Schema in your Schema class and call dbh_do.

default_sqlt_deploy_hook

Arguments: $source, $sqlt_table
Return value: undefined

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.

resultset

Arguments: None
Return value: $resultset

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.

resultset_class

Arguments: $classname
Return value: $classname
package My::Schema::ResultSet::Artist;
use base 'DBIx::Class::ResultSet';
...

# In the result class
__PACKAGE__->resultset_class('My::Schema::ResultSet::Artist');

# Or in code
$source->resultset_class('My::Schema::ResultSet::Artist');

Set the class of the resultset. This is useful if you want to create your own resultset methods. Create your own class derived from DBIx::Class::ResultSet, and set it here. If called with no arguments, this method returns the name of the existing resultset class, if one exists.

resultset_attributes

Arguments: \%attrs
Return value: \%attrs
# In the result class
__PACKAGE__->resultset_attributes({ order_by => [ 'id' ] });

# Or in code
$source->resultset_attributes({ order_by => [ 'id' ] });

Store a collection of resultset attributes, that will be set on every DBIx::Class::ResultSet produced from this result source. For a full list see "ATTRIBUTES" in DBIx::Class::ResultSet.

source_name

Arguments: $source_name
Result value: $source_name

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);

from

Arguments: None
Return value: FROM clause
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.

schema

Arguments: None
Return value: A schema object
my $schema = $source->schema();

Returns the DBIx::Class::Schema object that this result source belongs to.

storage

Arguments: None
Return value: A Storage object
$source->storage->debug(1);

Returns the storage handle for the current schema.

See also: DBIx::Class::Storage

add_relationship

Arguments: $relname, $related_source_name, \%cond, [ \%attrs ]
Return value: 1/true if it succeeded
$source->add_relationship('relname', 'related_source', $cond, $attrs);

DBIx::Class::Relationship 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 SQL::Abstract-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:

join_type

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.

proxy

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');
accessor

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.

relationships

Arguments: None
Return value: List of relationship names
my @relnames = $source->relationships();

Returns all relationship names for this source.

relationship_info

Arguments: $relname
Return value: Hashref of relation data,

Returns a hash of relationship information for the specified relationship name. The keys/values are as specified for "add_relationship".

has_relationship

Arguments: $rel
Return value: 1/0 (true/false)

Returns true if the source has a relationship of this name, false otherwise.

reverse_relationship_info

Arguments: $relname
Return value: Hashref of relationship data

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 DBIx::Class::Relationship.

The returned hashref is keyed by the name of the opposing relationship, and contains its data in the same manner as "relationship_info".

Arguments: $relname
Return value: $source

Returns the result source object for the given relationship.

Arguments: $relname
Return value: $classname

Returns the class name for objects in the given relationship.

handle

Obtain a new handle to this source. Returns an instance of a DBIx::Class::ResultSourceHandle.

throw_exception

See "throw_exception" in DBIx::Class::Schema.

source_info

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

new

$class->new();

$class->new({attribute_name => value});

Creates a new ResultSource object. Not normally called directly by end users.

column_info_from_storage

Arguments: 1/0 (default: 0)
Return value: 1/0
__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.

AUTHORS

Matt S. Trout <mst@shadowcatsystems.co.uk>

LICENSE

You may distribute this code under the same terms as Perl itself.