lib/DBIx/Class/Manual/Intro.pod

   1 =head1 NAME
   2
   3 DBIx::Class::Manual::Intro - Introduction to DBIx::Class
   4
   5 =head1 INTRODUCTION
   6
   7 So, you are bored with SQL, and want a native Perl interface for your
   8 database?  Or you've been doing this for a while with L<Class::DBI>,
   9 and think there's a better way?  You've come to the right place.
  10 Let's look at how you can set and use your first native L<DBIx::Class>
  11 tree.
  12
  13 First we'll see how you can set up your classes yourself.  If you want
  14 them to be auto-discovered, just skip to the next section, which shows
  15 you how to use L<DBIx::Class::Loader>.
  16
  17 =head2 Setting it up manually
  18
  19 First, you'll need a base class.  It should inherit from
  20 L<DBIx::Class> like this:
  21
  22   package MyApp::DB;
  23   use base qw/DBIx::Class/;
  24
  25 You will also want to load some of the L<DBIx::Class> components.
  26 L<DBIx::Class::Core> provides a good starter set.  In addition you'll
  27 have to use either L<DBIx::Class::Schema> or L<DBIx::Class::DB>.
  28 We'll use C<DB> in this introduction, since it involves less magic.
  29 C<Schema> is mostly useful if you want to use multiple database
  30 connections.
  31
  32   __PACKAGE__->load_components(qw/Core DB/);
  33
  34 If you want serial/auto-incrementing primary keys, you should use the
  35 L<DBIx::Class::PK::Auto> component.
  36   __PACKAGE__->load_components(qw/PK::Auto Core DB/);
  37
  38 C<PK::Auto> classes exist for many databases; see
  39 L<DBIx::Class::PK::Auto> for more information.
  40
  41 Once you've loaded the components, it's time to set up your
  42 connection:
  43
  44   __PACKAGE__->connection('dbi:SQLite:/home/me/myapp/my.db');
  45
  46 This method is similar to the normal L<DBI> C<connect> method, and can
  47 take username, password, and L<DBI> attribute hash as well as the DSN.
  48
  49 With that out of the way, we can define our first table class:
  50
  51   package MyApp::DB::Album;
  52   use base qw/MyApp::DB/;
  53
  54 Then we specify which table it uses,
  55
  56   __PACKAGE__->table('album');
  57
  58 and specify which columns it has.
  59
  60   __PACKAGE__->add_columns(qw/albumid artist title label year/);
  61
  62 This will automatically create accessors for each of the columns, so
  63 that you can read/update the values in rows you've retrieved.
  64
  65 Also, you need to tell it which column is the primary key:
  66
  67   __PACKAGE__->set_primary_key('albumid');
  68
  69 If you have a primary key composed of multiple columns, just pass a
  70 list instead.
  71
  72 That's pretty much all you need for a basic setup.  If you have more
  73 advanced needs like using more than one database connection for the
  74 same class, see L<DBIx::Class::Schema>.
  75
  76 =head2 Using L<DBIx::Class::Loader>
  77
  78 This is an additional class, and not part of the L<DBIx::Class>
  79 distribution.  Like L<Class::DBI::Loader>, it inspects your database,
  80 and automatically creates classes for all the tables in your database.
  81 Here's a simple setup:
  82
  83   package MyApp::DB;
  84   use DBIx::Class::Loader;
  85
  86   my $loader = DBIx::Class::Loader->new(
  87     dsn       => 'dbi:SQLite:/home/me/myapp/my.db',
  88     namespace => 'MyApp::DB'
  89   );
  90
  91   1;
  92
  93 This should be equivalent to the manual setup in the section above.
  94 L<DBIx::Class::Loader> takes lots of other options.  For more
  95 information, consult its documentation.
  96
  97 =head2 Basic usage
  98
  99 Once you've defined the basic classes, either manually or using
 100 L<DBIx::Class::Loader>, you can start interacting with your database.
 101 The simplest way to get a record is by primary key:
 102
 103   my $album = MyApp::DB::Album->find(14);
 104
 105 This will run a C<SELECT> with C<albumid = 14> in the C<WHERE> clause,
 106 and return an instance of C<MyApp::DB::Album> that represents this
 107 row.  Once you have that row, you can access and update columns:
 108
 109   $album->title('Physical Graffiti');
 110   my $title = $album->title; # $title holds 'Physical Graffiti'
 111
 112 If you prefer, you can use the C<set_column> and C<get_column>
 113 accessors instead:
 114
 115   $album->set_column('title', 'Presence');
 116   $title = $album->get_column('title');
 117
 118 Just like with L<Class::DBI>, you do an C<update> to commit your
 119 changes to the database:
 120
 121   $album->update;
 122
 123 If needed, you can throw away your local changes like this:
 124
 125   $album->discard_changes if $album->is_changed;
 126
 127 As you can see, C<is_changed> allows you to check if there are local
 128 changes to your object.
 129
 130 =head2 Adding and removing rows
 131
 132 To create a new record in the database, you can use the C<create>
 133 method.  It returns an instance of C<MyApp::DB::Album> that can be
 134 used to access the data in the new record:
 135
 136   my $new_album = MyApp::DB::Album->create({
 137     title  => 'Wish You Were Here',
 138     artist => 'Pink Floyd'
 139   });
 140
 141 Now you can add data to the new record:
 142
 143   $new_album->label('Capitol');
 144   $new_album->year('1975');
 145   $new_album->update;
 146
 147 Likewise, you can remove it from the database like this:
 148
 149   $new_album->delete;
 150
 151 You can also remove records without or retrieving first.  This
 152 operation takes the same kind of arguments as a search.
 153
 154   # Delete all of Falco's albums
 155   MyApp::DB::Album->delete({ artist => 'Falco' });
 156
 157 =head2 Finding your objects
 158
 159 L<DBIx::Class> provides a few different ways to retrieve data from
 160 your database.  Here's one example:
 161
 162   # Find all of Santana's albums
 163   my $rs = MyApp::DB::Album->search({ artist => 'Santana' });
 164
 165 In scalar context, as above, C<search> returns a
 166 L<DBIx::Class::ResultSet> object.  It can be used to peek at the first
 167 album returned by the database:
 168
 169   my $album = $rs->first;
 170   print $album->title;
 171
 172 Or, you can loop over the albums and update each one:
 173
 174   while (my $album = $rs->next) {
 175     print $album->artist . ' - ' . $album->title;
 176     $album->year(2001);
 177     $album->update;
 178   }
 179
 180 For more information on what you can do with a
 181 L<DBIx::Class::ResultSet>, see L<DBIx::Class::ResultSet/METHODS>.
 182
 183 In list context, the C<search> method returns all of the matching
 184 rows:
 185
 186   # Fetch immediately all of Carlos Santana's albums
 187   my @albums = MyApp::DB::Album->search({ artist => 'Carlos Santana' });
 188   foreach my $album (@albums) {
 189     print $album->artist . ' - ' . $album->title;
 190   }
 191
 192 We also provide a handy shortcut for doing a C<LIKE> search:
 193
 194   # Find albums whose artist starts with 'Jimi'
 195   my $rs = MyApp::DB::Album->search_like({ artist => 'Jimi%' });
 196
 197 Or you can provide your own handmade C<WHERE> clause, like:
 198
 199   # Find Peter Frampton albums from the year 1986
 200   my $where = 'artist = ? AND year = ?';
 201   my @bind  = ( 'Peter Frampton', 1986 );
 202   my $rs    = MyApp::DB::Album->search_literal( $where, @bind );
 203
 204 The preferred way to generate complex queries is to provide a
 205 L<SQL::Abstract> construct to C<search>:
 206
 207   my $rs = MyApp::DB::Album->search({
 208     artist  => { '!=', 'Janis Joplin' },
 209     year    => { '<' => 1980 },
 210     albumid => [ 1, 14, 15, 65, 43 ]
 211   });
 212
 213 This results in something like the following C<WHERE> clause:
 214
 215   WHERE artist != 'Janis Joplin'
 216     AND year < 1980
 217     AND albumid IN (1, 14, 15, 65, 43)
 218
 219 For more examples of complex queries, see
 220 L<DBIx::Class::Manual::Cookbook>.
 221
 222 The search can also be modified by passing another hash with
 223 attributes:
 224
 225   my @albums = MyApp::DB::Album->search(
 226     { artist => 'Bob Marley' },
 227     { rows => 2, order_by => 'year DESC' }
 228   );
 229
 230 C<@albums> then holds the two most recent Bob Marley albums.
 231
 232 For a complete overview of the available attributes, see
 233 L<DBIx::Class::ResultSet/ATTRIBUTES>.
 234
 235 =head1 SEE ALSO
 236
 237 =over 4
 238
 239 =item * L<DBIx::Class::Manual::Cookbook>
 240
 241 =item * L<DBIx::Class::Manual::FAQ>
 242
 243 =back
 244
 245 =cut