Commit | Line | Data |
3f341474 |
1 | =head1 NAME |
2 | |
3 | DBIx::Class::Manual::Example - Simple CD database example |
4 | |
5 | =head1 DESCRIPTION |
6 | |
880a1a0c |
7 | This tutorial will guide you through the process of setting up and |
3f341474 |
8 | testing a very basic CD database using SQLite, with DBIx::Class::Schema |
9 | as the database frontend. |
10 | |
1f9ae1a3 |
11 | The database structure is based on the following rules: |
3f341474 |
12 | |
1f9ae1a3 |
13 | An artist can have many cds, and each cd belongs to just one artist. |
14 | A cd can have many tracks, and each track belongs to just one cd. |
3f341474 |
15 | |
1f9ae1a3 |
16 | The database is implemented with the following: |
3f341474 |
17 | |
1f9ae1a3 |
18 | table 'artist' with columns: artistid, name |
19 | table 'cd' with columns: cdid, artistid, title, year |
20 | table 'track' with columns: trackid, cdid, title |
3f341474 |
21 | |
1f9ae1a3 |
22 | Each of the table's first columns is the primary key; any subsequent |
23 | keys are foreign keys. |
3f341474 |
24 | |
25 | =head2 Installation |
26 | |
1f9ae1a3 |
27 | You'll need to install DBIx::Class via CPAN, and you'll also need to |
28 | install sqlite3 (not sqlite) if it's not already intalled. |
3f341474 |
29 | |
1f9ae1a3 |
30 | =head3 The database/tables/data |
3f341474 |
31 | |
1f9ae1a3 |
32 | Your distribution already comes with a pre-filled SQLite database |
33 | F<examples/Schema/db/example.db>. You can see it by e.g. |
3f341474 |
34 | |
1f9ae1a3 |
35 | cpanm --look DBIx::Class |
3f341474 |
36 | |
1f9ae1a3 |
37 | If for some reason the file is unreadable on your system, you can |
38 | recreate it as follows: |
3f341474 |
39 | |
1f9ae1a3 |
40 | cp -a <unpacked-DBIC-tarball>/examples/Schema dbicapp |
41 | cd dbicapp |
42 | rm db/example.db |
43 | sqlite3 db/example.db < db/example.sql |
44 | perl insertdb.pl |
3f341474 |
45 | |
1f9ae1a3 |
46 | =head3 Testing the database |
3f341474 |
47 | |
1f9ae1a3 |
48 | Enter the example Schema directory |
3f341474 |
49 | |
1f9ae1a3 |
50 | cd <unpacked-DBIC-tarball>/examples/Schema |
3f341474 |
51 | |
1f9ae1a3 |
52 | Run the script testdb.pl, which will test that the database has |
53 | successfully been filled. |
3f341474 |
54 | |
1f9ae1a3 |
55 | When this script is run, it should output the following: |
3f341474 |
56 | |
1f9ae1a3 |
57 | get_tracks_by_cd(Bad): |
58 | Leave Me Alone |
59 | Smooth Criminal |
60 | Dirty Diana |
90efcf94 |
61 | |
1f9ae1a3 |
62 | get_tracks_by_artist(Michael Jackson): |
63 | Billie Jean (from the CD 'Thriller') |
64 | Beat It (from the CD 'Thriller') |
65 | Leave Me Alone (from the CD 'Bad') |
66 | Smooth Criminal (from the CD 'Bad') |
67 | Dirty Diana (from the CD 'Bad') |
59187a3b |
68 | |
1f9ae1a3 |
69 | get_cd_by_track(Stan): |
70 | The Marshall Mathers LP has the track 'Stan'. |
90efcf94 |
71 | |
1f9ae1a3 |
72 | get_cds_by_artist(Michael Jackson): |
73 | Thriller |
74 | Bad |
90efcf94 |
75 | |
1f9ae1a3 |
76 | get_artist_by_track(Dirty Diana): |
77 | Michael Jackson recorded the track 'Dirty Diana'. |
90efcf94 |
78 | |
1f9ae1a3 |
79 | get_artist_by_cd(The Marshall Mathers LP): |
80 | Eminem recorded the CD 'The Marshall Mathers LP'. |
90efcf94 |
81 | |
90efcf94 |
82 | |
1f9ae1a3 |
83 | =head3 Discussion about the results |
90efcf94 |
84 | |
1f9ae1a3 |
85 | The data model defined in this example has an artist with multiple CDs, |
86 | and a CD with multiple tracks; thus, it's simple to traverse from a |
87 | track back to a CD, and from there back to an artist. This is |
88 | demonstrated in the get_tracks_by_artist routine, where we easily walk |
89 | from the individual track back to the title of the CD that the track |
90 | came from ($track->cd->title). |
90efcf94 |
91 | |
1f9ae1a3 |
92 | Note also that in the get_tracks_by_cd and get_tracks_by_artist |
93 | routines, the result set is called multiple times with the 'next' |
94 | iterator. In contrast, get_cd_by_track uses the 'first' result set |
95 | method, since only one CD is expected to have a specific track. |
3f341474 |
96 | |
299ca323 |
97 | This example uses L<DBIx::Class::Schema/load_namespaces> to load in the |
5b545397 |
98 | appropriate L<Result|DBIx::Class::Manual::ResultClass> classes from the |
99 | C<MyApp::Schema::Result> namespace, and any required |
100 | L<ResultSet|DBIx::Class::ResultSet> classes from the |
1f9ae1a3 |
101 | C<MyApp::Schema::ResultSet> namespace (although we did not add, nor needed |
102 | any such classes in this example). |
fb7e51d7 |
103 | |
a2bd3796 |
104 | =head1 FURTHER QUESTIONS? |
3f341474 |
105 | |
a2bd3796 |
106 | Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>. |
3f341474 |
107 | |
a2bd3796 |
108 | =head1 COPYRIGHT AND LICENSE |
109 | |
110 | This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE> |
111 | by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can |
112 | redistribute it and/or modify it under the same terms as the |
113 | L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>. |
3f341474 |
114 | |
115 | =cut |