Commit | Line | Data |
113e8d16 |
1 | =head1 NAME |
2 | |
3 | DBIx::Class::Manual::QuickStart - up and running with DBIC in 10 minutes |
4 | |
5 | =head1 DESCRIPTION |
6 | |
7 | This document shows the minimum amount of code to make you a productive DBIC |
8 | user. It requires you to be familiar with just the basics of database |
9 | programming (what database tables, rows and columns are) and the basics of |
10 | Perl object-oriented programming (calling methods on an object instance). |
11 | It also helps if you already know a bit of SQL and how to connect to a |
12 | database through DBI. |
13 | |
14 | Follow along with the example database shipping with this distribution, |
15 | see directory F<examples/Schema>. This database is also used through-out the |
16 | rest of the documentation. |
17 | |
18 | =head2 Preparation |
19 | |
20 | First, install DBIx::Class like you do with any other CPAN distribution. |
21 | See L<http://www.cpan.org/modules/INSTALL.html> and L<perlmodinstall>. |
22 | |
23 | Then open the distribution in your shell and change to the subdirectory |
24 | mentioned earlier, the next command will download and unpack it: |
25 | |
26 | $ perl -mCPAN -e'CPAN::Shell->look("DBIx::Class")' |
27 | DBIx-Class$ cd examples/Schema |
28 | |
29 | Inspect the database: |
30 | |
31 | DBIx-Class/examples/Schema$ echo .dump | sqlite3 db/example.db |
32 | |
33 | You can also use a GUI database browser such as |
34 | L<SQLite Manager|https://addons.mozilla.org/firefox/addon/sqlite-manager>. |
35 | |
a5bd5d88 |
36 | Have a look at the schema classes files in the subdirectory F<MyApp>. The |
37 | C<MyApp::Schema> class is the entry point for loading the other classes and |
113e8d16 |
38 | interacting with the database through DBIC and the C<Result> classes correspond |
39 | to the tables in the database. L<DBIx::Class::Manual::Example> shows how to |
40 | write all that Perl code. That is almost never necessary, though. Instead use |
41 | L<dbicdump> (part of the distribution C<DBIx-Class-Schema-Loader>) to |
42 | automatically create schema classes files from an existing database. The |
43 | chapter L</"Resetting the database"> below shows an example invocation. |
44 | |
45 | =head2 Connecting to the database |
46 | |
47 | A L<schema|DBIx::Class::Manual::Glossary/Schema> object represents the database. |
48 | |
a5bd5d88 |
49 | use MyApp::Schema qw(); |
50 | my $schema = MyApp::Schema->connect('dbi:SQLite:db/example.db'); |
113e8d16 |
51 | |
52 | The first four arguments are the same as for L<DBI/connect>. |
53 | |
54 | =head2 Working with data |
55 | |
56 | Almost all actions go through a |
57 | L<resultset|DBIx::Class::Manual::Glossary/ResultSet> object. |
58 | |
59 | =head3 Adding data |
60 | |
61 | Via intermediate result objects: |
62 | |
63 | my $artist_ma = $schema->resultset('Artist')->create({ |
64 | name => 'Massive Attack', |
65 | }); |
66 | my $cd_mezz = $artist_ma->create_related(cds => { |
67 | title => 'Mezzanine', |
68 | }); |
69 | for ('Angel', 'Teardrop') { |
70 | $cd_mezz->create_related(tracks => { |
71 | title => $_ |
72 | }); |
73 | } |
74 | |
75 | Via relation accessors: |
76 | |
77 | $schema->resultset('Artist')->create({ |
78 | name => 'Metallica', |
79 | cds => [ |
80 | { |
81 | title => q{Kill 'Em All}, |
82 | tracks => [ |
83 | { title => 'Jump in the Fire' }, |
84 | { title => 'Whiplash' }, |
85 | ], |
86 | }, |
87 | { |
88 | title => 'ReLoad', |
89 | tracks => [ |
90 | { title => 'The Memory Remains' }, |
91 | { title => 'The Unforgiven II' }, |
92 | { title => 'Fuel' }, |
93 | ], |
94 | }, |
95 | ], |
96 | }); |
97 | |
98 | Columns that are not named are filled with default values. The value C<undef> |
99 | acts as a C<NULL> in the database. |
100 | |
101 | See the chapter L</"Introspecting the schema classes"> below to find out where |
102 | the non-obvious source name strings such as C<Artist> and accessors such as |
103 | C<cds> and C<tracks> come from. |
104 | |
105 | Set the environment variable C<DBI_TRACE='1|SQL'> to see the generated queries. |
106 | |
107 | =head3 Retrieving data |
108 | |
109 | Set up a condition. |
110 | |
111 | my $artists_starting_with_m = $schema->resultset('Artist')->search( |
112 | { |
113 | name => { like => 'M%' } |
114 | } |
115 | ); |
116 | |
a5bd5d88 |
117 | Iterate over result objects of class C<MyApp::Schema::Result::Artist>. |
113e8d16 |
118 | L<Result|DBIx::Class::Manual::Glossary/Result> objects represent a row and |
119 | automatically get accessors for their column names. |
120 | |
121 | for my $artist ($artists_starting_with_m->all) { |
122 | say $artist->name; |
123 | } |
124 | |
125 | =head3 Changing data |
126 | |
127 | Change the release year of all CDs titled I<ReLoad>. |
128 | |
129 | $schema->resultset('Cd')->search( |
130 | { |
131 | title => 'ReLoad', |
132 | } |
133 | )->update_all( |
134 | { |
135 | year => 1997, |
136 | } |
137 | ); |
138 | |
139 | =head3 Removing data |
140 | |
141 | Removes all tracks titled I<Fuel> regardless of which CD the belong to. |
142 | |
143 | $schema->resultset('Track')->search( |
144 | { |
145 | title => 'Fuel', |
146 | } |
147 | )->delete_all; |
148 | |
149 | =head2 Introspecting the schema classes |
150 | |
151 | This is useful for getting a feel for the naming of things in a REPL or during |
152 | explorative programming. |
153 | |
154 | From the root to the details: |
155 | |
156 | $schema->sources; # returns qw(Cd Track Artist) |
157 | $schema->source('Cd')->columns; # returns qw(cdid artist title year) |
158 | $schema->source('Cd')->relationships; # returns qw(artist tracks) |
159 | |
160 | From a detail to the root: |
161 | |
162 | $some_result->result_source; # returns appropriate source |
163 | $some_resultset->result_source; |
164 | $some_resultsource->schema; # returns appropriate schema |
165 | |
166 | =head2 Resetting the database |
167 | |
168 | # delete database file |
169 | DBIx-Class/examples/Schema$ rm -f db/example.db |
170 | |
171 | # create database and set up tables from definition |
172 | DBIx-Class/examples/Schema$ sqlite3 db/example.db < db/example.sql |
173 | |
174 | # fill them with data |
175 | DBIx-Class/examples/Schema$ perl ./insertdb.pl |
176 | |
177 | # delete the schema classes files |
a5bd5d88 |
178 | DBIx-Class/examples/Schema$ rm -rf MyApp |
113e8d16 |
179 | |
180 | # recreate schema classes files from database file |
181 | DBIx-Class/examples/Schema$ dbicdump \ |
a5bd5d88 |
182 | -o dump_directory=. MyApp::Schema dbi:SQLite:db/example.db |
113e8d16 |
183 | |
184 | =head2 Where to go next |
185 | |
186 | If you want to exercise what you learned with a more complicated schema, |
187 | load L<Northwind|http://code.google.com/p/northwindextended/> into your |
188 | database. |
189 | |
190 | If you want to transfer your existing SQL knowledge, read |
191 | L<DBIx::Class::Manual::SQLHackers>. |
192 | |
193 | Continue with L<DBIx::Class::Tutorial> and |
194 | L<DBIx::Class/"WHERE TO START READING">. |