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 MyDB::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 => 'MyDB::Schema::Result::CD');
18
19 1;
20
21 # Create a query (view) based result source, in a result class
22 package MyDB::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::ResultSoure::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 Row object:
62 $row->result_source;
63
64 From a ResultSet object:
65 $rs->result_source;
66
68 add_columns
69 Arguments: @columns
70 Return value: The ResultSource object
71
72 $source->add_columns(qw/col1 col2 col3/);
73
74 $source->add_columns('col1' => \%col1_info, 'col2' => \%col2_info, ...);
75
76 Adds columns to the result source. If supplied colname => hashref
77 pairs, uses the hashref as the "column_info" for that column. Repeated
78 calls of this method will add more columns, not replace them.
79
80 The column names given will be created as accessor methods on your
81 DBIx::Class::Row objects. You can change the name of the accessor by
82 supplying an "accessor" in the column_info hash.
83
84 The contents of the column_info are not set in stone. The following
85 keys are currently recognised/used by DBIx::Class:
86
87 accessor
88 { accessor => '_name' }
89
90 # example use, replace standard accessor with one of your own:
91 sub name {
92 my ($self, $value) = @_;
93
94 die "Name cannot contain digits!" if($value =~ /\d/);
95 $self->_name($value);
96
97 return $self->_name();
98 }
99
100 Use this to set the name of the accessor method for this column. If
101 unset, the name of the column will be used.
102
103 data_type
104 { data_type => 'integer' }
105
106 This contains the column type. It is automatically filled if you
107 use the SQL::Translator::Producer::DBIx::Class::File producer, or
108 the DBIx::Class::Schema::Loader module.
109
110 Currently there is no standard set of values for the data_type. Use
111 whatever your database supports.
112
113 size
114 { size => 20 }
115
116 The length of your column, if it is a column type that can have a
117 size restriction. This is currently only used to create tables from
118 your schema, see "deploy" in DBIx::Class::Schema.
119
120 is_nullable
121 { is_nullable => 1 }
122
123 Set this to a true value for a columns that is allowed to contain
124 NULL values, default is false. This is currently only used to
125 create tables from your schema, see "deploy" in
126 DBIx::Class::Schema.
127
128 is_auto_increment
129 { is_auto_increment => 1 }
130
131 Set this to a true value for a column whose value is somehow
132 automatically set, defaults to false. This is used to determine
133 which columns to empty when cloning objects using "copy" in
134 DBIx::Class::Row. It is also used by "deploy" in
135 DBIx::Class::Schema.
136
137 is_numeric
138 { is_numeric => 1 }
139
140 Set this to a true or false value (not "undef") to explicitly
141 specify if this column contains numeric data. This controls how
142 set_column decides whether to consider a column dirty after an
143 update: if "is_numeric" is true a numeric comparison "!=" will take
144 place instead of the usual "eq"
145
146 If not specified the storage class will attempt to figure this out
147 on first access to the column, based on the column "data_type". The
148 result will be cached in this attribute.
149
150 is_foreign_key
151 { is_foreign_key => 1 }
152
153 Set this to a true value for a column that contains a key from a
154 foreign table, defaults to false. This is currently only used to
155 create tables from your schema, see "deploy" in
156 DBIx::Class::Schema.
157
158 default_value
159 { default_value => \'now()' }
160
161 Set this to the default value which will be inserted into a column
162 by the database. Can contain either a value or a function (use a
163 reference to a scalar e.g. "\'now()'" if you want a function). This
164 is currently only used to create tables from your schema, see
165 "deploy" in DBIx::Class::Schema.
166
167 See the note on "new" in DBIx::Class::Row for more information
168 about possible issues related to db-side default values.
169
170 sequence
171 { sequence => 'my_table_seq' }
172
173 Set this on a primary key column to the name of the sequence used
174 to generate a new key value. If not specified,
175 DBIx::Class::PK::Auto will attempt to retrieve the name of the
176 sequence from the database automatically.
177
178 auto_nextval
179 Set this to a true value for a column whose value is retrieved
180 automatically from a sequence or function (if supported by your
181 Storage driver.) For a sequence, if you do not use a trigger to get
182 the nextval, you have to set the "sequence" value as well.
183
184 Also set this for MSSQL columns with the 'uniqueidentifier'
185 "data_type" in DBIx::Class::ResultSource whose values you want to
186 automatically generate using "NEWID()", unless they are a primary
187 key in which case this will be done anyway.
188
189 extra
190 This is used by "deploy" in DBIx::Class::Schema and SQL::Translator
191 to add extra non-generic data to the column. For example: "extra =>
192 { unsigned => 1}" is used by the MySQL producer to set an integer
193 column to unsigned. For more details, see
194 SQL::Translator::Producer::MySQL.
195
196 add_column
197 Arguments: $colname, \%columninfo?
198 Return value: 1/0 (true/false)
199
200 $source->add_column('col' => \%info);
201
202 Add a single column and optional column info. Uses the same column info
203 keys as "add_columns".
204
205 has_column
206 Arguments: $colname
207 Return value: 1/0 (true/false)
208
209 if ($source->has_column($colname)) { ... }
210
211 Returns true if the source has a column of this name, false otherwise.
212
213 column_info
214 Arguments: $colname
215 Return value: Hashref of info
216
217 my $info = $source->column_info($col);
218
219 Returns the column metadata hashref for a column, as originally passed
220 to "add_columns". See "add_columns" above for information on the
221 contents of the hashref.
222
223 columns
224 Arguments: None
225 Return value: Ordered list of column names
226
227 my @column_names = $source->columns;
228
229 Returns all column names in the order they were declared to
230 "add_columns".
231
232 remove_columns
233 Arguments: @colnames
234 Return value: undefined
235
236 $source->remove_columns(qw/col1 col2 col3/);
237
238 Removes the given list of columns by name, from the result source.
239
240 Warning: Removing a column that is also used in the sources primary
241 key, or in one of the sources unique constraints, will result in a
242 broken result source.
243
244 remove_column
245 Arguments: $colname
246 Return value: undefined
247
248 $source->remove_column('col');
249
250 Remove a single column by name from the result source, similar to
251 "remove_columns".
252
253 Warning: Removing a column that is also used in the sources primary
254 key, or in one of the sources unique constraints, will result in a
255 broken result source.
256
257 set_primary_key
258 Arguments: @cols
259 Return value: undefined
260
261 Defines one or more columns as primary key for this source. Must be
262 called after "add_columns".
263
264 Additionally, defines a unique constraint named "primary".
265
266 The primary key columns are used by DBIx::Class::PK::Auto to retrieve
267 automatically created values from the database. They are also used as
268 default joining columns when specifying relationships, see
269 DBIx::Class::Relationship.
270
271 primary_columns
272 Arguments: None
273 Return value: Ordered list of primary column names
274
275 Read-only accessor which returns the list of primary keys, supplied by
276 "set_primary_key".
277
278 add_unique_constraint
279 Arguments: $name?, \@colnames
280 Return value: undefined
281
282 Declare a unique constraint on this source. Call once for each unique
283 constraint.
284
285 # For UNIQUE (column1, column2)
286 __PACKAGE__->add_unique_constraint(
287 constraint_name => [ qw/column1 column2/ ],
288 );
289
290 Alternatively, you can specify only the columns:
291
292 __PACKAGE__->add_unique_constraint([ qw/column1 column2/ ]);
293
294 This will result in a unique constraint named "table_column1_column2",
295 where "table" is replaced with the table name.
296
297 Unique constraints are used, for example, when you pass the constraint
298 name as the "key" attribute to "find" in DBIx::Class::ResultSet. Then
299 only columns in the constraint are searched.
300
301 Throws an error if any of the given column names do not yet exist on
302 the result source.
303
304 name_unique_constraint
305 Arguments: @colnames
306 Return value: Constraint name
307
308 $source->table('mytable');
309 $source->name_unique_constraint('col1', 'col2');
310 # returns
311 'mytable_col1_col2'
312
313 Return a name for a unique constraint containing the specified columns.
314 The name is created by joining the table name and each column name,
315 using an underscore character.
316
317 For example, a constraint on a table named "cd" containing the columns
318 "artist" and "title" would result in a constraint name of
319 "cd_artist_title".
320
321 This is used by "add_unique_constraint" if you do not specify the
322 optional constraint name.
323
324 unique_constraints
325 Arguments: None
326 Return value: Hash of unique constraint data
327
328 $source->unique_constraints();
329
330 Read-only accessor which returns a hash of unique constraints on this
331 source.
332
333 The hash is keyed by constraint name, and contains an arrayref of
334 column names as values.
335
336 unique_constraint_names
337 Arguments: None
338 Return value: Unique constraint names
339
340 $source->unique_constraint_names();
341
342 Returns the list of unique constraint names defined on this source.
343
344 unique_constraint_columns
345 Arguments: $constraintname
346 Return value: List of constraint columns
347
348 $source->unique_constraint_columns('myconstraint');
349
350 Returns the list of columns that make up the specified unique
351 constraint.
352
353 sqlt_deploy_callback
354 Arguments: $callback
355
356 __PACKAGE__->sqlt_deploy_callback('mycallbackmethod');
357
358 An accessor to set a callback to be called during deployment of the
359 schema via "create_ddl_dir" in DBIx::Class::Schema or "deploy" in
360 DBIx::Class::Schema.
361
362 The callback can be set as either a code reference or the name of a
363 method in the current result class.
364
365 If not set, the "default_sqlt_deploy_hook" is called.
366
367 Your callback will be passed the $source object representing the
368 ResultSource instance being deployed, and the
369 SQL::Translator::Schema::Table object being created from it. The
370 callback can be used to manipulate the table object or add your own
371 customised indexes. If you need to manipulate a non-table object, use
372 the "sqlt_deploy_hook" in DBIx::Class::Schema.
373
374 See "Adding Indexes And Functions To Your SQL" in
375 DBIx::Class::Manual::Cookbook for examples.
376
377 This sqlt deployment callback can only be used to manipulate
378 SQL::Translator objects as they get turned into SQL. To execute post-
379 deploy statements which SQL::Translator does not currently handle,
380 override "deploy" in DBIx::Class::Schema in your Schema class and call
381 dbh_do.
382
383 default_sqlt_deploy_hook
384 Arguments: $source, $sqlt_table
385 Return value: undefined
386
387 This is the sensible default for "sqlt_deploy_callback".
388
389 If a method named "sqlt_deploy_hook" exists in your Result class, it
390 will be called and passed the current $source and the $sqlt_table being
391 deployed.
392
393 resultset
394 Arguments: None
395 Return value: $resultset
396
397 Returns a resultset for the given source. This will initially be
398 created on demand by calling
399
400 $self->resultset_class->new($self, $self->resultset_attributes)
401
402 but is cached from then on unless resultset_class changes.
403
404 resultset_class
405 Arguments: $classname
406 Return value: $classname
407
408 package My::Schema::ResultSet::Artist;
409 use base 'DBIx::Class::ResultSet';
410 ...
411
412 # In the result class
413 __PACKAGE__->resultset_class('My::Schema::ResultSet::Artist');
414
415 # Or in code
416 $source->resultset_class('My::Schema::ResultSet::Artist');
417
418 Set the class of the resultset. This is useful if you want to create
419 your own resultset methods. Create your own class derived from
420 DBIx::Class::ResultSet, and set it here. If called with no arguments,
421 this method returns the name of the existing resultset class, if one
422 exists.
423
424 resultset_attributes
425 Arguments: \%attrs
426 Return value: \%attrs
427
428 # In the result class
429 __PACKAGE__->resultset_attributes({ order_by => [ 'id' ] });
430
431 # Or in code
432 $source->resultset_attributes({ order_by => [ 'id' ] });
433
434 Store a collection of resultset attributes, that will be set on every
435 DBIx::Class::ResultSet produced from this result source. For a full
436 list see "ATTRIBUTES" in DBIx::Class::ResultSet.
437
438 source_name
439 Arguments: $source_name
440 Result value: $source_name
441
442 Set an alternate name for the result source when it is loaded into a
443 schema. This is useful if you want to refer to a result source by a
444 name other than its class name.
445
446 package ArchivedBooks;
447 use base qw/DBIx::Class/;
448 __PACKAGE__->table('books_archive');
449 __PACKAGE__->source_name('Books');
450
451 # from your schema...
452 $schema->resultset('Books')->find(1);
453
454 from
455 Arguments: None
456 Return value: FROM clause
457
458 my $from_clause = $source->from();
459
460 Returns an expression of the source to be supplied to storage to
461 specify retrieval from this source. In the case of a database, the
462 required FROM clause contents.
463
464 schema
465 Arguments: None
466 Return value: A schema object
467
468 my $schema = $source->schema();
469
470 Returns the DBIx::Class::Schema object that this result source belongs
471 to.
472
473 storage
474 Arguments: None
475 Return value: A Storage object
476
477 $source->storage->debug(1);
478
479 Returns the storage handle for the current schema.
480
481 See also: DBIx::Class::Storage
482
483 add_relationship
484 Arguments: $relname, $related_source_name, \%cond, [ \%attrs ]
485 Return value: 1/true if it succeeded
486
487 $source->add_relationship('relname', 'related_source', $cond, $attrs);
488
489 DBIx::Class::Relationship describes a series of methods which create
490 pre-defined useful types of relationships. Look there first before
491 using this method directly.
492
493 The relationship name can be arbitrary, but must be unique for each
494 relationship attached to this result source. 'related_source' should be
495 the name with which the related result source was registered with the
496 current schema. For example:
497
498 $schema->source('Book')->add_relationship('reviews', 'Review', {
499 'foreign.book_id' => 'self.id',
500 });
501
502 The condition $cond needs to be an SQL::Abstract-style representation
503 of the join between the tables. For example, if you're creating a
504 relation from Author to Book,
505
506 { 'foreign.author_id' => 'self.id' }
507
508 will result in the JOIN clause
509
510 author me JOIN book foreign ON foreign.author_id = me.id
511
512 You can specify as many foreign => self mappings as necessary.
513
514 Valid attributes are as follows:
515
516 join_type
517 Explicitly specifies the type of join to use in the relationship.
518 Any SQL join type is valid, e.g. "LEFT" or "RIGHT". It will be
519 placed in the SQL command immediately before "JOIN".
520
521 proxy
522 An arrayref containing a list of accessors in the foreign class to
523 proxy in the main class. If, for example, you do the following:
524
525 CD->might_have(liner_notes => 'LinerNotes', undef, {
526 proxy => [ qw/notes/ ],
527 });
528
529 Then, assuming LinerNotes has an accessor named notes, you can do:
530
531 my $cd = CD->find(1);
532 # set notes -- LinerNotes object is created if it doesn't exist
533 $cd->notes('Notes go here');
534
535 accessor
536 Specifies the type of accessor that should be created for the
537 relationship. Valid values are "single" (for when there is only a
538 single related object), "multi" (when there can be many), and
539 "filter" (for when there is a single related object, but you also
540 want the relationship accessor to double as a column accessor). For
541 "multi" accessors, an add_to_* method is also created, which calls
542 "create_related" for the relationship.
543
544 Throws an exception if the condition is improperly supplied, or cannot
545 be resolved.
546
547 relationships
548 Arguments: None
549 Return value: List of relationship names
550
551 my @relnames = $source->relationships();
552
553 Returns all relationship names for this source.
554
555 relationship_info
556 Arguments: $relname
557 Return value: Hashref of relation data,
558
559 Returns a hash of relationship information for the specified
560 relationship name. The keys/values are as specified for
561 "add_relationship".
562
563 has_relationship
564 Arguments: $rel
565 Return value: 1/0 (true/false)
566
567 Returns true if the source has a relationship of this name, false
568 otherwise.
569
570 reverse_relationship_info
571 Arguments: $relname
572 Return value: Hashref of relationship data
573
574 Looks through all the relationships on the source this relationship
575 points to, looking for one whose condition is the reverse of the
576 condition on this relationship.
577
578 A common use of this is to find the name of the "belongs_to" relation
579 opposing a "has_many" relation. For definition of these look in
580 DBIx::Class::Relationship.
581
582 The returned hashref is keyed by the name of the opposing relationship,
583 and contains its data in the same manner as "relationship_info".
584
585 related_source
586 Arguments: $relname
587 Return value: $source
588
589 Returns the result source object for the given relationship.
590
591 related_class
592 Arguments: $relname
593 Return value: $classname
594
595 Returns the class name for objects in the given relationship.
596
597 handle
598 Obtain a new handle to this source. Returns an instance of a
599 DBIx::Class::ResultSourceHandle.
600
601 throw_exception
602 See "throw_exception" in DBIx::Class::Schema.
603
604 source_info
605 Stores a hashref of per-source metadata. No specific key names have
606 yet been standardized, the examples below are purely hypothetical and
607 don't actually accomplish anything on their own:
608
609 __PACKAGE__->source_info({
610 "_tablespace" => 'fast_disk_array_3',
611 "_engine" => 'InnoDB',
612 });
613
614 new
615 $class->new();
616
617 $class->new({attribute_name => value});
618
619 Creates a new ResultSource object. Not normally called directly by end
620 users.
621
622 column_info_from_storage
623 Arguments: 1/0 (default: 0)
624 Return value: 1/0
625
626 __PACKAGE__->column_info_from_storage(1);
627
628 Enables the on-demand automatic loading of the above column metadata
629 from storage as necessary. This is *deprecated*, and should not be
630 used. It will be removed before 1.0.
631
633 Matt S. Trout <mst@shadowcatsystems.co.uk>
634
636 You may distribute this code under the same terms as Perl itself.
637
638
639
640perl v5.12.0 2010-05-12 DBIx::Class::ResultSource(3)