Catman...SideCar(3pm)

💖 Catmandu::Plugin::SideCar — the Catman...SideCar(3pm) page, but make it cute 💖

okay bestie, sit down, hydrate, because this one is a bop. This is the manual page for Catmandu::Plugin::SideCar, from the 3pm section (perl module manpages, you know the vibe), living in the User Contributed Perl Documentation corner of the internet. 🫶

---

✨ NAME ✨

Catmandu::Plugin::SideCar — automatically update a parallel Catmandu::Store with metadata. it's giving two stores holding hands. 💅

---

🌸 SYNOPSIS 🌸

first up, the command line era. look at this catmandu.yml:

# Using the command line

$ cat catmandu.yml
---
store:
    files:
     package: File::Simple
     options:
         root: /data/test123
         bags:
             index:
                 plugins:
                     - SideCar
                 sidecar:
                         package: ElasticSearch
                         options:
                             client: '1_0::Direct'
                             index_name: catmandu

   ...

okay now we do things. add files to the FileStore in bag 1234:

# Add files to the FileStore in bag 1234
$ catmandu stream /tmp/test.txt to files --bag 1234 --id test.txt

then add metadata to the FileStore for bag 1234:

# Add metadata to the FileStore for bag 1234
$ cat metadata.yml
---
_id: 1234
colors:
   - red
   - green
   - blue
name: test
...
$ catmandu import YAML to files < metadata.yml

and export the metadata right back out again, iconic behaviour:

# Export the metadata again from the FileStore
$ catmandu export files to YAML
---
_id: 1234
colors:
   - red
   - green
   - blue
name: test
...

or, if you're a Perl program girlie, do it in code:

# Or in your Perl program
my $store = Catmandu->store('File::Simple',
           root => 'data/test123'
           bags => {
               index => {
                   plugins => [qw(SideCar)],
                   sidecar => {
                       package => "ElasticSearch",
                       options => {
                           client => '1_0::Direct',
                           index_name => 'catmandu',
                       }
                   }
              }
           });

my $index = $store->index;

$index->add({ _id => '1234' , colors => [qw(red green blue)] , name => 'test'});

my $files = $index->files('1234');
$files->upload(IO::File->new('</tmp/test.txt'), 'test.txt');

my $file = $files->get('text.txt');

$files->steam(IO::File->new('>/tmp/test.txt'),$file);

---

🦋 DESCRIPTION 🦋

so, Catmandu::Plugin::SideCar lets you combine Catmandu::Store-s, Catmandu::FileStore-s (and yes, also Catmandu::Store::Multi and Catmandu::Store::File::Multi, we love a polycule) into one single access point. 🎀

and the way it works? every get, add, delete, drop and commit action in the store gets executed in the original store first, and then re-executed in the SideCar store. double the execution, double the slay. two birds, one plugin. ✨

---

🌈 COMBINING A FILESTORE WITH A STORE 🌈

want to add metadata to a Catmandu::FileStore? then a SideCar needs to be added to the "index" bag of the FileStore, like so:

    package: File::Simple
    options:
        root: /data/test123
        bags:
            index:
                plugins:
                    - SideCar
                sidecar:
                        package: ElasticSearch
                        options:
                            client: '1_0::Direct'
                            index_name: catmandu
                sidecar_bag: data

---

💜 COMBINING A STORE WITH A FILESTORE 💜

now the reverse. to add files to a Catmandu::Store, a SideCar needs to be added to the bag containing the metadata — by default that bag is "data":

    package: ElasticSearch
    options:
        client: '1_0::Direct'
        index_name: catmandu
        bags:
            data:
                plugins:
                    - SideCar
                sidecar:
                        package: File::Simple
                        options:
                            root: /data/test123
                            uuid: 1
                sidecar_bag: index

heads up bestie: notice we added the required "uuid" option for the Catmandu::Store::File::Simple — that's because Catmandu::Store::ElasticSearch is using UUIDs as default identifiers. no uuid, no vibe. 💀

---

🎀 RESTRICTIONS 🎀

some Catmandu::FileStore-s may set restrictions on the "_id"-s that can be used in records. yeah. they're picky like that. respect the boundaries. 🙈

---

👑 CONFIGURATION 👑

sidecar STRING

sidecar HASH

sidecar Catmandu::Store | Catmandu::FileStore

• the pointer to a configured Catmandu::Store or Catmandu::FileStore. that's it, that's the whole thing. 💅

sidecar_bag

• the SideCar Catmandu::Bag into which to store the data — default is 'bag'. 🍓

---

⭐ SEE ALSO ⭐

• Catmandu::Store
• Catmandu::Bag
• Catmandu::FileStore

---

and that's the whole page, bestie!! this was perl v5.36.0, dated 2022-12-10, straight from the User Contributed Perl Documentation. go forth and sidecar responsibly. 🧚✨💖