shard_handler 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c2728db474dde6a413de4340acebf59e340bd929
-  data.tar.gz: f4c4df74df1ea909359edf2f8f79fff624824090
+  metadata.gz: b73438164d74c6049b163a1f0b61dc62585a3fcb
+  data.tar.gz: 5dfdcf6cae3e106d57aed21e7d07a6150daed604
 SHA512:
-  metadata.gz: bac3f0308f32e0aee8f1ddd1e9e196b06902041158db7567f206435b549e58a944894ef21176007d4871b238175bf9b6cbffbbd6386781e72511e3933010296c
-  data.tar.gz: e90d66071b5e082ae1e09c071e204d74adc0b8b033f71715e27d1972ee277836c60c8c961fbf67833044bf7ea605f2d74f29ae0eb6788ca44257fb785762862f
+  metadata.gz: 3e95086eb004cabb1bf3a8872e966b4b32102e479cfd82e62fa992674cc4a6742d8651626fd3a7898990197f8039ac2c0f4a3c6c5e40a0bb427c5b5f07ffa13f
+  data.tar.gz: 5f1993cd1f41e851dd3cb7f51fca8ece2398d8c5c5dcfc3eeec56e532b687921dd0d3b4bf138952c65c8c70ff4c78a3f282baa95602028113c5149cd6f694dad

data/.travis.yml

@@ -1,4 +1,12 @@
 language: ruby
 rvm:
-  - 2.1.3
+  - 2.1.6
+  - 2.2.2
+addons:
+  postgresql: "9.3"
 before_install: gem install bundler -v 1.10.5
+before_script:
+  - cp spec/database.yml.travis spec/database.yml
+  - cp spec/shards.yml.travis spec/shards.yml
+script:
+  - bundle exec rake spec

data/Gemfile

@@ -2,3 +2,5 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in shard_handler.gemspec
 gemspec
+
+gem 'codeclimate-test-reporter', group: :test, require: nil

data/README.md

@@ -1,8 +1,17 @@
 # ShardHandler
 
+[![Build Status][travis-badge]][travis-build]
+[![Code Climate][cc-badge]][cc-details]
+[![Test Coverage][cc-cov-badge]][cc-cov-details]
+
 This gem is a simple sharding solution for Rails applications. It was created
-to be used in multitenant applications, when data is shared across multiple
-databases but accessed through the same ActiveRecord model.
+to be used in multitenant applications, where data is partitioned across
+multiple databases but accessed through the same ActiveRecord model. Basically,
+this gem is a nice connection switcher for ActiveRecord.
+
+Keep in mind that this gem is tested only with PostgreSQL databases.
+
+The documentation is [available on RubyDoc.info][docs].
 
 ## Installation
 
@@ -22,44 +31,120 @@ Or install it yourself as:
 
 ## Usage
 
-All models that need sharding must inherit from `ShardHandler::Model`. For
-example:
+First, create an abstract model that will handle the shard connection:
 
 ```ruby
-class Post < ShardHandler::Model
+class Shard < ShardHandler::Model
+  self.abstract_class = true
 end
 ```
 
-Before executing any query, you must switch to the appropriate shard:
+Create a YAML file like this one:
+
+```yaml
+# config/shards.yml
+development:
+  shard1:
+    adapter: postgresql
+    database: shard_db_1
+    username: postgres
+  shard2:
+    adapter: postgresql
+    database: shard_db_2
+    username: postgres
+test:
+  # ...
+production:
+  # ...
+```
+
+And configure your abstract model:
 
 ```ruby
-ShardHandler.current_shard = :shard1
-puts Post.pluck(:title)
+# config/initializers/shard_handler.rb
+Shard.setup(Rails.application.config_for(:shards))
+```
+
+Any model that has data shared across shards must inherit from your abstract
+model:
 
-# or
+```ruby
+class Message < Shard
+end
 
-ShardHandler.using(:shard1) do
-  puts Post.pluck(:title)
+class Contact < Shard
+end
+```
+
+To execute a query in a shard, you can use the `.using` method passing the
+appropriate shard name:
+
+```ruby
+user = User.first
+
+Shard.using(:shard1) do
+  puts user.messages.pluck(:title)
+  puts user.contacts.pluck(:email)
 end
 ```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run
-`rake test` to run the tests. You can also run `bin/console` for an interactive
-prompt that will allow you to experiment.
+After checking out the repo:
 
