X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FManual%2FExample.pod;h=2d0e2e3dcf80ff29fa0fc4c7d778f565a1b3d225;hb=59187a3bbcf176df838b00489cb0dfc592679aad;hp=16f41852f3be266b596cc860933449b11bb175a5;hpb=90efcf9497adb3d00a607e33835c23403b1d9741;p=dbsrgits%2FDBIx-Class.git

diff --git a/lib/DBIx/Class/Manual/Example.pod b/lib/DBIx/Class/Manual/Example.pod
index 16f4185..2d0e2e3 100644
--- a/lib/DBIx/Class/Manual/Example.pod
+++ b/lib/DBIx/Class/Manual/Example.pod
@@ -27,169 +27,183 @@ And these rules exists:
 
 Install DBIx::Class via CPAN should be sufficient.
 
-=head3 Create the database/tables.
+=head3 Create the database/tables
 
 First make and change the directory:
 
   mkdir app
   cd app
+  mkdir db
+  cd db
 
 This example uses SQLite which is a dependency of DBIx::Class, so you
 shouldn't have to install extra software.
 
-Save the following into a example.sql
+Save the following into a example.sql in the directory db
 
   CREATE TABLE artist (
-  artistid INTEGER PRIMARY KEY,
-  name TEXT NOT NULL 
+    artistid INTEGER PRIMARY KEY,
+    name TEXT NOT NULL
   );
 
   CREATE TABLE cd (
-  cdid INTEGER PRIMARY KEY,
-  artist INTEGER NOT NULL REFERENCES artist(artistid),
-  title TEXT NOT NULL);
+    cdid INTEGER PRIMARY KEY,
+    artist INTEGER NOT NULL REFERENCES artist(artistid),
+    title TEXT NOT NULL
+  );
 
   CREATE TABLE track (
-  trackid INTEGER PRIMARY KEY,
-  cd INTEGER NOT NULL REFERENCES cd(cdid),
-  title TEXT NOT NULL) ;
+    trackid INTEGER PRIMARY KEY,
+    cd INTEGER NOT NULL REFERENCES cd(cdid),
+    title TEXT NOT NULL
+  );
 
-and create the sqlite database file:
+and create the SQLite database file:
 
-sqlite3 example.db < example.sql
+  sqlite3 example.db < example.sql
 
 =head3 Set up DBIx::Class::Schema
 
-First, create some dirs and change working directory:
+Change directory back from db to the directory app:
+
+  cd ../
+
+Now create some more directories:
 
   mkdir MyDatabase
   mkdir MyDatabase/Main
+  mkdir MyDatabase/Main/Result
+  mkdir MyDatabase/Main/ResultSet
 
 Then, create the following DBIx::Class::Schema classes:
 
 MyDatabase/Main.pm:
-    
+
   package MyDatabase::Main;
   use base qw/DBIx::Class::Schema/;
-  __PACKAGE__->load_classes(qw/Artist Cd Track/);
+  __PACKAGE__->load_namespaces;
 
   1;
 
 
-MyDatabase/Main/Artist.pm:
+MyDatabase/Main/Result/Artist.pm:
 
-  package MyDatabase::Main::Artist;
-  use base qw/DBIx::Class/;
-  __PACKAGE__->load_components(qw/Core/);
+  package MyDatabase::Main::Result::Artist;
+  use base qw/DBIx::Class::Core/;
   __PACKAGE__->table('artist');
   __PACKAGE__->add_columns(qw/ artistid name /);
   __PACKAGE__->set_primary_key('artistid');
-  __PACKAGE__->has_many('cds' => 'MyDatabase::Main::Cd');
+  __PACKAGE__->has_many('cds' => 'MyDatabase::Main::Result::Cd');
 
   1;
 
 
-MyDatabase/Main/Cd.pm:
+MyDatabase/Main/Result/Cd.pm:
 
