1DBIx::Class::ResultSourUcsee(r3)Contributed Perl DocumenDtBaItxi:o:nClass::ResultSource(3)
2
6 DBIx::Class::ResultSource - Result source object
7
9 # Create a table based result source, in a result class.
10 package MyApp::Schema::Result::Artist;
12 use base qw/DBIx::Class::Core/;
13 __PACKAGE__->table('artist');
15 __PACKAGE__->add_columns(qw/ artistid name /);
16 __PACKAGE__->set_primary_key('artistid');
17 __PACKAGE__->has_many(cds => 'MyApp::Schema::Result::CD');
18 1;
20 # Create a query (view) based result source, in a result class
22 package MyApp::Schema::Result::Year2000CDs;
23 use base qw/DBIx::Class::Core/;
24 __PACKAGE__->load_components('InflateColumn::DateTime');
26 __PACKAGE__->table_class('DBIx::Class::ResultSource::View');
27 __PACKAGE__->table('year2000cds');
29 __PACKAGE__->result_source_instance->is_virtual(1);
30 __PACKAGE__->result_source_instance->view_definition(
31 "SELECT cdid, artist, title FROM cd WHERE year ='2000'"
32 );
33
35 A ResultSource is an object that represents a source of data for
36 querying.
37 This class is a base class for various specialised types of result
39 sources, for example DBIx::Class::ResultSource::Table. Table is the
40 default result source type, so one is created for you when defining a
41 result class as described in the synopsis above.
42 More specifically, the DBIx::Class::Core base class pulls in the
44 DBIx::Class::ResultSourceProxy::Table component, which defines the
45 table method. When called, "table" creates and stores an instance of
46 DBIx::Class::ResultSource::Table. Luckily, to use tables as result
47 sources, you don't need to remember any of this.
48 Result sources representing select queries, or views, can also be
50 created, see DBIx::Class::ResultSource::View for full details.
51 Finding result source objects
53 As mentioned above, a result source instance is created and stored for
54 you when you define a Result Class.
55 You can retrieve the result source at runtime in the following ways:
57 From a Schema object:
59 $schema->source($source_name);
60 From a Result object:
62 $result->result_source;
63 From a ResultSet object:
65 $rs->result_source;
66
68 new
69 $class->new();
70 $class->new({attribute_name => value});
72 Creates a new ResultSource object. Not normally called directly by end
74 users.
75 add_columns
77 Arguments: @columns
78 Return Value: $result_source
79 $source->add_columns(qw/col1 col2 col3/);
81 $source->add_columns('col1' => \%col1_info, 'col2' => \%col2_info, ...);
83 $source->add_columns(
85 'col1' => { data_type => 'integer', is_nullable => 1, ... },
86 'col2' => { data_type => 'text', is_auto_increment => 1, ... },
87 );
88 Adds columns to the result source. If supplied colname => hashref
90 pairs, uses the hashref as the "column_info" for that column. Repeated
91 calls of this method will add more columns, not replace them.
92 The column names given will be created as accessor methods on your
94 Result objects. You can change the name of the accessor by supplying an
95 "accessor" in the column_info hash.
96 If a column name beginning with a plus sign ('+col1') is provided, the
98 attributes provided will be merged with any existing attributes for the
99 column, with the new attributes taking precedence in the case that an
100 attribute already exists. Using this without a hashref
101 ("$source->add_columns(qw/+col1 +col2/)") is legal, but useless -- it
102 does the same thing it would do without the plus.
103 The contents of the column_info are not set in stone. The following
105 keys are currently recognised/used by DBIx::Class:
106 accessor
108 { accessor => '_name' }
109 # example use, replace standard accessor with one of your own:
111 sub name {
112 my ($self, $value) = @_;
113 die "Name cannot contain digits!" if($value =~ /\d/);
115 $self->_name($value);
116 return $self->_name();
118 }
119 Use this to set the name of the accessor method for this column. If
121 unset, the name of the column will be used.
122 data_type
124 { data_type => 'integer' }
125 This contains the column type. It is automatically filled if you
127 use the SQL::Translator::Producer::DBIx::Class::File producer, or
128 the DBIx::Class::Schema::Loader module.
129 Currently there is no standard set of values for the data_type. Use
131 whatever your database supports.
132 size
134 { size => 20 }
135 The length of your column, if it is a column type that can have a
137 size restriction. This is currently only used to create tables from
138 your schema, see "deploy" in DBIx::Class::Schema.
139 { size => [ 9, 6 ] }
141 For decimal or float values you can specify an ArrayRef in order to
143 control precision, assuming your database's
144 SQL::Translator::Producer supports it.
145 is_nullable
147 { is_nullable => 1 }
148 Set this to a true value for a column that is allowed to contain
150 NULL values, default is false. This is currently only used to
151 create tables from your schema, see "deploy" in
152 DBIx::Class::Schema.
153 is_auto_increment
155 { is_auto_increment => 1 }
156 Set this to a true value for a column whose value is somehow
158 automatically set, defaults to false. This is used to determine
159 which columns to empty when cloning objects using "copy" in
160 DBIx::Class::Row. It is also used by "deploy" in
161 DBIx::Class::Schema.
162 is_numeric
164 { is_numeric => 1 }
165 Set this to a true or false value (not "undef") to explicitly
167 specify if this column contains numeric data. This controls how
168 set_column decides whether to consider a column dirty after an
169 update: if "is_numeric" is true a numeric comparison "!=" will take
170 place instead of the usual "eq"
171 If not specified the storage class will attempt to figure this out
173 on first access to the column, based on the column "data_type". The
174 result will be cached in this attribute.
175 is_foreign_key
177 { is_foreign_key => 1 }
178 Set this to a true value for a column that contains a key from a
180 foreign table, defaults to false. This is currently only used to
181 create tables from your schema, see "deploy" in
182 DBIx::Class::Schema.
183 default_value
185 { default_value => \'now()' }
186 Set this to the default value which will be inserted into a column
188 by the database. Can contain either a value or a function (use a
189 reference to a scalar e.g. "\'now()'" if you want a function). This
190 is currently only used to create tables from your schema, see
191 "deploy" in DBIx::Class::Schema.
192 See the note on "new" in DBIx::Class::Row for more information
194 about possible issues related to db-side default values.
195 sequence
197 { sequence => 'my_table_seq' }
198 Set this on a primary key column to the name of the sequence used
200 to generate a new key value. If not specified,
201 DBIx::Class::PK::Auto will attempt to retrieve the name of the
202 sequence from the database automatically.
203 retrieve_on_insert
205 { retrieve_on_insert => 1 }
206 For every column where this is set to true, DBIC will retrieve the
208 RDBMS-side value upon a new row insertion (normally only the
209 autoincrement PK is retrieved on insert). "INSERT ... RETURNING" is
210 used automatically if supported by the underlying storage,
211 otherwise an extra SELECT statement is executed to retrieve the
212 missing data.
213 auto_nextval
215 { auto_nextval => 1 }
216 Set this to a true value for a column whose value is retrieved
218 automatically from a sequence or function (if supported by your
219 Storage driver.) For a sequence, if you do not use a trigger to get
220 the nextval, you have to set the "sequence" value as well.
221 Also set this for MSSQL columns with the 'uniqueidentifier'
223 data_type whose values you want to automatically generate using
224 "NEWID()", unless they are a primary key in which case this will be
225 done anyway.
226 extra
228 This is used by "deploy" in DBIx::Class::Schema and SQL::Translator
229 to add extra non-generic data to the column. For example: "extra =>
230 { unsigned => 1}" is used by the MySQL producer to set an integer
231 column to unsigned. For more details, see
232 SQL::Translator::Producer::MySQL.
233 add_column
235 Arguments: $colname, \%columninfo?
236 Return Value: 1/0 (true/false)
237 $source->add_column('col' => \%info);
239 Add a single column and optional column info. Uses the same column info
241 keys as "add_columns".
242 has_column
244 Arguments: $colname
245 Return Value: 1/0 (true/false)
246 if ($source->has_column($colname)) { ... }
248 Returns true if the source has a column of this name, false otherwise.
250 column_info
252 Arguments: $colname
253 Return Value: Hashref of info
254 my $info = $source->column_info($col);
256 Returns the column metadata hashref for a column, as originally passed
258 to "add_columns". See "add_columns" above for information on the
259 contents of the hashref.
260 columns
262 Arguments: none
263 Return Value: Ordered list of column names
264 my @column_names = $source->columns;
266 Returns all column names in the order they were declared to
268 "add_columns".
269 columns_info
271 Arguments: \@colnames ?
272 Return Value: Hashref of column name/info pairs
273 my $columns_info = $source->columns_info;
275 Like "column_info" but returns information for the requested columns.
277 If the optional column-list arrayref is omitted it returns info on all
278 columns currently defined on the ResultSource via "add_columns".
279 remove_columns
281 Arguments: @colnames
282 Return Value: not defined
283 $source->remove_columns(qw/col1 col2 col3/);
285 Removes the given list of columns by name, from the result source.
287 Warning: Removing a column that is also used in the sources primary
289 key, or in one of the sources unique constraints, will result in a
290 broken result source.
291 remove_column
293 Arguments: $colname
294 Return Value: not defined
295 $source->remove_column('col');
297 Remove a single column by name from the result source, similar to
299 "remove_columns".
300 Warning: Removing a column that is also used in the sources primary
302 key, or in one of the sources unique constraints, will result in a
303 broken result source.
304 set_primary_key
306 Arguments: @cols
307 Return Value: not defined
308 Defines one or more columns as primary key for this source. Must be
310 called after "add_columns".
311 Additionally, defines a unique constraint named "primary".
313 Note: you normally do want to define a primary key on your sources even
315 if the underlying database table does not have a primary key. See "The
316 Significance and Importance of Primary Keys" in
317 DBIx::Class::Manual::Intro for more info.
318 primary_columns
320 Arguments: none
321 Return Value: Ordered list of primary column names
322 Read-only accessor which returns the list of primary keys, supplied by
324 "set_primary_key".
325 sequence
327 Manually define the correct sequence for your table, to avoid the
328 overhead associated with looking up the sequence automatically. The
329 supplied sequence will be applied to the "column_info" of each
330 primary_key
331 Arguments: $sequence_name
333 Return Value: not defined
334 add_unique_constraint
336 Arguments: $name?, \@colnames
337 Return Value: not defined
338 Declare a unique constraint on this source. Call once for each unique
340 constraint.
341 # For UNIQUE (column1, column2)
343 __PACKAGE__->add_unique_constraint(
344 constraint_name => [ qw/column1 column2/ ],
345 );
346 Alternatively, you can specify only the columns:
348 __PACKAGE__->add_unique_constraint([ qw/column1 column2/ ]);
350 This will result in a unique constraint named "table_column1_column2",
352 where "table" is replaced with the table name.
353 Unique constraints are used, for example, when you pass the constraint
355 name as the "key" attribute to "find" in DBIx::Class::ResultSet. Then
356 only columns in the constraint are searched.
357 Throws an error if any of the given column names do not yet exist on
359 the result source.
360 add_unique_constraints
362 Arguments: @constraints
363 Return Value: not defined
364 Declare multiple unique constraints on this source.
366 __PACKAGE__->add_unique_constraints(
368 constraint_name1 => [ qw/column1 column2/ ],
369 constraint_name2 => [ qw/column2 column3/ ],
370 );
371 Alternatively, you can specify only the columns:
373 __PACKAGE__->add_unique_constraints(
375 [ qw/column1 column2/ ],
376 [ qw/column3 column4/ ]
377 );
378 This will result in unique constraints named "table_column1_column2"
380 and "table_column3_column4", where "table" is replaced with the table
381 name.
382 Throws an error if any of the given column names do not yet exist on
384 the result source.
385 See also "add_unique_constraint".
387 name_unique_constraint
389 Arguments: \@colnames
390 Return Value: Constraint name
391 $source->table('mytable');
393 $source->name_unique_constraint(['col1', 'col2']);
394 # returns
395 'mytable_col1_col2'
396 Return a name for a unique constraint containing the specified columns.
398 The name is created by joining the table name and each column name,
399 using an underscore character.
400 For example, a constraint on a table named "cd" containing the columns
402 "artist" and "title" would result in a constraint name of
403 "cd_artist_title".
404 This is used by "add_unique_constraint" if you do not specify the
406 optional constraint name.
407 unique_constraints
409 Arguments: none
410 Return Value: Hash of unique constraint data
411 $source->unique_constraints();
413 Read-only accessor which returns a hash of unique constraints on this
415 source.
416 The hash is keyed by constraint name, and contains an arrayref of
418 column names as values.
419 unique_constraint_names
421 Arguments: none
422 Return Value: Unique constraint names
423 $source->unique_constraint_names();
425 Returns the list of unique constraint names defined on this source.
427 unique_constraint_columns
429 Arguments: $constraintname
430 Return Value: List of constraint columns
431 $source->unique_constraint_columns('myconstraint');
433 Returns the list of columns that make up the specified unique
435 constraint.
436 sqlt_deploy_callback
438 Arguments: $callback_name | \&callback_code
439 Return Value: $callback_name | \&callback_code
440 __PACKAGE__->sqlt_deploy_callback('mycallbackmethod');
442 or
444 __PACKAGE__->sqlt_deploy_callback(sub {
446 my ($source_instance, $sqlt_table) = @_;
447 ...
448 } );
449 An accessor to set a callback to be called during deployment of the
451 schema via "create_ddl_dir" in DBIx::Class::Schema or "deploy" in
452 DBIx::Class::Schema.
453 The callback can be set as either a code reference or the name of a
455 method in the current result class.
456 Defaults to "default_sqlt_deploy_hook".
458 Your callback will be passed the $source object representing the
460 ResultSource instance being deployed, and the
461 SQL::Translator::Schema::Table object being created from it. The
462 callback can be used to manipulate the table object or add your own
463 customised indexes. If you need to manipulate a non-table object, use
464 the "sqlt_deploy_hook" in DBIx::Class::Schema.
465 See "Adding Indexes And Functions To Your SQL" in
467 DBIx::Class::Manual::Cookbook for examples.
468 This sqlt deployment callback can only be used to manipulate
470 SQL::Translator objects as they get turned into SQL. To execute post-
471 deploy statements which SQL::Translator does not currently handle,
472 override "deploy" in DBIx::Class::Schema in your Schema class and call
473 dbh_do.
474 default_sqlt_deploy_hook
476 This is the default deploy hook implementation which checks if your
477 current Result class has a "sqlt_deploy_hook" method, and if present
478 invokes it on the Result class directly. This is to preserve the
479 semantics of "sqlt_deploy_hook" which was originally designed to expect
480 the Result class name and the $sqlt_table instance of the table being
481 deployed.
482 result_class
484 Arguments: $classname
485 Return Value: $classname
486 use My::Schema::ResultClass::Inflator;
488 ...
489 use My::Schema::Artist;
491 ...
492 __PACKAGE__->result_class('My::Schema::ResultClass::Inflator');
493 Set the default result class for this source. You can use this to
495 create and use your own result inflator. See "result_class" in
496 DBIx::Class::ResultSet for more details.
497 Please note that setting this to something like
499 DBIx::Class::ResultClass::HashRefInflator will make every result
500 unblessed and make life more difficult. Inflators like those are
501 better suited to temporary usage via "result_class" in
502 DBIx::Class::ResultSet.
503 resultset
505 Arguments: none
506 Return Value: $resultset
507 Returns a resultset for the given source. This will initially be
509 created on demand by calling
510 $self->resultset_class->new($self, $self->resultset_attributes)
512 but is cached from then on unless resultset_class changes.
514 resultset_class
516 Arguments: $classname
517 Return Value: $classname
518 package My::Schema::ResultSet::Artist;
520 use base 'DBIx::Class::ResultSet';
521 ...
522 # In the result class
524 __PACKAGE__->resultset_class('My::Schema::ResultSet::Artist');
525 # Or in code
527 $source->resultset_class('My::Schema::ResultSet::Artist');
528 Set the class of the resultset. This is useful if you want to create
530 your own resultset methods. Create your own class derived from
531 DBIx::Class::ResultSet, and set it here. If called with no arguments,
532 this method returns the name of the existing resultset class, if one
533 exists.
534 resultset_attributes
536 Arguments: \%attrs
537 Return Value: \%attrs
538 # In the result class
540 __PACKAGE__->resultset_attributes({ order_by => [ 'id' ] });
541 # Or in code
543 $source->resultset_attributes({ order_by => [ 'id' ] });
544 Store a collection of resultset attributes, that will be set on every
546 DBIx::Class::ResultSet produced from this result source.
547 CAVEAT: "resultset_attributes" comes with its own set of issues and
549 bugs! While "resultset_attributes" isn't deprecated per se, its usage
550 is not recommended!
551 Since relationships use attributes to link tables together, the
553 "default" attributes you set may cause unpredictable and undesired
554 behavior. Furthermore, the defaults cannot be turned off, so you are
555 stuck with them.
556 In most cases, what you should actually be using are project-specific
558 methods:
559 package My::Schema::ResultSet::Artist;
561 use base 'DBIx::Class::ResultSet';
562 ...
563 # BAD IDEA!
565 #__PACKAGE__->resultset_attributes({ prefetch => 'tracks' });
566 # GOOD IDEA!
568 sub with_tracks { shift->search({}, { prefetch => 'tracks' }) }
569 # in your code
571 $schema->resultset('Artist')->with_tracks->...
572 This gives you the flexibility of not using it when you don't need it.
574 For more complex situations, another solution would be to use a virtual
576 view via DBIx::Class::ResultSource::View.
577 name
579 Arguments: none
580 Result value: $name
581 Returns the name of the result source, which will typically be the
583 table name. This may be a scalar reference if the result source has a
584 non-standard name.
585 source_name
587 Arguments: $source_name
588 Result value: $source_name
589 Set an alternate name for the result source when it is loaded into a
591 schema. This is useful if you want to refer to a result source by a
592 name other than its class name.
593 package ArchivedBooks;
595 use base qw/DBIx::Class/;
596 __PACKAGE__->table('books_archive');
597 __PACKAGE__->source_name('Books');
598 # from your schema...
600 $schema->resultset('Books')->find(1);
601 from
603 Arguments: none
604 Return Value: FROM clause
605 my $from_clause = $source->from();
607 Returns an expression of the source to be supplied to storage to
609 specify retrieval from this source. In the case of a database, the
610 required FROM clause contents.
611 source_info
613 Stores a hashref of per-source metadata. No specific key names have
614 yet been standardized, the examples below are purely hypothetical and
615 don't actually accomplish anything on their own:
616 __PACKAGE__->source_info({
618 "_tablespace" => 'fast_disk_array_3',
619 "_engine" => 'InnoDB',
620 });
621 schema
623 Arguments: $schema?
624 Return Value: $schema
625 my $schema = $source->schema();
627 Sets and/or returns the DBIx::Class::Schema object to which this result
629 source instance has been attached to.
630 storage
632 Arguments: none
633 Return Value: $storage
634 $source->storage->debug(1);
636 Returns the storage handle for the current schema.
638 add_relationship
640 Arguments: $rel_name, $related_source_name, \%cond, \%attrs?
641 Return Value: 1/true if it succeeded
642 $source->add_relationship('rel_name', 'related_source', $cond, $attrs);
644 DBIx::Class::Relationship describes a series of methods which create
646 pre-defined useful types of relationships. Look there first before
647 using this method directly.
648 The relationship name can be arbitrary, but must be unique for each
650 relationship attached to this result source. 'related_source' should be
651 the name with which the related result source was registered with the
652 current schema. For example:
653 $schema->source('Book')->add_relationship('reviews', 'Review', {
655 'foreign.book_id' => 'self.id',
656 });
657 The condition $cond needs to be an SQL::Abstract::Classic-style
659 representation of the join between the tables. For example, if you're
660 creating a relation from Author to Book,
661 { 'foreign.author_id' => 'self.id' }
663 will result in the JOIN clause
665 author me JOIN book foreign ON foreign.author_id = me.id
667 You can specify as many foreign => self mappings as necessary.
669 Valid attributes are as follows:
671 join_type
673 Explicitly specifies the type of join to use in the relationship.
674 Any SQL join type is valid, e.g. "LEFT" or "RIGHT". It will be
675 placed in the SQL command immediately before "JOIN".
676 proxy
678 An arrayref containing a list of accessors in the foreign class to
679 proxy in the main class. If, for example, you do the following:
680 CD->might_have(liner_notes => 'LinerNotes', undef, {
682 proxy => [ qw/notes/ ],
683 });
684 Then, assuming LinerNotes has an accessor named notes, you can do:
686 my $cd = CD->find(1);
688 # set notes -- LinerNotes object is created if it doesn't exist
689 $cd->notes('Notes go here');
690 accessor
692 Specifies the type of accessor that should be created for the
693 relationship. Valid values are "single" (for when there is only a
694 single related object), "multi" (when there can be many), and
695 "filter" (for when there is a single related object, but you also
696 want the relationship accessor to double as a column accessor). For
697 "multi" accessors, an add_to_* method is also created, which calls
698 "create_related" for the relationship.
699 Throws an exception if the condition is improperly supplied, or cannot
701 be resolved.
702 relationships
704 Arguments: none
705 Return Value: @rel_names
706 my @rel_names = $source->relationships();
708 Returns all relationship names for this source.
710 relationship_info
712 Arguments: $rel_name
713 Return Value: \%rel_data
714 Returns a hash of relationship information for the specified
716 relationship name. The keys/values are as specified for
717 "add_relationship" in DBIx::Class::Relationship::Base.
718 has_relationship
720 Arguments: $rel_name
721 Return Value: 1/0 (true/false)
722 Returns true if the source has a relationship of this name, false
724 otherwise.
725 reverse_relationship_info
727 Arguments: $rel_name
728 Return Value: \%rel_data
729 Looks through all the relationships on the source this relationship
731 points to, looking for one whose condition is the reverse of the
732 condition on this relationship.
733 A common use of this is to find the name of the "belongs_to" relation
735 opposing a "has_many" relation. For definition of these look in
736 DBIx::Class::Relationship.
737 The returned hashref is keyed by the name of the opposing relationship,
739 and contains its data in the same manner as "relationship_info".
740 related_source
742 Arguments: $rel_name
743 Return Value: $source
744 Returns the result source object for the given relationship.
746 related_class
748 Arguments: $rel_name
749 Return Value: $classname
750 Returns the class name for objects in the given relationship.
752 handle
754 Arguments: none
755 Return Value: $source_handle
756 Obtain a new result source handle instance for this source. Used as a
758 serializable pointer to this resultsource, as it is not easy (nor
759 advisable) to serialize CODErefs which may very well be present in e.g.
760 relationship definitions.
761 throw_exception
763 See "throw_exception" in DBIx::Class::Schema.
764 column_info_from_storage
766 Arguments: 1/0 (default: 0)
767 Return Value: 1/0
768 __PACKAGE__->column_info_from_storage(1);
770 Enables the on-demand automatic loading of the above column metadata
772 from storage as necessary. This is *deprecated*, and should not be
773 used. It will be removed before 1.0.
774
776 Check the list of additional DBIC resources.
777
779 This module is free software copyright by the DBIx::Class (DBIC)
780 authors. You can redistribute it and/or modify it under the same terms
781 as the DBIx::Class library.
782perl v5.32.0 2020-07-28 DBIx::Class::ResultSource(3)