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 MyDB::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 => 'MyDB::Schema::Result::CD');
18 1;
20 # 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 __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::ResultSoure::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 Row object:
62 $row->result_source;
63 From a ResultSet object:
65 $rs->result_source;
66
68 add_columns
69 Arguments: @columns
70 Return value: The ResultSource object
71 $source->add_columns(qw/col1 col2 col3/);
73 $source->add_columns('col1' => \%col1_info, 'col2' => \%col2_info, ...);
75 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 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 The contents of the column_info are not set in stone. The following
85 keys are currently recognised/used by DBIx::Class:
86 accessor
88 { accessor => '_name' }
89 # example use, replace standard accessor with one of your own:
91 sub name {
92 my ($self, $value) = @_;
93 die "Name cannot contain digits!" if($value =~ /\d/);
95 $self->_name($value);
96 return $self->_name();
98 }
99 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 data_type
104 { data_type => 'integer' }
105 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 Currently there is no standard set of values for the data_type. Use
111 whatever your database supports.
112 size
114 { size => 20 }
115 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 is_nullable
121 { is_nullable => 1 }
122 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 is_auto_increment
129 { is_auto_increment => 1 }
130 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 is_numeric
138 { is_numeric => 1 }
139 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 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 is_foreign_key
151 { is_foreign_key => 1 }
152 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 default_value
159 { default_value => \'now()' }
160 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 See the note on "new" in DBIx::Class::Row for more information
168 about possible issues related to db-side default values.
169 sequence
171 { sequence => 'my_table_seq' }
172 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 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 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 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 add_column
197 Arguments: $colname, \%columninfo?
198 Return value: 1/0 (true/false)
199 $source->add_column('col' => \%info);
201 Add a single column and optional column info. Uses the same column info
203 keys as "add_columns".
204 has_column
206 Arguments: $colname
207 Return value: 1/0 (true/false)
208 if ($source->has_column($colname)) { ... }
210 Returns true if the source has a column of this name, false otherwise.
212 column_info
214 Arguments: $colname
215 Return value: Hashref of info
216 my $info = $source->column_info($col);
218 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 columns
224 Arguments: None
225 Return value: Ordered list of column names
226 my @column_names = $source->columns;
228 Returns all column names in the order they were declared to
230 "add_columns".
231 remove_columns
233 Arguments: @colnames
234 Return value: undefined
235 $source->remove_columns(qw/col1 col2 col3/);
237 Removes the given list of columns by name, from the result source.
239 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 remove_column
245 Arguments: $colname
246 Return value: undefined
247 $source->remove_column('col');
249 Remove a single column by name from the result source, similar to
251 "remove_columns".
252 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 set_primary_key
258 Arguments: @cols
259 Return value: undefined
260 Defines one or more columns as primary key for this source. Must be
262 called after "add_columns".
263 Additionally, defines a unique constraint named "primary".
265 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 primary_columns
272 Arguments: None
273 Return value: Ordered list of primary column names
274 Read-only accessor which returns the list of primary keys, supplied by
276 "set_primary_key".
277 add_unique_constraint
279 Arguments: $name?, \@colnames
280 Return value: undefined
281 Declare a unique constraint on this source. Call once for each unique
283 constraint.
284 # For UNIQUE (column1, column2)
286 __PACKAGE__->add_unique_constraint(
287 constraint_name => [ qw/column1 column2/ ],
288 );
289 Alternatively, you can specify only the columns:
291 __PACKAGE__->add_unique_constraint([ qw/column1 column2/ ]);
293 This will result in a unique constraint named "table_column1_column2",
295 where "table" is replaced with the table name.
296 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 Throws an error if any of the given column names do not yet exist on
302 the result source.
303 name_unique_constraint
305 Arguments: @colnames
306 Return value: Constraint name
307 $source->table('mytable');
309 $source->name_unique_constraint('col1', 'col2');
310 # returns
311 'mytable_col1_col2'
312 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 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 This is used by "add_unique_constraint" if you do not specify the
322 optional constraint name.
323 unique_constraints
325 Arguments: None
326 Return value: Hash of unique constraint data
327 $source->unique_constraints();
329 Read-only accessor which returns a hash of unique constraints on this
331 source.
332 The hash is keyed by constraint name, and contains an arrayref of
334 column names as values.
335 unique_constraint_names
337 Arguments: None
338 Return value: Unique constraint names
339 $source->unique_constraint_names();
341 Returns the list of unique constraint names defined on this source.
343 unique_constraint_columns
345 Arguments: $constraintname
346 Return value: List of constraint columns
347 $source->unique_constraint_columns('myconstraint');
349 Returns the list of columns that make up the specified unique
351 constraint.
352 sqlt_deploy_callback
354 Arguments: $callback
355 __PACKAGE__->sqlt_deploy_callback('mycallbackmethod');
357 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 The callback can be set as either a code reference or the name of a
363 method in the current result class.
364 If not set, the "default_sqlt_deploy_hook" is called.
366 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 See "Adding Indexes And Functions To Your SQL" in
375 DBIx::Class::Manual::Cookbook for examples.
376 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 default_sqlt_deploy_hook
384 Arguments: $source, $sqlt_table
385 Return value: undefined
386 This is the sensible default for "sqlt_deploy_callback".
388 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 resultset
394 Arguments: None
395 Return value: $resultset
396 Returns a resultset for the given source. This will initially be
398 created on demand by calling
399 $self->resultset_class->new($self, $self->resultset_attributes)
401 but is cached from then on unless resultset_class changes.
403 resultset_class
405 Arguments: $classname
406 Return value: $classname
407 package My::Schema::ResultSet::Artist;
409 use base 'DBIx::Class::ResultSet';
410 ...
411 # In the result class
413 __PACKAGE__->resultset_class('My::Schema::ResultSet::Artist');
414 # Or in code
416 $source->resultset_class('My::Schema::ResultSet::Artist');
417 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 resultset_attributes
425 Arguments: \%attrs
426 Return value: \%attrs
427 # In the result class
429 __PACKAGE__->resultset_attributes({ order_by => [ 'id' ] });
430 # Or in code
432 $source->resultset_attributes({ order_by => [ 'id' ] });
433 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 source_name
439 Arguments: $source_name
440 Result value: $source_name
441 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 package ArchivedBooks;
447 use base qw/DBIx::Class/;
448 __PACKAGE__->table('books_archive');
449 __PACKAGE__->source_name('Books');
450 # from your schema...
452 $schema->resultset('Books')->find(1);
453 from
455 Arguments: None
456 Return value: FROM clause
457 my $from_clause = $source->from();
459 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 schema
465 Arguments: None
466 Return value: A schema object
467 my $schema = $source->schema();
469 Returns the DBIx::Class::Schema object that this result source belongs
471 to.
472 storage
474 Arguments: None
475 Return value: A Storage object
476 $source->storage->debug(1);
478 Returns the storage handle for the current schema.
480 See also: DBIx::Class::Storage
482 add_relationship
484 Arguments: $relname, $related_source_name, \%cond, [ \%attrs ]
485 Return value: 1/true if it succeeded
486 $source->add_relationship('relname', 'related_source', $cond, $attrs);
488 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 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 $schema->source('Book')->add_relationship('reviews', 'Review', {
499 'foreign.book_id' => 'self.id',
500 });
501 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 { 'foreign.author_id' => 'self.id' }
507 will result in the JOIN clause
509 author me JOIN book foreign ON foreign.author_id = me.id
511 You can specify as many foreign => self mappings as necessary.
513 Valid attributes are as follows:
515 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 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 CD->might_have(liner_notes => 'LinerNotes', undef, {
526 proxy => [ qw/notes/ ],
527 });
528 Then, assuming LinerNotes has an accessor named notes, you can do:
530 my $cd = CD->find(1);
532 # set notes -- LinerNotes object is created if it doesn't exist
533 $cd->notes('Notes go here');
534 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 Throws an exception if the condition is improperly supplied, or cannot
545 be resolved.
546 relationships
548 Arguments: None
549 Return value: List of relationship names
550 my @relnames = $source->relationships();
552 Returns all relationship names for this source.
554 relationship_info
556 Arguments: $relname
557 Return value: Hashref of relation data,
558 Returns a hash of relationship information for the specified
560 relationship name. The keys/values are as specified for
561 "add_relationship".
562 has_relationship
564 Arguments: $rel
565 Return value: 1/0 (true/false)
566 Returns true if the source has a relationship of this name, false
568 otherwise.
569 reverse_relationship_info
571 Arguments: $relname
572 Return value: Hashref of relationship data
573 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 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 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 related_source
586 Arguments: $relname
587 Return value: $source
588 Returns the result source object for the given relationship.
590 related_class
592 Arguments: $relname
593 Return value: $classname
594 Returns the class name for objects in the given relationship.
596 handle
598 Obtain a new handle to this source. Returns an instance of a
599 DBIx::Class::ResultSourceHandle.
600 throw_exception
602 See "throw_exception" in DBIx::Class::Schema.
603 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 __PACKAGE__->source_info({
610 "_tablespace" => 'fast_disk_array_3',
611 "_engine" => 'InnoDB',
612 });
613 new
615 $class->new();
616 $class->new({attribute_name => value});
618 Creates a new ResultSource object. Not normally called directly by end
620 users.
621 column_info_from_storage
623 Arguments: 1/0 (default: 0)
624 Return value: 1/0
625 __PACKAGE__->column_info_from_storage(1);
627 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.
637perl v5.12.0 2010-05-12 DBIx::Class::ResultSource(3)