Merge branch 'master' of github.com:appoxy/simple_record

README.markdown

@@ -19,7 +19,7 @@ Brought to you by: [![Appoxy](http://www.simpledeployr.com/images/global/appoxy-
         require 'simple_record'
 
         class MyModel < SimpleRecord::Base
-           has_attributes :name
+           has_strings :name
            has_ints :age
         end
 
@@ -45,25 +45,26 @@ More about ModelAttributes below.
         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)
 
+That's literally all you need to do to get started. No database install, no other setup required.
 
 ## Attributes and modifiers for models
 
 NOTE: All objects will automatically have :id, :created, :updated attributes.
 
-### has_attributes
+### has_strings
 
 Add string attributes.
 
     class MyModel < SimpleRecord::Base
-      has_attributes :name
+      has_strings :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.
+This is required because SimpleDB only has strings so SimpleRecord needs to know how to convert, pad, offset, etc.
 
     class MyModel < SimpleRecord::Base
-      has_attributes :name
+      has_strings :name
       has_ints :age, :height
       has_dates :birthday
       has_booleans :is_nerd
@@ -75,7 +76,7 @@ Creates a many-to-one relationship. Can only have one per belongs_to call.
 
     class MyModel < SimpleRecord::Base
         belongs_to :school
-        has_attributes :name
+        has_strings :name
         has_ints :age, :height
         has_dates :birthday
         has_booleans :is_nerd
@@ -166,6 +167,30 @@ For rails, be sure to add this to your Application controller if using per_threa
         SimpleRecord.close_connection
     end
 
+### LOB and any other S3 Storage
+
+    :s3_bucket=>...
+
+* :old (default) will use the existing lob location of "#{aws_access_key}_lobs", but any new features will use the :new bucket.
+* :new will use the new and recommended s3 bucket location of "simple_record_#{aws_access_key}".
+* Any string value will use that value as the bucket name.
+
+
+NOTE: All projects should set this as we may make this default in a future major version (v3?). Existing projects should use
+:s3_bucket=>:
+
+### Created and Updated At Columns
+
+The default uses the columns "created" and "updated" which unfortunately are not the same as ActiveRecord, which
+uses created_at and updated_at. Although you can use created_at and updated_at methods, you may still want the columns in
+SimpleDB to be created_at and updated_at.
+
+    :created_col=>"created", :updated_col=>"updated"
+
+NOTE: All projects should set these as we may make the "_at" postfix default in a future major version (v3?). Existing
+projects should set :created_col=>"created", :updated_col=>"updated" (default) so if it changes in a future version,
+there won't be any issues.
+
 ## 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.
@@ -194,11 +219,21 @@ This is most helpful on windows so Rails doesn't need sqlite or mysql gems/drive
 
 Typical databases support BLOB's and/or CLOB's, but SimpleDB has a 1024 character per attribute maximum so larger
 values should be stored in S3. Fortunately SimpleRecord takes care of this for you by defining has_clobs for a large
-string value.
+string value. There is no support for blobs yet.
 
     has_clobs :my_clob
 
-These clob values will be stored in s3 under a bucket named: "#{aws_access_key}_lobs"
+These clob values will be stored in s3 under a bucket named "#{aws_access_key}_lobs"
+OR "simple_record_#{aws_access_key}/lobs" if you set :s3_bucket=>:new in establish_connection (RECOMMENDED).
+
+If you have more than one clob on an object and if it makes sense for performance reasons, you can set a configuration option on the class to store all clobs
+as one item on s3 which means it will do a single put to s3 and a single get for all the clobs on the object.
+This would generally be good for somewhat small clob values or when you know you will always be accessing
+all the clobs on the object. 
+
+    sr_config :single_clob=>true
+
+Setting this will automatically use :s3_bucket=>:new as well.
 
 ## Tips and Tricks and Things to Know
 
@@ -236,20 +271,36 @@ or
 
     o.something_id = x
 
-### Batch Save
+Accessing the id can prevent a database call so if you only need the ID, then you
+should use this.
+
+## Batch Save
 
 To do a batch save using SimpleDB's batch saving feature to improve performance, simply create your objects, add them to an array, then call:
 
     MyClass.batch_save(object_list)
 
+## Batch Delete
+
+To do a batch delete using SimpleDB's batch delete feature to improve performance, simply create your objects, add them to an array, then call:
+
+    MyClass.batch_delete(object_list or list_of_ids)
+
+## Operations across a Query
+
+    MyClass.delete_all(find_options)
+    MyClass.destroy_all(find_options)
+
+find_options can include anything you'd add after a find(:all, find_options) including :conditions, :limit, etc.
+
 ## Caching
 
 You can use any cache that supports the ActiveSupport::Cache::Store interface.
 
     SimpleRecord::Base.cache_store = my_cache_store
 
-If you want a simple in memory cache store, try: http://gemcutter.org/gems/local_cache . It supports max cache size and
-timeouts. You can also use memcached or http://www.quetzall.com/cloudcache.
+If you want a simple in memory cache store that supports max cache size and expiration, try: <http://gemcutter.org/gems/local_cache>.
+You can also use memcached or http://www.quetzall.com/cloudcache.
 
 ## Encryption
 
@@ -275,6 +326,24 @@ ob2.password == "mypassword"
 
 This will actually be compared by hashing "mypassword" first.
 
+## Sharding
+
+Sharding allows you to partition your data for a single class across multiple domains allowing increased write throughput,
+faster queries and more space (multiply your 10GB per domain limit).  And it's very easy to implement with SimpleRecord.
+
+    shard :shards=>:my_shards_function, :map=>:my_mapping_function
+
+The :shards function should return a list of shard names, for example: ['CA', 'FL', 'HI', ...] or [1,2,3,4,...]
+
+The :map function should return which shard name the object should be stored to.
+
+When executing a find() operation, you can explicitly specify the shard(s) you'd like to find on. This is
+particularly useful if you know in advance which shard the data will be in.
+
+    MyClass.find(:all, :conditions=>....., :shard=>["CA", "FL"])
+
+You can see some [example classes here](https://github.com/appoxy/simple_record/blob/master/test/my_sharded_model.rb).
+
 ## Kudos
 
 Special thanks to Garrett Cox for creating Activerecord2sdb which SimpleRecord is based on:

VERSION.yml

@@ -1,5 +1,5 @@
 --- 
-:major: 1
-:minor: 5
-:patch: 8
+:major: 2
+:minor: 0
+:patch: 4
 :build: