For more information on generating complex queries, see
L<SQL::Abstract/WHERE CLAUSES>.
+=head3 Arbitrary SQL through a custom ResultSource
+
+Sometimes you have to run arbitrary SQL because your query is too complex
+(e.g. it contains Unions, Sub-Selects, Stored Procedures, etc.) or has to
+be optimized for your database in a special way, but you still want to
+get the results as a L<DBIx::Class::ResultSet>.
+The recommended way to accomplish this is by defining a separate ResultSource
+for your query. You can then inject complete SQL statements using a scalar
+reference (this is a feature of L<SQL::Abstract>).
+
+Say you want to run a complex custom query on your user data, here's what
+you have to add to your User class:
+
+ package My::Schema::User;
+
+ use base qw/DBIx::Class/;
+
+ # ->load_components, ->table, ->add_columns, etc.
+
+ # Make a new ResultSource based on the User class
+ my $source = __PACKAGE__->result_source_instance();
+ my $new_source = $source->new( $source );
+ $new_source->source_name( 'UserFriendsComplex' );
+
+ # Hand in your query as a scalar reference
+ # It will be added as a sub-select after FROM,
+ # so pay attention to the surrounding brackets!
+ $new_source->name( \<<SQL );
+ ( SELECT u.* FROM user u
+ INNER JOIN user_friends f ON u.id = f.user_id
+ WHERE f.friend_user_id = ?
+ UNION
+ SELECT u.* FROM user u
+ INNER JOIN user_friends f ON u.id = f.friend_user_id
+ WHERE f.user_id = ? )
+ SQL
+
+ # Finally, register your new ResultSource with your Schema
+ My::Schema->register_source( 'UserFriendsComplex' => $new_source );
+
+Next, you can execute your complex query using bind parameters like this:
+
+ my $friends = [ $schema->resultset( 'UserFriendsComplex' )->search( {},
+ {
+ bind => [ 12345, 12345 ]
+ }
+ ) ];
+
+... and you'll get back a perfect L<DBIx::Class::ResultSet>.
+
=head3 Using specific columns
-When you only want selected columns from a table, you can use C<cols> to
-specify which ones you need:
+When you only want specific columns from a table, you can use
+C<columns> to specify which ones you need. This is useful to avoid
+loading columns with large amounts of data that you aren't about to
+use anyway:
my $rs = $schema->resultset('Artist')->search(
undef,
# Equivalent SQL:
# SELECT artist.name FROM artist
+This is a shortcut for C<select> and C<as>, see below. C<columns>
+cannot be used together with C<select> and C<as>.
+
=head3 Using database functions or stored procedures
The combination of C<select> and C<as> can be used to return the result of a
to access the returned value:
my $rs = $schema->resultset('Artist')->search(
- undef,
+ {},
{
select => [ 'name', { LENGTH => 'name' } ],
as => [qw/ name name_length /],
);
# Equivalent SQL:
- # SELECT name name, LENGTH( name ) name_length
+ # SELECT name name, LENGTH( name )
# FROM artist
-If your alias exists as a column in your base class (i.e. it was added with
-C<add_columns>), you just access it as normal. Our C<Artist> class has a C<name>
-column, so we just use the C<name> accessor:
+Note that the C< as > attribute has absolutely nothing to with the sql
+syntax C< SELECT foo AS bar > (see the documentation in
+L<DBIx::Class::ResultSet/ATTRIBUTES>). If your alias exists as a
+column in your base class (i.e. it was added with C<add_columns>), you
+just access it as normal. Our C<Artist> class has a C<name> column, so
+we just use the C<name> accessor:
my $artist = $rs->first();
my $name = $artist->name();
If on the other hand the alias does not correspond to an existing column, you
-can get the value using the C<get_column> accessor:
+have to fetch the value using the C<get_column> accessor:
my $name_length = $artist->get_column('name_length');
=head3 SELECT DISTINCT with multiple columns
my $rs = $schema->resultset('Foo')->search(
- undef,
+ {},
{
select => [
{ distinct => [ $source->columns ] }
],
- as => [ $source->columns ]
+ as => [ $source->columns ] # remember 'as' is not the same as SQL AS :-)
}
);
=head3 SELECT COUNT(DISTINCT colname)
my $rs = $schema->resultset('Foo')->search(
- undef,
+ {},
{
select => [
{ count => { distinct => 'colname' } }
L<DBIx::Class> supports C<GROUP BY> as follows:
my $rs = $schema->resultset('Artist')->search(
- undef,
+ {},
{
join => [qw/ cds /],
select => [ 'name', { count => 'cds.cdid' } ],
# LEFT JOIN cd cds ON ( cds.artist = me.artistid )
# GROUP BY name
+Please see L<DBIx::Class::ResultSet/ATTRIBUTES> documentation if you
+are in any way unsure about the use of the attributes above (C< join
+>, C< select >, C< as > and C< group_by >).
+
=head3 Predefined searches
-You can write your own DBIx::Class::ResultSet class by inheriting from it
+You can write your own L<DBIx::Class::ResultSet> class by inheriting from it
and define often used searches as methods:
package My::DBIC::ResultSet::CD;
my $ordered_cds = $schema->resultset('CD')->search_cds_ordered();
-
-=head3 Predefined searches without writing a ResultSet class
-
-Alternatively you can automatically generate a DBIx::Class::ResultSet
-class by using the ResultSetManager component and tagging your method
-as ResultSet:
-
- __PACKAGE__->load_components(qw/ ResultSetManager Core /);
-
- sub search_cds_ordered : ResultSet {
- my ($self) = @_;
- return $self->search(
- {},
- { order_by => 'name DESC' },
- );
- }
-
-Then call your method in the same way from your code:
-
- my $ordered_cds = $schema->resultset('CD')->search_cds_ordered();
-
=head2 Using joins and prefetch
You can use the C<join> attribute to allow searching on, or sorting your
deep using the same syntax as a multi-step join:
my $rs = $schema->resultset('Tag')->search(
- undef,
+ {},
{
prefetch => {
cd => 'artist'
my $tag = $rs->first;
print $tag->cd->artist->name;
+=head2 Columns of data
+
+If you want to find the sum of a particular column there are several
+ways, the obvious one is to use search:
+
+ my $rs = $schema->resultset('Items')->search(
+ {},
+ {
+ select => [ { sum => 'Cost' } ],
+ as => [ 'total_cost' ], # remember this 'as' is for DBIx::Class::ResultSet not SQL
+ }
+ );
+ my $tc = $rs->first->get_column('total_cost');
+
+Or, you can use the L<DBIx::Class::ResultSetColumn>, which gets
+returned when you ask the C<ResultSet> for a column using
+C<get_column>:
+
+ my $cost = $schema->resultset('Items')->get_column('Cost');
+ my $tc = $cost->sum;
+
+With this you can also do:
+
+ my $minvalue = $cost->min;
+ my $maxvalue = $cost->max;
+
+Or just iterate through the values of this column only:
+
+ while ( my $c = $cost->next ) {
+ print $c;
+ }
+
+ foreach my $c ($cost->all) {
+ print $c;
+ }
+
+C<ResultSetColumn> only has a limited number of built-in functions, if
+you need one that it doesn't have, then you can use the C<func> method
+instead:
+
+ my $avg = $cost->func('AVERAGE');
+
+This will cause the following SQL statement to be run:
+
+ SELECT AVERAGE(Cost) FROM Items me
+
+Which will of course only work if your database supports this function.
+See L<DBIx::Class::ResultSetColumn> for more documentation.
+
=head2 Using relationships
=head3 Create a new row in a related table
my $author->delete_related('books', { name => 'Titanic' });
+=head3 Ordering a relationship result set
+
+If you always want a relation to be ordered, you can specify this when you
+create the relationship.
+
+To order C<< $book->pages >> by descending page_number.
+
+ Book->has_many('pages' => 'Page', 'book', { order_by => \'page_number DESC'} );
+
+
+
=head2 Transactions
As of version 0.04001, there is improved transaction support in
=head2 Many-to-many relationships
-This is straightforward using L<DBIx::Class::Relationship::ManyToMany>:
+This is straightforward using L<ManyToMany|DBIx::Class::Relationship/many_to_many>:
package My::DB;
# ... set up connection ...
C<next::method>.
sub new {
- my ( $class, $attrs ) = @_;
+ my ( $self, $attrs ) = @_;
$attrs->{foo} = 'bar' unless defined $attrs->{foo};
- $class->next::method($attrs);
+ my $new = $class->next::method($attrs);
+
+ return $new;
}
For more information about C<next::method>, look in the L<Class::C3>
ways to write your own base classes to do this.
People looking for ways to do "triggers" with DBIx::Class are probably
-just looking for this.
+just looking for this.
=head2 Stringification
Employ the standard stringification technique by using the C<overload>
-module. Replace C<foo> with the column/method of your choice.
+module.
+
+To make an object stringify itself as a single column, use something
+like this (replace C<foo> with the column/method of your choice):
+
+ use overload '""' => sub { shift->name}, fallback => 1;
+
+For more complex stringification, you can use an anonymous subroutine:
+
+ use overload '""' => sub { $_[0]->name . ", " .
+ $_[0]->address }, fallback => 1;
+
+=head3 Stringification Example
- use overload '""' => 'foo', fallback => 1;
+Suppose we have two tables: C<Product> and C<Category>. The table
+specifications are:
+
+ Product(id, Description, category)
+ Category(id, Description)
+
+C<category> is a foreign key into the Category table.
+
+If you have a Product object C<$obj> and write something like
+
+ print $obj->category
+
+things will not work as expected.
+
+To obtain, for example, the category description, you should add this
+method to the class defining the Category table:
+
+ use overload "" => sub {
+ my $self = shift;
+
+ return $self->Description;
+ }, fallback => 1;
=head2 Disconnecting cleanly
To create a MySQL database from an existing L<DBIx::Class> schema, convert the
schema to MySQL's dialect of SQL:
- sqlt --from DBIx::Class --to MySQL --DBIx::Class "MySchema.pm" > Schema1.sql
+ sqlt --from SQL::Translator::Parser::DBIx::Class
+ --to MySQL
+ --DBIx::Class "MySchema.pm" > Schema1.sql
And import using the mysql client:
Use C<sqlt> to transform your schema into an SQL script suitable for your
customer's database. E.g. for MySQL:
- sqlt --from DBIx::Class
+ sqlt --from SQL::Translator::Parser::DBIx::Class
--to MySQL
--DBIx::Class "MySchema.pm" > Schema1.mysql.sql
If you need to target databases from multiple vendors, just generate an SQL
script suitable for each. To support PostgreSQL too:
- sqlt --from DBIx::Class
+ sqlt --from SQL::Translator::DBIx::Class
--to PostgreSQL
--DBIx::Class "MySchema.pm" > Schema1.pgsql.sql
change functionality. Once the changes are made to your schema in DBIx::Class,
export the modified schema as before, taking care not to overwrite the original:
- sqlt --from DBIx::Class
+ sqlt --from SQL::Translator::DBIx::Class
--to MySQL
--DBIx::Class "Anything.pm" > Schema2.mysql.sql
=head2 Setting limit dialect for SQL::Abstract::Limit
-In some cases, SQL::Abstract::Limit cannot determine the dialect of the remote
-SQL-server by looking at the database-handle. This is a common problem when
-using the DBD::JDBC, since the DBD-driver only know that in has a Java-driver
-available, not which JDBC-driver the Java component has loaded.
-This specifically sets the limit_dialect to Microsoft SQL-server (Se more names
-in SQL::Abstract::Limit -documentation.
+In some cases, SQL::Abstract::Limit cannot determine the dialect of
+the remote SQL server by looking at the database handle. This is a
+common problem when using the DBD::JDBC, since the DBD-driver only
+know that in has a Java-driver available, not which JDBC driver the
+Java component has loaded. This specifically sets the limit_dialect
+to Microsoft SQL-server (See more names in SQL::Abstract::Limit
+-documentation.
__PACKAGE__->storage->sql_maker->limit_dialect('mssql');
-The JDBC-bridge is one way of getting access to a MSSQL-server from a platform
+The JDBC bridge is one way of getting access to a MSSQL server from a platform
that Microsoft doesn't deliver native client libraries for. (e.g. Linux)
-=head2 Setting quotes for the generated SQL.
+=head2 Setting quoting for the generated SQL.
-If the database contains columnames with spaces and/or reserved words, the
-SQL-query needs to be quoted. This is done using:
+If the database contains column names with spaces and/or reserved words, they
+need to be quoted in the SQL queries. This is done using:
__PACKAGE__->storage->sql_maker->quote_char([ qw/[ ]/] );
__PACKAGE__->storage->sql_maker->name_sep('.');
-The first sets the quotesymbols. If the quote i "symmetric" as " or '
+The first sets the quote characters. Either a pair of matching
+brackets, or a C<"> or C<'>:
__PACKAGE__->storage->sql_maker->quote_char('"');
-is enough. If the left quote differs form the right quote, the first
-notation should be used. name_sep needs to be set to allow the
-SQL generator to put the quotes the correct place.
+Check the documentation of your database for the correct quote
+characters to use. C<name_sep> needs to be set to allow the SQL
+generator to put the quotes the correct place.
=head2 Overloading methods
-L<DBIx::Class> uses the L<Class::C3> package, which provides for redispatch of
-method calls. You have to use calls to C<next::method> to overload methods.
-More information on using L<Class::C3> with L<DBIx::Class> can be found in
+L<DBIx::Class> uses the L<Class::C3> package, which provides for redispatch of
+method calls, useful for things like default values and triggers. You have to
+use calls to C<next::method> to overload methods. More information on using
+L<Class::C3> with L<DBIx::Class> can be found in
L<DBIx::Class::Manual::Component>.
=head3 Changing one field whenever another changes
}
Note that the hard work is done by the call to C<next::method>, which
-redispatches your call to store_column to the superclass(es).
+redispatches your call to store_column in the superclass(es).
=head3 Automatically creating related objects
-You might have a class C<Artist> which has many C<CD>s. Further, you
+You might have a class C<Artist> which has many C<CD>s. Further, if you
want to create a C<CD> object every time you insert an C<Artist> object.
You can accomplish this by overriding C<insert> on your objects:
=head2 Retrieving a row object's Schema
-It is possible to get a Schema object from a row object like so,
+It is possible to get a Schema object from a row object like so:
my $schema = $cd->result_source->schema;
- my $artist_rs = $schema->resultset('Artist');
- # for example
+ # use the schema as normal:
+ my $artist_rs = $schema->resultset('Artist');
This can be useful when you don't want to pass around a Schema object to every
method.
If you are not using autoincrementing primary keys, this will probably
not work, but then you already know the value of the last primary key anyway.
+=head2 Dynamic Sub-classing DBIx::Class proxy classes
+(AKA multi-class object inflation from one table)
+
+L<DBIx::Class> classes are proxy classes, therefore some different
+techniques need to be employed for more than basic subclassing. In
+this example we have a single user table that carries a boolean bit
+for admin. We would like like to give the admin users
+objects(L<DBIx::Class::Row>) the same methods as a regular user but
+also special admin only methods. It doesn't make sense to create two
+seperate proxy-class files for this. We would be copying all the user
+methods into the Admin class. There is a cleaner way to accomplish
+this.
+
+Overriding the C<inflate_result> method within the User proxy-class
+gives us the effect we want. This method is called by
+L<DBIx::Class::ResultSet> when inflating a result from storage. So we
+grab the object being returned, inspect the values we are looking for,
+bless it if it's an admin object, and then return it. See the example
+below:
+
+B<Schema Definition>
+
+ package DB::Schema;
+
+ use base qw/DBIx::Class::Schema/;
+
+ __PACKAGE__->load_classes(qw/User/);
+
+
+B<Proxy-Class definitions>
+
+ package DB::Schema::User;
+
+ use strict;
+ use warnings;
+ use base qw/DBIx::Class/;
+
+ ### Defined what our admin class is for ensure_class_loaded
+ my $admin_class = __PACKAGE__ . '::Admin';
+
+ __PACKAGE__->load_components(qw/Core/);
+
+ __PACKAGE__->table('users');
+
+ __PACKAGE__->add_columns(qw/user_id email password
+ firstname lastname active
+ admin/);
+
+ __PACKAGE__->set_primary_key('user_id');
+
+ sub inflate_result {
+ my $self = shift;
+ my $ret = $self->next::method(@_);
+ if( $ret->admin ) {### If this is an admin rebless for extra functions
+ $self->ensure_class_loaded( $admin_class );
+ bless $ret, $admin_class;
+ }
+ return $ret;
+ }
+
+ sub hello {
+ print "I am a regular user.\n";
+ return ;
+ }
+
+
+ package DB::Schema::User::Admin;
+
+ use strict;
+ use warnings;
+ use base qw/DB::Schema::User/;
+
+ sub hello
+ {
+ print "I am an admin.\n";
+ return;
+ }
+
+ sub do_admin_stuff
+ {
+ print "I am doing admin stuff\n";
+ return ;
+ }
+
+B<Test File> test.pl
+
+ use warnings;
+ use strict;
+ use DB::Schema;
+
+ my $user_data = { email => 'someguy@place.com',
+ password => 'pass1',
+ admin => 0 };
+
+ my $admin_data = { email => 'someadmin@adminplace.com',
+ password => 'pass2',
+ admin => 1 };
+
+ my $schema = DB::Schema->connection('dbi:Pg:dbname=test');
+
+ $schema->resultset('User')->create( $user_data );
+ $schema->resultset('User')->create( $admin_data );
+
+ ### Now we search for them
+ my $user = $schema->resultset('User')->single( $user_data );
+ my $admin = $schema->resultset('User')->single( $admin_data );
+
+ print ref $user, "\n";
+ print ref $admin, "\n";
+
+ print $user->password , "\n"; # pass1
+ print $admin->password , "\n";# pass2; inherited from User
+ print $user->hello , "\n";# I am a regular user.
+ print $admin->hello, "\n";# I am an admin.
+
+ ### The statement below will NOT print
+ print "I can do admin stuff\n" if $user->can('do_admin_stuff');
+ ### The statement below will print
+ print "I can do admin stuff\n" if $admin->can('do_admin_stuff');
+
+=head2 Skip object creation for faster results
+
+DBIx::Class is not built for speed, it's built for convenience and
+ease of use, but sometimes you just need to get the data, and skip the
+fancy objects.
+
+To do this simply use L<DBIx::Class::ResultClass::HashRefInflator>.
+
+ my $rs = $schema->resultset('CD');
+
+ $rs->result_class('DBIx::Class::ResultClass::HashRefInflator');
+
+ my $hash_ref = $rs->find(1);
+
+Wasn't that easy?
+
+=head2 Get raw data for blindingly fast results
+
+If the C<inflate_result> solution above is not fast enough for you, you
+can use a DBIx::Class to return values exactly as they come out of the
+data base with none of the convenience methods wrapped round them.
+
+This is used like so:-
+
+ my $cursor = $rs->cursor
+ while (my @vals = $cursor->next) {
+ # use $val[0..n] here
+ }
+
+You will need to map the array offsets to particular columns (you can
+use the I<select> attribute of C<search()> to force ordering).
+
+=head2 Want to know if find_or_create found or created a row?
+
+Just use C<find_or_new> instead, then check C<in_storage>:
+
+ my $obj = $rs->find_or_new({ blah => 'blarg' });
+ unless ($obj->in_storage) {
+ $obj->insert;
+ # do whatever else you wanted if it was a new row
+ }
+
+=head3 Wrapping/overloading a column accessor
+
+Problem: Say you have a table "Camera" and want to associate a description
+with each camera. For most cameras, you'll be able to generate the description from
+the other columns. However, in a few special cases you may want to associate a
+custom description with a camera.
+
+Solution:
+
+In your database schema, define a description field in the "Camera" table that
+can contain text and null values.
+
+In DBIC, we'll overload the column accessor to provide a sane default if no
+custom description is defined. The accessor will either return or generate the
+description, depending on whether the field is null or not.
+
+First, in your "Camera" schema class, define the description field as follows:
+
+ __PACKAGE__->add_columns(description => { accessor => '_description' });
+
+Next, we'll define the accessor-wrapper subroutine:
+
+ sub description {
+ my $self = shift;
+
+ # If there is an update to the column, we'll let the original accessor
+ # deal with it.
+ return $self->_description(@_) if @_;
+
+ # Fetch the column value.
+ my $description = $self->_description;
+
+ # If there's something in the description field, then just return that.
+ return $description if defined $description && length $descripton;
+
+ # Otherwise, generate a description.
+ return $self->generate_description;
+ }
+
=cut
projects / dbsrgits/DBIx-Class.git / blobdiff