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::Schema::Loader>.
  16
  17 =head2 Setting it up manually
  18
  19 First, you should create your base schema class, which inherits from
  20 L<DBIx::Class::Schema>:
  21
  22   package My::Schema;
  23   use base qw/DBIx::Class::Schema/;
  24
  25 In this class you load your result_source ("table", "model") classes, which
  26 we will define later, using the load_classes() method. You can specify which
  27 classes to load manually:
  28
  29   # load My::Schema::Album and My::Schema::Artist
  30   __PACKAGE__->load_classes(qw/ Album Artist /);
  31
  32 Or load classes by namespace:
  33
  34   # load My::Schema::Album, My::Schema::Artist and My::OtherSchema::LinerNotes
  35   __PACKAGE__->load_classes(
  36     {
  37       'My::Schema' => [qw/ Album Artist /],
  38       'My::OtherSchema' => [qw/ LinerNotes /]
  39     }
  40   );
  41
  42 Or let your schema class load all classes in its namespace automatically:
  43
  44    # load My::Schema::*
  45   __PACKAGE__->load_classes();
  46
  47 Next, create each of the classes you want to load as specified above:
  48
  49   package My::Schema::Album;
  50   use base qw/DBIx::Class/;
  51
  52 Load any components required by each class with the load_components() method.
  53 This should consist of "Core" plus any additional components you want to use.
  54 For example, if you want serial/auto-incrementing primary keys:
  55
  56   __PACKAGE__->load_components(qw/ PK::Auto Core /);
  57
  58 C<PK::Auto> is supported for many databases; see
  59 L<DBIx::Class::Storage::DBI> for more information.
  60
  61 Set the table for your class:
  62
  63   __PACKAGE__->table('album');
  64
  65 Add columns to your class:
  66
  67   __PACKAGE__->add_columns(qw/ albumid artist title /);
  68
  69 Each column can also be set up with its own accessor, data_type and other
  70 pieces of information that it may be useful to have, just pass C<add_columns>
  71 a hash such as:
  72
  73   __PACKAGE__->add_columns(albumid =>
  74                             { accessor  => 'album',
  75                               data_type => 'integer',
  76                               size      => 16,
  77                               is_nullable => 0,
  78                               is_auto_increment => 1,
  79                               default_value => '',
  80                             },
  81                           artist =>
  82                             { data_type => 'integer',
  83                               size      => 16,
  84                               is_nullable => 0,
  85                               is_auto_increment => 0,
  86                               default_value => '',
  87                             },
  88                           title  =>
  89                             { data_type => 'varchar',
  90                               size      => 256,
  91                               is_nullable => 0,
  92                               is_auto_increment => 0,
  93                               default_value => '',
  94                             }
  95                          );
  96
  97 Most of this data isn't yet used directly by DBIx::Class, but various related
  98 modules such as L<DBIx::Class::WebForm> make use of it. Also it allows you
  99 to create your database tables from your Schema, instead of the other way
 100 around. See L<SQL::Translator> for details.
 101
 102 See L<DBIx::Class::ResultSource> for more details of the possible column
 103 attributes.
 104
 105 Accessors are created for each column automatically, so My::Schema::Album will
 106 have albumid() (or album(), when using the accessor), artist() and title()
 107 methods.
 108
 109 Define a primary key for your class:
 110
 111   __PACKAGE__->set_primary_key('albumid');
 112
 113 If you have a multi-column primary key, just pass a list instead:
 114
 115   __PACKAGE__->set_primary_key( qw/ albumid artistid / );
 116
 117 Define relationships that the class has with any other classes by using
 118 either C<belongs_to> to describe a column which contains an ID of another
 119 table, or C<has_many> to make a predefined accessor for fetching objects
 120 that contain this tables foreign key in one of their columns:
 121
 122   __PACKAGE__->has_many('albums', 'My::Schema::Artist', 'album_id');
 123
 124 More information about the various types of relationships available, and
 125 how you can design your own, can be found in L<DBIx::Class::Relationship>.
 126
 127
 128 =head2 Using L<DBIx::Class::Schema::Loader>
 129
 130 This is an external module, and not part of the L<DBIx::Class>
 131 distribution.  Like L<Class::DBI::Loader>, it inspects your database,
 132 and automatically creates classes for all the tables in your database.
 133 Here's a simple setup:
 134
 135   package My::Schema;
 136   use base qw/DBIx::Class::Schema::Loader/;
 137
 138   __PACKAGE__->load_from_connection(
 139     connect_info = [ 'dbi:SQLite:/home/me/myapp/my.db' ]
 140   );
 141
 142   1;
 143
 144 This should be equivalent to the manual setup in the section above.
 145 L<DBIx::Class::Schema::Loader> takes lots of other options.  For more
 146 information, consult its documentation.
 147
 148 =head2 Connecting
 149
 150 L<DBIx::Class::Schema::Loader> already contains the connection info for the
 151 database, so to get started all you need to do is create an instance of your
 152 class:
 153
 154   my $schema = My::Schema->new();
 155
 156 To connect to your manually created Schema, you also need to provide the
 157 connection details:
 158
 159   my $schema = My::Schema->connect('dbi:SQLite:/home/me/myapp/my.db');
 160
 161 You can create as many different schema instances as you need. So if you have
 162 a second database you want to access:
 163
 164   my $other_schema = My::Schema->connect( $dsn, $user, $password, $attrs );
 165
 166 Note that L<DBIx::Class::Schema> does not cache connections for you. If you
 167 use multiple connections, you need to do this manually.
 168
 169 To execute some sql statements on every connect you can pass them to your schema after the connect:
 170
 171   $schema->storage->on_connect_do(\@on_connect_sql_statments);
 172
 173 =head2 Basic usage
 174
 175 Once you've defined the basic classes, either manually or using
 176 L<DBIx::Class::Schema::Loader>, you can start interacting with your database.
 177
 178 To access your database using your $schema object, you can fetch a L<DBIx::Class::Manual::Glossary/"ResultSet">
 179 representing each of your tables by calling the ->resultset method.
 180
 181 The simplest way to get a record is by primary key:
 182
 183   my $album = $schema->resultset('Album')->find(14);
 184
 185 This will run a C<SELECT> with C<albumid = 14> in the C<WHERE> clause,
 186 and return an instance of C<My::Schema::Album> that represents this
 187 row.  Once you have that row, you can access and update columns:
 188
 189   $album->title('Physical Graffiti');
 190   my $title = $album->title; # $title holds 'Physical Graffiti'
 191
 192 If you prefer, you can use the C<set_column> and C<get_column>
 193 accessors instead:
 194
 195   $album->set_column('title', 'Presence');
 196   $title = $album->get_column('title');
 197
 198 Just like with L<Class::DBI>, you call C<update> to commit your
 199 changes to the database:
 200
 201   $album->update;
 202
 203 If needed, you can throw away your local changes like this:
 204
 205   $album->discard_changes if $album->is_changed;
 206
 207 As you can see, C<is_changed> allows you to check if there are local
 208 changes to your object.
 209
 210 =head2 Adding and removing rows
 211
 212 To create a new record in the database, you can use the C<create>
 213 method.  It returns an instance of C<My::Schema::Album> that can be
 214 used to access the data in the new record:
 215
 216   my $new_album = $schema->resultset('Album')->create({
 217     title  => 'Wish You Were Here',
 218     artist => 'Pink Floyd'
 219   });
 220
 221 Now you can add data to the new record:
 222
 223   $new_album->label('Capitol');
 224   $new_album->year('1975');
 225   $new_album->update;
 226
 227 Likewise, you can remove it from the database like this:
 228
 229   $new_album->delete;
 230
 231 You can also remove records without retrieving them first, by calling
 232 delete directly on a ResultSet object.
 233
 234   # Delete all of Falco's albums
 235   $schema->resultset('Album')->search({ artist => 'Falco' })->delete;
 236
 237 =head2 Finding your objects
 238
 239 L<DBIx::Class> provides a few different ways to retrieve data from
 240 your database.  Here's one example:
 241
 242   # Find all of Santana's albums
 243   my $rs = $schema->resultset('Album')->search({ artist => 'Santana' });
 244
 245 In scalar context, as above, C<search> returns a
 246 L<DBIx::Class::ResultSet> object.  It can be used to peek at the first
 247 album returned by the database:
 248
 249   my $album = $rs->first;
 250   print $album->title;
 251
 252 You can loop over the albums and update each one:
 253
 254   while (my $album = $rs->next) {
 255     print $album->artist . ' - ' . $album->title;
 256     $album->year(2001);
 257     $album->update;
 258   }
 259
 260 Or, you can update them all at once:
 261
 262   $rs->update({ year => 2001 });
 263
 264 For more information on what you can do with a
 265 L<DBIx::Class::ResultSet>, see L<DBIx::Class::ResultSet/METHODS>.
 266
 267 In list context, the C<search> method returns all of the matching
 268 rows:
 269
 270   # Fetch immediately all of Carlos Santana's albums
 271   my @albums = $schema->resultset('Album')->search(
 272     { artist => 'Carlos Santana' }
 273   );
 274   foreach my $album (@albums) {
 275     print $album->artist . ' - ' . $album->title;
 276   }
 277
 278 We also provide a handy shortcut for doing a C<LIKE> search:
 279
 280   # Find albums whose artist starts with 'Jimi'
 281   my $rs = $schema->resultset('Album')->search_like({ artist => 'Jimi%' });
 282
 283 Or you can provide your own C<WHERE> clause, like:
 284
 285   # Find Peter Frampton albums from the year 1986
 286   my $where = 'artist = ? AND year = ?';
 287   my @bind  = ( 'Peter Frampton', 1986 );
 288   my $rs    = $schema->resultset('Album')->search_literal( $where, @bind );
 289
 290 The preferred way to generate complex queries is to provide a
 291 L<SQL::Abstract> construct to C<search>:
 292
 293   my $rs = $schema->resultset('Album')->search({
 294     artist  => { '!=', 'Janis Joplin' },
 295     year    => { '<' => 1980 },
 296     albumid => [ 1, 14, 15, 65, 43 ]
 297   });
 298
 299 This results in something like the following C<WHERE> clause:
 300
 301   WHERE artist != 'Janis Joplin'
 302     AND year < 1980
 303     AND albumid IN (1, 14, 15, 65, 43)
 304
 305 For more examples of complex queries, see
 306 L<DBIx::Class::Manual::Cookbook>.
 307
 308 The search can also be modified by passing another hash with
 309 attributes:
 310
 311   my @albums = My::Schema->resultset('Album')->search(
 312     { artist => 'Bob Marley' },
 313     { rows => 2, order_by => 'year DESC' }
 314   );
 315
 316 C<@albums> then holds the two most recent Bob Marley albums.
 317
 318 For a complete overview of the available attributes, see
 319 L<DBIx::Class::ResultSet/ATTRIBUTES>.
 320
 321 =head1 SEE ALSO
 322
 323 =over 4
 324
 325 =item * L<DBIx::Class::Manual::Cookbook>
 326
 327 =item * L<DBIx::Class::Manual::FAQ>
 328
 329 =back
 330
 331 =cut