sets

rules

 {
   "sets": [
     {
       "class": "Artist",
       "ids": ["1", "3"]
     },
     {
       "class": "Producer",
       "ids": ["5"],
       "fetch": [
         {
           "rel": "artists",
           "quantity": "2"
         }
       ]
     }
   ],
   "rules": {
     "Artist": {
       "fetch": [ {
         "rel": "cds",
         "quantity": "all"
       } ]
     }
   }
 }

In this case all the cds of artists 1, 3 and all producer 5's artists will be dumped as well. Note that 'cds' is a has_many DBIx::Class relation from Artist to CD. This is eqivalent to:

 {
   "sets": [
    {
       "class": "Artist",
       "ids": ["1", "3"],
       "fetch": [ {
         "rel": "cds",
         "quantity": "all"
       } ]
     },
     {
       "class": "Producer",
       "ids": ["5"],
       "fetch": [ {
         "rel": "artists",
         "quantity": "2",
         "fetch": [ {
           "rel": "cds",
           "quantity": "all"
         } ]
       } ]
     }
   ]
 }

rules must be a hash keyed by class name.

"RULE ATTRIBUTES"

includes

 {
   "sets": [ {
     "class": "Producer",
     "ids": ["5"]
   } ],
   "includes": [
     { "file": "base.json" }
   ]
 }

Includes must be an arrayref of hashrefs where the hashrefs have key 'file' which is the name of another config file in the same directory. The original config is merged with its includes using Hash::Merge.

datetime_relative

 {
   "sets": [ {
     "class": "RecentItems",
     "ids": ["9"]
   } ],
   "datetime_relative": "2007-10-30 00:00:00"
 }

This will work when dumping from a MySQL database and will cause any datetime fields (where datatype => 'datetime' in the column def of the schema class) to be dumped as a DateTime::Duration object relative to the date specified in the datetime_relative value. For example if the RecentItem object had a date field set to 2007-10-25, then when the fixture is imported the field will be set to 5 days in the past relative to the current time.

might_have

 {
   "might_have": { "fetch": 1 },
   "sets": [
     {
       "class": "Artist",
       "ids": ["1", "3"]
     },
     {
       "class": "Producer",
       "ids": ["5"]
     }
   ]
 }

Note: belongs_to rels are automatically dumped whether you like it or not, this is to avoid FKs to nowhere when importing. General rules on has_many rels are not accepted at this top level, but you can turn them on for individual sets - see "SET ATTRIBUTES".

class

ids

quantity

cond

 {
   "sets": [{
     "class": "Artist",
     "quantiy": "all",
     "cond": { "name": "Dave" }
   }]
 }

This will dump all artists whose name is 'dave'. Essentially $artist_rs->search({ name => 'Dave' })->all.

Sometimes in a search clause it's useful to use scalar refs to do things like:

 $artist_rs->search({ no1_singles => \'> no1_albums' })

This could be specified in the cond hash like so:

 {
   "sets": [ {
     "class": "Artist",
     "quantiy": "all",
     "cond": { "no1_singles": "\> no1_albums" }
   } ]
 }

So if the value starts with a backslash the value is made a scalar ref before being passed to search.

join

 {
   "sets": [ {
     "class": "Artist",
     "quantiy": "all",
     "cond": { "cds.position": { ">": 4 } },
     "join": ["cds"]
   } ]
 }

Fetch all artists who have cds with position greater than 4.

fetch

 {
   "sets": [ {
     "class": "Artist",
     "ids": ["1", "3"],
     "fetch": [ {
       "rel": "cds",
       "quantity": "3",
       "cond": { "position": "2" }
     } ]
   } ]
 }

Will cause the cds of artists 1 and 3 to be dumped where the cd position is 2.

Valid attributes are: 'rel', 'quantity', 'cond', 'has_many', 'might_have' and 'join'. rel is the name of the DBIx::Class rel to follow, the rest are the same as in the set attributes. quantity is necessary for has_many relationships, but not if using for belongs_to or might_have relationships.

has_many

Set fetch to 1 if you want to fetch them, and quantity to either 'all' or an integer.

Be careful here, dumping has_many rels can lead to a lot of data being dumped.

might_have

This value will be inherited by all fetches in this set. This is not true for the has_many attribute.

external

    {
        "sets": [{
            "class": "Photo",
            "quantity": "all",
            "external": {
                "file": {
                    "class": "File",
                    "args": {"path":"__ATTR(photo_dir)__"}
                }
            }
        }]
    }

This would use DBIx::Class::Fixtures::External::File to read from a directory where the path to a file is specified by the "file" field of the "Photo" source. We use the uninflated value of the field so you need to completely handle backup and restore. For the common case we provide DBIx::Class::Fixtures::External::File and you can create your own custom handlers by placing a '+' in the namespace:

    "class": "+MyApp::Schema::SomeExternalStorage",

Although if possible I'd love to get patches to add some of the other common types (I imagine storage in MogileFS, Redis, etc or even Amazon might be popular.)

See DBIx::Class::Fixtures::External::File for the external handler interface.

cond

fetch

join

has_many

might_have

ENV

ATTR

catfile

catdir

new

Arguments: \%$attrs

Return Value: $fixture_object

Returns a new DBIx::Class::Fixture object. %attrs can have the following parameters:

config_dir:

required. must contain a valid path to the directory in which your .json configs reside.

debug:

determines whether to be verbose

ignore_sql_errors:

ignore errors on import of DDL etc

config_attrs

