DBIx::...iokuDB(3pm)

💖 DBIx::Class::Schema::KiokuDB 💖

okay bestie, gather round, because today we're talking about DBIx::Class::Schema::KiokuDB — the hybrid KiokuDB / DBIx::Class::Schema support situation. it's giving "my database schema and my object store are dating" and honestly? iconic. 🫶

this one's from the User Contributed Perl Documentation, and it's version 1.23, periodt. ✨

---

🌈 VERSION 🌈

version 1.23 — yes, that's the one, no cap. 💅

---

✨ SYNOPSIS ✨

first things first: you gotta load this component into your schema, like so:

package MyApp::DB;
use base qw(DBIx::Class::Schema);

__PACKAGE__->load_components(qw(Schema::KiokuDB));

__PAKCAGE__->load_namespaces;

ngl, yes, __PAKCAGE__ is spelled like that in here. i'm not fixing it, i'm not touching it, it's not my business. copy it exactly as it is and we move on. 💀

then you load the DBIx::Class::KiokuDB component into every single table that wants to be able to refer to arbitrary KiokuDB objects. every. one. that wants it. 🎀

package MyApp::DB::Result::Album;
use base qw(DBIx::Class::Core);

__PACKAGE__->load_components(qw(KiokuDB));

__PACKAGE__->table('album');

__PACKAGE__->add_columns(
    id => { data_type => "integer" },
    title => { data_type => "varchar" },

    # the foreign key for the KiokuDB object:
    metadata => { data_type => "varchar" },
);

__PACKAGE__->set_primary_key('id');

# enable a KiokuDB rel on the column:
__PACKAGE__->kiokudb_column('metadata');

see that metadata column? that's the little doorway where your arbitrary KiokuDB object lives. and kiokudb_column('metadata') is you unlocking it. 🔑

next: connect to the DSN, bestie:

my $dir = KiokuDB->connect(
    'dbi:SQLite:dbname=:memory:',
    schema => "MyApp::DB",
    create => 1,
);

# get the connect DBIC schema instance
my $schema = $dir->backend->schema;

look at you, grabbing the DBIC schema instance straight off $dir->backend->schema. main character energy fr fr.

and then — and this is the fun part — you can freely refer to KiokuDB objects from your Album class:

$dir->txn_do(scope => 1, body => sub {

    $schema->resultset("Album")->create({
        title => "Blah blah",
        metadata => $any_object,
    });
});

and $any_object can literally be any object. the range. it's giving freedom. 🦋

---

🌸 DESCRIPTION 🌸

so what is this class, actually? this class provides the schema definition support code required for integrating an arbitrary DBIx::Class::Schema with KiokuDB::Backend::DBI. that's the whole job. it's the glue, and it's doing the most. 💜

🎀 REUSING AN EXISTING DBIx::Class SCHEMA 🎀

okay so the example up in the Synopsis assumes you want to first set up a KiokuDB and then link it to some DBIx::Class classes. makes sense, cute, we love that for you.

but there's another use case, and it's lowkey the relatable one: you already have a configured DBIx::Class Schema, and now you want to tack KiokuDB onto it. like, you're not rebuilding anything, you're just adding. obsessed. ✨

the trick here is to make sure you load the KiokuDB schema using __PACKAGE__->define_kiokudb_schema() in your Schema class:

package MyApp::DB;
use base qw(DBIx::Class::Schema);

__PACKAGE__->load_components(qw(Schema::KiokuDB));
__PACKAGE__->define_kiokudb_schema();

__PAKCAGE__->load_namespaces;

and now you can get the KiokuDB directory handle like so:

my $dir = $schema->kiokudb_handle;

one line!! one line and you have a handle!! 😭💖

and if you want a complete example, go take a look at t/autovivify_handle.t. it's right there. iykyk. 👑

---

🔥 USAGE AND LIMITATIONS 🔥

okay here's the real talk section, so listen up:

• KiokuDB managed objects may hold references to row objects, resultsets (which are treated as saved searches — the results or the cursor state gets saved), result source handles, and the schema itself.
• Foreign DBIx::Class objects — meaning ones that originated from a schema that isn't the underlying schema — are currently not supported. but!! this limitation may be lifted in the future, so don't lose hope bestie. 🙈
• All DBIC operations which may implicitly cause a lookup of a KiokuDB managed object require live object scope management, just as normal. no skipping that step, no shortcuts. 💅

it is recommended to use txn_do in KiokuDB, because that will invoke the appropriate transaction hooks on both layers — as opposed to just in DBIx::Class. so like, use it. please. for me. 🥺

---

💫 SEE ALSO 💫

• DBIx::Class::KiokuDB
• KiokuDB::Backend::DBI

go read them, they're the supporting cast and they ate. 🌟

---

👑 AUTHOR 👑

Yuval Kogman <nothingmuch@woobling.org>

---

🍓 COPYRIGHT AND LICENSE 🍓

This software is copyright (c) 2014 by Yuval Kogman, Infinity Interactive.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

and that's the whole page, bestie!! 🌈🎀

this was perl v5.34.0, dated 2022-05-24, and yes the module name up top is DBIx::Class::Schema::KiokuDB even though the running header keeps chopping it into DBIx::...iokuDB(3pm) like it's too iconic to fit. slay. 💅✨

go build something hybrid. you got this. 🫶