3 DBIx::Class::Manual::Intro - Introduction to DBIx::Class
7 So, you are bored with SQL, and want a native Perl interface for your
8 database? Or you've been doing this for a while with L<Class::DBI>,
9 and think there's a better way? You've come to the right place. Let's
10 look at how you can set and use your first native L<DBIx::Class> tree.
12 First we'll see how you can set up your classes yourself. If you want
13 them to be auto-discovered, just skip to the next section, which shows
14 you how to use L<DBIx::Class::Loader>.
16 =head2 Setting it up manually
18 First, you'll need a base class. It should inherit from DBIx::Class
22 use base qw/DBIx::Class/;
24 You will also want to load some of L<DBIx::Class>'s components.
25 L<DBIx::Class::Core> provides a good basic set. In addition you'll
26 have to use either L<DBIx::Class::Schema> or L<DBIx::Class::DB> We'll
27 use C<DB> in this introduction, since it involves less magic.
28 L<Schema> is mostly useful if you want to use multiple database
31 __PACKAGE__->load_components(qw/Core DB/);
33 If you want serial/auto-incremental primary keys, you'll need to add
34 the apropriate component for your db as well, for example. The
35 L<DBIx::Class::PK::Auto> modules help L<DBIx::Class> keep up with
36 newly generated keys in auto increment database fields.
38 __PACKAGE__->load_components(qw/PK::Auto::SQLite Core DB/);
40 Once you've loaded the components, it's time to set up your connection:
42 __PACKAGE__->connection('dbi:SQLite:/home/me/myapp/my.db');
44 This method is similar to the normal L<DBI>, and can take username,
45 password, and L<DBI> attribute hash as well as the DSN.
47 With that out of the way, we can define our first table class:
49 package MyApp::DB::Album;
50 use base qw/MyApp::DB/;
52 Then we specify which table it uses,
54 __PACKAGE__->table('album');
56 and specify which columns it has.
58 __PACKAGE__->add_columns(qw/albumID artist title label year/);
60 This will automatically create accessors for each of the columns, so
61 that you can read/update the values in rows you've retrieved.
63 Also, you need to tell it which column is the primary key:
65 __PACKAGE__->set_primary_key('albumID');
67 If you have multiple primary keys, just pass a list instead.
69 That's pretty much all you need for a basic setup. If you have more
70 advanced needs like using more than one database connection for the
71 same class, see L<DBIx::Class::Schema>.
73 =head2 Using L<DBIx::Class::Loader>
75 This is an additional class, and not part of the L<DBIx::Class>
76 distribution. Like L<Class::DBI::Loader>, it inspects your database,
77 and automatically creates classes for all the tables in your
78 database. Here's a simple setup:
81 use DBIx::Class::Loader;
83 my $loader = DBIx::Class::Loader->new(
84 dsn => 'dbi:SQLite:/home/me/myapp/my.db',
85 namespace => 'MyApp::DB'
90 This should be equivalent to the manual in the section above.
91 L<DBIx::Class::Loader> takes lots of other options. For more
92 information, consult its documentation.
96 Once you've defined the basic classes, you can start interacting with
97 your database. The simplest way to get a column is by primary key:
100 my $album = MyApp::DB::Album->find($albumID);
102 This will run a select with C<albumID = 14> in the C<WHERE> clause,
103 and return an instance of C<MyApp::DB::Artist> that represents this
104 row. Once you have that row, you can access and update columns:
106 $album->title('Physical Graffiti');
107 my $title = $album->title; # $title holds 'Physical Graffiti'
109 If you prefer, you can use the C<set_column> and C<get_column>
112 $album->set_column('title', 'Presence');
113 $title = $album->get_column('title');
115 Just like with L<Class::DBI>, you do an C<update> to commit your
116 changes to the database:
120 If needed, you can drop your local changes instead like this:
122 $album->discard_changes if $album->is_changed;
124 As you can see, C<is_changed> allows you to check if there are local
125 changes to your object.
127 =head2 Adding and removing rows
129 To create a new record in the database, you can use the C<create>
130 method from L<DBIx::Class::Row>. It returns a
131 L<DBIx::Class::ResultSet> object that can be used to access the data
134 my $new_album = MyApp::DB::Album->create({
135 title => 'Wish You Were Here',
136 artist => 'Pink Floyd'
139 Now you can add data to the new record:
141 $new_album->label('Capitol');
142 $new_album->year('1975');
144 Likewise, you can remove if from the database like this:
148 or even without retrieving first. This operation takes the same kind
149 of arguments as a search.
151 MyApp::DB::Album->delete({ artist => 'Falco' });
153 =head2 Finding your objects
155 L<DBIx::Class> provides a few different ways to retrieve data from
156 your database. The simplest looks something like this:
158 my $album = MyApp::DB::Album->search( artist => 'Santana' );
160 Note that all the search methods return a L<DBIx::Class::ResultSet>
161 object in scalar context or a list containing all the records in list
164 We also provide a handy shortcut for doing a C<LIKE> search:
166 my $album = MyApp::DB::Album->search_like( artist => 'Jimi%' );
168 Or you can provide your own handmade C<WHERE> clause, like:
170 my $album = MyApp::DB::Album->search_literal( 'artist = ?', 'Peter Frampton' );
172 The preferred way to generate complex queries is to provide a
173 L<SQL::Abstract> construct to C<search>:
175 my $album = MyApp::DB::Album->search({
176 artist => { '!=', 'Janis Joplin' },
177 year => { '<' => 1980 },
178 id => [ 1, 14, 15, 65, 43 ]
181 For more examples of complex searches, see
182 L<DBIx::Class::Manual::Cookbook>.
184 The search can also be modified by passing another hash with
187 my $album = MyApp::DB::Album->search(
188 { artist => 'Bob Marley' },
189 { page => 1, rows => 2, order_by => 'year' }
192 For a complete overview of the available attributes, see
193 L<DBIx::Class::ResultSet/ATTRIBUTES>.
199 =item * L<DBIx::Class::Manual::Cookbook>
201 =item * L<DBIx::Class::Manual::FAQ>