Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
DBIx::Class::ResultSouUser3Contributed Perl DocumeDBIx::Class::ResultSource(3)

       DBIx::Class::ResultSource - Result source object

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

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

	 __PACKAGE__->add_columns(qw/ artistid name /);
	 __PACKAGE__->has_many(cds => 'MyApp::Schema::Result::CD');


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


	     "SELECT cdid, artist, title FROM cd WHERE year ='2000'"

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

       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::ResultSource::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:

       From a Result object:

       From a ResultSet	object:


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

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

       Arguments: @columns
       Return Value: $result_source

	 $source->add_columns(qw/col1 col2 col3/);

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

	   'col1' => { data_type => 'integer', is_nullable => 1, ... },
	   'col2' => { data_type => 'text',    is_auto_increment => 1, ... },

       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
       Result 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 => '_name' }

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

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

		  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 => '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 =>	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.

	      {	size =>	[ 9, 6 ] }

	   For decimal or float	values you can specify an ArrayRef in order to
	   control precision, assuming your database's
	   SQL::Translator::Producer supports it.

	      {	is_nullable => 1 }

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

	      {	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

	      {	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 => 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

	      {	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 => '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 => 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 =>	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.

	   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

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

       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.

       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.

       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

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

       Arguments: @colnames
       Return Value: not defined

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

       Arguments: $colname
       Return Value: not defined


       Remove a	single column by name from the result source, similar to

       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.

       Arguments: @cols
       Return Value: not defined

       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.

       Arguments: none
       Return Value: Ordered list of primary column names

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

       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

       Arguments: $sequence_name
       Return Value: not defined

       Arguments: $name?, \@colnames
       Return Value: not defined

       Declare a unique	constraint on this source. Call	once for each unique

	 # For UNIQUE (column1,	column2)
	   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.

       Arguments: @constraints
       Return Value: not defined

       Declare multiple	unique constraints on this source.

	   constraint_name1 => [ qw/column1 column2/ ],
	   constraint_name2 => [ qw/column2 column3/ ],

       Alternatively, you can specify only the columns:

	   [ 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

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

       See also	"add_unique_constraint".

       Arguments: \@colnames
       Return Value: Constraint	name

	 $source->name_unique_constraint(['col1', 'col2']);
	 # returns

       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

       This is used by "add_unique_constraint" if you do not specify the
       optional	constraint name.

       Arguments: none
       Return Value: Hash of unique constraint data


       Read-only accessor which	returns	a hash of unique constraints on	this

       The hash	is keyed by constraint name, and contains an arrayref of
       column names as values.

       Arguments: none
       Return Value: Unique constraint names


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

       Arguments: $constraintname
       Return Value: List of constraint	columns


       Returns the list	of columns that	make up	the specified unique

       Arguments: $callback_name | \&callback_code
       Return Value: $callback_name | \&callback_code



	 __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

       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

       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

       Arguments: $classname
       Return Value: $classname

	use My::Schema::ResultClass::Inflator;

	use My::Schema::Artist;

       Set the default result class for	this source. You can use this to
       create and use your own result inflator.	See "result_class" in
       DBIx::Class::ResultSet for more details.

       Please note that	setting	this to	something like
       DBIx::Class::ResultClass::HashRefInflator will make every result
       unblessed and make life more difficult.	Inflators like those are
       better suited to	temporary usage	via "result_class" in

       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.

       Arguments: $classname
       Return Value: $classname

	 package My::Schema::ResultSet::Artist;
	 use base 'DBIx::Class::ResultSet';

	 # In the result class

	 # Or in code

       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

       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.

       CAVEAT: "resultset_attributes" comes with its own set of	issues and
       bugs! While "resultset_attributes" isn't	deprecated per se, its usage
       is not recommended!

       Since relationships use attributes to link tables together, the
       "default" attributes you	set may	cause unpredictable and	undesired
       behavior.  Furthermore, the defaults cannot be turned off, so you are
       stuck with them.

       In most cases, what you should actually be using	are project-specific

	 package My::Schema::ResultSet::Artist;
	 use base 'DBIx::Class::ResultSet';

	 #__PACKAGE__->resultset_attributes({ prefetch => 'tracks' });

	 sub with_tracks { shift->search({}, { prefetch	=> 'tracks' }) }

	 # in your code

       This gives you the flexibility of not using it when you don't need it.

       For more	complex	situations, another solution would be to use a virtual
       view via	DBIx::Class::ResultSource::View.

       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.

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

	 # from	your schema...

       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.

       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:

	   "_tablespace" => 'fast_disk_array_3',
	   "_engine" =>	'InnoDB',

       Arguments: $schema?
       Return Value: $schema

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

       Sets and/or returns the DBIx::Class::Schema object to which this	result
       source instance has been	attached to.

       Arguments: none
       Return Value: $storage


       Returns the storage handle for the current schema.

       Arguments: $rel_name, $related_source_name, \%cond, \%attrs?
       Return Value: 1/true if it succeeded

	 $source->add_relationship('rel_name', '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' =>	'',

       The condition $cond needs to be an SQL::Abstract::Classic-style
       representation of the join between the tables. For example, if you're
       creating	a relation from	Author to Book,

	 { 'foreign.author_id' => '' }

       will result in the JOIN clause

	 author	me JOIN	book foreign ON	foreign.author_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.

       Arguments: none
       Return Value: @rel_names

	 my @rel_names = $source->relationships();

       Returns all relationship	names for this source.

       Arguments: $rel_name
       Return Value: \%rel_data

       Returns a hash of relationship information for the specified
       relationship name. The keys/values are as specified for
       "add_relationship" in DBIx::Class::Relationship::Base.

       Arguments: $rel_name
       Return Value: 1/0 (true/false)

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

       Arguments: $rel_name
       Return Value: \%rel_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

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

       Arguments: $rel_name
       Return Value: $source

       Returns the result source object	for the	given relationship.

       Arguments: $rel_name
       Return Value: $classname

       Returns the class name for objects in the given relationship.

       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.

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

       Arguments: 1/0 (default:	0)
       Return Value: 1/0


       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.

       Check the list of additional DBIC resources.

       This module is free software copyright by the DBIx::Class (DBIC)
       authors.	You can	redistribute it	and/or modify it under the same	terms
       as the DBIx::Class library.

perl v5.32.0			  2020-06-13	  DBIx::Class::ResultSource(3)


Want to link to this manual page? Use this URL:

home | help