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