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 MyApp::DB;
 136   use DBIx::Class::Schema::Loader;
 137
 138   my $loader = DBIx::Class::Loader->new(
 139     dsn       => 'dbi:SQLite:/home/me/myapp/my.db',
 140     namespace => 'MyApp::DB'
 141   );
 142
 143   1;
 144
 145 This should be equivalent to the manual setup in the section above.
 146 L<DBIx::Class::Schema::Loader> takes lots of other options.  For more
 147 information, consult its documentation.
 148
 149 =head2 Connecting
 150
 151 L<DBIx::Class::Schema::Loader> already contains the connection info for the
 152 database, so to get started all you need to do is create an instance of your
 153 class:
 154
 155   my $schema = MyApp::DB->new();
 156
 157 To connect to your manually created Schema, you also need to provide the
 158 connection details:
 159
 160   my $schema = My::Schema->connect('dbi:SQLite:/home/me/myapp/my.db');
 161
 162 You can create as many different schema instances as you need. So if you have
 163 a second database you want to access:
 164
 165   my $other_schema = My::Schema->connect( $dsn, $user, $password, $attrs );
 166
 167 Note that L<DBIx::Class::Schema> does not cache connnections for you. If you
 168 use multiple connections, you need to do this manually.
 169
 170 To execute some sql statements on every connect you can pass them to your schema after the connect:
 171
 172   $schema->storage->on_connect_do(\@on_connect_sql_statments);
 173
 174 =head2 Basic usage
 175
 176 Once you've defined the basic classes, either manually or using
 177 L<DBIx::Class::Schema::Loader>, you can start interacting with your database.
 178
 179 To access your database using your $schema object, you can fetch a L<DBIx::Class::Manual::Glossary/"ResultSet">
 180 representing each of your tables by calling the ->resultset method.
 181
 182 The simplest way to get a record is by primary key:
 183
 184   my $album = $schema->resultset('Album')->find(14);
 185
 186 This will run a C<SELECT> with C<albumid = 14> in the C<WHERE> clause,
 187 and return an instance of C<MyApp::DB::Album> that represents this
 188 row.  Once you have that row, you can access and update columns:
 189
 190   $album->title('Physical Graffiti');
 191   my $title = $album->title; # $title holds 'Physical Graffiti'
 192
 193 If you prefer, you can use the C<set_column> and C<get_column>
 194 accessors instead:
 195
 196   $album->set_column('title', 'Presence');
 197   $title = $album->get_column('title');
 198
 199 Just like with L<Class::DBI>, you call C<update> to commit your
 200 changes to the database:
 201
 202   $album->update;
 203
 204 If needed, you can throw away your local changes like this:
 205
 206   $album->discard_changes if $album->is_changed;
 207
 208 As you can see, C<is_changed> allows you to check if there are local
 209 changes to your object.
 210
 211 =head2 Adding and removing rows
 212
 213 To create a new record in the database, you can use the C<create>
 214 method.  It returns an instance of C<MyApp::DB::Album> that can be
 215 used to access the data in the new record:
 216
 217   my $new_album = $schema->resultset('Album')->create({
 218     title  => 'Wish You Were Here',
 219     artist => 'Pink Floyd'
 220   });
 221
 222 Now you can add data to the new record:
 223
 224   $new_album->label('Capitol');
 225   $new_album->year('1975');
 226   $new_album->update;
 227
 228 Likewise, you can remove it from the database like this:
 229
 230   $new_album->delete;
 231
 232 You can also remove records without retrieving them first, by calling
 233 delete directly on a ResultSet object.
 234
 235   # Delete all of Falco's albums
 236   $schema->resultset('Album')->search({ artist => 'Falco' })->delete;
 237
 238 =head2 Finding your objects
 239
 240 L<DBIx::Class> provides a few different ways to retrieve data from
 241 your database.  Here's one example:
 242
 243   # Find all of Santana's albums
 244   my $rs = $schema->resultset('Album')->search({ artist => 'Santana' });
 245
 246 In scalar context, as above, C<search> returns a
 247 L<DBIx::Class::ResultSet> object.  It can be used to peek at the first
 248 album returned by the database:
 249
 250   my $album = $rs->first;
 251   print $album->title;
 252
 253 You can loop over the albums and update each one:
 254
 255   while (my $album = $rs->next) {
 256     print $album->artist . ' - ' . $album->title;
 257     $album->year(2001);
 258     $album->update;
 259   }
 260
 261 Or, you can update them all at once:
 262
 263   $rs->update({ year => 2001 });
 264
 265 For more information on what you can do with a
 266 L<DBIx::Class::ResultSet>, see L<DBIx::Class::ResultSet/METHODS>.
 267
 268 In list context, the C<search> method returns all of the matching
 269 rows:
 270
 271   # Fetch immediately all of Carlos Santana's albums
 272   my @albums = $schema->resultset('Album')->search(
 273     { artist => 'Carlos Santana' }
 274   );
 275   foreach my $album (@albums) {
 276     print $album->artist . ' - ' . $album->title;
 277   }
 278
 279 We also provide a handy shortcut for doing a C<LIKE> search:
 280
 281   # Find albums whose artist starts with 'Jimi'
 282   my $rs = MyApp::DB::Album->search_like({ artist => 'Jimi%' });
 283
 284 Or you can provide your own C<WHERE> clause, like:
 285
 286   # Find Peter Frampton albums from the year 1986
 287   my $where = 'artist = ? AND year = ?';
 288   my @bind  = ( 'Peter Frampton', 1986 );
 289   my $rs    = $schema->resultset('Album')->search_literal( $where, @bind );
 290
 291 The preferred way to generate complex queries is to provide a
 292 L<SQL::Abstract> construct to C<search>:
 293
 294   my $rs = $schema->resultset('Album')->search({
 295     artist  => { '!=', 'Janis Joplin' },
 296     year    => { '<' => 1980 },
 297     albumid => [ 1, 14, 15, 65, 43 ]
 298   });
 299
 300 This results in something like the following C<WHERE> clause:
 301
 302   WHERE artist != 'Janis Joplin'
 303     AND year < 1980
 304     AND albumid IN (1, 14, 15, 65, 43)
 305
 306 For more examples of complex queries, see
 307 L<DBIx::Class::Manual::Cookbook>.
 308
 309 The search can also be modified by passing another hash with
 310 attributes:
 311
 312   my @albums = MyApp::DB::Album->search(
 313     { artist => 'Bob Marley' },
 314     { rows => 2, order_by => 'year DESC' }
 315   );
 316
 317 C<@albums> then holds the two most recent Bob Marley albums.
 318
 319 For a complete overview of the available attributes, see
 320 L<DBIx::Class::ResultSet/ATTRIBUTES>.
 321
 322 =head1 SEE ALSO
 323
 324 =over 4
 325
 326 =item * L<DBIx::Class::Manual::Cookbook>
 327
 328 =item * L<DBIx::Class::Manual::FAQ>
 329
 330 =back
 331
 332 =cut