lib/DBIx/Class/Manual/QuickStart.pod

   1 =head1 NAME
   2
   3 DBIx::Class::Manual::QuickStart - up and running with DBIC in 10 minutes
   4
   5 =head1 DESCRIPTION
   6
   7 This document shows the minimum amount of code to make you a productive DBIC
   8 user. It requires you to be familiar with just the basics of database
   9 programming (what database tables, rows and columns are) and the basics of
  10 Perl object-oriented programming (calling methods on an object instance).
  11 It also helps if you already know a bit of SQL and how to connect to a
  12 database through DBI.
  13
  14 Follow along with the example database shipping with this distribution,
  15 see directory F<examples/Schema>. This database is also used through-out the
  16 rest of the documentation.
  17
  18 =head2 Preparation
  19
  20 First, install DBIx::Class like you do with any other CPAN distribution.
  21 See L<http://www.cpan.org/modules/INSTALL.html> and L<perlmodinstall>.
  22
  23 Then open the distribution in your shell and change to the subdirectory
  24 mentioned earlier, the next command will download and unpack it:
  25
  26     $ perl -mCPAN -e'CPAN::Shell->look("DBIx::Class")'
  27     DBIx-Class$ cd examples/Schema
  28
  29 Inspect the database:
  30
  31     DBIx-Class/examples/Schema$ echo .dump | sqlite3 db/example.db
  32
  33 You can also use a GUI database browser such as
  34 L<SQLite Manager|https://addons.mozilla.org/firefox/addon/sqlite-manager>.
  35
  36 Have a look at the schema classes files in the subdirectory F<MyDatabase>. The
  37 C<MyDatabase::Main> class is the entry point for loading the other classes and
  38 interacting with the database through DBIC and the C<Result> classes correspond
  39 to the tables in the database. L<DBIx::Class::Manual::Example> shows how to
  40 write all that Perl code. That is almost never necessary, though. Instead use
  41 L<dbicdump> (part of the distribution C<DBIx-Class-Schema-Loader>) to
  42 automatically create schema classes files from an existing database. The
  43 chapter L</"Resetting the database"> below shows an example invocation.
  44
  45 =head2 Connecting to the database
  46
  47 A L<schema|DBIx::Class::Manual::Glossary/Schema> object represents the database.
  48
  49     use MyDatabase::Main qw();
  50     my $schema = MyDatabase::Main->connect('dbi:SQLite:db/example.db');
  51
  52 The first four arguments are the same as for L<DBI/connect>.
  53
  54 =head2 Working with data
  55
  56 Almost all actions go through a
  57 L<resultset|DBIx::Class::Manual::Glossary/ResultSet> object.
  58
  59 =head3 Adding data
  60
  61 Via intermediate result objects:
  62
  63     my $artist_ma = $schema->resultset('Artist')->create({
  64         name => 'Massive Attack',
  65     });
  66     my $cd_mezz = $artist_ma->create_related(cds => {
  67         title => 'Mezzanine',
  68     });
  69     for ('Angel', 'Teardrop') {
  70         $cd_mezz->create_related(tracks => {
  71             title => $_
  72         });
  73     }
  74
  75 Via relation accessors:
  76
  77     $schema->resultset('Artist')->create({
  78         name => 'Metallica',
  79         cds => [
  80             {
  81                 title => q{Kill 'Em All},
  82                 tracks => [
  83                     { title => 'Jump in the Fire' },
  84                     { title => 'Whiplash' },
  85                 ],
  86             },
  87             {
  88                 title => 'ReLoad',
  89                 tracks => [
  90                     { title => 'The Memory Remains' },
  91                     { title => 'The Unforgiven II' },
  92                     { title => 'Fuel' },
  93                 ],
  94             },
  95         ],
  96     });
  97
  98 Columns that are not named are filled with default values. The value C<undef>
  99 acts as a C<NULL> in the database.
 100
 101 See the chapter L</"Introspecting the schema classes"> below to find out where
 102 the non-obvious source name strings such as C<Artist> and accessors such as
 103 C<cds> and C<tracks> come from.
 104
 105 Set the environment variable C<DBI_TRACE='1|SQL'> to see the generated queries.
 106
 107 =head3 Retrieving data
 108
 109 Set up a condition.
 110
 111     my $artists_starting_with_m = $schema->resultset('Artist')->search(
 112         {
 113             name => { like => 'M%' }
 114         }
 115     );
 116
 117 Iterate over result objects of class C<MyDatabase::Main::Result::Artist>.
 118 L<Result|DBIx::Class::Manual::Glossary/Result> objects represent a row and
 119 automatically get accessors for their column names.
 120
 121     for my $artist ($artists_starting_with_m->all) {
 122         say $artist->name;
 123     }
 124
 125 =head3 Changing data
 126
 127 Change the release year of all CDs titled I<ReLoad>.
 128
 129     $schema->resultset('Cd')->search(
 130         {
 131             title => 'ReLoad',
 132         }
 133     )->update_all(
 134         {
 135             year => 1997,
 136         }
 137     );
 138
 139 =head3 Removing data
 140
 141 Removes all tracks titled I<Fuel> regardless of which CD the belong to.
 142
 143     $schema->resultset('Track')->search(
 144         {
 145             title => 'Fuel',
 146         }
 147     )->delete_all;
 148
 149 =head2 Introspecting the schema classes
 150
 151 This is useful for getting a feel for the naming of things in a REPL or during
 152 explorative programming.
 153
 154 From the root to the details:
 155
 156     $schema->sources;                       # returns qw(Cd Track Artist)
 157     $schema->source('Cd')->columns;         # returns qw(cdid artist title year)
 158     $schema->source('Cd')->relationships;   # returns qw(artist tracks)
 159
 160 From a detail to the root:
 161
 162     $some_result->result_source;            # returns appropriate source
 163     $some_resultset->result_source;
 164     $some_resultsource->schema;             # returns appropriate schema
 165
 166 =head2 Resetting the database
 167
 168     # delete database file
 169     DBIx-Class/examples/Schema$ rm -f db/example.db
 170
 171     # create database and set up tables from definition
 172     DBIx-Class/examples/Schema$ sqlite3 db/example.db < db/example.sql
 173
 174     # fill them with data
 175     DBIx-Class/examples/Schema$ perl ./insertdb.pl
 176
 177     # delete the schema classes files
 178     DBIx-Class/examples/Schema$ rm -rf MyDatabase/
 179
 180     # recreate schema classes files from database file
 181     DBIx-Class/examples/Schema$ dbicdump \
 182         -o dump_directory=. MyDatabase::Main dbi:SQLite:db/example.db
 183
 184 =head2 Where to go next
 185
 186 If you want to exercise what you learned with a more complicated schema,
 187 load L<Northwind|http://code.google.com/p/northwindextended/> into your
 188 database.
 189
 190 If you want to transfer your existing SQL knowledge, read
 191 L<DBIx::Class::Manual::SQLHackers>.
 192
 193 Continue with L<DBIx::Class::Tutorial> and
 194 L<DBIx::Class/"WHERE TO START READING">.