Commit | Line | Data |
076652e8 |
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 |
429bd4f1 |
23 | use DB in this introduction, since it involves less magic. Schema is |
24 | mostly useful if you want to use multiple database connections. |
076652e8 |
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/Core DB PK::Auto::SQLite/); |
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 |