db-charmer 1.7.0.pre7 → 1.7.0

data/.gitignore

@@ -1,3 +1,4 @@
 /doc
 /pkg
 .DS_Store
+/_site

data/CHANGES

@@ -1,4 +1,4 @@
-1.7.0 (not released yet):
+1.7.0 (2011-08-29):
 
 Beta feature: Rails 3 support
 

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License
 
-Copyright (c) 2009, Alexey Kovyrin
+Copyright (c) 2011, Oleksiy Kovyrin
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.rdoc

@@ -1,33 +1,33 @@
 = DB Charmer - ActiveRecord Connection Magic Plugin
 
-+DbCharmer+ is a simple yet powerful plugin for ActiveRecord that does a few things:
++DbCharmer+ is a simple yet powerful plugin for ActiveRecord that significantly extends its ability to work with 
+multiple databases and/or database servers. The major features we add to ActiveRecord are:
 
-1. Allows you to easily manage AR models' connections (+switch_connection_to+ method)
-2. Allows you to switch AR models' default connections to a separate servers/databases
-3. Allows you to easily choose where your query should go (<tt>Model.on_*</tt> methods family)
-4. Allows you to automatically send read queries to your slaves while masters would handle all the updates.
-5. Adds multiple databases migrations to ActiveRecord
+1. Simple management for AR model connections (+switch_connection_to+ method)
+2. Switching of default AR model connections to separate servers/databases
+3. Ability to easily choose where your query should go (<tt>Model.on_*</tt> methods family)
+4. Automated master/slave queries routing (selects go to a slave, updates handled by the master).
+5. Multiple database migrations with very flexible query routing controls.
+6. Simple database sharding functionality with multiple sharding methods (value, range, mapping table).
 
+For more information on the project, you can check out our web site at http://kovyrin.github.com/db-charmer.
 
-== Installation
-
-There are two options when approaching db-charmer installation:
-* using the gem (recommended)
-* install as a Rails plugin
 
-To install as a gem, add this to your environment.rb:
+== Installation
 
-  config.gem 'db-charmer', :lib => 'db_charmer'
+There are two options when approaching +DbCharmer+ installation:
+* using the gem (recommended and the only way of using it with Rails 3.0+)
+* install as a Rails plugin (works in Rails 2.x only)
 
-And then run the command:
+To install as a gem, add this to your Gemfile:
 
-  sudo rake gems:install
+  gem 'db-charmer', :require => 'db_charmer'
 
-To install db-charmer as a Rails plugin use this:
+To install +DbCharmer+ as a Rails plugin use the following command:
 
-  script/plugin install git://github.com/kovyrin/db-charmer.git
+  ./script/plugin install git://github.com/kovyrin/db-charmer.git
 
-_Notice_: If you use db-charmer in a non-rails project, you may need to set <tt>DbCharmer.env</tt> to a correct value
+_Notice_: If you use +DbCharmer+ in a non-rails project, you may need to set <tt>DbCharmer.env</tt> to a correct value
 before using any of its connection management methods. Correct value here is a valid <tt>database.yml</tt>
 first-level section name.
 
@@ -395,29 +395,35 @@ impact, but it is worth noting.
 == Simple Sharding Support
 
 Starting with the release 1.6.0 of +DbCharmer+ we have added support for simple database sharding
-to our ActiveRecord extensions. The feature is still in alpha stage and should not be used in
-production without complete understanding of the principles of its work.
+to our ActiveRecord extensions. Even though this feature is tested in production, we do not recommend
+using it in your applications without complete understanding of the principles of its work.
 
-At this point we support three sharding methods:
+At this point we support four sharding methods:
 
-1) range - really simple sharding method that allows you to take a table, slice is to a set of
+1) +range+ - really simple sharding method that allows you to take a table, slice is to a set of
 smaller tables with pre-defined ranges of primary keys and then put those smaller tables to
 different databases/servers. This could be useful for situations where you have a huge table that
 is slowly growing and you just want to keep it simple and split the table load into a few servers
 without building any complex sharding schemes.
 
-2) hash_map - pretty simple sharding method that allows you to take a table and slice it to a set
+2) +hash_map+ - pretty simple sharding method that allows you to take a table and slice it to a set
 of smaller tables by some key that has a pre-defined key of values. For example, list of US mailing
 addresses could be sharded by states, where you'd be able to define which states are stored in which
 databases/servers.
 
-3) db_block_map - this is a really complex sharding method that allows you to shard your table into a
+3) +db_block_map+ - this is a really complex sharding method that allows you to shard your table into a
 set of small fixed-size blocks that then would be assigned to a set of shards (databases/servers).
 Whenever you would need an additional blocks they would be allocated automatically and then balanced
 across the shards you have defined in your database. This method could be used to scale out huge
 tables with hundreds of millions to billions of rows and allows relatively easy re-sharding techniques
 to be implemented on top.
 
+4) +db_block_group_map+ - really similar to the +db_block_map+ method with a single difference: this method
+allows you to have a set of databases (table groups) on each server and every group would be handled as a 
+separate shard of data. This approach is really useful for pre-sharding of your data before scaling your
+application out. You can easily start with one server, having 10-20-50 separate databases, and then
+move those databases to different servers as you see your database outgrow one machine.
+
 
 === How to enable sharding?
 