-  package MyDatabase::Main::Cd;
-  use base qw/DBIx::Class/;
-  __PACKAGE__->load_components(qw/Core/);
+  package MyDatabase::Main::Result::Cd;
+  use base qw/DBIx::Class::Core/;
+  __PACKAGE__->load_components(qw/InflateColumn::DateTime/);
   __PACKAGE__->table('cd');
   __PACKAGE__->add_columns(qw/ cdid artist title/);
   __PACKAGE__->set_primary_key('cdid');
-  __PACKAGE__->belongs_to('artist' => 'MyDatabase::Main::Artist');
-  __PACKAGE__->has_many('tracks' => 'MyDatabase::Main::Track');
+  __PACKAGE__->belongs_to('artist' => 'MyDatabase::Main::Result::Artist');
+  __PACKAGE__->has_many('tracks' => 'MyDatabase::Main::Result::Track');
 
   1;
 
 
-MyDatabase/Main/Track.pm:
+MyDatabase/Main/Result/Track.pm:
 
-  package MyDatabase::Main::Track;
-  use base qw/DBIx::Class/;
-  __PACKAGE__->load_components(qw/Core/);
+  package MyDatabase::Main::Result::Track;
+  use base qw/DBIx::Class::Core/;
   __PACKAGE__->table('track');
-  __PACKAGE__->add_columns(qw/ trackid cd title/);
+  __PACKAGE__->add_columns(qw/ trackid cd title /);
   __PACKAGE__->set_primary_key('trackid');
-  __PACKAGE__->belongs_to('cd' => 'MyDatabase::Main::Cd');
+  __PACKAGE__->belongs_to('cd' => 'MyDatabase::Main::Result::Cd');
 
   1;
 
 
-=head3 Write a script to insert some records.
+=head3 Write a script to insert some records
 
 insertdb.pl
 
-  #!/usr/bin/perl -w
+  #!/usr/bin/perl
 
-  use MyDatabase::Main;
   use strict;
+  use warnings;
+
+  use MyDatabase::Main;
 
-  my $schema = MyDatabase::Main->connect('dbi:SQLite:example.db');
+  my $schema = MyDatabase::Main->connect('dbi:SQLite:db/example.db');
 
-  #  here's some of the sql that is going to be generated by the schema
+  #  here's some of the SQL that is going to be generated by the schema
   #  INSERT INTO artist VALUES (NULL,'Michael Jackson');
   #  INSERT INTO artist VALUES (NULL,'Eminem');
 
   my @artists = (['Michael Jackson'], ['Eminem']);
   $schema->populate('Artist', [
-      [qw/name/],
-      @artists,
+     [qw/name/],
+     @artists,
   ]);
 
   my %albums = (
-      'Thriller' => 'Michael Jackson',
-      'Bad' => 'Michael Jackson',
-      'The Marshall Mathers LP' => 'Eminem',
-      );
+    'Thriller' => 'Michael Jackson',
+    'Bad' => 'Michael Jackson',
+    'The Marshall Mathers LP' => 'Eminem',
+  );
 
   my @cds;
   foreach my $lp (keys %albums) {
-      my $artist = $schema->resultset('Artist')->search({
-          name => $albums{$lp}
-      });
-      push @cds, [$lp, $artist->first];
+    my $artist = $schema->resultset('Artist')->find({
+      name => $albums{$lp}
+    });
+    push @cds, [$lp, $artist->id];
   }
 
   $schema->populate('Cd', [
-      [qw/title artist/],
-      @cds,
+    [qw/title artist/],
+    @cds,
   ]);
 
 
   my %tracks = (
-      'Beat It'         => 'Thriller',
-      'Billie Jean'     => 'Thriller',
-      'Dirty Diana'     => 'Bad',
-      'Smooth Criminal' => 'Bad',
-      'Leave Me Alone'  => 'Bad',
-      'Stan'            => 'The Marshall Mathers LP',
-      'The Way I Am'    => 'The Marshall Mathers LP',
+    'Beat It'         => 'Thriller',
+    'Billie Jean'     => 'Thriller',
+    'Dirty Diana'     => 'Bad',
+    'Smooth Criminal' => 'Bad',
+    'Leave Me Alone'  => 'Bad',
+    'Stan'            => 'The Marshall Mathers LP',
+    'The Way I Am'    => 'The Marshall Mathers LP',
   );
 
   my @tracks;
   foreach my $track (keys %tracks) {
-      my $cdname = $schema->resultset('Cd')->search({
-          title => $tracks{$track},
-      });
-      push @tracks, [$cdname->first, $track];
+    my $cdname = $schema->resultset('Cd')->find({
+      title => $tracks{$track},
+    });
+    push @tracks, [$cdname->id, $track];
   }
 
   $schema->populate('Track',[
-      [qw/cd title/],
-      @tracks,
+    [qw/cd title/],
+    @tracks,
   ]);
 
