makes search_related on extended rels without the optimized version work. involves...
[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::Core/;
109
110 Load any additional components you may need with the load_components() method,
111 and provide component configuration if required. For example, if you want
112 automatic row ordering:
113
114   __PACKAGE__->load_components(qw/ Ordered /);
115   __PACKAGE__->position_column('rank');
116
117 Ordered will refer to a field called 'position' unless otherwise directed.  Here you are defining
118 the ordering field to be named 'rank'.  (NOTE: Insert errors may occur if you use the Ordered 
119 component, but have not defined a position column or have a 'position' field in your row.)
120
121 Set the table for your class:
122
123   __PACKAGE__->table('album');
124
125 Add columns to your class:
126
127   __PACKAGE__->add_columns(qw/ albumid artist title rank /);
128
129 Each column can also be set up with its own accessor, data_type and other pieces
130 of information that it may be useful to have -- just pass C<add_columns> a hash:
131
132   __PACKAGE__->add_columns(albumid =>
133                             { accessor  => 'album',
134                               data_type => 'integer',
135                               size      => 16,
136                               is_nullable => 0,
137                               is_auto_increment => 1,
138                               default_value => '',
139                             },
140                           artist =>
141                             { data_type => 'integer',
142                               size      => 16,
143                               is_nullable => 0,
144                               is_auto_increment => 0,
145                               default_value => '',
146                             },
147                           title  =>
148                             { data_type => 'varchar',
149                               size      => 256,
150                               is_nullable => 0,
151                               is_auto_increment => 0,
152                               default_value => '',
153                             },
154                           rank =>
155                             { data_type => 'integer',
156                               size      => 16,
157                               is_nullable => 0,
158                               is_auto_increment => 0,
159                               default_value => '',
160                             }
161                          );
162
163 DBIx::Class doesn't directly use most of this data yet, but various related
164 modules such as L<DBIx::Class::WebForm> make use of it. Also it allows you to
165 create your database tables from your Schema, instead of the other way around.
166 See L<DBIx::Class::Schema/deploy> for details.
167
168 See L<DBIx::Class::ResultSource> for more details of the possible column
169 attributes.
170
171 Accessors are created for each column automatically, so My::Schema::Result::Album will
172 have albumid() (or album(), when using the accessor), artist() and title()
173 methods.
174
175 Define a primary key for your class:
176
177   __PACKAGE__->set_primary_key('albumid');
178
179 If you have a multi-column primary key, just pass a list instead:
180
181   __PACKAGE__->set_primary_key( qw/ albumid artistid / );
182
183 Define this class' relationships with other classes using either C<belongs_to>
184 to describe a column which contains an ID of another Table, or C<has_many> to
185 make a predefined accessor for fetching objects that contain this Table's
186 foreign key:
187
188   # in My::Schema::Result::Artist
189   __PACKAGE__->has_many('albums', 'My::Schema::Result::Album', 'artist');
190
191 See L<DBIx::Class::Relationship> for more information about the various types of
192 available relationships and how you can design your own.
193
194 =head2 Using L<DBIx::Class::Schema::Loader>
195
196 This is an external module, and not part of the L<DBIx::Class> distribution.
197 It inspects your database, and automatically creates classes for all the tables
198 in your database.
199
200 The simplest way to use it is via the L<dbicdump> script from the
201 L<DBIx::Class::Schema::Loader> distribution. For example:
202
203     $ dbicdump -o dump_directory=./lib MyApp::Schema dbi:mysql:mydb user pass
204
205 If you have a mixed-case database, use the C<preserve_case> option, e.g.:
206
207     $ dbicdump -o dump_directory=./lib -o preserve_case=1 MyApp::Schema \
208         dbi:mysql:mydb user pass
209
210 If you are using L<Catalyst>, then you can use the helper that comes with
211 L<Catalyst::Model::DBIC::Schema>:
212
213     $ script/myapp_create.pl model MyDB DBIC::Schema MyDB::Schema \
214         create=static moniker_map='{ foo => "FOO" }' dbi:SQLite:./myapp.db \
215         on_connect_do='PRAGMA foreign_keys=ON' quote_char='"'
216
217 See L<Catalyst::Helper::Model::DBIC::Schema> for more information on this
218 helper.
219
220 See the L<DBIx::Class::Schema::Loader> and L<DBIx::Class::Schema::Loader::Base>
221 documentation for more information on the many loader options.
222
223 =head2 Connecting
224
225 To connect to your Schema, you need to provide the connection details or a
226 database handle.
227
228 =head3 Via connection details
229
230 The arguments are the same as for L<DBI/connect>:
231
232   my $schema = My::Schema->connect('dbi:SQLite:/home/me/myapp/my.db');
233
234 You can create as many different schema instances as you need. So if you have a
235 second database you want to access:
236
237   my $other_schema = My::Schema->connect( $dsn, $user, $password, $attrs );
238
239 Note that L<DBIx::Class::Schema> does not cache connections for you. If you use
240 multiple connections, you need to do this manually.
241
242 To execute some SQL statements on every connect you can add them as an option in
243 a special fifth argument to connect:
244
245   my $another_schema = My::Schema->connect(
246       $dsn,
247       $user,
248       $password,
249       $attrs,
250       { on_connect_do => \@on_connect_sql_statments }
251   );
252
253 See L<DBIx::Class::Storage::DBI/connect_info> for more information about
254 this and other special C<connect>-time options.
255
256 =head3 Via a database handle
257
258 The supplied coderef is expected to return a single connected database handle
259 (e.g. a L<DBI> C<$dbh>)
260
261   my $schema = My::Schema->connect (
262     sub { Some::DBH::Factory->connect },
263     \%extra_attrs,
264   );
265
266 =head2 Basic usage
267
268 Once you've defined the basic classes, either manually or using
269 L<DBIx::Class::Schema::Loader>, you can start interacting with your database.
270
271 To access your database using your $schema object, you can fetch a
272 L<DBIx::Class::Manual::Glossary/"ResultSet"> representing each of your tables by
273 calling the C<resultset> method.
274
275 The simplest way to get a record is by primary key:
276
277   my $album = $schema->resultset('Album')->find(14);
278
279 This will run a C<SELECT> with C<albumid = 14> in the C<WHERE> clause, and
280 return an instance of C<My::Schema::Result::Album> that represents this row.  Once you
281 have that row, you can access and update columns:
282
283   $album->title('Physical Graffiti');
284   my $title = $album->title; # $title holds 'Physical Graffiti'
285
286 If you prefer, you can use the C<set_column> and C<get_column> accessors
287 instead:
288
289   $album->set_column('title', 'Presence');
290   $title = $album->get_column('title');
291
292 Just like with L<Class::DBI>, you call C<update> to save your changes to the
293 database (by executing the actual C<UPDATE> statement):
294
295   $album->update;
296
297 If needed, you can throw away your local changes:
298
299   $album->discard_changes if $album->is_changed;
300
301 As you can see, C<is_changed> allows you to check if there are local changes to
302 your object.
303
304 =head2 Adding and removing rows
305
306 To create a new record in the database, you can use the C<create> method.  It
307 returns an instance of C<My::Schema::Result::Album> that can be used to access the data
308 in the new record:
309
310   my $new_album = $schema->resultset('Album')->create({
311     title  => 'Wish You Were Here',
312     artist => 'Pink Floyd'
313   });
314
315 Now you can add data to the new record:
316
317   $new_album->label('Capitol');
318   $new_album->year('1975');
319   $new_album->update;
320
321 Likewise, you can remove it from the database:
322
323   $new_album->delete;
324
325 You can also remove records without retrieving them first, by calling delete
326 directly on a ResultSet object.
327
328   # Delete all of Falco's albums
329   $schema->resultset('Album')->search({ artist => 'Falco' })->delete;
330
331 =head2 Finding your objects
332
333 L<DBIx::Class> provides a few different ways to retrieve data from your
334 database.  Here's one example:
335
336   # Find all of Santana's albums
337   my $rs = $schema->resultset('Album')->search({ artist => 'Santana' });
338
339 In scalar context, as above, C<search> returns a L<DBIx::Class::ResultSet>
340 object.  It can be used to peek at the first album returned by the database:
341
342   my $album = $rs->first;
343   print $album->title;
344
345 You can loop over the albums and update each one:
346
347   while (my $album = $rs->next) {
348     print $album->artist . ' - ' . $album->title;
349     $album->year(2001);
350     $album->update;
351   }
352
353 Or, you can update them all at once:
354
355   $rs->update({ year => 2001 });
356
357 In list context, the C<search> method returns all of the matching rows:
358
359   # Fetch immediately all of Carlos Santana's albums
360   my @albums = $schema->resultset('Album')->search(
361     { artist => 'Carlos Santana' }
362   );
363   foreach my $album (@albums) {
364     print $album->artist . ' - ' . $album->title;
365   }
366
367 We also provide a handy shortcut for doing a C<LIKE> search:
368
369   # Find albums whose artist starts with 'Jimi'
370   my $rs = $schema->resultset('Album')->search_like({ artist => 'Jimi%' });
371
372 Or you can provide your own C<WHERE> clause:
373
374   # Find Peter Frampton albums from the year 1986
375   my $where = 'artist = ? AND year = ?';
376   my @bind  = ( 'Peter Frampton', 1986 );
377   my $rs    = $schema->resultset('Album')->search_literal( $where, @bind );
378
379 The preferred way to generate complex queries is to provide a L<SQL::Abstract>
380 construct to C<search>:
381
382   my $rs = $schema->resultset('Album')->search({
383     artist  => { '!=', 'Janis Joplin' },
384     year    => { '<' => 1980 },
385     albumid => { '-in' => [ 1, 14, 15, 65, 43 ] }
386   });
387
388 This results in something like the following C<WHERE> clause:
389
390   WHERE artist != 'Janis Joplin'
391     AND year < 1980
392     AND albumid IN (1, 14, 15, 65, 43)
393
394 For more examples of complex queries, see L<DBIx::Class::Manual::Cookbook>.
395
396 The search can also be modified by passing another hash with
397 attributes:
398
399   my @albums = My::Schema->resultset('Album')->search(
400     { artist => 'Bob Marley' },
401     { rows => 2, order_by => 'year DESC' }
402   );
403
404 C<@albums> then holds the two most recent Bob Marley albums.
405
406 For more information on what you can do with a L<DBIx::Class::ResultSet>, see
407 L<DBIx::Class::ResultSet/METHODS>.
408
409 For a complete overview of the available attributes, see
410 L<DBIx::Class::ResultSet/ATTRIBUTES>.
411
412 =head1 NOTES
413
414 =head2 The Significance and Importance of Primary Keys
415
416 The concept of a L<primary key|DBIx::Class::ResultSource/set_primary_key> in
417 DBIx::Class warrants special discussion. The formal definition (which somewhat
418 resembles that of a classic RDBMS) is I<a unique constraint that is least
419 likely to change after initial row creation>. However this is where the
420 similarity ends. Any time you call a CRUD operation on a row (e.g.
421 L<delete|DBIx::Class::Row/delete>,
422 L<update|DBIx::Class::Row/update>,
423 L<discard_changes|DBIx::Class::Row/discard_changes>,
424 etc.) DBIx::Class will use the values of of the
425 L<primary key|DBIx::Class::ResultSource/set_primary_key> columns to populate
426 the C<WHERE> clause necessary to accomplish the operation. This is why it is
427 important to declare a L<primary key|DBIx::Class::ResultSource/set_primary_key>
428 on all your result sources B<even if the underlying RDBMS does not have one>.
429 In a pinch one can always declare each row identifiable by all its columns:
430
431  __PACKAGE__->set_primary_keys (__PACKAGE__->columns);
432
433 Note that DBIx::Class is smart enough to store a copy of the PK values before
434 any row-object changes take place, so even if you change the values of PK
435 columns the C<WHERE> clause will remain correct.
436
437 If you elect not to declare a C<primary key>, DBIx::Class will behave correctly
438 by throwing exceptions on any row operation that relies on unique identifiable
439 rows. If you inherited datasets with multiple identical rows in them, you can
440 still operate with such sets provided you only utilize
441 L<DBIx::Class::ResultSet> CRUD methods:
442 L<search|DBIx::Class::ResultSet/search>,
443 L<update|DBIx::Class::ResultSet/update>,
444 L<delete|DBIx::Class::ResultSet/delete>
445
446 For example, the following would not work (assuming C<People> does not have
447 a declared PK):
448
449  my $row = $schema->resultset('People')
450                    ->search({ last_name => 'Dantes' })
451                     ->next;
452  $row->update({ children => 2 }); # <-- exception thrown because $row isn't
453                                   # necessarily unique
454
455 So instead the following should be done:
456
457  $schema->resultset('People')
458          ->search({ last_name => 'Dantes' })
459           ->update({ children => 2 }); # <-- update's ALL Dantes to have children of 2
460
461 =head2 Problems on RHEL5/CentOS5
462
463 There used to be an issue with the system perl on Red Hat Enterprise
464 Linux 5, some versions of Fedora and derived systems. Further
465 information on this can be found in L<DBIx::Class::Manual::Troubleshooting>
466
467 =head1 SEE ALSO
468
469 =over 4
470
471 =item * L<DBIx::Class::Manual::Cookbook>
472
473 =back
474
475 =cut