Extra FAQ entry
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class / Manual / Intro.pod
1 =head1 NAME
2
3 DBIx::Class::Manual::Intro - Introduction to DBIx::Class
4
5 =head1 INTRODUCTION
6
7 You're bored with SQL, and want a native Perl interface for your database?  Or
8 you've been doing this for a while with L<Class::DBI>, and think there's a
9 better way?  You've come to the right place.
10
11 =head1 THE DBIx::Class WAY
12
13 Here are a few simple tips that will help you get your bearings with
14 DBIx::Class.
15
16 =head2 Tables become Result classes
17
18 DBIx::Class needs to know what your Table structure looks like.  You
19 do that by defining Result classes. Result classes are defined by
20 calling methods proxied to L<DBIx::Class::ResultSource>.  Each Result
21 class defines one Table, which defines the Columns it has, along with
22 any Relationships it has to other tables.  (And oh, so much more
23 besides) The important thing to understand:
24
25   A Result class == Table
26
27 (most of the time, but just bear with my simplification)
28
29 =head2 It's all about the ResultSet
30
31 So, we've got some ResultSources defined.  Now, we want to actually use those
32 definitions to help us translate the queries we need into handy perl objects!
33
34 Let's say we defined a ResultSource for an "album" table with three columns:
35 "albumid", "artist", and "title".  Any time we want to query this table, we'll
36 be creating a L<DBIx::Class::ResultSet> from its ResultSource.  For example, the
37 results of:
38
39   SELECT albumid, artist, title FROM album;
40
41 Would be retrieved by creating a ResultSet object from the album table's
42 ResultSource, likely by using the "search" method.
43
44 DBIx::Class doesn't limit you to creating only simple ResultSets -- if you
45 wanted to do something like:
46
47   SELECT title FROM album GROUP BY title;
48
49 You could easily achieve it.
50
51 The important thing to understand:
52
53   Any time you would reach for a SQL query in DBI, you are
54   creating a DBIx::Class::ResultSet.
55
56 =head2 Search is like "prepare"
57
58 DBIx::Class tends to wait until it absolutely must fetch information from the
59 database.  If you are returning a ResultSet, the query won't execute until you
60 use a method that wants to access the data. (Such as "next", or "first")
61
62 The important thing to understand:
63
64   Setting up a ResultSet does not execute the query; retrieving
65   the data does.
66
67 =head2 Search results are returned as Rows
68
69 Rows of the search from the database are blessed into
70 L<DBIx::Class::Row> objects.
71
72 =head1 SETTING UP DBIx::Class
73
74 Let's look at how you can set and use your first native L<DBIx::Class> tree.
75
76 First we'll see how you can set up your classes yourself.  If you want them to
77 be auto-discovered, just skip to the next section, which shows you how to use
78 L<DBIx::Class::Schema::Loader>.
79
80 =head2 Setting it up manually
81
82 First, you should create your base schema class, which inherits from
83 L<DBIx::Class::Schema>:
84
85   package My::Schema;
86   use base qw/DBIx::Class::Schema/;
87
88 In this class you load your result_source ("table", "model") classes, which we
89 will define later, using the load_namespaces() method:
90
91   # load My::Schema::Result::* and their resultset classes
92   __PACKAGE__->load_namespaces();
93
94 By default this loads all the Result (Row) classes in the
95 My::Schema::Result:: namespace, and also any resultset classes in the
96 My::Schema::ResultSet:: namespace (if missing, the resultsets are
97 defaulted to be DBIx::Class::ResultSet objects). You can change the
98 result and resultset namespaces by using options to the
99 L<DBIx::Class::Schema/load_namespaces> call.
100
101 It is also possible to do the same things manually by calling
102 C<load_classes> for the Row classes and defining in those classes any
103 required resultset classes.
104
105 Next, create each of the classes you want to load as specified above:
106
107   package My::Schema::Result::Album;
108   use base qw/DBIx::Class/;
109
110 Load any components required by each class with the load_components() method.
111 This should consist of "Core" plus any additional components you want to use.
112 For example, if you want to force columns to use UTF-8 encoding:
113
114   __PACKAGE__->load_components(qw/ ForceUTF8 Core /);
115
116 Set the table for your class:
117
118   __PACKAGE__->table('album');
119
120 Add columns to your class:
121
122   __PACKAGE__->add_columns(qw/ albumid artist title /);
123
124 Each column can also be set up with its own accessor, data_type and other pieces
125 of information that it may be useful to have -- just pass C<add_columns> a hash:
126
127   __PACKAGE__->add_columns(albumid =>
128                             { accessor  => 'album',
129                               data_type => 'integer',
130                               size      => 16,
131                               is_nullable => 0,
132                               is_auto_increment => 1,
133                               default_value => '',
134                             },
135                           artist =>
136                             { data_type => 'integer',
137                               size      => 16,
138                               is_nullable => 0,
139                               is_auto_increment => 0,
140                               default_value => '',
141                             },
142                           title  =>
143                             { data_type => 'varchar',
144                               size      => 256,
145                               is_nullable => 0,
146                               is_auto_increment => 0,
147                               default_value => '',
148                             }
149                          );
150
151 DBIx::Class doesn't directly use most of this data yet, but various related
152 modules such as L<DBIx::Class::WebForm> make use of it. Also it allows you to
153 create your database tables from your Schema, instead of the other way around.
154 See L<SQL::Translator> for details.
155
156 See L<DBIx::Class::ResultSource> for more details of the possible column
157 attributes.
158
159 Accessors are created for each column automatically, so My::Schema::Result::Album will
160 have albumid() (or album(), when using the accessor), artist() and title()
161 methods.
162
163 Define a primary key for your class:
164
165   __PACKAGE__->set_primary_key('albumid');
166
167 If you have a multi-column primary key, just pass a list instead:
168
169   __PACKAGE__->set_primary_key( qw/ albumid artistid / );
170
171 Define this class' relationships with other classes using either C<belongs_to>
172 to describe a column which contains an ID of another Table, or C<has_many> to
173 make a predefined accessor for fetching objects that contain this Table's
174 foreign key:
175
176   # in My::Schema::Result::Artist
177   __PACKAGE__->has_many('albums', 'My::Schema::Result::Album', 'artist');
178
179 See L<DBIx::Class::Relationship> for more information about the various types of
180 available relationships and how you can design your own.
181
182 =head2 Using L<DBIx::Class::Schema::Loader>
183
184 This is an external module, and not part of the L<DBIx::Class> distribution.
185 Like L<Class::DBI::Loader>, it inspects your database, and automatically creates
186 classes for all the tables in your database.  Here's a simple setup:
187
188   package My::Schema;
189   use base qw/DBIx::Class::Schema::Loader/;
190
191   __PACKAGE__->loader_options( relationships => 1 );
192
193   1;
194
195 The actual autoloading process will occur when you create a connected instance
196 of your schema below.
197
198 See the L<DBIx::Class::Schema::Loader> documentation for more information on its
199 many options.
200
201 =head2 Connecting
202
203 To connect to your Schema, you need to provide the connection details or a
204 database handle.
205
206 =head3 Via connection details
207
208 The arguments are the same as for L<DBI/connect>:
209
210   my $schema = My::Schema->connect('dbi:SQLite:/home/me/myapp/my.db');
211
212 You can create as many different schema instances as you need. So if you have a
213 second database you want to access:
214
215   my $other_schema = My::Schema->connect( $dsn, $user, $password, $attrs );
216
217 Note that L<DBIx::Class::Schema> does not cache connections for you. If you use
218 multiple connections, you need to do this manually.
219
220 To execute some sql statements on every connect you can add them as an option in
221 a special fifth argument to connect:
222
223   my $another_schema = My::Schema->connect(
224       $dsn,
225       $user,
226       $password,
227       $attrs,
228       { on_connect_do => \@on_connect_sql_statments }
229   );
230
231 See L<DBIx::Class::Schema::Storage::DBI/connect_info> for more information about
232 this and other special C<connect>-time options.
233
234 =head3 Via a database handle
235
236 The supplied coderef is expected to return a single connected database handle
237 (e.g. a L<DBI> C<$dbh>)
238
239   my $schema = My::Schema->connect (
240     sub { Some::DBH::Factory->connect },
241     \%extra_attrs,
242   );
243
244 =head2 Basic usage
245
246 Once you've defined the basic classes, either manually or using
247 L<DBIx::Class::Schema::Loader>, you can start interacting with your database.
248
249 To access your database using your $schema object, you can fetch a
250 L<DBIx::Class::Manual::Glossary/"ResultSet"> representing each of your tables by
251 calling the C<resultset> method.
252
253 The simplest way to get a record is by primary key:
254
255   my $album = $schema->resultset('Album')->find(14);
256
257 This will run a C<SELECT> with C<albumid = 14> in the C<WHERE> clause, and
258 return an instance of C<My::Schema::Result::Album> that represents this row.  Once you
259 have that row, you can access and update columns:
260
261   $album->title('Physical Graffiti');
262   my $title = $album->title; # $title holds 'Physical Graffiti'
263
264 If you prefer, you can use the C<set_column> and C<get_column> accessors
265 instead:
266
267   $album->set_column('title', 'Presence');
268   $title = $album->get_column('title');
269
270 Just like with L<Class::DBI>, you call C<update> to save your changes to the
271 database (by executing the actual C<UPDATE> statement):
272
273   $album->update;
274
275 If needed, you can throw away your local changes:
276
277   $album->discard_changes if $album->is_changed;
278
279 As you can see, C<is_changed> allows you to check if there are local changes to
280 your object.
281
282 =head2 Adding and removing rows
283
284 To create a new record in the database, you can use the C<create> method.  It
285 returns an instance of C<My::Schema::Result::Album> that can be used to access the data
286 in the new record:
287
288   my $new_album = $schema->resultset('Album')->create({
289     title  => 'Wish You Were Here',
290     artist => 'Pink Floyd'
291   });
292
293 Now you can add data to the new record:
294
295   $new_album->label('Capitol');
296   $new_album->year('1975');
297   $new_album->update;
298
299 Likewise, you can remove it from the database:
300
301   $new_album->delete;
302
303 You can also remove records without retrieving them first, by calling delete
304 directly on a ResultSet object.
305
306   # Delete all of Falco's albums
307   $schema->resultset('Album')->search({ artist => 'Falco' })->delete;
308
309 =head2 Finding your objects
310
311 L<DBIx::Class> provides a few different ways to retrieve data from your
312 database.  Here's one example:
313
314   # Find all of Santana's albums
315   my $rs = $schema->resultset('Album')->search({ artist => 'Santana' });
316
317 In scalar context, as above, C<search> returns a L<DBIx::Class::ResultSet>
318 object.  It can be used to peek at the first album returned by the database:
319
320   my $album = $rs->first;
321   print $album->title;
322
323 You can loop over the albums and update each one:
324
325   while (my $album = $rs->next) {
326     print $album->artist . ' - ' . $album->title;
327     $album->year(2001);
328     $album->update;
329   }
330
331 Or, you can update them all at once:
332
333   $rs->update({ year => 2001 });
334
335 In list context, the C<search> method returns all of the matching rows:
336
337   # Fetch immediately all of Carlos Santana's albums
338   my @albums = $schema->resultset('Album')->search(
339     { artist => 'Carlos Santana' }
340   );
341   foreach my $album (@albums) {
342     print $album->artist . ' - ' . $album->title;
343   }
344
345 We also provide a handy shortcut for doing a C<LIKE> search:
346
347   # Find albums whose artist starts with 'Jimi'
348   my $rs = $schema->resultset('Album')->search_like({ artist => 'Jimi%' });
349
350 Or you can provide your own C<WHERE> clause:
351
352   # Find Peter Frampton albums from the year 1986
353   my $where = 'artist = ? AND year = ?';
354   my @bind  = ( 'Peter Frampton', 1986 );
355   my $rs    = $schema->resultset('Album')->search_literal( $where, @bind );
356
357 The preferred way to generate complex queries is to provide a L<SQL::Abstract>
358 construct to C<search>:
359
360   my $rs = $schema->resultset('Album')->search({
361     artist  => { '!=', 'Janis Joplin' },
362     year    => { '<' => 1980 },
363     albumid => { '-in' => [ 1, 14, 15, 65, 43 ] }
364   });
365
366 This results in something like the following C<WHERE> clause:
367
368   WHERE artist != 'Janis Joplin'
369     AND year < 1980
370     AND albumid IN (1, 14, 15, 65, 43)
371
372 For more examples of complex queries, see L<DBIx::Class::Manual::Cookbook>.
373
374 The search can also be modified by passing another hash with
375 attributes:
376
377   my @albums = My::Schema->resultset('Album')->search(
378     { artist => 'Bob Marley' },
379     { rows => 2, order_by => 'year DESC' }
380   );
381
382 C<@albums> then holds the two most recent Bob Marley albums.
383
384 For more information on what you can do with a L<DBIx::Class::ResultSet>, see
385 L<DBIx::Class::ResultSet/METHODS>.
386
387 For a complete overview of the available attributes, see
388 L<DBIx::Class::ResultSet/ATTRIBUTES>.
389
390 =head1 NOTES
391
392 =head2 Problems on RHEL5/CentOS5
393
394 There used to be an issue with the system perl on Red Hat Enterprise
395 Linux 5, some versions of Fedora and derived systems. Further
396 information on this can be found in L<DBIx::Class::Manual::Troubleshooting>
397
398 =head1 SEE ALSO
399
400 =over 4
401
402 =item * L<DBIx::Class::Manual::Cookbook>
403
404 =back
405
406 =cut