vendor/gems/composite_primary_keys-2.2.2/website/index.txt

   1 h1. Composite Primary Keys
   2
   3 h1. -> Ruby on Rails
   4
   5 h1. -> ActiveRecords
   6
   7 h2. What
   8
   9 Ruby on Rails does not support composite primary keys. This free software is an extension
  10 to the database layer of Rails - "ActiveRecords":http://wiki.rubyonrails.com/rails/pages/ActiveRecord - to support composite primary keys as transparently as possible.
  11
  12 Any Ruby script using ActiveRecords can use Composite Primary Keys with this library.
  13
  14 h2. Installing
  15
  16 <pre syntax="ruby">sudo gem install composite_primary_keys</pre>
  17
  18 Rails: Add the following to the bottom of your <code>environment.rb</code> file
  19
  20 <pre syntax="ruby">require 'composite_primary_keys'</pre>
  21
  22 Ruby scripts: Add the following to the top of your script
  23
  24 <pre syntax="ruby">require 'rubygems'
  25 require 'composite_primary_keys'</pre>
  26
  27 h2. The basics
  28
  29 A model with composite primary keys would look like...
  30
  31 <pre syntax="ruby">class Membership < ActiveRecord::Base
  32   # set_primary_keys *keys - turns on composite key functionality
  33   set_primary_keys :user_id, :group_id
  34   belongs_to :user
  35   belongs_to :group
  36   has_many :statuses, :class_name => 'MembershipStatus', :foreign_key => [:user_id, :group_id]
  37 end</pre>
  38
  39 A model associated with a composite key model would be defined like...
  40
  41 <pre syntax="ruby">class MembershipStatus < ActiveRecord::Base
  42   belongs_to :membership, :foreign_key => [:user_id, :group_id]
  43 end</pre>
  44
  45 That is, associations can include composite keys too. Nice.
  46
  47 h2. Demonstration of usage
  48
  49 Once you've created your models to specify composite primary keys (such as the Membership class) and associations (such as MembershipStatus#membership), you can uses them like any normal model with associations.
  50
  51 But first, lets check out our primary keys.
  52
  53 <pre syntax="ruby">MembershipStatus.primary_key # => "id"    # normal single key
  54 Membership.primary_key  # => [:user_id, :group_id] # composite keys
  55 Membership.primary_key.to_s # => "user_id,group_id"</pre>
  56
  57 Now we want to be able to find instances using the same syntax we always use for ActiveRecords...
  58
  59 <pre syntax="ruby">MembershipStatus.find(1)    # single id returns single instance
  60 => <MembershipStatus:0x392a8c8 @attributes={"id"=>"1", "status"=>"Active"}>
  61 Membership.find(1,1)  # composite ids returns single instance
  62 => <Membership:0x39218b0 @attributes={"user_id"=>"1", "group_id"=>"1"}></pre>
  63
  64 Using "Ruby on Rails":http://www.rubyonrails.org? You'll want to your url_for helpers
  65 to convert composite keys into strings and back again...
  66
  67 <pre syntax="ruby">Membership.find(:first).to_param # => "1,1"</pre>
  68
  69 And then use the string id within your controller to find the object again
  70
  71 <pre syntax="ruby">params[:id] # => '1,1'
  72 Membership.find(params[:id])
  73 => <Membership:0x3904288 @attributes={"user_id"=>"1", "group_id"=>"1"}></pre>
  74
  75 That is, an ActiveRecord supporting composite keys behaves transparently
  76 throughout your application. Just like a normal ActiveRecord.
  77
  78
  79 h2. Other tricks
  80
  81 h3. Pass a list of composite ids to the <code>#find</code> method
  82
  83 <pre syntax="ruby">Membership.find [1,1], [2,1]
  84 => [
  85   <Membership:0x394ade8 @attributes={"user_id"=>"1", "group_id"=>"1"}>,
  86   <Membership:0x394ada0 @attributes={"user_id"=>"2", "group_id"=>"1"}>
  87 ]</pre>
  88
  89 Perform <code>#count</code> operations
  90
  91 <pre syntax="ruby">MembershipStatus.find(:first).memberships.count # => 1</pre>
  92
  93 h3. Routes with Rails
  94
  95 From Pete Sumskas:
  96
  97 <blockquote>
  98         I ran into one problem that I didn't see mentioned on "this list":http://groups.google.com/group/compositekeys -
  99         and I   didn't see any information about what I should do to address it in the
 100         documentation (might have missed it).
 101
 102         The problem was that the urls being generated for a 'show' action (for
 103         example) had a syntax like:
 104
 105         <pre>/controller/show/123000,Bu70</pre>
 106
 107         for a two-field composite PK. The default routing would not match that,
 108         so after working out how to do the routing I added:
 109
 110         <pre syntax="ruby">map.connect ':controller/:action/:id', :id => /\w+(,\w+)*/</pre>
 111
 112         to my <code>route.rb</code> file.
 113
 114 </blockquote>
 115
 116 <a name="dbs"></a>
 117
 118 h2. Which databases?
 119
 120
 121 A suite of unit tests have been run on the following databases supported by ActiveRecord:
 122
 123 |_.Database|_.Test Success|_.User feedback|
 124 |mysql     |<span class=success>YES</span>|<span class=success>YES</span> ("Yes!":mailto:compositekeys@googlegroups.com?subject=Mysql+is+working or "No...":mailto:compositekeys@googlegroups.com?subject=Mysql+is+failing)|
 125 |sqlite3   |<span class=success>YES</span>|<span class=success>YES</span> ("Yes!":mailto:compositekeys@googlegroups.com?subject=Sqlite3+is+working or "No...":mailto:compositekeys@googlegroups.com?subject=Sqlite3+is+failing)|
 126 |postgresql|<span class=success>YES</span>|<span class=success>YES</span> ("Yes!":mailto:compositekeys@googlegroups.com?subject=Postgresql+is+working or "No...":mailto:compositekeys@googlegroups.com?subject=Postgresql+is+failing)|
 127 |oracle    |<span class=success>YES</span>|<span class=success>YES</span> ("Yes!":mailto:compositekeys@googlegroups.com?subject=Oracle+is+working or "No...":mailto:compositekeys@googlegroups.com?subject=Oracle+is+failing)|
 128 |sqlserver |<span class=unknown>???</span> ("I can help":mailto:compositekeys@googlegroups.com?subject=Help+with+SQLServer)|<span class=unknown>???</span> ("Yes!":mailto:compositekeys@googlegroups.com?subject=SQLServer+is+working or "No...":mailto:compositekeys@googlegroups.com?subject=SQLServer+is+failing)|
 129 |db2       |<span class=unknown>???</span> ("I can help":mailto:compositekeys@googlegroups.com?subject=Help+with+DB2)|<span class=unknown>???</span> ("Yes!":mailto:compositekeys@googlegroups.com?subject=DB2+is+working or "No...":mailto:compositekeys@googlegroups.com?subject=DB2+is+failing)|
 130 |firebird  |<span class=unknown>???</span> ("I can help":mailto:compositekeys@googlegroups.com?subject=Help+with+Firebird)|<span class=unknown>???</span> ("Yes!":mailto:compositekeys@googlegroups.com?subject=Firebird+is+working or "No...":mailto:compositekeys@googlegroups.com?subject=Firebird+is+failing)|
 131 |sybase    |<span class=unknown>???</span> ("I can help":mailto:compositekeys@googlegroups.com?subject=Help+with+Sybase)|<span class=unknown>???</span> ("Yes!":mailto:compositekeys@googlegroups.com?subject=Sybase+is+working or "No...":mailto:compositekeys@googlegroups.com?subject=Sybase+is+failing)|
 132 |openbase  |<span class=unknown>???</span> ("I can help":mailto:compositekeys@googlegroups.com?subject=Help+with+Openbase)|<span class=unknown>???</span> ("Yes!":mailto:compositekeys@googlegroups.com?subject=Openbase+is+working or "No...":mailto:compositekeys@googlegroups.com?subject=Openbase+is+failing)|
 133 |frontbase |<span class=unknown>???</span> ("I can help":mailto:compositekeys@googlegroups.com?subject=Help+with+Frontbase)|<span class=unknown>???</span> ("Yes!":mailto:compositekeys@googlegroups.com?subject=Frontbase+is+working or "No...":mailto:compositekeys@googlegroups.com?subject=Frontbase+is+failing)|
 134
 135 h2. Dr Nic's Blog
 136
 137 "http://www.drnicwilliams.com":http://www.drnicwilliams.com - for future announcements and
 138 other stories and things.
 139
 140 h2. Forum
 141
 142 "http://groups.google.com/group/compositekeys":http://groups.google.com/group/compositekeys
 143
 144 h2. How to submit patches
 145
 146 Read the "8 steps for fixing other people's code":http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/ and for section "8b: Submit patch to Google Groups":http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/#8b-google-groups, use the Google Group above.
 147
 148
 149 The source for this project is available via git. You can "browse and/or fork the source":http://github.com/drnic/composite_primary_keys/tree/master, or to clone the project locally:
 150
 151 <pre>git clone git://github.com/drnic/composite_primary_keys.git</pre>
 152
 153 h2. Licence
 154
 155 This code is free to use under the terms of the MIT licence.
 156
 157 h2. Contact
 158
 159 Comments are welcome. Send an email to "Dr Nic Williams":mailto:drnicwilliams@gmail.com.