ruby script/plugin install http://svn.geeksomnia.com/rathole/trunk/

=== Manually Specifying Primary Keys

This example may look familiar:

  george:
    id: 1
    name: George the Monkey

  reginald:
    id: 2
    name: Reginald the Pirate

Bleh. Remember DRY? This ain't. Each of these fixtures has two unique identifiers: one for the database and one for the humans. Rather than specifying it inline, Rathole generates the primary key of each fixture by hashing its label. No more explicit PK's!

  george: # generated id: 503576764
    name: George the Monkey

  reginald: # generated id: 324201669
    name: Reginald the Pirate

Rathole looks at the fixture's model class, discovers the correct primary key, and generates it right before inserting the fixture into the database.

Rathole's generated ID for a given label is constant, so we can discover the PK of any fixture without loading it. This is incredibly useful when we're trying to fix...

=== Out-of-sync and Opaque +belongs_to+ and +habtm+ Foreign Keys

Specifying FK's in fixtures smells bad. Not only is it pretty darn fragile, it's really hard to tell what the key is pointing at! Since Rathole can figure out the ID of a fixture from its label, we can easily specify FK's by label instead of ID.

==== belongs_to

Let's break out some more monkeys and pirates.

  ### in pirates.yml
  
  reginald:
    id: 1
    name: Reginald the Pirate
    monkey_id: 1
  
  ### in monkeys.yml
  
  george:
    id: 1
    name: George the Monkey
    pirate_id: 1

It's pretty obvious that a Pirate +belongs_to+ a Monkey, and vice versa, and it's easy to see how things get confusing: Separate these examples into two files, add a few more monkeys and pirates, and it's almost impossible to keep the sacred bonds of monkey and pirate organized. Time to rathole this mofo.

  ### in pirates.yml

  reginald:
    name: Reginald the Pirate
    monkey: george

  ### in monkeys.yml

  george:
    name: George the Monkey
    pirate: reginald

Pow! All is made clear. Rathole reflects on the fixture's model class, finds all the +belongs_to+ associations, and allows you to specify a target *label* for the *association* (monkey: george) rather than a target *id* for the *FK* (monkey_id: 1).

Okay, so +belongs_to+ (and, by extension, +has_many+ and +has_one+), but what about...

==== has_and_belongs_to_many

Join table fixtures are *really* unpleasant to maintain, so Rathole makes them go away. Time to give our monkey some fruit.

  ### in monkeys.yml
  
  george:
    id: 1
    name: George the Monkey
    pirate_id: 1

  ### in fruits.yml
  
  apple:
    id: 1
    name: apple

  orange:
    id: 2
    name: orange

  grape:
    id: 3
    name: grape
  
  ### in fruits_monkeys.yml
  
  apple_george:
    fruit_id: 1
    monkey_id: 1

  orange_george:
    fruit_id: 2
    monkey_id: 1

  grape_george:
    fruit_id: 3
    monkey_id: 1

Holy cow. Tons of duplication, and if we want to know the answer to a simple data question ("Hey, what fruits does george have?"), we have to consult three different files. Even then, it's pretty darn easy to get out-of-sync labels or ID's. Let's see what we can do:

  ### in monkeys.yml

  george:
    name: George the Monkey
    pirate: reginald
    fruits: apple, orange, grape

  ### in fruits.yml

  apple:
    name: apple

  orange:
    name: orange

  grape:
    name: grape

Zap! No more fruits_monkeys.yml file. I've specified the list of fruits on George's fixture, but I could've just as easily specified a list of monkeys on each fruit. As with +belongs_to+, Rathole reflects on the fixture's model class and discovers the +has_and_belongs_to_many+ associations.

No more join table fixture files! Join me in doing the dance of clarity.

=== Timestamps

This one's pretty darn simple: If your table/model specifies any of Rails' standard timestamp columns (created_at, created_on, updated_at, updated_on), Rathole will automatically set them to Time.now.

If you've set specific values, don't worry: Rathole will leave them alone.

=== Default Values

You probably already know how to use YAML to set and reuse defaults in your +database.yml+ file, but Rathole lets you use the same technique in your fixtures.

  DEFAULTS: &DEFAULTS
    created_on: <%= 3.weeks.ago.to_s(:db) %>
    
  first:
    name: Smurf
    <<<%= Fixtures.identify(:reginald) %>
    pirate_id: <%= Fixtures.identify(:george) %>

There is currently no advanced documentation for this plugin.