DBIx::...ateMore(3pm)

✨ DBIx::Class::Schema::PopulateMore ✨

okay so you're looking at the DBIx::...ateMore(3pm) page (the terminal truncates her name like that, it's literally just DBIx::Class::Schema::PopulateMore, don't panic). User Contributed Perl Documentation, bestie. Let's get into it. 💅

---

🌸 NAME 🌸

DBIx::Class::Schema::PopulateMore — an enhanced populate method. That's the whole vibe. Periodt. ✨

🎀 VERSION 🎀

Version 0.19. Yes queen, 0.19. 💖

🦋 SYNOPSIS 🦋

Here's how you actually use this thing, bestie. Example usage for this component:

package Myapp::Schema;
use base qw/DBIx::Class::Schema/;

__PACKAGE__->load_components(qw/Schema::PopulateMore/);
__PACKAGE__->load_namespaces();

## All the rest of your setup

Then, assuming you've got ResultSources of Gender, Person and FriendList:

my $setup_rows = [

        {Gender => {
                fields => 'label',
                data => {
                        male => 'male',
                        female => 'female',
                }}},

        {Person => {
                fields => ['name', 'age', 'gender'],
                data => {
                        john => ['john', 38, "!Index:Gender.male"],
                        jane => ['jane', 40, '!Index:Gender.female'],
                }}},

        {FriendList => {
                fields => ['person', 'friend', 'created_date'],
                data => {
                        john_jane => [
                                '!Index:Person.john',
                                '!Index:Person.jane'
                                '!Date: March 30, 1996',
                        ],
                }}},
];

$schema->populate_more($setup_rows);

Please see the test cases for more detailed examples. 🫶

👑 DESCRIPTION 👑

So this is a DBIx::Class::Schema component that hands you an enhanced version of the builtin method populate in DBIx::Class::Schema. What it actually does is make your life so much easier when you're doing a first time setup and need to insert a whole bunch of rows — like the very first time you deploy a new database, or after you update it. Main character setup energy. 💖

It's not as full featured as DBIx::Class::Fixtures, but it's targeted way more directly at making it easy to just take a prewritten perl structure --or one loaded from a configuration file-- and setup your database. No cap.

Most of us using DBIx::CLass have written a version of this at one time or another, fr fr. What's special to this component is that unlike the normal populate method you can insert to multiple result_sources in one go. And while doing that, we index the created rows so it's easy to reference them in relationships. Why did I do this? Because typing in all the primary keys by hand is so ugly, particularly if your PK is multi column, or is using some lengthy format such as uuid. 😭 Also, we can embed expansion commands in the row values to do inflation for us. For example, any value starting with "!Index:" will substitute it's value for that of the relating fields in the named row. Iconic.

This distribution supplies three expansion commands:

