Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DBIx::Class::Schema::PUseraContributed PerDBIx::Class::Schema::PopulateMore(3)

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

VERSION
       Version 0.19

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 the 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, "<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.

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

	   perldoc DBIx::Class::Schema::PopulateMore

       You can also look for information at:

       o   RT: CPAN's request tracker

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

       o   AnnoCPAN: Annotated CPAN documentation

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

       o   CPAN	Ratings

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

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

perl v5.24.1			  2014-10-DBIx::Class::Schema::PopulateMore(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | ARGUMENT NOTES | AUTHOR | BUGS | SUPPORT | ACKNOWLEDGEMENTS | COPYRIGHT & LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=DBIx::Class::Schema::PopulateMore&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help