lib/DBIx/Class/Manual/Intro.pod

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