Commit | Line | Data |
8292706e |
1 | =head1 NAME |
2 | |
3 | DBIx::Class::Manual::SchemaIntro - Introduction to DBIx::Class::Schema |
4 | |
5 | =head1 INTRODUCTION |
6 | |
7 | This document describes how to set up DBIx::Class using the recommended |
8 | schema-based approach. |
9 | |
10 | =head2 Setup |
11 | |
12 | First, you should create your base schema class, which inherits from |
13 | L<DBIx::Class::Schema>: |
14 | |
15 | package My::Schema; |
16 | use base qw/DBIx::Class::Schema/; |
17 | |
80c90f5d |
18 | In this class you load your result_source ("table", "model") classes, which |
8292706e |
19 | we will define later, using the load_classes() method. You can specify which |
20 | classes to load manually: |
21 | |
22 | # load My::Schema::Album and My::Schema::Artist |
23 | __PACKAGE__->load_classes(qw/ Album Artist /); |
24 | |
25 | Or load classes by namespace: |
26 | |
27 | # load My::Schema::Album, My::Schema::Artist and My::OtherSchema::LinerNotes |
28 | __PACKAGE__->load_classes( |
29 | { |
30 | 'My::Schema' => qw/ Album Artist /, |
31 | 'My::OtherSchema' => qw/ LinerNotes / |
32 | } |
33 | ); |
34 | |
35 | Or let your schema class load all classes in its namespace automatically: |
36 | |
37 | # load My::Schema::* |
38 | __PACKAGE__->load_classes(); |
39 | |
40 | Next, create each of the classes you want to load as specified above: |
41 | |
42 | package My::Schema::Album; |
43 | use base qw/DBIx::Class/; |
44 | |
45 | Load any components required by each class with the load_components() method. |
46 | This should consist of "Core" plus any additional components you want to use. |
47 | For example, if you use SQLite and want serial/auto-incrementing primary keys: |
48 | |
49 | __PACKAGE__->load_components(qw/ PK::Auto::SQLite Core /); |
50 | |
51 | C<PK::Auto> classes exist for many databases; see |
52 | L<DBIx::Class::PK::Auto> for more information. |
53 | |
54 | Set the table for your class: |
55 | |
56 | __PACKAGE__->table('album'); |
57 | |
58 | Add columns to your class: |
59 | |
60 | __PACKAGE__->add_columns(qw/ albumid artist title /); |
61 | |
62 | Accessors are created for each column automatically, so My::Schema::Album will |
63 | have albumid(), artist() and title() methods. |
64 | |
65 | Define a primary key for your class: |
66 | |
67 | __PACKAGE__->set_primary_key('albumid'); |
68 | |
69 | If you have a multi-column primary key, just pass a list instead: |
70 | |
71 | __PACKAGE__->set_primary_key( qw/ albumid artistid / ); |
72 | |
73 | You can define relationships for any of your classes. L<DBIx::Class> will |
74 | automatically fill in the correct namespace, so if you want to say |
75 | "a My::Schema::Album object belongs to a My::Schema::Artist object" you do not |
76 | need to include the namespace when declaring the relationship: |
77 | |
78 | __PACKAGE__->belongs_to('artist' => 'Artist'); |
79 | |
80 | That's all you need in terms of setup. |
81 | |
82 | =head2 Usage |
83 | |
84 | In your application code, you should first create a connected schema object: |
85 | |
86 | my $schema = My::Schema->connect( $dsn, $user, $password, $attrs ); |
87 | |
88 | You can create as many different schema instances as you need. So if you have |
89 | a second database you want to access: |
90 | |
91 | my $other_schema = My::Schema->connect( $dsn, $user, $password, $attrs ); |
92 | |
93 | Note that L<DBIx::Class::Schema> does not cache connnections for you. If you |
94 | use multiple connections, you need to do this manually. |
95 | |
d7c4c15c |
96 | To execute some sql statements on every connect you can pass them to your schema after the connect: |
97 | |
98 | $schema->storage->on_connect_do(\@on_connect_sql_statments); |
99 | |
8292706e |
100 | The simplest way to get a record is by primary key: |
101 | |
102 | my $schema = My::Schema->connect( ... ); |
103 | my $album = $schema->resultset('Album')->find(14); |
104 | |
105 | This will run a C<SELECT> with C<albumid = 14> in the C<WHERE> clause, |
106 | and return an instance of C<My::Schema::Album> that represents this |
107 | row. Once you have that row, you can access and update columns: |
108 | |
109 | $album->name('Physical Graffiti'); |
110 | my $title = $album->title; # holds 'Physical Graffiti' |
111 | |
112 | If you prefer, you can use the C<set_column> and C<get_column> |
113 | accessors instead: |
114 | |
115 | $album->set_column('title', 'Presence'); |
116 | $title = $album->get_column('title'); |
117 | |
118 | You use C<update> to commit your changes to the database: |
119 | |
120 | $album->update(); |
121 | |
122 | If needed, you can throw away your local changes like this: |
123 | |
124 | $album->discard_changes() if $album->is_changed(); |
125 | |
126 | As you can see, C<is_changed> allows you to check if there are local |
127 | changes to your object. |
128 | |
129 | =head2 Adding and removing rows |
130 | |
131 | To create a new record in the database, you can use the C<create> |
132 | method. It returns an instance of C<My::Schema::Album> that can be |
133 | used to access the data in the new record: |
134 | |
135 | my $new_album = $schema->resultset('Album')->create({ |
136 | title => 'Wish You Were Here', |
137 | artist => 'Pink Floyd' |
138 | }); |
139 | |
140 | Now you can add data to the new record: |
141 | |
142 | $new_album->label('Capitol'); |
143 | $new_album->year('1975'); |
144 | $new_album->update; |
145 | |
146 | Likewise, you can remove it from the database like this: |
147 | |
148 | $new_album->delete; |
149 | |
150 | You can also remove records without or retrieving first. This |
151 | operation takes the same kind of arguments as a search. |
152 | |
153 | # Delete all of Falco's albums |
154 | $schema->resultset('Album')->delete({ artist => 'Falco' }); |
155 | |
156 | =head2 Finding your objects |
157 | |
158 | L<DBIx::Class> provides a few different ways to retrieve data from |
159 | your database. Here's one example: |
160 | |
161 | # Find all of Santana's albums |
162 | my $rs = $schema->resultset('Album')->search({ artist => 'Santana' }); |
163 | |
164 | In scalar context, as above, C<search> returns a |
165 | L<DBIx::Class::ResultSet> object. It can be used to peek at the first |
166 | album returned by the database: |
167 | |
168 | my $album = $rs->first; |
169 | print $album->title; |
170 | |
171 | Or, you can loop over the albums and update each one: |
172 | |
173 | while (my $album = $rs->next) { |
174 | print $album->artist . ' - ' . $album->title; |
175 | $album->year(2001); |
176 | $album->update; |
177 | } |
178 | |
179 | For more information on what you can do with a |
180 | L<DBIx::Class::ResultSet>, see L<DBIx::Class::ResultSet/METHODS>. |
181 | |
182 | In list context, the C<search> method returns all of the matching |
183 | rows: |
184 | |
185 | # Fetch immediately all of Carlos Santana's albums |
186 | my @albums = @{ $schema->resultset('Album')->search( |
187 | { artist => 'Carlos Santana' } |
188 | ) }; |
189 | foreach my $album (@albums) { |
190 | print $album->artist . ' - ' . $album->title; |
191 | } |
192 | |
193 | We also provide a handy shortcut for doing a C<LIKE> search: |
194 | |
195 | # Find albums whose artist starts with 'Jimi' |
c31f8021 |
196 | my $rs = $schema->resultset('Album')->search_like({ artist => 'Jimi%' }); |
8292706e |
197 | |
198 | Or you can provide your own handmade C<WHERE> clause, like: |
199 | |
200 | # Find Peter Frampton albums from the year 1986 |
201 | my $where = 'artist = ? AND year = ?'; |
202 | my @bind = ( 'Peter Frampton', 1986 ); |
203 | my $rs = $schema->resultset('Album')->search_literal( $where, @bind ); |
204 | |
205 | The preferred way to generate complex queries is to provide a |
206 | L<SQL::Abstract> construct to C<search>: |
207 | |
208 | my $rs = $schema->resultset('Album')->search({ |
209 | artist => { '!=', 'Janis Joplin' }, |
210 | year => { '<' => 1980 }, |
211 | albumid => [ 1, 14, 15, 65, 43 ] |
212 | }); |
213 | |
214 | This results in something like the following C<WHERE> clause: |
215 | |
216 | WHERE artist != 'Janis Joplin' |
217 | AND year < 1980 |
218 | AND albumid IN (1, 14, 15, 65, 43) |
219 | |
220 | For more examples of complex queries, see |
221 | L<DBIx::Class::Manual::Cookbook>. |
222 | |
223 | The search can also be modified by passing another hash with |
224 | attributes: |
225 | |
226 | my @albums = $schema->resultset('Album')->search( |
227 | { artist => 'Bob Marley' }, |
228 | { rows => 2, order_by => 'year DESC' } |
229 | ); |
230 | |
231 | C<@albums> then holds the two most recent Bob Marley albums. |
232 | |
233 | For a complete overview of the available attributes, see |
234 | L<DBIx::Class::ResultSet/ATTRIBUTES>. |
235 | |
236 | =head1 SEE ALSO |
237 | |
238 | =over 4 |
239 | |
240 | =item * L<DBIx::Class::Manual::Cookbook> |
241 | |
242 | =item * L<DBIx::Class::Manual::FAQ> |
243 | |
244 | =back |
245 | |
246 | =cut |