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 classes?
   8 Or you've been doing this for a while with L<Class::DBI>, and think there's
   9 a better way? You've come to the right place. Let's look at how you can set
  10 and use your first native DBIx::Class tree.
  11
  12 First we'll see how you can set up your classes yourself. If you want them
  13 to be auto-discovered, just skip to the next section, which shows you how
  14 to use 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 DB in this introduction, since it involves less magic. Schema is
  28 mostly useful if you want to use multiple database connections.
  29
  30   __PACKAGE__->load_components(qw/Core DB/);
  31
  32 If you want serial/auto-incremental primary keys, you'll need to add
  33 the apropriate component for your db as well, for example. The
  34 PK::Auto::* modules help L<DBIx::Class> keep up with newly generated
  35 keys in auto increment database fields.
  36
  37   __PACKAGE__->load_components(qw/PK::Auto::SQLite Core DB/);
  38
  39 Once you've loaded the components, it's time to  set up your connection:
  40
  41   __PACKAGE__->connection('dbi:SQLite:/home/me/myapp/my.db');
  42
  43 This method is similar to the normal L<DBI>, and can take user/pass/dbi
  44 attribute hash as well as the dsn.
  45
  46 With that out of the way, we can define our first table class:
  47
  48   package MyApp::DB::Album;
  49
  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 that
  61 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 advanced
  70 needs like using more than 1 database connections for the same class, see
  71 L<DBIx::Class::Schema>.
  72
  73 =head2 Using L<DBIx::Class::Loader>.
  74
  75 This is an additional class, and not part of the DBIx::Class distribution.
  76 Like L<Class::DBI::Loader>, it inspects your database, and automatically
  77 creates classes for all the tables in your database. Here's a simple setup:
  78
  79   package MyApp::DB;
  80
  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   1;
  87
  88 This should be equivalent to the manual in the section above.
  89 L<DBIx::Class::Loader> takes lots of other options. For more information,
  90 consult the reference documentation.
  91
  92 =head2 Basic Usage
  93
  94 Once you've defined the basic classes, you can start interacting with your
  95 database. The simplest way to get a column is by primary key:
  96
  97   $albumID = 14;
  98   $album = MyApp::DB::Album->find($albumID);
  99
 100 This will run a select with albumID=14 in the WHERE clause, and return an instance
 101 of MyApp::DB::Artist that represents this row. Once you have that row, you can
 102 access and update columns
 103
 104   $album->title('Physical Graffiti');
 105   $title = $album->title;   # $title holds 'Physical Graffiti'
 106
 107 or if you prefer, you can use the set_column/get_column accessors instead
 108 of the autogenerated accessors based on your column names.
 109
 110 Just like with L<Class::DBI>, you do an 'update' to commit your changes
 111 to the database:
 112
 113   $album->update;
 114
 115 If needed, you can drop your local changes instead like this:
 116
 117   $album->discard_changes if $album->is_changed;
 118
 119 As you can see, is_changed allows you to check if there are local changes to
 120 your object.
 121
 122 =head2 Adding and removing rows.
 123
 124 To create a new record in the database, you can use the 'create'
 125 method from L<DBIx::Class::Row>.  It returns a L<DBIx::Class::ResultSet>
 126 object that can be used to access the data in the new record.
 127
 128   $new_album = MyApp::DB::Album->create({
 129                 title => 'Wish You Were Here',
 130                 artist => 'Pink Floyd'
 131   });
 132
 133 Now you can add data to the new record:
 134
 135   $new_album->label('Capitol');
 136   $new_album->year('1975');
 137
 138 likewise, you can remove if from the database like this:
 139
 140   $new_album->delete();
 141
 142 or even without retrieving first. This operation takes the same kind of
 143 arguments as a search.
 144
 145   MyApp::DB::Album->delete({ artist => 'Falco' });
 146
 147 =head2 Finding your objects.
 148
 149 DBIx::Class provides a few different ways to retrieve data from your database.
 150 The simplest looks something like this:
 151
 152   $album = MyApp::DB::Album->search( artist => 'Santana' );
 153
 154 note that all the search methods return a L<DBIx::Class::ResultSet> object
 155 in scalar context or a list containing all the records in list context.
 156
 157 We also provide a handy shortcut for doing a "like" search:
 158
 159   $album = MyApp::DB::Album->search_like( artist => 'Jimi%');
 160
 161 Or you can provide your own handmade WHERE clause, like
 162
 163   $album = MyApp::DB::Album->search_literal('artist=?','Peter Frampton');
 164
 165 The other way to provide more complex queries, is to provide a
 166 L<SQL::Abstract> construct to search:
 167
 168   $album = MyApp::DB::Album->search({
 169         artist => { '!=', 'Janis Joplin' },
 170         year => { '<' => 1980 },
 171         id => [ 1, 14, 15, 65, 43 ]
 172   });
 173
 174 The search can also be modifyed by passing another hash with attributes:
 175
 176   $album = MyApp::DB::Album->search(
 177                 { artist => 'Bob Marley' },
 178                 { page => 1, rows => 2, order_by => 'year' }
 179   );
 180
 181 For a complete overview over the available attributes, see
 182 L<DBIx::Class::ResultSet>
 183
 184 =cut