Commit | Line | Data |
9c82c181 |
1 | =head1 NAME |
2 | |
3b44ccc6 |
3 | DBIx::Class::Manual::Intro - Introduction to DBIx::Class |
9c82c181 |
4 | |
076652e8 |
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 |
429bd4f1 |
27 | use DB in this introduction, since it involves less magic. Schema is |
28 | mostly useful if you want to use multiple database connections. |
076652e8 |
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 | |
8918977e |
35 | __PACKAGE__->load_components(qw/PK::Auto::SQLite Core DB/); |
076652e8 |
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 |