A hash of information you can use to do replacements inside your configuration sets. For example, if your set looks like:

   {
     "sets": [ {
       "class": "Artist",
       "ids": ["1", "3"],
       "fetch": [ {
         "rel": "cds",
         "quantity": "__ATTR(quantity)__",
       } ]
     } ]
   }

    my $fixtures = DBIx::Class::Fixtures->new( {
      config_dir => '/home/me/app/fixture_configs'
      config_attrs => {
        quantity => 100,
      },
    });
    

You may wish to do this if you want to let whoever runs the dumps have a bit more control

 my $fixtures = DBIx::Class::Fixtures->new( {
   config_dir => '/home/me/app/fixture_configs'
 } );

available_config_sets

dump

Arguments: \%$attrs

Return Value: 1

 $fixtures->dump({
   config => 'set_config.json', # config file to use. must be in the config
                                # directory specified in the constructor
   schema => $source_dbic_schema,
   directory => '/home/me/app/fixtures' # output directory
 });

or

 $fixtures->dump({
   all => 1, # just dump everything that's in the schema
   schema => $source_dbic_schema,
   directory => '/home/me/app/fixtures', # output directory
   #excludes => [ qw/Foo MyView/ ], # optionally exclude certain sources
 });

In this case objects will be dumped to subdirectories in the specified directory. For example:

 /home/me/app/fixtures/artist/1.fix
 /home/me/app/fixtures/artist/3.fix
 /home/me/app/fixtures/producer/5.fix

"schema" and "directory" are required attributes. also, one of "config" or "all" must be specified.

The optional parameter "excludes" takes an array ref of source names and can be used to exclude those sources when dumping the whole schema. This is useful if you have views in there, since those do not need fixtures and will currently result in an error when they are created and then used with "populate".

Lastly, the "config" parameter can be a Perl HashRef instead of a file name. If this form is used your HashRef should conform to the structure rules defined for the JSON representations.

dump_config_sets

The parameters are the same as for "dump" except instead of a "directory" parameter we have a "directory_template" which is a coderef expected to return a scalar that is a root directory where we will do the actual dumping. This coderef get three arguments: $self, $params and $set_name. For example:

    $fixture->dump_all_config_sets({
      schema => $schema,
      configs => [qw/one.json other.json/],
      directory_template => sub {
        my ($fixture, $params, $set) = @_;
        return io->catdir('var', 'fixtures', $params->{schema}->version, $set);
      },
    });

dump_all_config_sets

    my %local_params = %$params;
    my $local_self = bless { %$self }, ref($self);
    $local_params{directory} = $directory_template->($self, \%local_params, $set);
    $local_params{config} = $set;
    $self->dump(\%local_params);

Works just like "dump" but instead of specifying a single json config set located in "config_dir" we dump each set in turn to the specified directory.

The parameters are the same as for "dump" except instead of a "directory" parameter we have a "directory_template" which is a coderef expected to return a scalar that is a root directory where we will do the actual dumping. This coderef get three arguments: $self, $params and $set_name. For example:

    $fixture->dump_all_config_sets({
      schema => $schema,
      directory_template => sub {
        my ($fixture, $params, $set) = @_;
        return io->catdir('var', 'fixtures', $params->{schema}->version, $set);
      },
    });

populate

Arguments: \%$attrs

Return Value: 1

 $fixtures->populate( {
   # directory to look for fixtures in, as specified to dump
   directory => '/home/me/app/fixtures',

   # DDL to deploy
   ddl => '/home/me/app/sql/ddl.sql',

   # database to clear, deploy and then populate
   connection_details => ['dbi:mysql:dbname=app_dev', 'me', 'password'],

   # DDL to deploy after populating records, ie. FK constraints
   post_ddl => '/home/me/app/sql/post_ddl.sql',

   # use CASCADE option when dropping tables
   cascade => 1,

   # optional, set to 1 to run ddl but not populate
   no_populate => 0,

   # optional, set to 1 to run each fixture through ->create rather than have
   # each $rs populated using $rs->populate. Useful if you have overridden new() logic
   # that effects the value of column(s).
   use_create => 0,

   # optional, same as use_create except with find_or_create.
   # Useful if you are populating a persistent data store.
   use_find_or_create => 0,

   # Dont try to clean the database, just populate over whats there. Requires
   # schema option. Use this if you want to handle removing old data yourself
   # no_deploy => 1
   # schema => $schema
 } );

In this case the database app_dev will be cleared of all tables, then the specified DDL deployed to it, then finally all fixtures found in /home/me/app/fixtures will be added to it. populate will generate its own DBIx::Class schema from the DDL rather than being passed one to use. This is better as custom insert methods are avoided which can to get in the way. In some cases you might not have a DDL, and so this method will eventually allow a $schema object to be passed instead.

If needed, you can specify a post_ddl attribute which is a DDL to be applied after all the fixtures have been added to the database. A good use of this option would be to add foreign key constraints since databases like Postgresql cannot disable foreign key checks.

If your tables have foreign key constraints you may want to use the cascade attribute which will make the drop table functionality cascade, ie 'DROP TABLE $table CASCADE'.

"directory" is a required attribute.

If you wish for DBIx::Class::Fixtures to clear the database for you pass in "dll" (path to a DDL sql file) and "connection_details" (array ref of DSN, user and pass).

If you wish to deal with cleaning the schema yourself, then pass in a "schema" attribute containing the connected schema you wish to operate on and set the "no_deploy" attribute.