NAME
   DBIx::Class::Schema::PopulateMore - An enhanced populate method

VERSION
   Version 0.15

SYNOPSIS
   The following is 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 have 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
   This is a DBIx::Class::Schema component that provides an enhanced
   version of the builtin method "populate" in DBIx::Class::Schema. What it
   does is make it easier when you are doing a first time setup and need to
   insert a bunch of rows, like the first time you deploy a new database,
   or after you update it.

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

   Most of us using DBIx::CLass have written a version of this at one time
   or another. What is special to this component is the fact that unlike
   the normal populate method you can insert to multiple result_sources in
   one go. While doing this, we index the created rows so as to make it
   easy to reference them in relationships. I did this because I think it's
   very ugly to have to type in all the primary keys by hand, 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.

   This distribution supplies three expansion commands:

   Index
       Use for creating relationships. This is 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 from key
       part of the data hash.

   Env Get's 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. Will use a 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.) 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.

   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.

   '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.

AUTHOR
   John Napiorkowski, "<[email protected]>"

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.

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-Populate
       More>

   *   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.

LICENSE & COPYRIGHT
   Copyright 2008-2010, John Napiorkowski <[email protected]>

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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.