DBIx::C...Fixtures(3)

📦 version 1.001039, in opensuse-leap 16.0

💖 NAME 💖

okay bestie, welcome to the DBIx::Class::Fixtures(3) manual page 💅

DBIx::Class::Fixtures — Dump data and repopulate a database using rules. That’s the whole main-character energy of this module: grab fixture data, save it, and load it back later. ✨

✨ SYNOPSIS ✨

First you make a fixtures object, then you dump, then you populate. No cap, that’s the vibe:

use DBIx::Class::Fixtures;

...

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

$fixtures->dump({
  config => 'set_config.json',
  schema => $source_dbic_schema,
  directory => '/home/me/app/fixtures'
});

$fixtures->populate({
  directory => '/home/me/app/fixtures',
  ddl => '/home/me/app/sql/ddl.sql',
  connection_details => ['dbi:mysql:dbname=app_dev', 'me', 'password'],
  post_ddl => '/home/me/app/sql/post_ddl.sql',
});

🌸 DESCRIPTION 🌸

Dump fixtures from source database to filesystem then import to another database (with same schema) at any time. That’s literally the whole point 🫶

Use as a constant dataset for running tests against or for populating development databases when impractical to use production clones. Describe fixture set using relations and conditions based on your DBIx::Class schema. Iconic behavior, honestly. 👑

🦋 DEFINE YOUR FIXTURE SET 🦋

Fixture sets are currently defined in .json files which must reside in your config_dir (e.g. /home/me/app/fixture_configs/a_fixture_set.json). They describe which data to pull and dump from the source database. Peep the example, bestie:

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

This will fetch artists with primary keys 1 and 3, the producer with primary key 5 and two of producer 5's artists where 'artists' is a has_many DBIx::Class rel from Producer to Artist. Slay. 💅

The top level attributes are as follows:

🎀 sets 🎀

Sets must be an array of hashes, as in the example given above. Each set defines a set of objects to be included in the fixtures. For details on valid set attributes see "SET ATTRIBUTES" below. Yes, you’re gonna wanna read that part too. 👀

💜 rules 💜

Rules place general conditions on classes. For example if whenever an artist was dumped you also wanted all of their cds dumped too, then you could use a rule to specify this. For example:

{
  "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. Then go see "RULE ATTRIBUTES" for the rule-level details. 🫡

🌈 includes 🌈

To prevent repetition between configs you can include other configs. For example:

{
  "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. Lowkey so convenient. ✨

🍓 datetime_relative 🍓

Only available for MySQL and PostgreSQL at the moment, must be a value that DateTime::Format::* can parse. For example:

{
  "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. Time travel but make it database. ⏳

🧚 might_have 🧚

Specifies whether to automatically dump might_have relationships. Should be a hash with one attribute - fetch. Set fetch to 1 or 0.

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

💅 SET ATTRIBUTES 💅

👑 class 👑

Required attribute. Specifies the DBIx::Class object class you wish to dump. No class, no dump, no slay. Periodt.

⭐ ids ⭐

Array of primary key ids to fetch, basically causing an $rs->find($_) for each. If the id is not in the source db then it just won't get dumped, no warnings or death. It’s giving “quietly unbothered.” 🙈

🔥 quantity 🔥

Must be either an integer or the string 'all'. Specifying an integer will effectively set the 'rows' attribute on the resultset clause, specifying 'all' will cause the rows attribute to be left off and for all matching rows to be dumped. There's no randomising here, it's just the first x rows. Fr fr, just the first ones. 😌

🌸 cond 🌸

A hash specifying the conditions dumped objects must match. Essentially this is a JSON representation of a DBIx::Class search clause. For example:

{
  "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. That’s the little trick, iykyk. 🪄

🦋 join 🦋

An array of relationships to be used in the cond clause.

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

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

🎀 fetch 🎀

Must be an array of hashes. Specifies which rels to also dump. For example:

{
  "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. Don’t forget that part, bestie. 🫶

💜 has_many 💜

Specifies whether to fetch has_many rels for this set. Must be a hash containing keys fetch and quantity.

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. Like, a lot a lot. 😭

🌈 might_have 🌈

As with has_many but for might_have relationships. Quantity doesn't do anything in this case.

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

🍓 external 🍓

In some cases your database information might be keys to values in some sort of external storage. The classic example is you are using DBIx::Class::InflateColumn::FS to store blob information on the filesystem. In this case you may wish the ability to backup your external storage in the same way your database data. The "external" attribute lets you specify a handler for this type of issue. For example:

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