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 structure is based on the following rules:
  12
  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.
  15
  16 The database is implemented with the following:
  17
  18   table 'artist' with columns:  artistid, name
  19   table 'cd'     with columns:  cdid, artistid, title, year
  20   table 'track'  with columns:  trackid, cdid, title
  21
  22 Each of the table's first columns is the primary key; any subsequent
  23 keys are foreign keys.
  24
  25 =head2 Installation
  26
  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.
  29
  30 =head3 The database/tables/data
  31
  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.
  34
  35   cpanm --look DBIx::Class
  36
  37 If for some reason the file is unreadable on your system, you can
  38 recreate it as follows:
  39
  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
  45
  46 =head3 Testing the database
  47
  48 Enter the example Schema directory
  49
  50   cd <unpacked-DBIC-tarball>/examples/Schema
  51
  52 Run the script testdb.pl, which will test that the database has
  53 successfully been filled.
  54
  55 When this script is run, it should output the following:
  56
  57  get_tracks_by_cd(Bad):
  58  Leave Me Alone
  59  Smooth Criminal
  60  Dirty Diana
  61
  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')
  68
  69  get_cd_by_track(Stan):
  70  The Marshall Mathers LP has the track 'Stan'.
  71
  72  get_cds_by_artist(Michael Jackson):
  73  Thriller
  74  Bad
  75
  76  get_artist_by_track(Dirty Diana):
  77  Michael Jackson recorded the track 'Dirty Diana'.
  78
  79  get_artist_by_cd(The Marshall Mathers LP):
  80  Eminem recorded the CD 'The Marshall Mathers LP'.
  81
  82
  83 =head3 Discussion about the results
  84
  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).
  91
  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.
  96
  97 This example uses L<DBIx::Class::Schema/load_namespaces> to load in the
  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
 101 C<MyApp::Schema::ResultSet> namespace (although we did not add, nor needed
 102 any such classes in this example).
 103
 104 =head1 FURTHER QUESTIONS?
 105
 106 Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
 107
 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>.
 114
 115 =cut