Catmandu::Store(3pm)

✨ Catmandu::Store ✨

okay bestie, welcome to Catmandu::Store — the namespace for packages that can make data persistent 💾✨ (yes, this is a Perl thing, and yes it's from Catmandu::Store(3pm) in User Contributed Perl Documentation, iykyk)

---

🌈 SYNOPSIS 🌈

so first, the command line vibe check:

# From the command line

$ catmandu import JSON into MongoDB --database_name 'bibliography' < data.json

$ catmandu export MongoDB --database_name 'bibliography' to YAML
$ catmandu export MongoDB --database_name 'bibliography' --query '{"PublicationYear": "1937"}'
$ catmandu count  MongoDB --database_name 'bibliography' --query '{"PublicationYear": "1937"}'

and now the Perl side, where the real main character energy lives:

# From Perl
use Catmandu;

my $store = Catmandu->store('MongoDB',database_name => 'bibliography');

my $obj1 = $store->bag->add({ name => 'Patrick' });

printf "obj1 stored as %s\n" , $obj1->{_id};

# Force an id in the store
my $obj2 = $store->bag->add({ _id => 'test123' , name => 'Nicolas' });

my $obj3 = $store->bag->get('test123');

$store->bag->delete('test123');

$store->bag->delete_all;

# Some stores can be searched
my $hits = $store->bag->search(query => 'name:Patrick');

---

💖 DESCRIPTION 💖

okay so here's the tea ☕ — a Catmandu::Store is a stub for Perl packages that can store data into databases or search engines. The database as a whole? That's the 'store' 👑

But wait, there's layers bestie. Databases also have compartments (like, say, tables) and those are called Catmandu::Bag-s 🎀. And some stores can be searched using Catmandu::Searchable methods. iconic.

---

🎀 CONFIGURATION 🎀

default_plugins

Specify plugins that will be applied to every single bag in the store. all of them. no bag left behind 💅

my $store = Catmandu::Store::MyDB->new(default_plugins => ['Datestamps']);

default_bag

The name of the bag to use if no explicit bag is given. Default is 'data'.

my $store = Catmandu::Store::MyDB->new(default_bag => 'stuff');
# this will return the stuff bag
my $bag = $store->bag;

bags

Specify configuration for individual bags 👜 — so you can treat each one different, no cap.

my $store = Catmandu::Store::Hash->new(
    bags => {stuff => {plugins => ['Datestamps']}});
# this bag will use the L<Catmandu::Plugin::Datestamps> role
$store->bag('stuff')
# this bag won't
$store->bag('otherbag')

bag_class

An optional custom class to use for bags. Default is "Bag" in the store's namespace. This class should consume the Catmandu::Bag role, fr fr.

# this will use the Catmandu::Store::MyDB::Bag class for bags
Catmandu::Store::MyDB->new()
# this will use MyBag
Catmandu::Store::MyDB->new(bag_class => 'MyBag')

key_prefix

Use a custom prefix to mark the reserved or special keys that the store uses. By default an underscore gets prependend. The only special key in a normal store is '_id'. Catmandu::Plugin::Versioning will also use '_version'. Other plugins or stores may add their own special keys — the lore runs deep 🧚

# this store will use the my_id key to hold id's
Catmandu::Store::MyDB->new(key_prefix => 'my_')

id_key

Define a custom key to hold id's for all bags of this store. See "key_prefix" for the default value. Also aliased as "id_field". Note that this can also be overriden on a per bag basis 👀

---

🦋 METHODS 🦋

bag($name)

Create or retieve a bag with name $name. Returns a Catmandu::Bag. simple as that 💅

key_for($key)

Helper method that applies "key_prefix" to the $key given. cute little utility, love that for us.

log

Return the current logger. Can be used when creating your own Stores 🔥

E.g.

package Catmandu::Store::Hash;

...

sub generator {
    my ($self) = @_;

    $self->log->debug("generating record");
    ...
}

See also: Catmandu for activating the logger in your main code.

---

🌸 SEE ALSO 🌸

Catmandu::Bag, Catmandu::Searchable

---

and that's the whole page bestie, we ate and left no crumbs 🍓✨ — this little masterpiece lives in Catmandu::Store(3pm) from User Contributed Perl Documentation, running on perl v5.40.1, dated 2026-01-24. go forth and make your data persistent, you've got this 💜🫶