So, you are bored with SQL, and want a native Perl interface for your
database? Or you've been doing this for a while with L<Class::DBI>,
and think there's a better way? You've come to the right place.
+
+=head1 THE DBIx::Class WAY
+
+Here are a few simple tips that will help you get your bearings
+with DBIx::Class.
+
+=head2 Tables become ResultSources
+
+DBIx::Class needs to know what your Table structure looks like. You do that
+by defining L<DBIx::Class::ResultSource>s. Each table get's a ResultSource,
+which defines the Columns it has, along with any Relationships it has to
+other tables. (And oh, so much more besides) The important thing to
+understand:
+
+ A ResultSource == Table
+
+(most of the time, but just bear with my simplification)
+
+=head2 It's all about the ResultSet
+
+So, we've got some ResultSources defined. Now, we want to actually use
+those definitions to help us translate the queries we need into
+handy perl objects!
+
+Let's say we defined a ResultSource for an "album" table with three
+columns: "albumid", "artist", and "title". Any time we want to query
+this table, we'll be creating a L<DBIx::Class::ResultSet> from it's
+ResultSource. For example, the results of:
+
+ SELECT albumid, artist, title FROM album;
+
+Would be retrieved by creating a ResultSet object from the album
+table's ResultSource, likely by using the "search" method.
+
+DBIx::Class doesn't limit you to creating only simple ResultSets --
+if you wanted to do something like:
+
+ SELECT title FROM album GROUP BY title;
+
+You could easily achieve it.
+
+The important thing to understand:
+
+ Any time you would reach for a SQL query in DBI, you are
+ creating a DBIx::Class::ResultSet.
+
+=head2 Search is like "prepare"
+
+DBIx::Class tends to wait until it absolutely must fetch information
+from the database. If you are returning a ResultSet, the query won't
+execute until you use a method that wants to access the data. (Such
+as "next", or "first")
+
+The important thing to understand:
+
+ Setting up a ResultSet does not execute the query; retrieving
+ the data does.
+
+=head1 SETTING UP DBIx::Class
+
Let's look at how you can set and use your first native L<DBIx::Class>
tree.
and automatically creates classes for all the tables in your database.
Here's a simple setup:
- package MyApp::DB;
- use DBIx::Class::Schema::Loader;
+ package My::Schema;
+ use base qw/DBIx::Class::Schema::Loader/;
- my $loader = DBIx::Class::Loader->new(
- dsn => 'dbi:SQLite:/home/me/myapp/my.db',
- namespace => 'MyApp::DB'
+ __PACKAGE__->load_from_connection(
+ connect_info = [ 'dbi:SQLite:/home/me/myapp/my.db' ]
);
1;
database, so to get started all you need to do is create an instance of your
class:
- my $schema = MyApp::DB->new();
+ my $schema = My::Schema->new();
To connect to your manually created Schema, you also need to provide the
connection details:
my $other_schema = My::Schema->connect( $dsn, $user, $password, $attrs );
-Note that L<DBIx::Class::Schema> does not cache connnections for you. If you
+Note that L<DBIx::Class::Schema> does not cache connections for you. If you
use multiple connections, you need to do this manually.
To execute some sql statements on every connect you can pass them to your schema after the connect:
my $album = $schema->resultset('Album')->find(14);
This will run a C<SELECT> with C<albumid = 14> in the C<WHERE> clause,
-and return an instance of C<MyApp::DB::Album> that represents this
+and return an instance of C<My::Schema::Album> that represents this
row. Once you have that row, you can access and update columns:
$album->title('Physical Graffiti');
=head2 Adding and removing rows
To create a new record in the database, you can use the C<create>
-method. It returns an instance of C<MyApp::DB::Album> that can be
+method. It returns an instance of C<My::Schema::Album> that can be
used to access the data in the new record:
my $new_album = $schema->resultset('Album')->create({
We also provide a handy shortcut for doing a C<LIKE> search:
# Find albums whose artist starts with 'Jimi'
- my $rs = MyApp::DB::Album->search_like({ artist => 'Jimi%' });
+ my $rs = $schema->resultset('Album')->search_like({ artist => 'Jimi%' });
Or you can provide your own C<WHERE> clause, like:
The search can also be modified by passing another hash with
attributes:
- my @albums = MyApp::DB::Album->search(
+ my @albums = My::Schema->resultset('Album')->search(
{ artist => 'Bob Marley' },
{ rows => 2, order_by => 'year DESC' }
);
=item * L<DBIx::Class::Manual::Cookbook>
-=item * L<DBIx::Class::Manual::FAQ>
-
=back
=cut
projects / dbsrgits/DBIx-Class.git / blobdiff