1DBIx::Class::ResultSourUcsee(r3)Contributed Perl DocumenDtBaItxi:o:nClass::ResultSource(3)
2
3
4
6 DBIx::Class::ResultSource - Result source object
7
9 # Create a table based result source, in a result class.
10
11 package MyApp::Schema::Result::Artist;
12 use base qw/DBIx::Class::Core/;
13
14 __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
19 1;
20
21 # 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
25 __PACKAGE__->load_components('InflateColumn::DateTime');
26 __PACKAGE__->table_class('DBIx::Class::ResultSource::View');
27
28 __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
38 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
43 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
49 Result sources representing select queries, or views, can also be
50 created, see DBIx::Class::ResultSource::View for full details.
51
52 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
56 You can retrieve the result source at runtime in the following ways:
57
58 From a Schema object:
59 $schema->source($source_name);
60
61 From a Result object:
62 $result->result_source;
63
64 From a ResultSet object:
65 $rs->result_source;
66
68 new
69 $class->new();
70
71 $class->new({attribute_name => value});
72
73 Creates a new ResultSource object. Not normally called directly by end
74 users.
75
76 add_columns
77 Arguments: @columns
78 Return Value: $result_source
79
80 $source->add_columns(qw/col1 col2 col3/);
81
82 $source->add_columns('col1' => \%col1_info, 'col2' => \%col2_info, ...);
83
84 $source->add_columns(
85 'col1' => { data_type => 'integer', is_nullable => 1, ... },
86 'col2' => { data_type => 'text', is_auto_increment => 1, ... },
87 );
88
89 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
93 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
97 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
104 The contents of the column_info are not set in stone. The following
105 keys are currently recognised/used by DBIx::Class:
106
107 accessor
108 { accessor => '_name' }
109
110 # example use, replace standard accessor with one of your own:
111 sub name {
112 my ($self, $value) = @_;
113
114 die "Name cannot contain digits!" if($value =~ /\d/);
115 $self->_name($value);
116
117 return $self->_name();
118 }
119
120 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
123 data_type
124 { data_type => 'integer' }
125
126 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
130 Currently there is no standard set of values for the data_type. Use
131 whatever your database supports.
132
133 size
134 { size => 20 }
135
136 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
140 { size => [ 9, 6 ] }
141
142 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
146 is_nullable
147 { is_nullable => 1 }
148
149 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
154 is_auto_increment
155 { is_auto_increment => 1 }
156
157 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
163 is_numeric
164 { is_numeric => 1 }
165
166 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
172 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
176 is_foreign_key
177 { is_foreign_key => 1 }
178
179 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
184 default_value
185 { default_value => \'now()' }
186
187 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
193 See the note on "new" in DBIx::Class::Row for more information
194 about possible issues related to db-side default values.
195
196 sequence
197 { sequence => 'my_table_seq' }
198
199 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
204 retrieve_on_insert
205 { retrieve_on_insert => 1 }
206
207 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
214 auto_nextval
215 { auto_nextval => 1 }
216
217 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
222 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
227 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
234 add_column
235 Arguments: $colname, \%columninfo?
236 Return Value: 1/0 (true/false)
237
238 $source->add_column('col' => \%info);
239
240 Add a single column and optional column info. Uses the same column info
241 keys as "add_columns".
242
243 has_column
244 Arguments: $colname
245 Return Value: 1/0 (true/false)
246
247 if ($source->has_column($colname)) { ... }
248
249 Returns true if the source has a column of this name, false otherwise.
250
251 column_info
252 Arguments: $colname
253 Return Value: Hashref of info
254
255 my $info = $source->column_info($col);
256
257 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
261 columns
262 Arguments: none
263 Return Value: Ordered list of column names
264
265 my @column_names = $source->columns;
266
267 Returns all column names in the order they were declared to
268 "add_columns".
269
270 columns_info
271 Arguments: \@colnames ?
272 Return Value: Hashref of column name/info pairs
273
274 my $columns_info = $source->columns_info;
275
276 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
280 remove_columns
281 Arguments: @colnames
282 Return Value: not defined
283
284 $source->remove_columns(qw/col1 col2 col3/);
285
286 Removes the given list of columns by name, from the result source.
287
288 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
292 remove_column
293 Arguments: $colname
294 Return Value: not defined
295
296 $source->remove_column('col');
297
298 Remove a single column by name from the result source, similar to
299 "remove_columns".
300
301 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
305 set_primary_key
306 Arguments: @cols
307 Return Value: not defined
308
309 Defines one or more columns as primary key for this source. Must be
310 called after "add_columns".
311
312 Additionally, defines a unique constraint named "primary".
313
314 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
319 primary_columns
320 Arguments: none
321 Return Value: Ordered list of primary column names
322
323 Read-only accessor which returns the list of primary keys, supplied by
324 "set_primary_key".
325
326 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
332 Arguments: $sequence_name
333 Return Value: not defined
334
335 add_unique_constraint
336 Arguments: $name?, \@colnames
337 Return Value: not defined
338
339 Declare a unique constraint on this source. Call once for each unique
340 constraint.
341
342 # For UNIQUE (column1, column2)
343 __PACKAGE__->add_unique_constraint(
344 constraint_name => [ qw/column1 column2/ ],
345 );
346
347 Alternatively, you can specify only the columns:
348
349 __PACKAGE__->add_unique_constraint([ qw/column1 column2/ ]);
350
351 This will result in a unique constraint named "table_column1_column2",
352 where "table" is replaced with the table name.
353
354 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
358 Throws an error if any of the given column names do not yet exist on
359 the result source.
360
361 add_unique_constraints
362 Arguments: @constraints
363 Return Value: not defined
364
365 Declare multiple unique constraints on this source.
366
367 __PACKAGE__->add_unique_constraints(
368 constraint_name1 => [ qw/column1 column2/ ],
369 constraint_name2 => [ qw/column2 column3/ ],
370 );
371
372 Alternatively, you can specify only the columns:
373
374 __PACKAGE__->add_unique_constraints(
375 [ qw/column1 column2/ ],
376 [ qw/column3 column4/ ]
377 );
378
379 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
383 Throws an error if any of the given column names do not yet exist on
384 the result source.
385
386 See also "add_unique_constraint".
387
388 name_unique_constraint
389 Arguments: \@colnames
390 Return Value: Constraint name
391
392 $source->table('mytable');
393 $source->name_unique_constraint(['col1', 'col2']);
394 # returns
395 'mytable_col1_col2'
396
397 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
401 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
405 This is used by "add_unique_constraint" if you do not specify the
406 optional constraint name.
407
408 unique_constraints
409 Arguments: none
410 Return Value: Hash of unique constraint data
411
412 $source->unique_constraints();
413
414 Read-only accessor which returns a hash of unique constraints on this
415 source.
416
417 The hash is keyed by constraint name, and contains an arrayref of
418 column names as values.
419
420 unique_constraint_names
421 Arguments: none
422 Return Value: Unique constraint names
423
424 $source->unique_constraint_names();
425
426 Returns the list of unique constraint names defined on this source.
427
428 unique_constraint_columns
429 Arguments: $constraintname
430 Return Value: List of constraint columns
431
432 $source->unique_constraint_columns('myconstraint');
433
434 Returns the list of columns that make up the specified unique
435 constraint.
436
437 sqlt_deploy_callback
438 Arguments: $callback_name | \&callback_code
439 Return Value: $callback_name | \&callback_code
440
441 __PACKAGE__->sqlt_deploy_callback('mycallbackmethod');
442
443 or
444
445 __PACKAGE__->sqlt_deploy_callback(sub {
446 my ($source_instance, $sqlt_table) = @_;
447 ...
448 } );
449
450 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
454 The callback can be set as either a code reference or the name of a
455 method in the current result class.
456
457 Defaults to "default_sqlt_deploy_hook".
458
459 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
466 See "Adding Indexes And Functions To Your SQL" in
467 DBIx::Class::Manual::Cookbook for examples.
468
469 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
475 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
483 result_class
484 Arguments: $classname
485 Return Value: $classname
486
487 use My::Schema::ResultClass::Inflator;
488 ...
489
490 use My::Schema::Artist;
491 ...
492 __PACKAGE__->result_class('My::Schema::ResultClass::Inflator');
493
494 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
498 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
504 resultset
505 Arguments: none
506 Return Value: $resultset
507
508 Returns a resultset for the given source. This will initially be
509 created on demand by calling
510
511 $self->resultset_class->new($self, $self->resultset_attributes)
512
513 but is cached from then on unless resultset_class changes.
514
515 resultset_class
516 Arguments: $classname
517 Return Value: $classname
518
519 package My::Schema::ResultSet::Artist;
520 use base 'DBIx::Class::ResultSet';
521 ...
522
523 # In the result class
524 __PACKAGE__->resultset_class('My::Schema::ResultSet::Artist');
525
526 # Or in code
527 $source->resultset_class('My::Schema::ResultSet::Artist');
528
529 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
535 resultset_attributes
536 Arguments: \%attrs
537 Return Value: \%attrs
538
539 # In the result class
540 __PACKAGE__->resultset_attributes({ order_by => [ 'id' ] });
541
542 # Or in code
543 $source->resultset_attributes({ order_by => [ 'id' ] });
544
545 Store a collection of resultset attributes, that will be set on every
546 DBIx::Class::ResultSet produced from this result source.
547
548 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
552 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
557 In most cases, what you should actually be using are project-specific
558 methods:
559
560 package My::Schema::ResultSet::Artist;
561 use base 'DBIx::Class::ResultSet';
562 ...
563
564 # BAD IDEA!
565 #__PACKAGE__->resultset_attributes({ prefetch => 'tracks' });
566
567 # GOOD IDEA!
568 sub with_tracks { shift->search({}, { prefetch => 'tracks' }) }
569
570 # in your code
571 $schema->resultset('Artist')->with_tracks->...
572
573 This gives you the flexibility of not using it when you don't need it.
574
575 For more complex situations, another solution would be to use a virtual
576 view via DBIx::Class::ResultSource::View.
577
578 name
579 Arguments: none
580 Result value: $name
581
582 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
586 source_name
587 Arguments: $source_name
588 Result value: $source_name
589
590 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
594 package ArchivedBooks;
595 use base qw/DBIx::Class/;
596 __PACKAGE__->table('books_archive');
597 __PACKAGE__->source_name('Books');
598
599 # from your schema...
600 $schema->resultset('Books')->find(1);
601
602 from
603 Arguments: none
604 Return Value: FROM clause
605
606 my $from_clause = $source->from();
607
608 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
612 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
617 __PACKAGE__->source_info({
618 "_tablespace" => 'fast_disk_array_3',
619 "_engine" => 'InnoDB',
620 });
621
622 schema
623 Arguments: $schema?
624 Return Value: $schema
625
626 my $schema = $source->schema();
627
628 Sets and/or returns the DBIx::Class::Schema object to which this result
629 source instance has been attached to.
630
631 storage
632 Arguments: none
633 Return Value: $storage
634
635 $source->storage->debug(1);
636
637 Returns the storage handle for the current schema.
638
639 add_relationship
640 Arguments: $rel_name, $related_source_name, \%cond, \%attrs?
641 Return Value: 1/true if it succeeded
642
643 $source->add_relationship('rel_name', 'related_source', $cond, $attrs);
644
645 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
649 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
654 $schema->source('Book')->add_relationship('reviews', 'Review', {
655 'foreign.book_id' => 'self.id',
656 });
657
658 The condition $cond needs to be an SQL::Abstract-style representation
659 of the join between the tables. For example, if you're creating a
660 relation from Author to Book,
661
662 { 'foreign.author_id' => 'self.id' }
663
664 will result in the JOIN clause
665
666 author me JOIN book foreign ON foreign.author_id = me.id
667
668 You can specify as many foreign => self mappings as necessary.
669
670 Valid attributes are as follows:
671
672 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
677 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
681 CD->might_have(liner_notes => 'LinerNotes', undef, {
682 proxy => [ qw/notes/ ],
683 });
684
685 Then, assuming LinerNotes has an accessor named notes, you can do:
686
687 my $cd = CD->find(1);
688 # set notes -- LinerNotes object is created if it doesn't exist
689 $cd->notes('Notes go here');
690
691 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
700 Throws an exception if the condition is improperly supplied, or cannot
701 be resolved.
702
703 relationships
704 Arguments: none
705 Return Value: @rel_names
706
707 my @rel_names = $source->relationships();
708
709 Returns all relationship names for this source.
710
711 relationship_info
712 Arguments: $rel_name
713 Return Value: \%rel_data
714
715 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
719 has_relationship
720 Arguments: $rel_name
721 Return Value: 1/0 (true/false)
722
723 Returns true if the source has a relationship of this name, false
724 otherwise.
725
726 reverse_relationship_info
727 Arguments: $rel_name
728 Return Value: \%rel_data
729
730 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
734 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
738 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
741 related_source
742 Arguments: $rel_name
743 Return Value: $source
744
745 Returns the result source object for the given relationship.
746
747 related_class
748 Arguments: $rel_name
749 Return Value: $classname
750
751 Returns the class name for objects in the given relationship.
752
753 handle
754 Arguments: none
755 Return Value: $source_handle
756
757 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
762 throw_exception
763 See "throw_exception" in DBIx::Class::Schema.
764
765 column_info_from_storage
766 Arguments: 1/0 (default: 0)
767 Return Value: 1/0
768
769 __PACKAGE__->column_info_from_storage(1);
770
771 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.
782
783
784
785perl v5.28.1 2018-01-29 DBIx::Class::ResultSource(3)