From: Jess Robinson Date: Sun, 2 Aug 2009 12:10:53 +0000 (+0000) Subject: Docs: Explainations of result sources and how to find them X-Git-Tag: v0.08109~54 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=16ccb4fe1206cde82c2fe6b7bb6c8a80bb96c1d1;p=dbsrgits%2FDBIx-Class.git Docs: Explainations of result sources and how to find them --- diff --git a/lib/DBIx/Class.pm b/lib/DBIx/Class.pm index 7c2715e..34ab70d 100644 --- a/lib/DBIx/Class.pm +++ b/lib/DBIx/Class.pm @@ -117,7 +117,7 @@ Then you can use these classes in your application's code: # Output all artists names # $artist here is a DBIx::Class::Row, which has accessors - # for all its columns. + # for all its columns. Rows are also subclasses of your Result class. foreach $artist (@artists) { print $artist->name, "\n"; } diff --git a/lib/DBIx/Class/ResultSource.pm b/lib/DBIx/Class/ResultSource.pm index 89b8eda..f50cffd 100644 --- a/lib/DBIx/Class/ResultSource.pm +++ b/lib/DBIx/Class/ResultSource.pm @@ -24,12 +24,75 @@ DBIx::Class::ResultSource - Result source object =head1 SYNOPSIS + # Create a table based result source, in a result class. + + package MyDB::Schema::Result::Artist; + use base qw/DBIx::Class/; + + __PACKAGE__->load_components(qw/Core/); + __PACKAGE__->table('artist'); + __PACKAGE__->add_columns(qw/ artistid name /); + __PACKAGE__->set_primary_key('artistid'); + __PACKAGE__->has_many(cds => 'MyDB::Schema::Result::CD'); + + 1; + + # Create a query (view) based result source, in a result class + package MyDB::Schema::Result::Year2000CDs; + + use DBIx::Class::ResultSource::View; + + __PACKAGE__->load_components('Core'); + __PACKAGE__->table_class('DBIx::Class::ResultSource::View'); + + __PACKAGE__->table('year2000cds'); + __PACKAGE__->result_source_instance->is_virtual(1); + __PACKAGE__->result_source_instance->view_definition( + "SELECT cdid, artist, title FROM cd WHERE year ='2000'" + ); + + =head1 DESCRIPTION -A ResultSource is a component of a schema from which results can be directly -retrieved, most usually a table (see L) +A ResultSource is an object that represents a source of data for querying. + +This class is a base class for various specialised types of result +sources, for example L. Table is the +default result source type, so one is created for you when defining a +result class as described in the synopsis above. + +More specifically, the L component pulls in the +L as a base class, which +defines the L +method. When called, C creates and stores an instance of +L. Luckily, to use tables as result +sources, you don't need to remember any of this. + +Result sources representing select queries, or views, can also be +created, see L for full details. + +=head2 Finding result source objects + +As mentioned above, a result source instance is created and stored for +you when you define a L. + +You can retrieve the result source at runtime in the following ways: + +=over + +=item From a Schema object: + + $schema->source($source_name); + +=item From a Row object: -Basic view support also exists, see L<. + $row->result_source; + +=item From a ResultSet object: + + $rs->result_source; + +=back =head1 METHODS @@ -69,9 +132,9 @@ sub new { $source->add_columns('col1' => \%col1_info, 'col2' => \%col2_info, ...); -Adds columns to the result source. If supplied key => hashref pairs, uses -the hashref as the column_info for that column. Repeated calls of this -method will add more columns, not replace them. +Adds columns to the result source. If supplied colname => hashref +pairs, uses the hashref as the L for that column. Repeated +calls of this method will add more columns, not replace them. The column names given will be created as accessor methods on your L objects. You can change the name of the accessor @@ -84,40 +147,62 @@ keys are currently recognised/used by DBIx::Class: =item accessor + { accessor => '_name' } + + # example use, replace standard accessor with one of your own: + sub name { + my ($self, $value) = @_; + + die "Name cannot contain digits!" if($value =~ /\d/); + $self->_name($value); + + return $self->_name(); + } + Use this to set the name of the accessor method for this column. If unset, the name of the column will be used. =item data_type -This contains the column type. It is automatically filled by the -L producer, and the -L module. If you do not enter a -data_type, DBIx::Class will attempt to retrieve it from the -database for you, using L's column_info method. The values of this -key are typically upper-cased. + { data_type => 'integer' } + +This contains the column type. It is automatically filled if you use the +L producer, or the +L module. Currently there is no standard set of values for the data_type. Use whatever your database supports. =item size + { size => 20 } + The length of your column, if it is a column type that can have a size -restriction. This is currently only used by L. +restriction. This is currently only used to create tables from your +schema, see L. =item is_nullable -Set this to a true value for a columns that is allowed to contain -NULL values. This is currently only used by L. + { is_nullable => 1 } + +Set this to a true value for a columns that is allowed to contain NULL +values, default is false. This is currently only used to create tables +from your schema, see L. =item is_auto_increment + { is_auto_increment => 1 } + Set this to a true value for a column whose value is somehow -automatically set. This is used to determine which columns to empty -when cloning objects using L. It is also used by +automatically set, defaults to false. This is used to determine which +columns to empty when cloning objects using +L. It is also used by L. =item is_numeric + { is_numeric => 1 } + Set this to a true or false value (not C) to explicitly specify if this column contains numeric data. This controls how set_column decides whether to consider a column dirty after an update: if @@ -130,22 +215,29 @@ result will be cached in this attribute. =item is_foreign_key + { is_foreign_key => 1 } + Set this to a true value for a column that contains a key from a -foreign table. This is currently only used by -L. +foreign table, defaults to false. This is currently only used to +create tables from your schema, see L. =item default_value -Set this to the default value which will be inserted into a column -by the database. Can contain either a value or a function (use a + { default_value => \'now()' } + +Set this to the default value which will be inserted into a column by +the database. Can contain either a value or a function (use a reference to a scalar e.g. C<\'now()'> if you want a function). This -is currently only used by L. +is currently only used to create tables from your schema, see +L. See the note on L for more information about possible issues related to db-side default values. =item sequence + { sequence => 'my_table_seq' } + Set this on a primary key column to the name of the sequence used to generate a new key value. If not specified, L will attempt to retrieve the name of the sequence from the database @@ -171,13 +263,13 @@ L. =over -=item Arguments: $colname, [ \%columninfo ] +=item Arguments: $colname, \%columninfo? =item Return value: 1/0 (true/false) =back - $source->add_column('col' => \%info?); + $source->add_column('col' => \%info); Add a single column and optional column info. Uses the same column info keys as L. @@ -237,8 +329,8 @@ sub has_column { my $info = $source->column_info($col); Returns the column metadata hashref for a column, as originally passed -to L. See the description of L for information -on the contents of the hashref. +to L. See L above for information on the +contents of the hashref. =cut @@ -362,14 +454,16 @@ sub remove_column { shift->remove_columns(@_); } # DO NOT CHANGE THIS TO GLOB =back -Defines one or more columns as primary key for this source. Should be +Defines one or more columns as primary key for this source. Must be called after L. Additionally, defines a L named C. The primary key columns are used by L to -retrieve automatically created values from the database. +retrieve automatically created values from the database. They are also +used as default joining columns when specifying relationships, see +L. =cut @@ -408,7 +502,7 @@ sub primary_columns { =over 4 -=item Arguments: [ $name ], \@colnames +=item Arguments: $name?, \@colnames =item Return value: undefined @@ -426,11 +520,13 @@ Alternatively, you can specify only the columns: __PACKAGE__->add_unique_constraint([ qw/column1 column2/ ]); -This will result in a unique constraint named C, where -C
is replaced with the table name. +This will result in a unique constraint named +C, where C
is replaced with the table +name. -Unique constraints are used, for example, when you call -L. Only columns in the constraint are searched. +Unique constraints are used, for example, when you pass the constraint +name as the C attribute to L. Then +only columns in the constraint are searched. Throws an error if any of the given column names do not yet exist on the result source. @@ -499,7 +595,8 @@ sub name_unique_constraint { $source->unique_constraints(); -Read-only accessor which returns a hash of unique constraints on this source. +Read-only accessor which returns a hash of unique constraints on this +source. The hash is keyed by constraint name, and contains an arrayref of column names as values. @@ -659,11 +756,15 @@ but is cached from then on unless resultset_class changes. =back - package My::ResultSetClass; + package My::Schema::ResultSet::Artist; use base 'DBIx::Class::ResultSet'; ... - $source->resultset_class('My::ResultSet::Class'); + # In the result class + __PACKAGE__->resultset_class('My::Schema::ResultSet::Artist'); + + # Or in code + $source->resultset_class('My::Schema::ResultSet::Artist'); Set the class of the resultset. This is useful if you want to create your own resultset methods. Create your own class derived from @@ -681,6 +782,10 @@ exists. =back + # In the result class + __PACKAGE__->resultset_attributes({ order_by => [ 'id' ] }); + + # Or in code $source->resultset_attributes({ order_by => [ 'id' ] }); Store a collection of resultset attributes, that will be set on every diff --git a/lib/DBIx/Class/ResultSource/View.pm b/lib/DBIx/Class/ResultSource/View.pm index 0bcb0fc..a9c3755 100644 --- a/lib/DBIx/Class/ResultSource/View.pm +++ b/lib/DBIx/Class/ResultSource/View.pm @@ -17,7 +17,7 @@ DBIx::Class::ResultSource::View - ResultSource object representing a view =head1 SYNOPSIS - package MyDB::Schema::Year2000CDs; + package MyDB::Schema::Result::Year2000CDs; use DBIx::Class::ResultSource::View;