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