octoshark 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8a42c9187a7bf3516c5462a53b9d66b66571ddce
+  data.tar.gz: 6b5a5c331d7f899972277a4badba921b26adf61b
+SHA512:
+  metadata.gz: 9916b8edd7ebb3a0c906f7a71434881fcf41ba9f8e483bb389bfdd07dec5b60d96e278ca10a31d6fe223de9c845c9ecae1bb25701ba9814a484d0d4fe5ecd41d
+  data.tar.gz: a7e6be40e45b850c0f73933d372bb64a6ffcc2ea6ab74271375f379beb7732300abc1a855f8d508cb21685324b521e7c3bd435a4bc849e9abbe74cae1529a193

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1 @@
+--color

data/.travis.yml

@@ -0,0 +1,8 @@
+rvm:
+  - 2.1.0
+cache:
+  - bundler
+notifications:
+  email:
+    - dalibor.nasevic@gmail.com
+script: bundle exec rspec spec

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in octoshark.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Dalibor Nasevic
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,129 @@
+![Travis status](https://travis-ci.org/dalibor/octoshark.png)
+
+# Octoshark
+
+Octoshark is a simple ActiveRecord connection switcher. It provides a general purpose connection switching that can be used in a multi-database systems such as sharded environments in your Rails application. It **does not** monkey-patch any `ActiveRecord::Base` methods and requires to specify which ActiveRecord models will use the Octoshark connection.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```
+gem 'octoshark'
+```
+
+And then execute:
+
+```
+$ bundle
+```
+
+Or install it yourself as:
+
+```
+$ gem install octoshark
+```
+
+
+## Usage
+
+Specify the connections for Octoshark to manage. This is usually done in an app initializer.
+
+```ruby
+Octoshark.setup({
+  db1: { adapter: "sqlite3", database: "db/db1.sqlite" },
+  db2: { adapter: "sqlite3", database: "db/db2.sqlite" }
+})
+```
+
+Configure which ActiveRecord models will use the Octoshark connection by overriding the Model.connection method. If there are many models, extract it in a module and include it.
+
+```ruby
+class Post < ActiveRecord::Base
+  def self.connection
+    Octoshark.current_connection
+  end
+end
+```
+
+To use a specific database connection, do:
+
+```ruby
+Octoshark.with_connection(:db1) do
+  # work with db1
+  Post.first
+end
+```
+
+Octoshark connection is changed for the duration of that block and then reversed back to the previous connection. Multiple connection switch blocks can be nested:
+
+```ruby
+Octoshark.with_connection(:db1) do
+  # work with db1
+
+  Octoshark.with_connection(:db2) do
+    # work with db2
+  end
+
+  # work with db1
+end
+```
+
+
+## Sharding Example
+
+For example, let's say we have few models that are in the default Rails database (User, Account, etc) and few models that we want to shard (Blog, Post, Comment, etc). For all models in the default database, we can use the default ActiveRecord connection, and for all sharded models we need to the Octoshark connection.
+
+We specify the connection for the sharded models based on the shard key (User) in a controller with an around filter:
+
+```ruby
+# before_filter :find_user
+around_filter :select_shard
+
+def select_shard(&block)
+  Octoshark.with_connection(current_user.shard, &block)
+end
+```
+
+Similarly, in all other application entry-points that start with the default ActiveRecord connection (background jobs for an example), we need to switch the shard connection and then proceed.
+
+
+## Database Cleaner
+
+Here's an example how to clean default and shard databases using both default connection and Octoshark connections:
+
+```ruby
+config.before(:suite) do
+  clean_database_with(:truncation)
+end
+
+config.before(:each) do
+  DatabaseCleaner.start
+end
+
+config.after(:each) do
+  clean_database_with(:transaction)
+end
+
+def clean_database_with
+  # default ActiveRecord::Base connection pool
+  DatabaseCleaner[:active_record, {connection: ActiveRecord::Base.connection_pool}]
+
+  # Octoshark connection pool for the connection
+  Octoshark.connection_pools.each_pair do |name, connection_pool|
+    DatabaseCleaner[:active_record, {connection: connection_pool}]
+  end
+
+  DatabaseCleaner.clean_with(strategy)
+end
+```
+
+
+## Contributing
+
+1. Fork it ( http://github.com/dalibor/octoshark/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/octoshark.rb

@@ -0,0 +1,34 @@
+require "octoshark/version"
+require 'active_record'
+
+module Octoshark
+  autoload :ConnectionSwitcher, 'octoshark/connection_switcher'
+
+  class NotConfiguredError < RuntimeError; end
+  class NoConnectionError < StandardError; end;
+  class NoCurrentConnectionError < StandardError; end;
+
+  OCTOSHARK = :octoshark
+
+  class << self
+    delegate :current_connection, :with_connection, :connection,
+      :connection_pools, :find_connection_pool, to: :switcher
+  end
+
+  def self.setup(configs)
+    @switcher = ConnectionSwitcher.new(configs)
+  end
+
+  def self.reset!
+    @switcher = nil
+    Thread.current[OCTOSHARK] = nil
+  end
+
+  def self.switcher
+    if @switcher
+      @switcher
+    else
+      raise NotConfiguredError, "Octoshark is not setup. Setup connections with Octoshark.setup(configs)"
+    end
+  end
+end

data/lib/octoshark/connection_switcher.rb

@@ -0,0 +1,52 @@
+module Octoshark
+  class ConnectionSwitcher
+
+    attr_reader :connection_pools
+
+    def initialize(configs = {})
+      @default_pool     = ActiveRecord::Base.connection_pool
+      @connection_pools = { default: @default_pool }.with_indifferent_access
+
+      configs.each_pair do |name, config|
+        spec = ActiveRecord::ConnectionAdapters::ConnectionSpecification.new(
+          config, "#{config[:adapter]}_connection"
+        )
+        @connection_pools[name] = ActiveRecord::ConnectionAdapters::ConnectionPool.new(spec)
+      end
+    end
+
+    def current_connection
+      Thread.current[OCTOSHARK] || raise(NoCurrentConnectionError, "No current connection.")
+    end
+
+    def connection(name)
+      Thread.current[OCTOSHARK] = find_connection_pool(name).connection
+    end
+
+    def with_connection(name, &block)
+      result = nil
+
+      find_connection_pool(name).with_connection do |connection|
+        previous_connection = Thread.current[OCTOSHARK]
+        Thread.current[OCTOSHARK] = connection
+        begin
+          result = yield(connection)
+        ensure
+          Thread.current[OCTOSHARK] = previous_connection
+        end
+      end
+
+      result
+    end
+
+    def find_connection_pool(name, &block)
+      connection_pool = @connection_pools[name]
+
+      if connection_pool
+        connection_pool
+      else
+        raise NoConnectionError, "No such database connection '#{name}'"
+      end
+    end
+  end
+end

data/lib/octoshark/version.rb

@@ -0,0 +1,3 @@
+module Octoshark
+  VERSION = "0.0.1"
+end

data/octoshark.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'octoshark/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "octoshark"
+  spec.version       = Octoshark::VERSION
+  spec.authors       = ["Dalibor Nasevic"]
+  spec.email         = ["dalibor.nasevic@gmail.com"]
+  spec.summary       = %q{Octoshark is an ActiveRecord connection switcher}
+  spec.description   = %q{Octoshark is a library for switching between multiple ActiveRecord connections}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "activerecord", ">= 4.0"
+
+  spec.add_development_dependency "bundler",  "~> 1.5"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec",    "~> 3.0.0"
+  spec.add_development_dependency "sqlite3",  "~> 1.3.0"
+end

data/spec/config/database.yml

@@ -0,0 +1,2 @@
+adapter: sqlite3
+database: tmp/default.sqlite

data/spec/octoshark/connection_switcher_spec.rb

@@ -0,0 +1,118 @@
+require 'spec_helper'
+
+describe Octoshark::ConnectionSwitcher do
+  let(:config) { {
+    db1: { adapter: "sqlite3", database: "tmp/db1.sqlite" },
+    db2: { adapter: "sqlite3", database: "tmp/db2.sqlite" }
+  } }
+
+  def current_database_name(connection)
+    connection.execute('PRAGMA database_list').first['file'].split('/').last
+  end
+
+  describe "#initialize" do
+    it "can initialize connection switcher with default connection" do
+      switcher = Octoshark::ConnectionSwitcher.new
+      conn = ActiveRecord::Base.connection
+
+      expect(switcher.connection_pools.length).to eq(1)
+      expect(switcher.connection_pools[:default]).to be_an_instance_of(ActiveRecord::ConnectionAdapters::ConnectionPool)
+    end
+
+    it "can initialize connection switcher with custom connections" do
+      switcher = Octoshark::ConnectionSwitcher.new(config)
+
+      expect(switcher.connection_pools.length).to eq(3)
+      expect(switcher.connection_pools[:default]).to be_an_instance_of(ActiveRecord::ConnectionAdapters::ConnectionPool)
+      expect(switcher.connection_pools[:db1]).to be_an_instance_of(ActiveRecord::ConnectionAdapters::ConnectionPool)
+    end
+  end
+
+  describe "#current_connection" do
+    it "returns last used connection as current one" do
+      switcher = Octoshark::ConnectionSwitcher.new(config)
+      connection = switcher.connection(:db1)
+
+      expect(switcher.current_connection).to eq(connection)
+    end
+
+    it "raises error when no current connection" do
+      switcher = Octoshark::ConnectionSwitcher.new
+
+      expect { switcher.current_connection }.to raise_error(Octoshark::NoCurrentConnectionError)
+    end
+
+  end
+
+  describe '#find_connection_pool' do
+    it "can find connection pool by name" do
+      switcher = Octoshark::ConnectionSwitcher.new(config)
+      expect(switcher.find_connection_pool(:db1)).to be_an_instance_of(ActiveRecord::ConnectionAdapters::ConnectionPool)
+    end
+
+    it "raises Octoshark::NoConnectionError when no pool with that name" do
+      switcher = Octoshark::ConnectionSwitcher.new({})
+      expect { switcher.find_connection_pool(:invalid) }.to raise_error(Octoshark::NoConnectionError)
+    end
+  end
+
+  describe "#connection" do
+    it "returns useful connection from the pool" do
+      switcher = Octoshark::ConnectionSwitcher.new(config)
+      connection = switcher.connection(:db1)
+      expect(current_database_name(connection)).to eq("db1.sqlite")
+    end
+
+    it "raises Octoshark::NoConnectionError" do
+      switcher = Octoshark::ConnectionSwitcher.new({})
+
+      expect { switcher.connection(:invalid) }.to raise_error(Octoshark::NoConnectionError)
+    end
+  end
+
+  describe '#with_connection' do
+    it "can select default connection" do
+      switcher = Octoshark::ConnectionSwitcher.new({})
+
+      switcher.with_connection(:default) do |connection|
+        expect(current_database_name(switcher.current_connection)).to eq("default.sqlite")
+      end
+    end
+
+    it "can use multiple connections" do
+      switcher = Octoshark::ConnectionSwitcher.new(config)
+
+      switcher.with_connection(:default) do |connection|
+        expect(current_database_name(switcher.current_connection)).to eq("default.sqlite")
+      end
+
+      switcher.with_connection(:db1) do |connection|
+        expect(current_database_name(switcher.current_connection)).to eq("db1.sqlite")
+      end
+
+      switcher.with_connection(:db2) do |connection|
+        expect(current_database_name(switcher.current_connection)).to eq("db2.sqlite")
+      end
+    end
+
+    it "can nest connection" do
+      switcher = Octoshark::ConnectionSwitcher.new(config)
+
+      switcher.with_connection(:db1) do |connection|
+        expect(current_database_name(switcher.current_connection)).to eq("db1.sqlite")
+
+        switcher.with_connection(:db2) do |connection|
+          expect(current_database_name(switcher.current_connection)).to eq("db2.sqlite")
+        end
+
+        expect(current_database_name(switcher.current_connection)).to eq("db1.sqlite")
+      end
+    end
+
+    it "raises Octoshark::NoConnectionError" do
+      switcher = Octoshark::ConnectionSwitcher.new({})
+
+      expect { switcher.with_connection(:invalid) }.to raise_error(Octoshark::NoConnectionError)
+    end
+  end
+end

data/spec/octoshark_spec.rb

@@ -0,0 +1,27 @@
+require 'spec_helper'
+
+describe Octoshark do
+
+  it "can setup Octoshark with default connection" do
+    Octoshark.setup({})
+    expect(Octoshark.switcher).to_not be_nil
+  end
+
+  it "raises NotConfiguredError exception when not configured" do
+    Octoshark.setup({})
+    Octoshark.reset!
+    expect { Octoshark.switcher }.to raise_error(Octoshark::NotConfiguredError)
+  end
+
+  [
+    :current_connection, :with_connection, :connection,
+    :connection_pools, :find_connection_pool
+  ].each do |method_name|
+    it "delegates #{method_name} to connection switcher" do
+      Octoshark.setup({})
+      expect(Octoshark.switcher).to receive(method_name)
+
+      Octoshark.send(method_name)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,8 @@
+require 'octoshark'
+
+RSpec.configure do |config|
+  config.before :each do
+    ActiveRecord::Base.establish_connection(YAML.load(File.read('spec/config/database.yml')))
+    Octoshark.reset!
+  end
+end

metadata

@@ -0,0 +1,134 @@
+--- !ruby/object:Gem::Specification
+name: octoshark
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Dalibor Nasevic
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-07-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+description: Octoshark is a library for switching between multiple ActiveRecord connections
+email:
+- dalibor.nasevic@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/octoshark.rb
+- lib/octoshark/connection_switcher.rb
+- lib/octoshark/version.rb
+- octoshark.gemspec
+- spec/config/database.yml
+- spec/octoshark/connection_switcher_spec.rb
+- spec/octoshark_spec.rb
+- spec/spec_helper.rb
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.0
+signing_key: 
+specification_version: 4
+summary: Octoshark is an ActiveRecord connection switcher
+test_files:
+- spec/config/database.yml
+- spec/octoshark/connection_switcher_spec.rb
+- spec/octoshark_spec.rb
+- spec/spec_helper.rb
+has_rdoc: