1DBIx::Class::ResultSourUcsee(r3)Contributed Perl DocumenDtBaItxi:o:nClass::ResultSource(3)
2
3
4

NAME

6       DBIx::Class::ResultSource - Result source object
7

SYNOPSIS

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

DESCRIPTION

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

METHODS

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

FURTHER QUESTIONS?

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