-To install this gem onto your local machine, run `bundle exec rake install`. To
-release a new version, update the version number in `version.rb`, and then run
-`bundle exec rake release`, which will create a git tag for the version, push
-git commits and tags, and push the `.gem` file to
-[rubygems.org](https://rubygems.org).
+1. Install dependencies using `bin/setup`.
+2. Create these 2 files: `spec/database.yml` and `spec/shards.yml` and configure
+them with your PostgreSQL database. There are examples at
+`spec/database.yml.example` and `spec/shards.yml.example`. **Important:**
+these databases *will be destroyed and recreated* on test execution.
+3. Run specs using `bundle exec rake spec` to make sure that everything is fine.
 
-## Contributing
+You can use `bin/console` to get an interactive prompt that will allow you to
+experiment.
+
+## Releasing a new version
+
+If you are the maintainer of this project:
+
+1. Update the version number in `lib/shard_handler/version.rb`.
+2. Make sure that all tests are green (run `bundle exec rake spec`).
+3. Execute `bundle exec rake release` to create a git tag for the version, push
+git commits and tags, and publish the gem on [RubyGems.org][rubygems].
+
+## Debugging PostgreSQL
+
+To see what is going on in a PostgreSQL database, you can enable a more verbose
+log for the database:
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/shard_handler.
+```txt
+# %d = database name
+# %l = session line number
+# %x = transaction ID (0 if none)
+log_line_prefix = '%d %l %x - '
+log_statement = 'all'
+```
+
+After restarting your database, the log will be like this:
+
+```txt
+my_db 1 0 - LOG:  statement: SELECT foo FROM bar
+```
+
+## Contributing
 
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/locaweb/shard_handler.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the
+[MIT License](http://opensource.org/licenses/MIT).
+
+[travis-badge]: https://travis-ci.org/locaweb/shard_handler.svg?branch=master
+[travis-build]: https://travis-ci.org/locaweb/shard_handler
+[cc-badge]: https://codeclimate.com/github/locaweb/shard_handler/badges/gpa.svg
+[cc-details]: https://codeclimate.com/github/locaweb/shard_handler
+[cc-cov-badge]: https://codeclimate.com/github/locaweb/shard_handler/badges/coverage.svg
+[cc-cov-details]: https://codeclimate.com/github/locaweb/shard_handler/coverage
+[docs]: http://www.rubydoc.info/gems/shard_handler
+[rubygems]: https://rubygems.org/gems/shard_handler

data/Rakefile

@@ -1,10 +1,6 @@
 require 'bundler/gem_tasks'
-require 'rake/testtask'
+require 'rspec/core/rake_task'
 
-Rake::TestTask.new(:test) do |t|
-  t.libs << 'test'
-  t.libs << 'lib'
-  t.test_files = FileList['test/**/*_test.rb']
-end
+RSpec::Core::RakeTask.new(:spec)
 
-task default: :test
+task default: :spec

data/lib/shard_handler/handler.rb

@@ -35,7 +35,6 @@ module ShardHandler
     # @param name [Symbol, String] shard name
     # @return [ActiveRecord::ConnectionAdapters::ConnectionHandler]
     def connection_handler_for(name)
-      return if name.nil?
       @cache.fetch(name.to_sym) do
         fail UnknownShardError, "#{name.inspect} is not a valid shard name"
       end

data/lib/shard_handler/model.rb

@@ -61,8 +61,13 @@ module ShardHandler
       # @api private
       # @return (see Handler#connection_handler_for)
       def connection_handler
-        fail(SetupError, 'the model was not setup') unless @@handler
-        @@handler.connection_handler_for(current_shard) || super
+        return super if use_master_connection?
+
+        unless defined?(@@handler)
+          fail(SetupError, 'the model was not setup')
+        end
+
+        @@handler.connection_handler_for(current_shard)
       end
 
       # This method will switch to the passed shard making all queries be
@@ -83,6 +88,12 @@ module ShardHandler
       end
 
       private :establish_connection
+
+      protected
+
+      def use_master_connection?
+        current_shard.nil?
+      end
     end
   end
 end

data/lib/shard_handler/thread_registry.rb

@@ -3,7 +3,7 @@ require 'active_support/per_thread_registry'
 module ShardHandler
   # This class is used as a registry for the shard name that is being used in
   # the current thread. Because ActiveRecord's connections are global in the
-  # thread scope, we need to make sure that the shard name is change only for
+  # thread scope, we need to make sure that the shard name is changed only for
   # the current thread and not on process or other threads.
   #
   # @see ActiveSupport::PerThreadRegistry

data/lib/shard_handler/version.rb

@@ -1,3 +1,3 @@
 module ShardHandler
-  VERSION = '0.1.3'
+  VERSION = '0.1.4'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shard_handler
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Lenon Marcel