Commit | Line | Data |
9c82c181 |
1 | =head1 NAME |
2 | |
3b44ccc6 |
3 | DBIx::Class::Manual::Intro - Introduction to DBIx::Class |
9c82c181 |
4 | |
40dbc108 |
5 | =head1 INTRODUCTION |
076652e8 |
6 | |
40dbc108 |
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. |
076652e8 |
11 | |
40dbc108 |
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>. |
076652e8 |
15 | |
16 | =head2 Setting it up manually |
17 | |
18 | First, you'll need a base class. It should inherit from DBIx::Class |
19 | like this: |
20 | |
40dbc108 |
21 | package MyApp::DB; |
22 | use base qw/DBIx::Class/; |
076652e8 |
23 | |
40dbc108 |
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 |
076652e8 |
26 | have to use either L<DBIx::Class::Schema> or L<DBIx::Class::DB> We'll |
40dbc108 |
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 |
29 | connections. |
076652e8 |
30 | |
40dbc108 |
31 | __PACKAGE__->load_components(qw/Core DB/); |
076652e8 |
32 | |
33 | If you want serial/auto-incremental primary keys, you'll need to add |
40dbc108 |
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. |
076652e8 |
37 | |
40dbc108 |
38 | __PACKAGE__->load_components(qw/PK::Auto::SQLite Core DB/); |
076652e8 |
39 | |
40 | Once you've loaded the components, it's time to set up your connection: |
41 | |
40dbc108 |
42 | __PACKAGE__->connection('dbi:SQLite:/home/me/myapp/my.db'); |
076652e8 |
43 | |
40dbc108 |
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. |
076652e8 |
46 | |
47 | With that out of the way, we can define our first table class: |
48 | |
40dbc108 |
49 | package MyApp::DB::Album; |
50 | use base qw/MyApp::DB/; |
076652e8 |
51 | |
52 | Then we specify which table it uses, |
53 | |
40dbc108 |
54 | __PACKAGE__->table('album'); |
076652e8 |
55 | |
56 | and specify which columns it has. |
57 | |
40dbc108 |
58 | __PACKAGE__->add_columns(qw/albumID artist title label year/); |
076652e8 |
59 | |
40dbc108 |
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. |
076652e8 |
62 | |
63 | Also, you need to tell it which column is the primary key: |
64 | |
40dbc108 |
65 | __PACKAGE__->set_primary_key('albumID'); |
076652e8 |
66 | |
67 | If you have multiple primary keys, just pass a list instead. |
68 | |
40dbc108 |
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>. |
076652e8 |
72 | |
40dbc108 |
73 | =head2 Using L<DBIx::Class::Loader> |
076652e8 |
74 | |
40dbc108 |
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: |
076652e8 |
79 | |
40dbc108 |
80 | package MyApp::DB; |
81 | use DBIx::Class::Loader; |
82 | |
83 | my $loader = DBIx::Class::Loader->new( |
84 | dsn => 'dbi:SQLite:/home/me/myapp/my.db', |
85 | namespace => 'MyApp::DB' |
86 | ); |
076652e8 |
87 | |
40dbc108 |
88 | 1; |
076652e8 |
89 | |
40dbc108 |
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. |
076652e8 |
93 | |
40dbc108 |
94 | =head2 Basic usage |
076652e8 |
95 | |
40dbc108 |
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: |
076652e8 |
98 | |
40dbc108 |
99 | my $albumID = 14; |
100 | my $album = MyApp::DB::Album->find($albumID); |
076652e8 |
101 | |
40dbc108 |
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: |
076652e8 |
105 | |
40dbc108 |
106 | $album->title('Physical Graffiti'); |
107 | my $title = $album->title; # $title holds 'Physical Graffiti' |
076652e8 |
108 | |
40dbc108 |
109 | If you prefer, you can use the C<set_column> and C<get_column> |
110 | accessors instead: |
076652e8 |
111 | |
40dbc108 |
112 | $album->set_column('title', 'Presence'); |
113 | $title = $album->get_column('title'); |
076652e8 |
114 | |
40dbc108 |
115 | Just like with L<Class::DBI>, you do an C<update> to commit your |
116 | changes to the database: |
117 | |
118 | $album->update; |
076652e8 |
119 | |
120 | If needed, you can drop your local changes instead like this: |
121 | |
40dbc108 |
122 | $album->discard_changes if $album->is_changed; |
076652e8 |
123 | |
40dbc108 |
124 | As you can see, C<is_changed> allows you to check if there are local |
125 | changes to your object. |
076652e8 |
126 | |
40dbc108 |
127 | =head2 Adding and removing rows |
076652e8 |
128 | |
40dbc108 |
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 |
132 | in the new record. |
076652e8 |
133 | |
40dbc108 |
134 | my $new_album = MyApp::DB::Album->create({ |
135 | title => 'Wish You Were Here', |
136 | artist => 'Pink Floyd' |
137 | }); |
dfeba824 |
138 | |
139 | Now you can add data to the new record: |
140 | |
40dbc108 |
141 | $new_album->label('Capitol'); |
142 | $new_album->year('1975'); |
076652e8 |
143 | |
40dbc108 |
144 | Likewise, you can remove if from the database like this: |
076652e8 |
145 | |
40dbc108 |
146 | $new_album->delete; |
076652e8 |
147 | |
40dbc108 |
148 | or even without retrieving first. This operation takes the same kind |
149 | of arguments as a search. |
076652e8 |
150 | |
40dbc108 |
151 | MyApp::DB::Album->delete({ artist => 'Falco' }); |
076652e8 |
152 | |
40dbc108 |
153 | =head2 Finding your objects |
076652e8 |
154 | |
40dbc108 |
155 | L<DBIx::Class> provides a few different ways to retrieve data from |
156 | your database. The simplest looks something like this: |
076652e8 |
157 | |
40dbc108 |
158 | my $album = MyApp::DB::Album->search( artist => 'Santana' ); |
076652e8 |
159 | |
40dbc108 |
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 |
162 | context. |
076652e8 |
163 | |
40dbc108 |
164 | We also provide a handy shortcut for doing a C<LIKE> search: |
076652e8 |
165 | |
40dbc108 |
166 | my $album = MyApp::DB::Album->search_like( artist => 'Jimi%' ); |
076652e8 |
167 | |
40dbc108 |
168 | Or you can provide your own handmade C<WHERE> clause, like: |
076652e8 |
169 | |
40dbc108 |
170 | my $album = MyApp::DB::Album->search_literal( 'artist = ?', 'Peter Frampton' ); |
171 | |
172 | The preferred way to generate complex queries is to provide a |
173 | L<SQL::Abstract> construct to C<search>: |
174 | |
175 | my $album = MyApp::DB::Album->search({ |
176 | artist => { '!=', 'Janis Joplin' }, |
177 | year => { '<' => 1980 }, |
178 | id => [ 1, 14, 15, 65, 43 ] |
179 | }); |
180 | |
181 | For more examples of complex searches, see |
182 | L<DBIx::Class::Manual::Cookbook>. |
183 | |
184 | The search can also be modified by passing another hash with |
185 | attributes: |
186 | |
187 | my $album = MyApp::DB::Album->search( |
188 | { artist => 'Bob Marley' }, |
189 | { page => 1, rows => 2, order_by => 'year' } |
190 | ); |
191 | |
192 | For a complete overview of the available attributes, see |
193 | L<DBIx::Class::ResultSet/ATTRIBUTES>. |
076652e8 |
194 | |
40dbc108 |
195 | =head1 SEE ALSO |
076652e8 |
196 | |
40dbc108 |
197 | =over 4 |
076652e8 |
198 | |
40dbc108 |
199 | =item * L<DBIx::Class::Manual::Cookbook> |
076652e8 |
200 | |
40dbc108 |
201 | =item * L<DBIx::Class::Manual::FAQ> |
076652e8 |
202 | |
40dbc108 |
203 | =back |
076652e8 |
204 | |
205 | =cut |