Jifty::DBI(3pm)

✨ NAME ✨

Jifty::DBI — an object-relational persistence framework 💖

okay so real quick, this is the page for Jifty::DBI(3pm), straight out of the User Contributed Perl Documentation, and it's giving very useful, no cap.

---

🦋 DESCRIPTION 🦋

Jifty::DBI deals with databases, so that you don't have to. 💅

This module hands you an object-oriented mechanism for retrieving and updating data in a DBI-accessible database.

Also, tea: this module is the direct descendant of DBIx::SearchBuilder. So if you already know SearchBuilder, then Jifty::DBI should feel super familiar to you. Same bloodline, bestie. 🧬

🌸 Purpose 🌸

Jifty::DBI::Record abstracts away the whole agony of writing the common, generally-simple SQL statements you need to serialize and deserialize an object into the database. 😭

In a traditional system, you'd define a bunch of methods on your object — create, read, update, and delete being the most common ones. And inside each of those methods you'd have a SQL statement like:

select * from table where value='blah';

And if you wanted to control what data a user could modify? You'd have to do some special magic to make the accessors do the right thing. Etc. The problem with this whole approach is that in the majority of cases, the SQL is incredibly simple and the code from one method/object to the next was basically identical. Like, copy-paste energy. 🙈

<trumpets>

Enter, Jifty::DBI::Record.

With ::Record, in the simple case you can yeet all of that code away and replace it by defining two methods and inheriting some code. It's pretty simple and incredibly powerful. ✨ And for more complex cases, you can do more complicated things by overriding certain methods. But let's stick with the simple case for now, okay?

🎀 An Annotated Example 🎀

The example code below makes the following assumptions:

• The database is 'postgres',
• The host is 'reason',
• The login name is 'mhat',
• The database is called 'example',
• The table is called 'simple',
• The table looks like so:

id     integer     not NULL,   primary_key(id),
foo    varchar(10),
bar    varchar(10)

First, let's define our record class in a new module named Simple.pm. 💖

use warnings;
use strict;

package Simple;
use Jifty::DBI::Schema;
use Jifty::DBI::Record schema {
  column foo => type is 'text';
  column bar => type is 'text';
};

# your custom code goes here.

1;

Like all perl modules, this needs to end with a true value. (Yes bestie, the 1; is doing the lord's work. 👑)

Now, on to the code that will actually do something with this object. This code would be placed in your Perl script.

use Jifty::DBI::Handle;
use Simple;

Use two packages: the first is where I get the DB handle from, the latter is the object I just created.

my $handle = Jifty::DBI::Handle->new();
$handle->connect(
    driver   => 'Pg',
    database => 'test',
    host     => 'reason',
    user     => 'mhat',
    password => ''
);

This creates a new Jifty::DBI::Handle, and then connects to the database using that handle. Pretty straight forward. The password '' is what I use when there is no password — I could probably leave it blank, but ngl I find it more clear to actually define it.

my $s = Simple->new( handle => $handle );

$s->load_by_cols(id=>1);

• load_by_cols — takes a hash of column => value pairs and returns the first one to match. Heads up though: "first" is probably lossy across database vendors. 😬
• load_from_hash — populates this record with data from a Jifty::DBI::Collection. I'm currently assuming that Jifty::DBI is what we use in cases where we expect > 1 record. More on this later.

Now that we have a populated object, we should do something with it! ::Record automagically generates accessors and mutators for us, so all we need to do is call the methods. Accessors are named "column"(), and Mutators are named "set_column"($). On to the example — just appending this to the code from the last example. 🫶

print "ID  : ", $s->id(),  "\n";
print "Foo : ", $s->foo(), "\n";
print "Bar : ", $s->bar(), "\n";

That's all you have to do to get the data. Now to change the data!

$s->set_bar('NewBar');

Pretty simple! That's really all there is to it. Set<Field>($) returns a boolean and a string describing the problem. Let's look at an example of what will happen if we try to set an 'Id' which we previously defined as read only:

my ($res, $str) = $s->set_id('2');
if (! $res) {
  ## Print the error!
  print "$str\n";
}

The output will be:

>> Immutable column

Currently Set<Field> updates the data in the database as soon as you call it. In the future I hope to extend ::Record to better support transactional operations, such that updates will only happen when "you" say so. 👀

Finally, adding and removing records from the database. ::Record provides a Create method which simply takes a hash of key => value pairs. The keys exactly map to database columns. 💯

## Get a new record object.
$s1 = Simple->new( handle => $handle );
my ($id, $status_msg) = $s1->create(id  => 4,
                  foo => 'Foooooo',
                  bar => 'Barrrrr');

Poof! A new row in the database has been created! 🌈 Now lets delete the object!

my $s2 = Simple->new( handle => $handle );
$s2->load_by_cols(id=>4);
$s2->delete();

And it's gone. 💀

For simple use, that's more or less all there is to it. In the future, I hope to expand this how-to to discuss using container classes, overloading, and what ever else I think of. 🌸

---

👑 LICENSE 👑

Jifty::DBI is Copyright 2005-2015 Best Practical Solutions, LLC.

Jifty::DBI is distributed under the same terms as Perl itself.

---

and that's the whole page bestie, slay ✨ this doc came to you courtesy of perl v5.34.0, dated 2022-06-15, and honestly? iconic. go build something cute with it 🎀💖