3 DBIx::Class::Manual::Intro
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.
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.
16 =head2 Setting it up manually
18 First, you'll need a base class. It should inherit from DBIx::Class
22 use base qw/DBIx::Class/;
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.
30 __PACKAGE__->load_components(qw/Core DB/);
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
35 __PACKAGE__->load_components(qw/PK::Auto::SQLite Core DB/);
37 Once you've loaded the components, it's time to set up your connection:
39 __PACKAGE__->connection('dbi:SQLite:/home/me/myapp/my.db');
41 This method is similar to the normal L<DBI>, and can take user/pass/dbi
42 attribute hash as well as the dsn.
44 With that out of the way, we can define our first table class:
46 package MyApp::DB::Frob
48 use base qw/MyApp::DB/;
50 Then we specify which table it uses,
52 __PACKAGE__->table('frob');
54 and specify which columns it has.
56 __PACKAGE__->add_columns(qw/id foo bar/);
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.
61 Also, you need to tell it which column is the primary key:
63 __PACKAGE__->set_primary_key('id');
65 If you have multiple primary keys, just pass a list instead.
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>.
71 =head2 Using L<DBIx::Class::Loader>.
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:
79 use DBIx::Class::Loader;
81 my $loader=DBIx::Class::Loader->new(
82 dsn => 'dbi:SQLite:/home/me/myapp/my.db',
83 namespace => 'MyApp::DB');
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.
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:
95 my $frob=MyApp::DB::Frob->find(14);
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
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.
107 Just like with L<Class::DBI>, you do an 'update' to commit your changes
112 If needed, you can drop your local changes instead like this:
114 $frob->discard_changes if $frob->is_changed;
116 As you can see, is_changed allows you to check if there are local changes to
119 =head2 Adding and removing rows.
121 To make a new row, and put it into the database, you can use the 'create'
122 method from L<DBIx::Class::Row>
124 my $new_thingie=MyApp::DB::Frob->create({
128 likewise, you can remove if from the database like this:
130 $new_thingie->delete();
132 or even without retrieving first. This operation takes the same kind of
133 arguments as a search.
135 MyApp::DB::Frob->delete({foo=>'bart'});
137 =head2 Finding your objects.
139 DBIx::Class provides a few different ways to retrieve data from your database.
140 The simplest looks something like this:
142 $rs=MyApp::DB::Frob->search(foo=>'bart');
144 note that all the search methods return a recordset in scalar context or
145 a list containing all the elements in list context.
147 We also provide a handy shortcut for doing a like search:
149 $rs=MyApp::DB::Frob->search_like(foo=>'bar%');
151 Or you can provide your own handmade WHERE clause, like
153 $rs=MyApp::DB::Frob->search_literal('foo=?','bart');
155 The other way to provide more complex queries, is to provide a
156 L<SQL::Abstract> construct to search:
158 $rs=MyApp::DB::Frob->search({
161 id => [1,14,15,65,43]
164 The search can also be modifyed by passing another hash with attributes:
166 $rs=MyApp::DB::Frob->search( {foo=>'bart'},
167 { page=>1, rows=>2, order_by=>'bar' } );
169 For a complete overview over the available attributes, see
170 L<DBIx::Class::ResultSet>