New DB2 Automagic primary key collecting
[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / Manual / Intro.pod
CommitLineData
9c82c181 1=head1 NAME
2
3b44ccc6 3DBIx::Class::Manual::Intro - Introduction to DBIx::Class
9c82c181 4
076652e8 5=head1 Introduction.
6
7So, you are bored with SQL, and want a native perl interface for your classes?
8Or you've been doing this for a while with L<Class::DBI>, and think there's
9a better way? You've come to the right place. Let's look at how you can set
10and use your first native DBIx::Class tree.
11
12First we'll see how you can set up your classes yourself. If you want them
13to be auto-discovered, just skip to the next section, which shows you how
14to use DBIx::Class::Loader.
15
16=head2 Setting it up manually
17
18First, you'll need a base class. It should inherit from DBIx::Class
19like this:
20
21 package MyApp::DB
22 use base qw/DBIx::Class/;
23
24You will also want to load some of L<DBIx::Class>'s components.
25L<DBIx::Class::Core> provides a good basic set. In addition you'll
26have to use either L<DBIx::Class::Schema> or L<DBIx::Class::DB> We'll
429bd4f1 27use DB in this introduction, since it involves less magic. Schema is
28mostly useful if you want to use multiple database connections.
076652e8 29
30 __PACKAGE__->load_components(qw/Core DB/);
31
32If you want serial/auto-incremental primary keys, you'll need to add
dfeba824 33the apropriate component for your db as well, for example. The
34PK::Auto::* modules help L<DBIx::Class> keep up with newly generated
35keys in auto increment database fields.
076652e8 36
8918977e 37 __PACKAGE__->load_components(qw/PK::Auto::SQLite Core DB/);
076652e8 38
39Once you've loaded the components, it's time to set up your connection:
40
41 __PACKAGE__->connection('dbi:SQLite:/home/me/myapp/my.db');
42
43This method is similar to the normal L<DBI>, and can take user/pass/dbi
44attribute hash as well as the dsn.
45
46With that out of the way, we can define our first table class:
47
dfeba824 48 package MyApp::DB::Album;
076652e8 49
50 use base qw/MyApp::DB/;
51
52Then we specify which table it uses,
53
dfeba824 54 __PACKAGE__->table('album');
076652e8 55
56and specify which columns it has.
57
dfeba824 58 __PACKAGE__->add_columns(qw/albumID artist title label year/);
076652e8 59
60This will automatically create accessors for each of the columns, so that
61you can read/update the values in rows you've retrieved.
62
63Also, you need to tell it which column is the primary key:
64
dfeba824 65 __PACKAGE__->set_primary_key('albumID');
076652e8 66
67If you have multiple primary keys, just pass a list instead.
68
69That's pretty much all you need for a basic setup. If you have more advanced
70needs like using more than 1 database connections for the same class, see
71L<DBIx::Class::Schema>.
72
73=head2 Using L<DBIx::Class::Loader>.
74
75This is an additional class, and not part of the DBIx::Class distribution.
76Like L<Class::DBI::Loader>, it inspects your database, and automatically
77creates classes for all the tables in your database. Here's a simple setup:
78
79 package MyApp::DB;
80
81 use DBIx::Class::Loader;
82
dfeba824 83 my $loader = DBIx::Class::Loader->new(
84 dsn => 'dbi:SQLite:/home/me/myapp/my.db',
85 namespace => 'MyApp::DB');
076652e8 86 1;
87
88This should be equivalent to the manual in the section above.
89L<DBIx::Class::Loader> takes lots of other options. For more information,
90consult the reference documentation.
91
92=head2 Basic Usage
93
94Once you've defined the basic classes, you can start interacting with your
95database. The simplest way to get a column is by primary key:
96
dfeba824 97 $albumID = 14;
98 $album = MyApp::DB::Album->find($albumID);
076652e8 99
dfeba824 100This will run a select with albumID=14 in the WHERE clause, and return an instance
101of MyApp::DB::Artist that represents this row. Once you have that row, you can
076652e8 102access and update columns
103
dfeba824 104 $album->title('Physical Graffiti');
105 $title = $album->title; # $title holds 'Physical Graffiti'
076652e8 106
107or if you prefer, you can use the set_column/get_column accessors instead
108of the autogenerated accessors based on your column names.
109
110Just like with L<Class::DBI>, you do an 'update' to commit your changes
111to the database:
112
dfeba824 113 $album->update;
076652e8 114
115If needed, you can drop your local changes instead like this:
116
dfeba824 117 $album->discard_changes if $album->is_changed;
076652e8 118
119As you can see, is_changed allows you to check if there are local changes to
120your object.
121
122=head2 Adding and removing rows.
123
dfeba824 124To create a new record in the database, you can use the 'create'
125method from L<DBIx::Class::Row>. It returns a L<DBIx::Class::ResultSet>
126object that can be used to access the data in the new record.
076652e8 127
dfeba824 128 $new_album = MyApp::DB::Album->create({
129 title => 'Wish You Were Here',
130 artist => 'Pink Floyd'
131 });
132
133Now you can add data to the new record:
134
135 $new_album->label('Capitol');
136 $new_album->year('1975');
076652e8 137
138likewise, you can remove if from the database like this:
139
dfeba824 140 $new_album->delete();
076652e8 141
142or even without retrieving first. This operation takes the same kind of
143arguments as a search.
144
dfeba824 145 MyApp::DB::Album->delete({ artist => 'Falco' });
076652e8 146
147=head2 Finding your objects.
148
149DBIx::Class provides a few different ways to retrieve data from your database.
150The simplest looks something like this:
151
dfeba824 152 $album = MyApp::DB::Album->search( artist => 'Santana' );
076652e8 153
dfeba824 154note that all the search methods return a L<DBIx::Class::ResultSet> object
155in scalar context or a list containing all the records in list context.
076652e8 156
dfeba824 157We also provide a handy shortcut for doing a "like" search:
076652e8 158
dfeba824 159 $album = MyApp::DB::Album->search_like( artist => 'Jimi%');
076652e8 160
161Or you can provide your own handmade WHERE clause, like
162
dfeba824 163 $album = MyApp::DB::Album->search_literal('artist=?','Peter Frampton');
076652e8 164
165The other way to provide more complex queries, is to provide a
166L<SQL::Abstract> construct to search:
167
dfeba824 168 $album = MyApp::DB::Album->search({
169 artist => { '!=', 'Janis Joplin' },
170 year => { '<' => 1980 },
171 id => [ 1, 14, 15, 65, 43 ]
076652e8 172 });
173
174The search can also be modifyed by passing another hash with attributes:
175
dfeba824 176 $album = MyApp::DB::Album->search(
177 { artist => 'Bob Marley' },
178 { page => 1, rows => 2, order_by => 'year' }
179 );
076652e8 180
181For a complete overview over the available attributes, see
182L<DBIx::Class::ResultSet>
183
184=cut