Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
DBIx::Class(3)	      User Contributed Perl Documentation	DBIx::Class(3)

       DBIx::Class - Extensible	and flexible object <->	relational mapper.

       See DBIx::Class::Manual::DocMap for an overview of the exhaustive
       documentation.  To get the most out of DBIx::Class with the least
       confusion it is strongly	recommended to read (at	the very least)	the
       Manuals in the order presented there.

       Due to the sheer	size of	its problem domain, DBIx::Class	is a
       relatively complex framework. After you start using DBIx::Class
       questions will inevitably arise.	If you are stuck with a	problem	or
       have doubts about a particular approach do not hesitate to contact us
       via any of the following	options	(the list is sorted by "fastest
       response	time"):

       o   RT Bug Tracker:

       o   Email: <>

       o   Twitter:

       For the very impatient: DBIx::Class::Manual::QuickStart

       This code in the	next step can be generated automatically from an
       existing	database, see dbicdump from the	distribution

   Schema classes preparation
       Create a	schema class called MyApp/

	 package MyApp::Schema;
	 use base qw/DBIx::Class::Schema/;



       Create a	result class to	represent artists, who have many CDs, in

       See DBIx::Class::ResultSource for docs on defining result classes.

	 package MyApp::Schema::Result::Artist;
	 use base qw/DBIx::Class::Core/;

	 __PACKAGE__->add_columns(qw/ artistid name /);
	 __PACKAGE__->has_many(cds => 'MyApp::Schema::Result::CD', 'artistid');


       A result	class to represent a CD, which belongs to an artist, in

	 package MyApp::Schema::Result::CD;
	 use base qw/DBIx::Class::Core/;

	 __PACKAGE__->add_columns(qw/ cdid artistid title year /);
	 __PACKAGE__->belongs_to(artist	=> 'MyApp::Schema::Result::Artist', 'artistid');


   API usage
       Then you	can use	these classes in your application's code:

	 # Connect to your database.
	 use MyApp::Schema;
	 my $schema = MyApp::Schema->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.
	 # $schema->resultset returns a	DBIx::Class::ResultSet
	 my @all_artists = $schema->resultset('Artist')->all;
	 my $all_artists_rs = $schema->resultset('Artist');

	 # Output all artists names
	 # $artist here	is a DBIx::Class::Row, which has accessors
	 # for all its columns.	Rows are also subclasses of your Result	class.
	 foreach $artist (@all_artists)	{
	   print $artist->name,	"\n";

	 # Create a result set to search for artists.
	 # This	does not query the DB.
	 my $johns_rs =	$schema->resultset('Artist')->search(
	   # Build your	WHERE using an SQL::Abstract::Classic-compatible structure:
	   { name => { like => 'John%' } }

	 # Execute a joined query to get the cds.
	 my @all_john_cds = $johns_rs->search_related('cds')->all;

	 # Fetch the next available row.
	 my $first_john	= $johns_rs->next;

	 # Specify ORDER BY on the query.
	 my $first_john_cds_by_title_rs	= $first_john->cds(
	   { order_by => 'title' }

	 # Create a result set that will fetch the artist data
	 # at the same time as it fetches CDs, using only one query.
	 my $millennium_cds_rs = $schema->resultset('CD')->search(
	   { year => 2000 },
	   { prefetch => 'artist' }

	 my $cd	= $millennium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
	 my $cd_artist_name = $cd->artist->name; # Already has the data	so no 2nd query

	 # new() makes a Result	object but doesn't insert it into the DB.
	 # create() is the same	as new() then insert().
	 my $new_cd = $schema->resultset('CD')->new({ title => 'Spoon' });
	 $new_cd->insert; # Auto-increment primary key filled in after INSERT

	 $schema->txn_do(sub { $new_cd->update }); # Runs the update in	a transaction

	 # change the year of all the millennium CDs at	once
	 $millennium_cds_rs->update({ year => 2002 });

       This is an SQL to OO mapper with	an object API inspired by Class::DBI
       (with a compatibility layer as a	springboard for	porting) and a
       resultset API that allows abstract encapsulation	of database
       operations. It aims to make representing	queries	in your	code as	perl-
       ish as possible while still providing access to as many of the
       capabilities of the database as possible, including retrieving related
       records from multiple tables in a single	query, "JOIN", "LEFT JOIN",
       "COUNT",	"DISTINCT", "GROUP BY",	"ORDER BY" and "HAVING"	support.

       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	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

       This project is still under rapid development, so large new features
       may be marked experimental - such APIs are still	usable but may have
       edge bugs.  Failing test	cases are always welcome and point releases
       are put out rapidly as bugs are found and fixed.

       We do our best to maintain full backwards compatibility for published
       APIs, since DBIx::Class is used in production in	many organisations,
       and even	backwards incompatible changes to non-published	APIs will be
       fixed if	they're	reported and doing so doesn't cost the codebase

       The test	suite is quite substantial, and	several	developer releases are
       generally made to CPAN before the branch	for the	next release is	merged
       back to trunk for a major release.

       Contributions are always	welcome, in all	usable forms (we especially
       welcome documentation improvements). The	delivery methods include git-
       or unified-diff formatted patches, GitHub pull requests,	or plain bug
       reports either via RT or	the Mailing list. Do not hesitate to get in
       touch with any further questions	you may	have.

       This project is maintained in a git repository. The code	and related
       tools are accessible at the following locations:

       o   Current git repository: <>

       o   Travis-CI log:

       Even though a large portion of the source appears to be written by just
       a handful of people, this library continues to remain a collaborative
       effort -	perhaps	one of the most	successful such	projects on CPAN
       <>.  It is important to remember that ideas do not
       always result in	a direct code contribution, but	deserve
       acknowledgement just the	same. Time and time again the seemingly	most
       insignificant questions and suggestions have been shown to catalyze
       monumental improvements in consistency, accuracy	and performance.

       The canonical source of authors and their details is the	AUTHORS	file
       at the root of this distribution	(or repository). The canonical source
       of per-line authorship is the git repository history itself.

       Copyright (c) 2005 by mst, castaway, ribasushi, and other DBIx::Class
       "AUTHORS" as listed above and in	AUTHORS.

       This library is free software and may be	distributed under the same
       terms as	perl5 itself. See LICENSE for the complete licensing terms.

perl v5.32.1			  2020-06-16			DBIx::Class(3)


Want to link to this manual page? Use this URL:

home | help