Skip to content
This repository
Browse code

adding some documentation of the Active Record conventions and reserv…

…ed words.
  • Loading branch information...
commit 67ed370d8e69133bc48abd8185d002f60226990e 1 parent e6b1674
authored October 23, 2008
54  railties/doc/guides/source/active_record_basics.txt
@@ -19,10 +19,56 @@ By following a few simple conventions the Rails Active Record will automatically
19 19
 * Classes & Database Tables
20 20
 * Class attributes & Database Table Columns
21 21
 
22  
-Here are the key conventions to consider when using Active Record:
23  
-Class Names are Singular: e.g. “Post, Item, BookClub, Subscriber”.
24  
-Tables names are the lowercase plural name of the class name e.g. “posts, items, book_clubs, subscribers”
25  
-Notice in the case of the BookClub class that the individual words in database table name is separated using an underscore “book_clubs”.
  22
+=== Rails Active Record Conventions
  23
+Here are the key conventions to consider when using Active Record.
  24
+
  25
+==== Naming Conventions
  26
+Database Table - Plural with underscores separating words i.e. (book_clubs)
  27
+Model Class - Singular with the first letter of each word capitalized i.e. (BookClub) 
  28
+Here are some additional Examples:
  29
+[grid="all"]
  30
+`-------------`---------------
  31
+Model / Class Table / Schema
  32
+Post          posts
  33
+LineItem      line_items
  34
+Deer          deer
  35
+Mouse         mice
  36
+Person        people
  37
+
  38
+==== Schema Conventions
  39
+
  40
+To take advantage of some of the magic of Rails database tables must be modeled 
  41
+to reflect the ORM decisions that Rails makes.
  42
+
  43
+[grid="all"]
  44
+`-------------`---------------------------------------------------------------------------------
  45
+Convention
  46
+-------------------------------------------------------------------------------------------------
  47
+Foreign keys  These fields are named table_id i.e. (item_id, order_id)
  48
+Primary Key   Rails automatically creates a primary key column named "id" unless told otherwise.
  49
+-------------------------------------------------------------------------------------------------
  50
+
  51
+==== Magic Field Names
  52
+
  53
+When these optional fields are used in your database table definition they give the Active Record
  54
+instance additional features. 
  55
+
  56
+NOTE: While these column names are optional they are in fact reserved by ActiveRecord. Steer clear of reserved keywords unless you want the extra functionality. For example, "type" is a reserved keyword
  57
+used to designate a table using Single Table Inheritance. If you are not using STI, try an analogous 
  58
+keyword like "context", that may still accurately describe the data you are modeling.
  59
+
  60
+[grid=all]
  61
+`-------------------`---------------------------------------------------------------------------------
  62
+created_at           Rails stores the current date to this field when creating the record.
  63
+created_on           Rails stores the current date & time to this field when creating the record.
  64
+updated_at           Rails stores the current date to this field when updating the record.
  65
+updated_on           Rails stores the current date & time to this field when updating the record.
  66
+lock_version         Adds optimistic locking to a model link:http://api.rubyonrails.com/classes/ActiveRecord/Locking.html[more about optimistic locking].
  67
+type                 Specifies that the model uses Single Table Inheritance link:http://api.rubyonrails.com/classes/ActiveRecord/Base.html[more about STI].
  68
+id                   All models require an id. the default is name is "id" but can be changed using the "set_primary_key" or "primary_key" methods.
  69
+#{table_name}_count  Can be used to caches the number of belonging objects on the associated class.
  70
+------------------------------------------------------------------------------------------------------
  71
+
26 72
 By default rails assumes all tables will use “id” as their primary key to identify each record. Though fortunately you won’t have explicitly declare this, Rails will automatically create that field unless you tell it not to.
27 73
 
28 74
 For example suppose you created a database table called cars:

0 notes on commit 67ed370

Please sign in to comment.
Something went wrong with that request. Please try again.