appoxy-simple_record 1.1.11 → 1.1.12

data/README.markdown

@@ -1,15 +1,184 @@
-# simple_record
-
-http://code.google.com/p/simple-record/
-
-## DESCRIPTION:
+# SimpleRecord - ActiveRecord for SimpleDB
 
 An ActiveRecord interface for SimpleDB.  Can be used as a drop in replacement for ActiveRecord in rails.
 
 Special thanks to Garrett Cox for creating Activerecord2sdb which SimpleRecord is based on: 
 http://activrecord2sdb.rubyforge.org/
 
-## Usage
+## Getting Started
+
+1. Install gems
+
+        gem install appoxy-aws uuidtools appoxy-simple_record
+
+2. Create a model
+
+        require 'simple_record'
+    
+        class MyModel < SimpleRecord::Base
+           has_attributes :name
+           has_ints :age
+        end
+
+More about ModelAttributes below.
+
+3. Setup environment
+
+        AWS_ACCESS_KEY_ID='XXXX'
+        AWS_SECRET_ACCESS_KEY='YYYY'
+        SimpleRecord.establish_connection(AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY)
+
+4. Go to town
+
+        # Store a model object to SimpleDB
+        mm = MyModel.new
+        mm.name = "Travis"
+        mm.age = 32
+        mm.save
+        id = mm.id
+
+        # Get an object from SimpleDB
+        mm2 = MyModel.find(id)
+        puts 'got=' + mm2.name + ' and he/she is ' + mm.age.to_s + ' years old'
+        # Or more advanced queries? mms = MyModel?.find(:all, ["age=?", 32], :order=>"name", :limit=>10)
+
+
+## Attributes and modifiers for models
+
+NOTE: All objects will automatically have :id, :created, :updated attributes.
+
+### has_attributes
+
+Add string attributes.
+
+    class MyModel
+      has_attributes :name
+    end
+
+### has_ints, has_dates and has_booleans
+
+Lets simple_record know that certain attributes defined in has_attributes should be treated as integers, dates or booleans. This is required because SimpleDB only has strings so SimpleRecord needs to know how to convert, pad, offset, etc.
+
+    class MyModel
+      has_attributes :name
+      has_ints :age, :height
+      has_dates :birthday
+      has_booleans :is_nerd
+    end
+
+### belongs_to
+
+Creates a many-to-one relationship. Can only have one per belongs_to call.
+
+    class MyModel
+        belongs_to :school
+        has_attributes :name
+        has_ints :age, :height
+        has_dates :birthday
+        has_booleans :is_nerd
+    end
+
+Which requires another class called 'School' or you can specify the class explicitly with:
+
+    belongs_to :school, :class_name => "Institution"
+
+### set_table_name or set_domain_name
+
+If you want to use a custom domain for a model object, you can specify it with set_table_name (or set_domain_name).
+
+    class SomeModel
+        set_table_name :different_model
+    end
+
+
+## Configuration
+
+### Domain Prefix
+
+To set a global prefix across all your models, use:
+
+    SimpleRecord::Base.set_domain_prefix("myprefix_")
+
+### Connection Modes
+
+There are 4 different connection modes:
+
+* per_request (default) - opens and closes a new connection to simpledb for every simpledb request. Not the best performance, but it's safe and can handle many concurrent requests at the same time (unlike single mode).
+* single - one connection across the entire application, not recommended unless the app is used by a single person.
+* per_thread - a connection is used for every thread in the application. This is good, but the catch is that you have to ensure to close the connection.
+* pool - NOT IMPLEMENTED YET - opens a maximum number of connections and round robins them for any simpledb request.
+
+You set the mode when you call establish_connection:
+
+    SimpleRecord.establish_connection(AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY, :connection_mode=>:per_thread)
+
+We recommend per_thread with explicitly closing the connection after each Rails request (not to be mistaken for a SimpleDB request) or pool for rails apps.
+
+For rails, be sure to add this to your Application controller if using per_thread mode:
+
+    after_filter :close_sdb_connection
+
+    def close_sdb_connection
+        SimpleRecord.close_connection
+    end
+
+## SimpleRecord on Rails
+
+You don't really have to do anything except have your models extends SimpleRecord::Base instead of ActiveRecord::Base, but here are some tips you can use.
+
+### Change Connection Mode
+
+Use per_thread connection mode and close the connection after each request.
+
+    after_filter :close_sdb_connection
+
+    def close_sdb_connection
+        SimpleRecord.close_connection
+    end
+
+### Disable ActiveRecord so you don't have to setup another database
+
+This is most helpful on windows so Rails doesn't need sqlite or mysql gems/drivers installed which are painful to install on windows. In environment.rb, add 'config.frameworks -= [ :active_record ]', should look something like:
+
+    Rails::Initializer.run do |config|
+      config.frameworks -= [ :active_record ]
+      ....
+    end
+
+
+## Tips and Tricks and Things to Know
+
+### Automagic Stuff
+
+
+#### Automatic common fields
+
+Every object will automatically get the following attributes so you don't need to define them:
+
+  * id - UUID string
+  * created - set when first save
+  * updated - set every time you save/update
+
+
+#### belongs_to foreign keys/IDs are accessible without touching the database
+
+If you had the following in your model:
+
+    belongs_to :something
+
+Then in addition to being able to access the something object with:
+
+    o.something
+
+or setting it with:
+
+    o.something = someo
+
+You can also access the ID for something directly with:
+
+    o.something_id
+
+or
 
