`add_foreign_key` gotchas in Rails 4.2

Rails 4.2 finally added native support for database-level foreign keys, which is great. You can write the following code in a migration (assuming the presence of a users table):

def change
  create_table :posts do |t|
    t.references :user, index: true
  end
  add_foreign_key :posts, :users
end

And Rails will apply its conventions and infer what you expect:

Column   |  Type   |                     Modifiers
---------+---------+----------------------------------------------------
 id      | integer | not null default nextval('posts_id_seq'::regclass)
 user_id | integer |
Indexes:
    "posts_pkey" PRIMARY KEY, btree (id)
    "index_posts_on_user_id" btree (user_id)
Foreign-key constraints:
    "fk_rails_cbe63c1bd4" FOREIGN KEY (user_id) REFERENCES users(id)

We have a database-level foreign key pointing from the user_id column of the posts table, to the id column of the posts table. You can specify all of the expected options for the foreign key - on_delete, on_cascade, etc. This will work just fine in both PostgreSQL and MySQL - it's a no-op in every other ActiveRecord adapter (including SQLite!)

The problem is when you want to name your associations and columns more semantically - a post doesn't have a user, it has an author. So you generate your model nicely on the command line:

$ bin/rails g model Post author:references

Which generates a migration that includes:

def change
  create_table :posts do |t|
    t.references :author, index: true
  end
  add_foreign_key :posts, :authors
end

This will error out when you try to run the migration:

== [timestamp] CreatePosts: migrating =====================================
-- create_table(:posts)
   -> 0.0382s
-- add_foreign_key(:posts, :authors)
rake aborted!
StandardError: An error has occurred, this and all later migrations canceled:

PG::UndefinedTable: ERROR:  relation "authors" does not exist
: ALTER TABLE "posts" ADD CONSTRAINT "fk_rails_2cb0a9abaa"
FOREIGN KEY ("author_id")
  REFERENCES "authors" ("id")
...

Rails' automatic inference has failed - it doesn't know that our author association is actually to the users table.

To fix this, you can modify the migration before running it, and configure which column the foreign key should use, and which table the key should point to:

add_foreign_key :posts, :users, column: :author_id

And then the foreign key is created as you would expect:

  Column     |  Type   |                      Modifiers
-----------+---------+-----------------------------------------------------
 id        | integer | not null default nextval('posts_id_seq'::regclass)
 author_id | integer |
Indexes:
    "posts_pkey" PRIMARY KEY, btree (id)
    "index_posts_on_author_id" btree (author_id)
Foreign-key constraints:
    "fk_rails_5492f4e861" FOREIGN KEY (author_id) REFERENCES users(id)

Success! Rails can do some amazing things when it comes to following its conventions, but sometimes it requires a little help to take full advantage of the functionality it provides. I hope this helps someone!