Clarification cascade_* attribute defaults documentation
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class / Manual / Example.pod
1 =head1 NAME
2
3 DBIx::Class::Manual::Example - Simple CD database example
4
5 =head1 DESCRIPTION
6
7 This tutorial will guide you through the process of setting up and
8 testing a very basic CD database using SQLite, with DBIx::Class::Schema
9 as the database frontend.
10
11 The database consists of the following:
12
13   table 'artist' with columns:  artistid, name
14   table 'cd'     with columns:  cdid, artist, title
15   table 'track'  with columns:  trackid, cd, title
16
17
18 And these rules exists:
19
20   one artist can have many cds
21   one cd belongs to one artist
22   one cd can have many tracks
23   one track belongs to one cd
24
25
26 =head2 Installation
27
28 Install DBIx::Class via CPAN should be sufficient.
29
30 =head3 Create the database/tables
31
32 First make and change the directory:
33
34   mkdir app
35   cd app
36   mkdir db
37   cd db
38
39 This example uses SQLite which is a dependency of DBIx::Class, so you
40 shouldn't have to install extra software.
41
42 Save the following into a example.sql in the directory db
43
44   CREATE TABLE artist (
45     artistid INTEGER PRIMARY KEY,
46     name TEXT NOT NULL
47   );
48
49   CREATE TABLE cd (
50     cdid INTEGER PRIMARY KEY,
51     artist INTEGER NOT NULL REFERENCES artist(artistid),
52     title TEXT NOT NULL
53   );
54
55   CREATE TABLE track (
56     trackid INTEGER PRIMARY KEY,
57     cd INTEGER NOT NULL REFERENCES cd(cdid),
58     title TEXT NOT NULL
59   );
60
61 and create the SQLite database file:
62
63   sqlite3 example.db < example.sql
64
65 =head3 Set up DBIx::Class::Schema
66
67 Change directory back from db to the directory app:
68
69   cd ../
70
71 Now create some more directories:
72
73   mkdir MyDatabase
74   mkdir MyDatabase/Main
75   mkdir MyDatabase/Main/Result
76   mkdir MyDatabase/Main/ResultSet
77
78 Then, create the following DBIx::Class::Schema classes:
79
80 MyDatabase/Main.pm:
81
82   package MyDatabase::Main;
83   use base qw/DBIx::Class::Schema/;
84   __PACKAGE__->load_namespaces;
85
86   1;
87
88
89 MyDatabase/Main/Result/Artist.pm:
90
91   package MyDatabase::Main::Result::Artist;
92   use base qw/DBIx::Class::Core/;
93   __PACKAGE__->table('artist');
94   __PACKAGE__->add_columns(qw/ artistid name /);
95   __PACKAGE__->set_primary_key('artistid');
96   __PACKAGE__->has_many('cds' => 'MyDatabase::Main::Result::Cd');
97
98   1;
99
100
101 MyDatabase/Main/Result/Cd.pm:
102
103   package MyDatabase::Main::Result::Cd;
104   use base qw/DBIx::Class::Core/;
105   __PACKAGE__->load_components(qw/InflateColumn::DateTime/);
106   __PACKAGE__->table('cd');
107   __PACKAGE__->add_columns(qw/ cdid artist title/);
108   __PACKAGE__->set_primary_key('cdid');
109   __PACKAGE__->belongs_to('artist' => 'MyDatabase::Main::Result::Artist');
110   __PACKAGE__->has_many('tracks' => 'MyDatabase::Main::Result::Track');
111
112   1;
113
114
115 MyDatabase/Main/Result/Track.pm:
116
117   package MyDatabase::Main::Result::Track;
118   use base qw/DBIx::Class::Core/;
119   __PACKAGE__->table('track');
120   __PACKAGE__->add_columns(qw/ trackid cd title /);
121   __PACKAGE__->set_primary_key('trackid');
122   __PACKAGE__->belongs_to('cd' => 'MyDatabase::Main::Result::Cd');
123
124   1;
125
126
127 =head3 Write a script to insert some records
128
129 insertdb.pl
130
131   #!/usr/bin/perl -w
132
133   use MyDatabase::Main;
134   use strict;
135
136   my $schema = MyDatabase::Main->connect('dbi:SQLite:db/example.db');
137
138   #  here's some of the SQL that is going to be generated by the schema
139   #  INSERT INTO artist VALUES (NULL,'Michael Jackson');
140   #  INSERT INTO artist VALUES (NULL,'Eminem');
141
142   my @artists = (['Michael Jackson'], ['Eminem']);
143   $schema->populate('Artist', [
144      [qw/name/],
145      @artists,
146   ]);
147
148   my %albums = (
149     'Thriller' => 'Michael Jackson',
150     'Bad' => 'Michael Jackson',
151     'The Marshall Mathers LP' => 'Eminem',
152   );
153
154   my @cds;
155   foreach my $lp (keys %albums) {
156     my $artist = $schema->resultset('Artist')->find({
157       name => $albums{$lp}
158     });
159     push @cds, [$lp, $artist->id];
160   }
161
162   $schema->populate('Cd', [
163     [qw/title artist/],
164     @cds,
165   ]);
166
167
168   my %tracks = (
169     'Beat It'         => 'Thriller',
170     'Billie Jean'     => 'Thriller',
171     'Dirty Diana'     => 'Bad',
172     'Smooth Criminal' => 'Bad',
173     'Leave Me Alone'  => 'Bad',
174     'Stan'            => 'The Marshall Mathers LP',
175     'The Way I Am'    => 'The Marshall Mathers LP',
176   );
177
178   my @tracks;
179   foreach my $track (keys %tracks) {
180     my $cdname = $schema->resultset('Cd')->find({
181       title => $tracks{$track},
182     });
183     push @tracks, [$cdname->id, $track];
184   }
185
186   $schema->populate('Track',[
187     [qw/cd title/],
188     @tracks,
189   ]);
190
191 =head3 Create and run the test scripts
192
193 testdb.pl:
194
195   #!/usr/bin/perl -w
196
197   use MyDatabase::Main;
198   use strict;
199
200   my $schema = MyDatabase::Main->connect('dbi:SQLite:db/example.db');
201   # for other DSNs, e.g. MySQL, see the perldoc for the relevant dbd
202   # driver, e.g perldoc L<DBD::mysql>.
203
204   get_tracks_by_cd('Bad');
205   get_tracks_by_artist('Michael Jackson');
206
207   get_cd_by_track('Stan');
208   get_cds_by_artist('Michael Jackson');
209
210   get_artist_by_track('Dirty Diana');
211   get_artist_by_cd('The Marshall Mathers LP');
212
213
214   sub get_tracks_by_cd {
215     my $cdtitle = shift;
216     print "get_tracks_by_cd($cdtitle):\n";
217     my $rs = $schema->resultset('Track')->search(
218       {
219         'cd.title' => $cdtitle
220       },
221       {
222         join     => [qw/ cd /],
223       }
224     );
225     while (my $track = $rs->next) {
226       print $track->title . "\n";
227     }
228     print "\n";
229   }
230
231   sub get_tracks_by_artist {
232     my $artistname = shift;
233     print "get_tracks_by_artist($artistname):\n";
234     my $rs = $schema->resultset('Track')->search(
235       {
236         'artist.name' => $artistname
237       },
238       {
239         join => {
240           'cd' => 'artist'
241         },
242       }
243     );
244     while (my $track = $rs->next) {
245       print $track->title . "\n";
246     }
247     print "\n";
248   }
249
250
251   sub get_cd_by_track {
252     my $tracktitle = shift;
253     print "get_cd_by_track($tracktitle):\n";
254     my $rs = $schema->resultset('Cd')->search(
255       {
256         'tracks.title' => $tracktitle
257       },
258       {
259         join     => [qw/ tracks /],
260       }
261     );
262     my $cd = $rs->first;
263     print $cd->title . "\n\n";
264   }
265
266   sub get_cds_by_artist {
267     my $artistname = shift;
268     print "get_cds_by_artist($artistname):\n";
269     my $rs = $schema->resultset('Cd')->search(
270       {
271         'artist.name' => $artistname
272       },
273       {
274         join     => [qw/ artist /],
275       }
276     );
277     while (my $cd = $rs->next) {
278       print $cd->title . "\n";
279     }
280     print "\n";
281   }
282
283
284
285   sub get_artist_by_track {
286     my $tracktitle = shift;
287     print "get_artist_by_track($tracktitle):\n";
288     my $rs = $schema->resultset('Artist')->search(
289       {
290         'tracks.title' => $tracktitle
291       },
292       {
293         join => {
294           'cds' => 'tracks'
295         }
296       }
297     );
298     my $artist = $rs->first;
299     print $artist->name . "\n\n";
300   }
301
302   sub get_artist_by_cd {
303     my $cdtitle = shift;
304     print "get_artist_by_cd($cdtitle):\n";
305     my $rs = $schema->resultset('Artist')->search(
306       {
307         'cds.title' => $cdtitle
308       },
309       {
310         join     => [qw/ cds /],
311       }
312     );
313     my $artist = $rs->first;
314     print $artist->name . "\n\n";
315   }
316
317
318
319 It should output:
320
321   get_tracks_by_cd(Bad):
322   Dirty Diana
323   Smooth Criminal
324   Leave Me Alone
325
326   get_tracks_by_artist(Michael Jackson):
327   Beat it
328   Billie Jean
329   Dirty Diana
330   Smooth Criminal
331   Leave Me Alone
332
333   get_cd_by_track(Stan):
334   The Marshall Mathers LP
335
336   get_cds_by_artist(Michael Jackson):
337   Thriller
338   Bad
339
340   get_artist_by_track(Dirty Diana):
341   Michael Jackson
342
343   get_artist_by_cd(The Marshall Mathers LP):
344   Eminem
345
346 =head1 Notes
347
348 A reference implementation of the database and scripts in this example
349 are available in the main distribution for DBIx::Class under the
350 directory F<t/examples/Schema>.
351
352 With these scripts we're relying on @INC looking in the current
353 working directory.  You may want to add the MyDatabase namespaces to
354 @INC in a different way when it comes to deployment.
355
356 The F<testdb.pl> script is an excellent start for testing your database
357 model.
358
359 This example uses L<DBIx::Class::Schema/load_namespaces> to load in the
360 appropriate L<Row|DBIx::Class::Row> classes from the MyDatabase::Main::Result namespace,
361 and any required resultset classes from the MyDatabase::Main::ResultSet
362 namespace (although we created the directory in the directions above we
363 did not add, or need to add, any resultset classes).
364
365 =head1 TODO
366
367 =head1 AUTHOR
368
369   sc_ from irc.perl.org#dbix-class
370   Kieren Diment <kd@totaldatasolution.com>
371   Nigel Metheringham <nigelm@cpan.org>
372
373 =cut