-=head3 Create and run the scripts
+=head3 Create and run the test scripts
 
 testdb.pl:
 
-  #!/usr/bin/perl -w
+  #!/usr/bin/perl
 
-  use MyDatabase::Main;
   use strict;
+  use warnings;
 
-  my $schema = MyDatabase::Main->connect('dbi:SQLite:example.db');
+  use MyDatabase::Main;
+
+  my $schema = MyDatabase::Main->connect('dbi:SQLite:db/example.db');
+  # for other DSNs, e.g. MySQL, see the perldoc for the relevant dbd
+  # driver, e.g perldoc L<DBD::mysql>.
 
   get_tracks_by_cd('Bad');
   get_tracks_by_artist('Michael Jackson');
@@ -202,109 +216,106 @@ testdb.pl:
 
 
   sub get_tracks_by_cd {
-      my $cdtitle = shift;
-      print "get_tracks_by_cd($cdtitle):\n";
-      my $rs = $schema->resultset('Track')->search(
-          {
-              'cd.title' => $cdtitle
-          },
-          {
-              join     => [qw/ cd /],
-              prefetch => [qw/ cd /]
-          }
-      );
-      while (my $track = $rs->next) {
-          print $track->title . "\n";
+    my $cdtitle = shift;
+    print "get_tracks_by_cd($cdtitle):\n";
+    my $rs = $schema->resultset('Track')->search(
+      {
+        'cd.title' => $cdtitle
+      },
+      {
+        join     => [qw/ cd /],
       }
-      print "\n";
+    );
+    while (my $track = $rs->next) {
+      print $track->title . "\n";
+    }
+    print "\n";
   }
 
   sub get_tracks_by_artist {
-      my $artistname = shift;
-      print "get_tracks_by_artist($artistname):\n";
-      my $rs = $schema->resultset('Track')->search(
-          {
-              'artist.name' => $artistname
-          },
-          {
-              join => {
-                  'cd' => 'artist'
-              },
-          }
-      );
-      while (my $track = $rs->next) {
-          print $track->title . "\n";
+    my $artistname = shift;
+    print "get_tracks_by_artist($artistname):\n";
+    my $rs = $schema->resultset('Track')->search(
+      {
+        'artist.name' => $artistname
+      },
+      {
+        join => {
+          'cd' => 'artist'
+        },
       }
-      print "\n";
+    );
+    while (my $track = $rs->next) {
+      print $track->title . "\n";
+    }
+    print "\n";
   }
-  
-  
-  
+
+
   sub get_cd_by_track {
-      my $tracktitle = shift;
-      print "get_cd_by_track($tracktitle):\n";
-      my $rs = $schema->resultset('Cd')->search(
-          {
-              'tracks.title' => $tracktitle
-          },
-          {
-              join     => [qw/ tracks /],
-          }
-      );
-      my $cd = $rs->first;
-      print $cd->title . "\n\n";
+    my $tracktitle = shift;
+    print "get_cd_by_track($tracktitle):\n";
+    my $rs = $schema->resultset('Cd')->search(
+      {
+        'tracks.title' => $tracktitle
+      },
+      {
+        join     => [qw/ tracks /],
+      }
+    );
+    my $cd = $rs->first;
+    print $cd->title . "\n\n";
   }
-  
+
   sub get_cds_by_artist {
-      my $artistname = shift;
-      print "get_cds_by_artist($artistname):\n";
-      my $rs = $schema->resultset('Cd')->search(
-          {
-              'artist.name' => $artistname
-          },
-          {
-              join     => [qw/ artist /],
-              prefetch => [qw/ artist /]
-          }
-      );
-      while (my $cd = $rs->next) {
-          print $cd->title . "\n";
+    my $artistname = shift;
+    print "get_cds_by_artist($artistname):\n";
+    my $rs = $schema->resultset('Cd')->search(
+      {
+        'artist.name' => $artistname
+      },
+      {
+        join     => [qw/ artist /],
       }
-      print "\n";
+    );
+    while (my $cd = $rs->next) {
+      print $cd->title . "\n";
+    }
+    print "\n";
   }
 
 
 
   sub get_artist_by_track {
-      my $tracktitle = shift;
-      print "get_artist_by_track($tracktitle):\n";
-      my $rs = $schema->resultset('Artist')->search(
-          {
-              'tracks.title' => $tracktitle
-          },
-          {
-	     join => {
-	     'cds' => 'tracks'
-              }
-          }
-      );
-      my $artist = $rs->first;
-      print $artist->name . "\n\n";
+    my $tracktitle = shift;
+    print "get_artist_by_track($tracktitle):\n";
+    my $rs = $schema->resultset('Artist')->search(
+      {
+        'tracks.title' => $tracktitle
+      },
+      {
+        join => {
+          'cds' => 'tracks'
+        }
+      }
+    );
+    my $artist = $rs->first;
+    print $artist->name . "\n\n";
   }
 
   sub get_artist_by_cd {
-      my $cdtitle = shift;
-      print "get_artist_by_cd($cdtitle):\n";
-      my $rs = $schema->resultset('Artist')->search(
-          {
-              'cds.title' => $cdtitle
-          },
-          {
-              join     => [qw/ cds /],
-          }
-      );
-      my $artist = $rs->first;
-      print $artist->name . "\n\n";
+    my $cdtitle = shift;
+    print "get_artist_by_cd($cdtitle):\n";
+    my $rs = $schema->resultset('Artist')->search(
+      {
+        'cds.title' => $cdtitle
+      },
+      {
+        join     => [qw/ cds /],
+      }
+    );
+    my $artist = $rs->first;
+    print $artist->name . "\n\n";
   }
 
 
@@ -338,18 +349,29 @@ It should output:
 
 =head1 Notes
 
+A reference implementation of the database and scripts in this example
+are available in the main distribution for DBIx::Class under the
+directory F<t/examples/Schema>.
+
 With these scripts we're relying on @INC looking in the current
 working directory.  You may want to add the MyDatabase namespaces to
 @INC in a different way when it comes to deployment.
 
-The testdb.pl script is an excellent start for testing your database
+The F<testdb.pl> script is an excellent start for testing your database
 model.
 
+This example uses L<DBIx::Class::Schema/load_namespaces> to load in the
+appropriate L<Row|DBIx::Class::Row> classes from the MyDatabase::Main::Result namespace,
+and any required resultset classes from the MyDatabase::Main::ResultSet
+namespace (although we created the directory in the directions above we
+did not add, or need to add, any resultset classes).
+
 =head1 TODO
 
 =head1 AUTHOR
 
   sc_ from irc.perl.org#dbix-class
   Kieren Diment <kd@totaldatasolution.com>
+  Nigel Metheringham <nigelm@cpan.org>
 
 =cut