@@ -514,17 +520,17 @@ allows you to switch to the default shard:
   Text.on_default_shard.create(:body => 'hello', :user_id => 123)
 
 And finally, there is a method that allows you to run your code on each shard in the system (at this
-point the method is supported in db_block_map method only):
+point the method is supported in db_block_map and db_block_group_map methods only):
 
   Event.on_each_shard { |event| event.delete_all }
 
 
 === Defining your own sharding methods
 
-It is possing with +DbCharmer+ for the users to define their own sharding methods. You need to do a
+It is possible with +DbCharmer+ for the users to define their own sharding methods. You need to do a
 few things to implement your very own sharding scheme:
 
-1) Create a class with a name DbCharmer::Sharding::Method::YourOwnName
+1) Create a class with a name <tt>DbCharmer::Sharding::Method::YourOwnName</tt>
 
 2) Implement at least a constructor <tt>initialize(config)</tt> and a lookup instance
 method <tt>shard_for_key(key)</tt> that would return either a connection name from <tt>database.yml</tt>
@@ -534,7 +540,7 @@ file or just a hash of connection parameters for rails connection adapters.
 
   DbCharmer::Sharding.register_connection(
     :name => :some_name,
-    :method => :your_own_name,    # your sharder class name in lower case
+    :method => :your_own_name,    # your sharding method class name in lower case
     ... some additional parameters if needed ...
   )
 
@@ -555,32 +561,36 @@ would return +true+ if you do support default shard specification and +false+ ot
 === Adding support for shards enumeration in your custom sharding methods
 
 To add shards enumeration support to your custom-sharded models you need to implement
-just one instance method +shard_connections+ on your sharded class. This method should
-return an array of sharding connection names or connection configurations to be used to
-establish shard connections in a loop.
+an instance method +shard_connections+ on your class. This method should return an array of
+sharding connection names or connection configurations to be used to establish connections in a loop.
 
 
 == Documentation/Questions
 
-For more information on the plugin internals, please check out the source code. All the plugin's
-code is ~100% covered with tests that were placed in a separate staging rails project located
-at http://github.com/kovyrin/db-charmer-sandbox. The project has unit tests for all or at least the
-most of the parts of plugin's code.
+For more information about the library, please visit our site at http://kovyrin.github.com/db-charmer.
+If you need more defails on DbCharmer internals, please check out the source code. All the plugin's
+code is ~100% covered with tests (located in a separate staging rails project
+at http://github.com/kovyrin/db-charmer-sandbox). The project has unit tests for all or at
+least the most actively used code paths.
 
 If you have any questions regarding this project, you could contact the author using
 the DbCharmer Users Group mailing list:
 
 - Group Info: http://groups.google.com/group/db-charmer
-- Subscribe using the info page or by sending an email to db-charmer-subscribe@googlegroups.com
+- Subscribe using the info page or by sending an email to mailto:db-charmer-subscribe@googlegroups.com
 
 
 == What Ruby and Rails implementations does it work for?
 
-We have a continuous integration setups for this plugin on MRI 1.8.7 with Rails 2.2, 2.3 and 3.0.
-We use the plugin in production on Scribd.com with MRI (Ruby Enterprise Edition) 1.8.7 and
-Rails 2.2, Rails 2.3, Sinatra and plain Rack applications.
+We have a continuous integration setup for this gem on with Rails 2.2, 2.3 and 3.0 using a few
+different versions of Ruby. For more information about the build matrix please visit
+http://github.com/kovyrin/db-charmer-sandbox web site.
+
+In addition to CI testing, we use this gem in production on Scribd.com (one of the largest RoR
+sites in the world) with Ruby Enterprise Edition and Rails 2.2, Rails 2.3, Sinatra and plain
+Rack applications.
 
-Starting with version 1.7.0 we support Rails 3.0, but until further notice we consider it a 
+Starting with version 1.7.0 we support Rails 3.0, but until further notice we consider it a
 beta-quality feature since we do not run any production software on this version of Rails. If you
 run your application on Rails 3.0, please contact the author.
 

data/lib/db_charmer/version.rb

@@ -3,7 +3,7 @@ module DbCharmer
     MAJOR = 1
     MINOR = 7
     PATCH = 0
-    BUILD = 'pre7'
+    BUILD = nil
 
     STRING = [MAJOR, MINOR, PATCH, BUILD].compact.join('.')
   end

metadata

@@ -1,15 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: db-charmer
 version: !ruby/object:Gem::Version 
-  hash: 1923832055
-  prerelease: 6
+  hash: 11
+  prerelease: 
   segments: 
   - 1
   - 7
   - 0
-  - pre
-  - 7
-  version: 1.7.0.pre7
+  version: 1.7.0
 platform: ruby
 authors: 
 - Oleksiy Kovyrin
@@ -17,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-08-27 00:00:00 Z
+date: 2011-08-29 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: activesupport
@@ -160,14 +158,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version 
-      hash: 25
+      hash: 3
       segments: 
-      - 1
-      - 3
-      - 1
-      version: 1.3.1
+      - 0
+      version: "0"
 requirements: []
 
 rubyforge_project: