File Coverage

blib/lib/Jifty/DBI.pm
Criterion Covered Total %
statement 6 6 100.0
branch n/a
condition n/a
subroutine 2 2 100.0
pod n/a
total 8 8 100.0


line stmt bran cond sub pod time code
1             package Jifty::DBI;
2 1     1   4036 use warnings;
  1         2  
  1         59  
3 1     1   7 use strict;
  1         2  
  1         111  
4              
5             $Jifty::DBI::VERSION = '0.77';
6              
7             =head1 NAME
8              
9             Jifty::DBI - An object-relational persistence framework
10              
11             =head1 DESCRIPTION
12              
13             Jifty::DBI deals with databases, so that you don't have to.
14              
15             This module provides an object-oriented mechanism for retrieving and
16             updating data in a DBI-accessible database.
17              
18             This module is the direct descendant of L. If you're familiar
19             with SearchBuilder, Jifty::DBI should be quite familiar to you.
20              
21             =head2 Purpose
22              
23             Jifty::DBI::Record abstracts the agony of writing the common and generally
24             simple SQL statements needed to serialize and deserialize an object to the
25             database. In a traditional system, you would define various methods on
26             your object 'create', 'read', 'update', and 'delete' being the most common.
27             In each method you would have a SQL statement like:
28              
29             select * from table where value='blah';
30              
31             If you wanted to control what data a user could modify, you would have to
32             do some special magic to make accessors do the right thing. Etc. The
33             problem with this approach is that in a majority of the cases, the SQL is
34             incredibly simple and the code from one method/object to the next was
35             basically the same.
36              
37            
38              
39             Enter, Jifty::DBI::Record.
40              
41             With ::Record, you can in the simple case, remove all of that code and
42             replace it by defining two methods and inheriting some code. It's pretty
43             simple and incredibly powerful. For more complex cases, you can
44             do more complicated things by overriding certain methods. Let's stick with
45             the simple case for now.
46              
47              
48              
49             =head2 An Annotated Example
50              
51             The example code below makes the following assumptions:
52              
53             =over 4
54              
55             =item *
56              
57             The database is 'postgres',
58              
59             =item *
60              
61             The host is 'reason',
62              
63             =item *
64              
65             The login name is 'mhat',
66              
67             =item *
68              
69             The database is called 'example',
70              
71             =item *
72              
73             The table is called 'simple',
74              
75             =item *
76              
77             The table looks like so:
78              
79             id integer not NULL, primary_key(id),
80             foo varchar(10),
81             bar varchar(10)
82              
83             =back
84              
85             First, let's define our record class in a new module named "Simple.pm".
86              
87             use warnings;
88             use strict;
89              
90             package Simple;
91             use Jifty::DBI::Schema;
92             use Jifty::DBI::Record schema {
93             column foo => type is 'text';
94             column bar => type is 'text';
95             };
96              
97             # your custom code goes here.
98              
99             1;
100              
101             Like all perl modules, this needs to end with a true value.
102              
103             Now, on to the code that will actually *do* something with this object.
104             This code would be placed in your Perl script.
105              
106             use Jifty::DBI::Handle;
107             use Simple;
108              
109             Use two packages, the first is where I get the DB handle from, the latter
110             is the object I just created.
111              
112              
113             my $handle = Jifty::DBI::Handle->new();
114             $handle->connect(
115             driver => 'Pg',
116             database => 'test',
117             host => 'reason',
118             user => 'mhat',
119             password => ''
120             );
121              
122             Creates a new Jifty::DBI::Handle, and then connects to the database using
123             that handle. Pretty straight forward, the password '' is what I use
124             when there is no password. I could probably leave it blank, but I find
125             it to be more clear to define it.
126              
127              
128             my $s = Simple->new( handle => $handle );
129              
130             $s->load_by_cols(id=>1);
131              
132              
133             =over
134              
135             =item load_by_cols
136              
137             Takes a hash of column => value pairs and returns the *first* to match.
138             First is probably lossy across databases vendors.
139              
140             =item load_from_hash
141              
142             Populates this record with data from a Jifty::DBI::Collection. I'm
143             currently assuming that Jifty::DBI is what we use in
144             cases where we expect > 1 record. More on this later.
145              
146             =back
147              
148             Now that we have a populated object, we should do something with it! ::Record
149             automagically generates accessors and mutators for us, so all we need to do
150             is call the methods. accessors are named C(), and Mutators are named
151             C($). On to the example, just appending this to the code from
152             the last example.
153              
154              
155             print "ID : ", $s->id(), "\n";
156             print "Foo : ", $s->foo(), "\n";
157             print "Bar : ", $s->bar(), "\n";
158              
159             That's all you have to to get the data, now to change the data!
160              
161              
162             $s->set_bar('NewBar');
163              
164             Pretty simple! That's really all there is to it. Set($) returns
165             a boolean and a string describing the problem. Lets look at an example of
166             what will happen if we try to set a 'Id' which we previously defined as
167             read only.
168              
169             my ($res, $str) = $s->set_id('2');
170             if (! $res) {
171             ## Print the error!
172             print "$str\n";
173             }
174              
175             The output will be:
176              
177             >> Immutable column
178              
179             Currently Set updates the data in the database as soon as you call
180             it. In the future I hope to extend ::Record to better support transactional
181             operations, such that updates will only happen when "you" say so.
182              
183             Finally, adding and removing records from the database. ::Record provides a
184             Create method which simply takes a hash of key => value pairs. The keys
185             exactly map to database columns.
186              
187             ## Get a new record object.
188             $s1 = Simple->new( handle => $handle );
189             my ($id, $status_msg) = $s1->create(id => 4,
190             foo => 'Foooooo',
191             bar => 'Barrrrr');
192              
193             Poof! A new row in the database has been created! Now lets delete the
194             object!
195              
196             my $s2 = Simple->new( handle => $handle );
197             $s2->load_by_cols(id=>4);
198             $s2->delete();
199              
200             And it's gone.
201              
202             For simple use, that's more or less all there is to it. In the future, I hope to expand
203             this how-to to discuss using container classes, overloading, and what
204             ever else I think of.
205              
206             =head1 LICENSE
207              
208             Jifty::DBI is Copyright 2005-2010 Best Practical Solutions, LLC.
209             Jifty::DBI is distributed under the same terms as Perl itself.
210              
211             =cut
212              
213             1;