-See http://code.google.com/p/simple-record/ for documentation.
+    o.something_id = x
 

data/lib/simple_record.rb

@@ -186,8 +186,11 @@ module SimpleRecord
 
 
         attr_accessor :errors
-        @@domain_prefix = ''
-        @domain_name_for_class = nil
+
+        @domain_prefix = ''
+        class << self; attr_accessor :domain_prefix; end
+
+        #@domain_name_for_class = nil
 
         @@cache_store = nil
         # Set the cache to use
@@ -200,7 +203,8 @@ module SimpleRecord
 
         # If you want a domain prefix for all your models, set it here.
         def self.set_domain_prefix(prefix)
-            @@domain_prefix = prefix
+            #puts 'set_domain_prefix=' + prefix
+            self.domain_prefix = prefix
         end
 
         # Same as set_table_name
@@ -211,25 +215,29 @@ module SimpleRecord
         # Sets the domain name for this class
         def self.set_domain_name(table_name)
             # puts 'setting domain name for class ' + self.inspect + '=' + table_name
-            @domain_name_for_class = table_name
+            #@domain_name_for_class = table_name
             super
         end
 
-        def self.get_domain_name
+=begin
+ def self.get_domain_name
             # puts 'returning domain_name=' + @domain_name_for_class.to_s
-            return @domain_name_for_class
+            #return @domain_name_for_class
+            return self.domain
         end
 
+=end
 
         def domain
             super # super.domain
         end
 
         def self.domain
-            return self.get_domain_name unless self.get_domain_name.nil?
+            #return self.get_domain_name unless self.get_domain_name.nil?
             d = super
-            domain_name_for_class = @@domain_prefix + d.to_s
-            self.set_domain_name(domain_name_for_class)
+            #puts 'in self.domain, d=' + d.to_s + ' domain_prefix=' + SimpleRecord::Base.domain_prefix.to_s
+            domain_name_for_class = SimpleRecord::Base.domain_prefix + d.to_s
+            #self.set_domain_name(domain_name_for_class)
             domain_name_for_class
         end
 
@@ -916,7 +924,7 @@ module SimpleRecord
         end
 
         def self.table_name
-            return @@domain_prefix + self.class.name.tableize
+            return domain
         end
 
         def changed

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: appoxy-simple_record
 version: !ruby/object:Gem::Version 
-  version: 1.1.11
+  version: 1.1.12
 platform: ruby
 authors: 
 - Travis Reeder
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-08-04 00:00:00 -07:00
+date: 2009-08-18 00:00:00 -07:00
 default_executable: 
 dependencies: []