From 080bd83df9ee96845370a73d6152bbe5f231f618 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rafael=20Mendon=C3=A7a=20Fran=C3=A7a?=
 <rafaelmfranca@gmail.com>
Date: Fri, 27 Jan 2012 14:57:43 -0200
Subject: Add `create_join_table` migration helper to create HABTM join tables

---
 railties/guides/source/migrations.textile | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

(limited to 'railties/guides/source/migrations.textile')

diff --git a/railties/guides/source/migrations.textile b/railties/guides/source/migrations.textile
index 66160f8b26..c11f8e221b 100644
--- a/railties/guides/source/migrations.textile
+++ b/railties/guides/source/migrations.textile
@@ -114,6 +114,7 @@ database independent way (you'll read about them in detail later):
 * +change_column+
 * +change_table+
 * +create_table+
+* +create_join_table+
 * +drop_table+
 * +remove_column+
 * +remove_index+
@@ -384,6 +385,35 @@ end
 will append +ENGINE=BLACKHOLE+ to the SQL statement used to create the table
 (when using MySQL, the default is +ENGINE=InnoDB+).
 
+h4. Creating a Join Table
+
+Migration method +create_join_table+ creates a HABTM join table. A typical use
+would be
+
+<ruby>
+create_join_table :products, :categories
+</ruby>
+
+which creates a +categories_products+ table with two columns called +category_id+ and +product_id+.
+These columns have the option +:null+ set to +false+ by default.
+
+You can pass the option +:table_name+ with you want to customize the table name. For example,
+
+<ruby>
+create_join_table :products, :categories, :table_name => :categorization
+</ruby>
+
+will create a +categorization+ table.
+
+By default, +create_join_table+ will create two columns with no options, but you can specify these
+options using the +:column_options+ option. For example,
+
+<ruby>
+create_join_table :products, :categories, :column_options => {:null => true}
+</ruby>
+
+will create the +product_id+ and +category_id+ with the +:null+ option as +true+.
+
 h4. Changing Tables
 
 A close cousin of +create_table+ is +change_table+, used for changing existing
-- 
cgit v1.2.3

