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