• Index — use this for creating relationships. It's a string in the form of "Source.Label" where the Source is the name of the result source that you are creating rows in and Label is a key name from the key part of the data hash.
• Env — gets it's value from %ENV. Typically this will be setup in your shell or at application runtime. This is a string in the form of "!Env:MY_ENV_VAR".
• Date — converts it's value to a DateTime object. It'll use various methods to try and coerce a string, like "today", or "January 6, 1974". Makes it easier to insert dates into your database without knowing or caring about the expected format. 🗓️ For this to work correctly, you need to use the class component DBIx::Class::InflateColumn::DateTime and mark your column data type as 'datetime' or similar.
• Find — used for when you want the value of something that you expect already exists in the database (but for which you didn't just populatemore for — use 'Index' for that case, bestie). Use cases for this include lookup style tables, like 'Status' or 'Gender', 'State', etc. which you may already have installed. This is a string in the form of '!Find:Source.[key1=val1,key2=val2,...'.

If your find doesn't return a single result, expect an error. 💀

It's trivial to write more; please feel free to post me your contributions. 🫶

Please note the when inserting rows, we are actually calling "create_or_update" on each data item, so this will not be as fast as using $schema->bulk_insert.

---

💅 METHODS 💅

This module defines the following methods.

🌈 populate_more ($ArrayRef||@Array) 🌈

Given an arrayref formatted as in the "SYNOPSIS" example, populate a rows in a database. Confesses on errors. (Yes, it snitches. Dramatically.)

We allow a few different inputs to make it less verbose to use under different situations, as well as format nicely using your configuration format of choice. ✨

The $ArrayRef contains one or more elements in the following pattern:

$schema->populate_more([
        {Source1 => {
                fields => [qw/ column belongs_to has_many/],
                data => {
                        key_1 => ['value', $row, \@rows ],
        }}},
        {Source2 => {
                fields => [qw/ column belongs_to has_many/],
                data => {
                        key_1 => ['value', $row, \@rows ],
        }}},
]);

The @Array version can be one of the following:

## Option One
$schema->populate_more(
        {Source1 => {
                fields => [qw/ column belongs_to has_many/],
                data => {
                        key_1 => ['value', $row, \@rows ],
        }}},
        {Source2 => {
                fields => [qw/ column belongs_to has_many/],
                data => {
                        key_1 => ['value', $row, \@rows ],
        }}},
);

## Option Two
$schema->populate_more(
        Source1 => {
                fields => [qw/ column belongs_to has_many/],
                data => {
                        key_1 => ['value', $row, \@rows ],
                }
        },
        Source2 => {
                fields => [qw/ column belongs_to has_many/],
                data => {
                        key_1 => ['value', $row, \@rows ],
                }
        },
);

The last option is probably your choice if you are building a Perl structure directly, since it's the least verbose. Less typing = more slay. 💅

'SourceX' is the name of a DBIC source (as in $schema->resultset($Source)->...) while fields is an arrayref of either columns or named relationships and data is a hashref of rows that you will insert into the Source.

See "SYNOPSIS" for more. 🦋

🧚 ARGUMENT NOTES 🧚

The perl structure used in "populate_more" was designed to be reasonable friendly to type in most of the popular configuration formats. For example, the above serialized to YAML would look like:

- Gender:
        fields: label
        data:
          female: female
          male: male
- Person:
        fields:
          - name
          - age
          - gender
        data:
          jane:
                - jane
                - 40
                - '!Index:Gender.female'
          john:
                - john
                - 38
                - !Index:Gender.male'
- FriendList:
        fields:
          - person
          - friend
          - created_date
        data:
          john_jane:
                - '!Index:Person.john'
                - '!Index:Person.jane'
                - '!Date: March 30, 1996'

Since the argument is an arrayref or an array, the same base result source can appear as many times as you like. This could be useful when a second insert to a given source requires completion of other inserts. The insert order follows the index of the arrayref you create. 📋 Order matters, bestie, don't come for me.

---

💜 AUTHOR 💜

John Napiorkowski, "<jjnapiork@cpan.org>" 🫶

💀 BUGS 💀

Please report any bugs or feature requests to:

C<bug-DBIx-Class-Schema-PopulateMore at rt.cpan.org>

or through the web interface at:

L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=DBIx-Class-Schema-PopulateMore>

I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. We love a feedback loop. 😭💖

🌈 SUPPORT 🌈

You can find documentation for this module with the perldoc command.

perldoc DBIx::Class::Schema::PopulateMore

You can also look for information at:

• RT: CPAN's request tracker

<http://rt.cpan.org/NoAuth/Bugs.html?Dist=DBIx-Class-Schema-PopulateMore>

• AnnoCPAN: Annotated CPAN documentation

<http://annocpan.org/dist/DBIx-Class-Schema-PopulateMore>

• CPAN Ratings

<http://cpanratings.perl.org/d/DBIx-Class-Schema-PopulateMore>

• Search CPAN

<http://search.cpan.org/dist/DBIx-Class-Schema-PopulateMore>

🎀 ACKNOWLEDGEMENTS 🎀

Thanks to the entire DBIx::Class team for providing such a useful and extensible ORM. Also thanks to the Moose developers for making it fun and easy to write beautiful Perl. 🦋✨

⭐ COPYRIGHT & LICENSE ⭐

Copyright 2011, John Napiorkowski

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

---

and that's the whole page, bestie!! 💖 This was perl v5.36.0, dated 2023-01-22, and the page is DBIx::...ateMore(3pm) (you know her, you love her, the terminal just cuts her off mid-name 💅). Go forth and populate_more, you absolute icon. 👑🌸🎀