=head1 SYNOPSIS
-Create a base schema class called DB/Main.pm:
+Create a schema class called DB/Main.pm:
package DB::Main;
use base qw/DBIx::Class::Schema/;
1;
-Create a class to represent artists, who have many CDs, in DB/Main/Artist.pm:
+Create a table class to represent artists, who have many CDs, in DB/Main/Artist.pm:
package DB::Main::Artist;
use base qw/DBIx::Class/;
__PACKAGE__->table('artist');
__PACKAGE__->add_columns(qw/ artistid name /);
__PACKAGE__->set_primary_key('artistid');
- __PACKAGE__->has_many('cds' => 'DB::Main::CD');
+ __PACKAGE__->has_many(cds => 'DB::Main::CD');
1;
-A class to represent a CD, which belongs to an artist, in DB/Main/CD.pm:
+A table class to represent a CD, which belongs to an artist, in DB/Main/CD.pm:
package DB::Main::CD;
use base qw/DBIx::Class/;
__PACKAGE__->load_components(qw/PK::Auto Core/);
__PACKAGE__->table('cd');
- __PACKAGE__->add_columns(qw/ cdid artist title year/);
+ __PACKAGE__->add_columns(qw/ cdid artist title year /);
__PACKAGE__->set_primary_key('cdid');
- __PACKAGE__->belongs_to('artist' => 'DB::Main::Artist');
+ __PACKAGE__->belongs_to(artist => 'DB::Main::Artist');
1;
Then you can use these classes in your application's code:
# Connect to your database.
- my $ds = DB::Main->connect(@dbi_dsn);
+ use DB::Main;
+ my $schema = DB::Main->connect($dbi_dsn, $user, $pass, \%dbi_params);
# Query for all artists and put them in an array,
# or retrieve them as a result set object.
- my @all_artists = $ds->resultset('Artist')->all;
- my $all_artists_rs = $ds->resultset('Artist');
+ my @all_artists = $schema->resultset('Artist')->all;
+ my $all_artists_rs = $schema->resultset('Artist');
# Create a result set to search for artists.
# This does not query the DB.
- my $johns_rs = $ds->resultset('Artist')->search(
- # Build your WHERE using an SQL::Abstract structure:
- { 'name' => { 'like', 'John%' } }
+ my $johns_rs = $schema->resultset('Artist')->search(
+ # Build your WHERE using an L<SQL::Abstract> structure:
+ { name => { like => 'John%' } }
);
- # This executes a joined query to get the cds
+ # Execute a joined query to get the cds.
my @all_john_cds = $johns_rs->search_related('cds')->all;
- # Queries but only fetches one row so far.
+ # Fetch only the next row.
my $first_john = $johns_rs->next;
+ # Specify ORDER BY on the query.
my $first_john_cds_by_title_rs = $first_john->cds(
undef,
{ order_by => 'title' }
);
+ # Create a result set that will fetch the artist relationship
+ # at the same time as it fetches CDs, using only one query.
my $millennium_cds_rs = $ds->resultset('CD')->search(
{ year => 2000 },
{ prefetch => 'artist' }
DBIx::Class can handle multi-column primary and foreign keys, complex
queries and database-level paging, and does its best to only query the
-database when it actually needs to in order to return something you've directly
-asked for. If a resultset is used as an iterator it only fetches rows off
-the statement handle as requested in order to minimise memory usage. It
-has auto-increment support for SQLite, MySQL, PostgreSQL, Oracle, SQL
-Server and DB2 and is known to be used in production on at least the first
-four, and is fork- and thread-safe out of the box (although your DBD may not
-be).
+database in order to return something you've directly asked for. If a
+resultset is used as an iterator it only fetches rows off the statement
+handle as requested in order to minimise memory usage. It has auto-increment
+support for SQLite, MySQL, PostgreSQL, Oracle, SQL Server and DB2 and is
+known to be used in production on at least the first four, and is fork-
+and thread-safe out of the box (although your DBD may not be).
This project is still under rapid development, so features added in the
-latest major release may not work 100% yet - check the Changes if you run
+latest major release may not work 100% yet -- check the Changes if you run
into trouble, and beware of anything explicitly marked EXPERIMENTAL. Failing
test cases are *always* welcome and point releases are put out rapidly as
bugs are found and fixed.
Even so, we do our best to maintain full backwards compatibility for published
-APIs since DBIx::Class is used in production in a number of organisations;
-the test suite is now fairly substantial and several developer releases are
+APIs, since DBIx::Class is used in production in a number of organisations.
+The test suite is quite substantial, and several developer releases are
generally made to CPAN before the -current branch is merged back to trunk for
a major release.
-The community can be found via -
+The community can be found via:
Mailing list: http://lists.rawmode.org/mailman/listinfo/dbix-class/
CDBICompat::MightHave
/);
-=head1 Components
+=head1 COMPONENTS
=over 4
=item HasA
-Responsible for HasA relationships.
-
=item HasMany
-Responsible for HasMany relationships.
-
=item ImaDBI
=item LazyLoading
=item MightHave
-Responsible for MightHave relationships.
-
=item ObjIndexStubs
=item ReadOnly
=item Triggers
-This class implements the trigger functionality.
-
=item PassThrough
=back
=over 4
+=item L<DBIx::Class::Serialize::Storable>
+
=item L<DBIx::Class::InflateColumn>
=item L<DBIx::Class::Relationship>
# year = 2005 OR year = 2004
If you need to pass in additional attributes but no additional condition,
-call it as C<search(undef, \%attrs);>.
+call it as C<search(undef, \%attrs)>.
# "SELECT name, artistid FROM $artist_table"
my @all_artists = $schema->resultset('Artist')->search(undef, {
name => 'Emo-R-Us',
});
-Search the specified relationship, optionally specify a condition and
+Searches the specified relationship, optionally specifying a condition and
attributes for matching records. See L</ATTRIBUTES> for more information.
=cut
# WHERE title LIKE '%blue%'
$cd_rs = $rs->search_like({ title => '%blue%'});
-Perform a search, but use C<LIKE> instead of C<=> as the condition. Note
+Performs a search, but uses C<LIKE> instead of C<=> as the condition. Note
that this is simply a convenience method. You most likely want to use
L</search> with specific operators.
=back
Returns a resultset or object list representing a subset of elements from the
-resultset slice is called on. Indexes are from 0 - i.e. to get the first
-three records, call
+resultset slice is called on. Indexes are from 0, i.e., to get the first
+three records, call:
my ($one, $two, $three) = $rs->slice(0, 2);
=back
Resets the resultset and returns an object for the first result (if the
-resultset contains anything).
+resultset returns anything).
=cut
=back
-Fetches all objects and updates them one at a time. Note that C<update_all>
-will run cascade triggers while L</update> will not.
+Fetches all objects and updates them one at a time. Note that C<update_all>
+will run DBIC cascade triggers, while L</update> will not.
=cut
=back
Deletes the contents of the resultset from its result source. Note that this
-will not run cascade triggers. See L</delete_all> if you need triggers to run.
+will not run DBIC cascade triggers. See L</delete_all> if you need triggers
+to run.
=cut
=back
-Fetches all objects and deletes them one at a time. Note that C<delete_all>
-will run cascade triggers while L</delete> will not.
+Fetches all objects and deletes them one at a time. Note that C<delete_all>
+will run DBIC cascade triggers, while L</delete> will not.
=cut
Returns a resultset for the $page_number page of the resultset on which page
is called, where each page contains a number of rows equal to the 'rows'
-attribute set on the resultset, or 10 by default
+attribute set on the resultset (10 by default).
=cut
$class->update_or_create({ col => $val, ... });
-First, search for an existing row matching one of the unique constraints
-(including the primary key) on the source of this resultset. If a row is
-found, update it with the other given column values. Otherwise, create a new
+First, searches for an existing row matching one of the unique constraints
+(including the primary key) on the source of this resultset. If a row is
+found, updates it with the other given column values. Otherwise, creates a new
row.
Takes an optional C<key> attribute to search on a specific unique constraint.
If no C<key> is specified, it searches on all unique constraints defined on the
source, including the primary key.
-If the C<key> is specified as C<primary>, search only on the primary key.
+If the C<key> is specified as C<primary>, it searches only on the primary key.
See also L</find> and L</find_or_create>.
=back
-Gets the contents of the cache for the resultset if the cache is set
+Gets the contents of the cache for the resultset, if the cache is set.
=cut
$table->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.
+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.
-Repeated calls of this method will add more columns, not replace them.
-
-The contents of the column_info are not set in stone, the following
-keys are currently recognised/used by DBIx::Class.
+The contents of the column_info are not set in stone. The following
+keys are currently recognised/used by DBIx::Class:
=over 4
=item data_type
-This contains the column type, it is automatically filled by the
+This contains the column type. It is automatically filled by the
L<SQL::Translator::Producer::DBIx::Class::File> producer, and the
-L<DBIx::Class::Schema::Loader> module. If you do not enter the
+L<DBIx::Class::Schema::Loader> module. If you do not enter a
data_type, DBIx::Class will attempt to retrieve it from the
-database for you, using L<DBI>s column_info method. The values of this
+database for you, using L<DBI>'s column_info method. The values of this
key are typically upper-cased.
-Currently there is no standard set of values for the data_type, use
-whatever your database(s) support.
+Currently there is no standard set of values for the data_type. Use
+whatever your database supports.
=item size
=item is_nullable
-If the column is allowed to contain NULL values, set a true value
-(typically 1), here. This is currently not used by DBIx::Class.
+Set this to a true value for a columns that is allowed to contain
+NULL values. This is currently not used by DBIx::Class.
=item is_auto_increment
-Set this to a true value if this is a column that is somehow
-automatically filled. This is used to determine which columns to empty
+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 C<copy>.
=item is_foreign_key
-Set this to a true value if this column represents a key from a
+Set this to a true value for a column that contains a key from a
foreign table. This is currently not used by DBIx::Class.
=item default_value
-Set this to the default value which will be inserted into this column
-by the database. Can contain either values or functions. This is
+Set this to the default value which will be inserted into a column
+by the database. Can contain either a value or a function. This is
currently not used by DBIx::Class.
=item sequence
-Sets the name of the sequence to use to generate values. If not
-specified, L<DBIx::Class::PK::Auto> will attempt to retrieve the
-name of the sequence from the database automatically.
+Set this on a primary key column to the name of the sequence used to
+generate a new key value. If not specified, L<DBIx::Class::PK::Auto>
+will attempt to retrieve the name of the sequence from the database
+automatically.
=back
$table->add_column('col' => \%info?);
-Convenience alias to add_columns
+Convenience alias to add_columns.
=cut
if ($obj->has_column($col)) { ... }
-Returns 1 if the source has a column of this name, 0 otherwise.
+Returns true if the source has a column of this name, false otherwise.
=cut
my @column_names = $obj->columns;
-Returns all column names in the order they were declared to add_columns
+Returns all column names in the order they were declared to add_columns.
=cut
Declare a unique constraint on this source. Call once for each unique
constraint. Unique constraints are used when you call C<find> on a
-L<DBIx::Class::ResultSet>, only columns in the constraint are searched,
-
-e.g.,
+L<DBIx::Class::ResultSet>. Only columns in the constraint are searched,
+for example:
# For UNIQUE (column1, column2)
__PACKAGE__->add_unique_constraint(
=head2 from
Returns an expression of the source to be supplied to storage to specify
-retrieval from this source; in the case of a database the required FROM clause
-contents.
+retrieval from this source. In the case of a database, the required FROM
+clause contents.
=cut
'foreign.book_id' => 'self.id',
});
-The condition C<$cond> needs to be an SQL::Abstract-style
+The condition C<$cond> needs to be an L<SQL::Abstract>-style
representation of the join between the tables. For example, if you're
creating a rel from Author to Book,
Then, assuming LinerNotes has an accessor named notes, you can do:
my $cd = CD->find(1);
- $cd->notes('Notes go here'); # set notes -- LinerNotes object is
- # created if it doesn't exist
+ # set notes -- LinerNotes object is created if it doesn't exist
+ $cd->notes('Notes go here');
=item accessor
=head2 relationships
-Returns all valid relationship names for this source
+Returns all relationship names for this source.
=cut
=back
-Returns the relationship information for the specified relationship name
+Returns a hash of relationship information for the specified relationship
+name.
=cut
=back
-Returns 1 if the source has a relationship of this name, 0 otherwise.
+Returns true if the source has a relationship of this name, false otherwise.
=cut
=back
-Returns the join structure required for the related result source
+Returns the join structure required for the related result source.
=cut
=back
-Returns the result source object for the given relationship
+Returns the result source object for the given relationship.
=cut
=back
-Returns the class object for the given relationship
+Returns the class name for objects in the given relationship.
=cut
=head2 throw_exception
-See throw_exception in L<DBIx::Class::Schema>.
+See L<DBIx::Class::Schema/"throw_exception">.
=cut
}
}
-
=head1 AUTHORS
Matt S. Trout <mst@shadowcatsystems.co.uk>
with your classes.
NB: If you're used to L<Class::DBI> it's worth reading the L</SYNOPSIS>
-carefully as DBIx::Class does things a little differently. Note in
+carefully, as DBIx::Class does things a little differently. Note in
particular which module inherits off which.
=head1 METHODS
=back
Registers a class which isa L<DBIx::Class::ResultSourceProxy>. Equivalent to
-calling
+calling:
$schema->register_source($moniker, $component_class->result_source_instance);
=back
-Retrieves the result class name for the given moniker.
-
-e.g.,
+Retrieves the result class name for the given moniker. For example:
my $class = $schema->class('CD');
=back
Returns the source monikers of all source registrations on this schema.
-
-e.g.,
+For example:
my @source_monikers = $schema->sources;
the schema's namespace. Otherwise, this method loads the classes you specify
(using L<use>), and registers them (using L</"register_class">).
-It is possible to comment out classes with a leading '#', but note that perl
-will think it's a mistake (trying to use a comment in a qw list) so you'll
-need to add "no warnings 'qw';" before your load_classes call.
+It is possible to comment out classes with a leading C<#>, but note that perl
+will think it's a mistake (trying to use a comment in a qw list), so you'll
+need to add C<no warnings 'qw';> before your load_classes call.
-e.g.,
+Example:
My::Schema->load_classes(); # loads My::Schema::CD, My::Schema::Artist,
# etc. (anything under the My::Schema namespace)
=back
-Calls L<DBIx::Class::schema/"compose_namespace"> to the target namespace,
-calls L<DBIx::Class::Schema/connection>(@db_info) on the new schema, then
-injects the L<DBix::Class::ResultSetProxy> component and a resultset_instance
-classdata entry on all the new classes in order to support
+Calls L<DBIx::Class::Schema/"compose_namespace"> to the target namespace,
+calls L<DBIx::Class::Schema/connection> with @db_info on the new schema,
+then injects the L<DBix::Class::ResultSetProxy> component and a
+resultset_instance classdata entry on all the new classes, in order to support
$target_namespaces::$class->search(...) method calls.
This is primarily useful when you have a specific need for class method access
classes will inherit from first the corresponding classe from the current
schema then the base class.
-e.g. (for a schema with My::Schema::CD and My::Schema::Artist classes),
+For example, for a schema with My::Schema::CD and My::Schema::Artist classes,
$schema->compose_namespace('My::DB', 'Base::Class');
print join (', ', @My::DB::CD::ISA) . "\n";
print join (', ', @My::DB::Artist::ISA) ."\n";
-Will produce the output
+will produce the output
My::Schema::CD, Base::Class
My::Schema::Artist, Base::Class
=head1 NAME
DBIx::Class::Serialize::Storable - hooks for Storable freeze/thaw
- (EXPERIMENTAL)
=head1 SYNOPSIS
# meanwhile, in a nearby piece of code
my $cd = $schema->resultset('CD')->find(12);
- $cache->set($cd->ID, $cd); # if the cache uses Storable, this
- # will work automatically
+ # if the cache uses Storable, this will work automatically
+ $cache->set($cd->ID, $cd);
=head1 DESCRIPTION
This component adds hooks for Storable so that row objects can be
serialized. It assumes that your row object class (C<result_class>) is
-the same as your table class, which is the normal situation. However,
-this code is not yet well tested, and so should be considered
-experimental.
+the same as your table class, which is the normal situation.
=head1 AUTHORS
projects / dbsrgits/DBIx-Class.git / commitdiff