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
  34
  35   __PACKAGE__->load_components(qw/PK::Auto::SQLite Core DB/);
  36
  37 Once you've loaded the components, it's time to  set up your connection:
  38
  39   __PACKAGE__->connection('dbi:SQLite:/home/me/myapp/my.db');
  40
  41 This method is similar to the normal L<DBI>, and can take user/pass/dbi
  42 attribute hash as well as the dsn.
  43
  44 With that out of the way, we can define our first table class:
  45
  46   package MyApp::DB::Frob
  47
  48   use base qw/MyApp::DB/;
  49
  50 Then we specify which table it uses,
  51
  52   __PACKAGE__->table('frob');
  53
  54 and specify which columns it has.
  55
  56   __PACKAGE__->add_columns(qw/id foo bar/);
  57
  58 This will automatically create accessors for each of the columns, so that
  59 you can read/update the values in rows you've retrieved.
  60
  61 Also, you need to tell it which column is the primary key:
  62
  63   __PACKAGE__->set_primary_key('id');
  64
  65 If you have multiple primary keys, just pass a list instead.
  66
  67 That's pretty much all you need for a basic setup. If you have more advanced
  68 needs like using more than 1 database connections for the same class, see
  69 L<DBIx::Class::Schema>.
  70
  71 =head2 Using L<DBIx::Class::Loader>.
  72
  73 This is an additional class, and not part of the DBIx::Class distribution.
  74 Like L<Class::DBI::Loader>, it inspects your database, and automatically
  75 creates classes for all the tables in your database. Here's a simple setup:
  76
  77   package MyApp::DB;
  78
  79   use DBIx::Class::Loader;
  80
  81   my $loader=DBIx::Class::Loader->new(
  82       dsn       => 'dbi:SQLite:/home/me/myapp/my.db',
  83       namespace => 'MyApp::DB');
  84   1;
  85
  86 This should be equivalent to the manual in the section above.
  87 L<DBIx::Class::Loader> takes lots of other options. For more information,
  88 consult the reference documentation.
  89
  90 =head2 Basic Usage
  91
  92 Once you've defined the basic classes, you can start interacting with your
  93 database. The simplest way to get a column is by primary key:
  94
  95   my $frob=MyApp::DB::Frob->find(14);
  96
  97 This will run a select with id=14 in the WHERE clause, and return an instance
  98 of MyApp::DB::Frob that represents this row. Once you have that row, you can
  99 access and update columns
 100
 101     my $val=$frob->bar;
 102     $frob->bar(14);
 103
 104 or if you prefer, you can use the set_column/get_column accessors instead
 105 of the autogenerated accessors based on your column names.
 106
 107 Just like with L<Class::DBI>, you do an 'update' to commit your changes
 108 to the database:
 109
 110    $frob->update;
 111
 112 If needed, you can drop your local changes instead like this:
 113
 114   $frob->discard_changes if $frob->is_changed;
 115
 116 As you can see, is_changed allows you to check if there are local changes to
 117 your object.
 118
 119 =head2 Adding and removing rows.
 120
 121 To make a new row, and put it into the database, you can use the 'create'
 122 method from L<DBIx::Class::Row>
 123
 124   my $new_thingie=MyApp::DB::Frob->create({
 125     foo=>'homer',
 126     bar=>'bart' });
 127
 128 likewise, you can remove if from the database like this:
 129
 130   $new_thingie->delete();
 131
 132 or even without retrieving first. This operation takes the same kind of
 133 arguments as a search.
 134
 135   MyApp::DB::Frob->delete({foo=>'bart'});
 136
 137 =head2 Finding your objects.
 138
 139 DBIx::Class provides a few different ways to retrieve data from your database.
 140 The simplest looks something like this:
 141
 142   $rs=MyApp::DB::Frob->search(foo=>'bart');
 143
 144 note that all the search methods return a recordset in scalar context or
 145 a list containing all the elements in list context.
 146
 147 We also provide a handy shortcut for doing a like search:
 148
 149   $rs=MyApp::DB::Frob->search_like(foo=>'bar%');
 150
 151 Or you can provide your own handmade WHERE clause, like
 152
 153   $rs=MyApp::DB::Frob->search_literal('foo=?','bart');
 154
 155 The other way to provide more complex queries, is to provide a
 156 L<SQL::Abstract> construct to search:
 157
 158   $rs=MyApp::DB::Frob->search({
 159     bar=>{'>' => 10 },
 160     foo=>{'!=','bart'},
 161     id => [1,14,15,65,43]
 162   });
 163
 164 The search can also be modifyed by passing another hash with attributes:
 165
 166   $rs=MyApp::DB::Frob->search( {foo=>'bart'},
 167       { page=>1, rows=>2, order_by=>'bar' } );
 168
 169 For a complete overview over the available attributes, see
 170 L<DBIx::Class::ResultSet>
 171
 172 =cut