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

FreeBSD Manual Pages


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

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

       Version 0.19

       The following is	example	usage for this component.

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


	       ## 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 => [
					       '!Date: March 30, 1996',


       Please see the test cases for more detailed examples.

       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:

	   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

	   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.

	   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

       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.

       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;

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

       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
			 female: female
			 male: male
	       - Person:
			 - name
			 - age
			 - gender
			       - jane
			       - 40
			       - '!Index:Gender.female'
			       - john
			       - 38
			       - !Index:Gender.male'
	       - FriendList:
			 - person
			 - friend
			 - created_date
			       - '!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.

       John Napiorkowski, "<>"

       Please report any bugs or feature requests to:

	       C<bug-DBIx-Class-Schema-PopulateMore at>

       or through the web interface at:


       I will be notified, and then you'll automatically be notified of
       progress	on your	bug as I make changes.

       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


       o   AnnoCPAN: Annotated CPAN documentation


       o   CPAN	Ratings


       o   Search CPAN


       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 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)


Want to link to this manual page? Use this URL:

home | help