DBIx::Class::ResultSource5.16 man page on Darwin

Man page or keyword search:  
man Server   23457 pages
apropos Keyword Search (all sections)
Output format
Darwin logo
[printable version]

DBIx::Class::ResultSouUser3Contributed Perl DocumeDBIx::Class::ResultSource(3)

NAME
       DBIx::Class::ResultSource - Result source object

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

	 package MyApp::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 => 'MyApp::Schema::Result::CD');

	 1;

	 # Create a query (view) based result source, in a result class
	 package MyApp::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.

       If a column name beginning with a plus sign ('+col1') is provided, the
       attributes provided will be merged with any existing attributes for the
       column, with the new attributes taking precedence in the case that an
       attribute already exists. Using this without a hashref
       ("$source->add_columns(qw/+col1 +col2/)") is legal, but useless -- it
       does the same thing it would do without the plus.

       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.

       retrieve_on_insert
	     { retrieve_on_insert => 1 }

	   For every column where this is set to true, DBIC will retrieve the
	   RDBMS-side value upon a new row insertion (normally only the
	   autoincrement PK is retrieved on insert). "INSERT ... RETURNING" is
	   used automatically if supported by the underlying storage,
	   otherwise an extra SELECT statement is executed to retrieve the
	   missing data.

       auto_nextval
	      { auto_nextval => 1 }

	   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 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".

   columns_info
       Arguments: \@colnames ?
       Return value: Hashref of column name/info pairs

	 my $columns_info = $source->columns_info;

       Like "column_info" but returns information for the requested columns.
       If the optional column-list arrayref is omitted it returns info on all
       columns currently defined on the ResultSource via "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".

       Note: you normally do want to define a primary key on your sources even
       if the underlying database table does not have a primary key.  See "The
       Significance and Importance of Primary Keys" in
       DBIx::Class::Manual::Intro for more info.

   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".

   sequence
       Manually define the correct sequence for your table, to avoid the
       overhead associated with looking up the sequence automatically. The
       supplied sequence will be applied to the "column_info" of each
       primary_key

       Arguments: $sequence_name
       Return value: undefined

   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.

   add_unique_constraints
       Arguments: @constraints
       Return value: undefined

       Declare multiple unique constraints on this source.

	 __PACKAGE__->add_unique_constraints(
	   constraint_name1 => [ qw/column1 column2/ ],
	   constraint_name2 => [ qw/column2 column3/ ],
	 );

       Alternatively, you can specify only the columns:

	 __PACKAGE__->add_unique_constraints(
	   [ qw/column1 column2/ ],
	   [ qw/column3 column4/ ]
	 );

       This will result in unique constraints named "table_column1_column2"
       and "table_column3_column4", where "table" is replaced with the table
       name.

       Throws an error if any of the given column names do not yet exist on
       the result source.

       See also "add_unique_constraint".

   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_name | \&callback_code
       Return value: $callback_name | \&callback_code

	 __PACKAGE__->sqlt_deploy_callback('mycallbackmethod');

	  or

	 __PACKAGE__->sqlt_deploy_callback(sub {
	   my ($source_instance, $sqlt_table) = @_;
	   ...
	 } );

       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.

       Defaults to "default_sqlt_deploy_hook".

       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
       This is the default deploy hook implementation which checks if your
       current Result class has a "sqlt_deploy_hook" method, and if present
       invokes it on the Result class directly. This is to preserve the
       semantics of "sqlt_deploy_hook" which was originally designed to expect
       the Result class name and the $sqlt_table instance of the 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.

   name
       Arguments: None
       Result value: $name

       Returns the name of the result source, which will typically be the
       table name. This may be a scalar reference if the result source has a
       non-standard name.

   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: $schema
       Return value: A schema object

	 my $schema = $source->schema();

       Sets and/or returns the DBIx::Class::Schema object to which this result
       source instance has been attached 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".

   related_source
       Arguments: $relname
       Return value: $source

       Returns the result source object for the given relationship.

   related_class
       Arguments: $relname
       Return value: $classname

       Returns the class name for objects in the given relationship.

   handle
       Arguments: None
       Return value: $source_handle

       Obtain a new result source handle instance for this source. Used as a
       serializable pointer to this resultsource, as it is not easy (nor
       advisable) to serialize CODErefs which may very well be present in e.g.
       relationship definitions.

   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 necessary.  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.

perl v5.16.2			  2012-10-18	  DBIx::Class::ResultSource(3)
[top]

List of man pages available for Darwin

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net