octoshark 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8a42c9187a7bf3516c5462a53b9d66b66571ddce
-  data.tar.gz: 6b5a5c331d7f899972277a4badba921b26adf61b
+  metadata.gz: edbe9d237528071174741f9625af2b2f752ebb3f
+  data.tar.gz: a0f0081430d9987ceaa43f375526cab9acec3817
 SHA512:
-  metadata.gz: 9916b8edd7ebb3a0c906f7a71434881fcf41ba9f8e483bb389bfdd07dec5b60d96e278ca10a31d6fe223de9c845c9ecae1bb25701ba9814a484d0d4fe5ecd41d
-  data.tar.gz: a7e6be40e45b850c0f73933d372bb64a6ffcc2ea6ab74271375f379beb7732300abc1a855f8d508cb21685324b521e7c3bd435a4bc849e9abbe74cae1529a193
+  metadata.gz: 01b1279e3d8036eed43a2ef8f780fe5ec13281d424f1202ea2a3d3857cea5a9a826a508a10d35603082fef1b9304883d7a12a801d41e2663bce639cd721ffe37
+  data.tar.gz: 5050e8c20e16acae21138f85cea4cc033500f27f6fba0c4c1c57d85ff20c08a10a233bbcd6517c3592752ed1895250e9c7113ff35ad84e07ae1bfb1feb188dd2

data/README.md

@@ -2,7 +2,7 @@
 
 # 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.
+Octoshark is a simple ActiveRecord connection switcher. It provides a general purpose connection switching mechanism that can be used in sharding and master-slave multi-database environments. It's up to you to specify how ActiveRecord models will use the Octoshark connections, see below for example scenarios.
 
 
 ## Installation
@@ -56,7 +56,11 @@ Octoshark.with_connection(:db1) do
 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:
+Octoshark connection is changed for the duration of the block and then reversed back to the previous connection.
+
+`Octoshark.current_connection` returns the active connection while in `with_connection` block, and outside it raises `Octoshark::NoCurrentConnectionError` error.
+
+Multiple connection switch blocks can be nested:
 
 ```ruby
 Octoshark.with_connection(:db1) do
@@ -89,6 +93,32 @@ 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.
 
 
+## Master-Slave Example
+
+When we want to do something in the slave database with all ActiveRecord models, then we need to add Octoshark's current or default connection to all models, either by overriding `ActiveRecord:Base.connection` or using a module that we include in all models.
+
+```ruby
+class ActiveRecord::Base
+  def self.connection
+    Octoshark.current_or_default_connection
+  end
+end
+```
+
+Here we use `Octoshark.current_or_default_connection` method which returns the current connection while in `with_connection` block and fallback to the default connection when outside.
+
+
+## Octoshark.reload!
+
+While Octoshark tries hard to avoid any **monkey-patching** of `ActiveRecord`, there is a single patch it applies so that end-user does not have to do it manually. Basically, whenever ActiveRecord::Base establishes a new database connection, `Octoshark.reload!` needs to be called. This is necessary for Octoshark to disconnect old connection pools and set new ones, otherwise `ActiveRecord::ConnectionNotEstablished` will be raised.
+
+Few examples where database connections are re-established:
+
+* Unicorn before/after fork
+* Spring prefork/serve
+* Some rake tasks like `rake db:test:prepare`
+
+
 ## Database Cleaner
 
 Here's an example how to clean default and shard databases using both default connection and Octoshark connections:
@@ -119,7 +149,6 @@ def clean_database_with
 end
 ```
 
-
 ## Contributing
 
 1. Fork it ( http://github.com/dalibor/octoshark/fork )

data/lib/octoshark.rb

@@ -1,5 +1,6 @@
-require "octoshark/version"
+require 'octoshark/version'
 require 'active_record'
+require 'octoshark/active_record_extensions'
 
 module Octoshark
   autoload :ConnectionSwitcher, 'octoshark/connection_switcher'
@@ -11,24 +12,41 @@ module Octoshark
   OCTOSHARK = :octoshark
 
   class << self
-    delegate :current_connection, :with_connection, :connection,
-      :connection_pools, :find_connection_pool, to: :switcher
-  end
+    delegate :current_connection, :with_connection,
+      :connection, :current_or_default_connection,
+      :connection_pools, :find_connection_pool,
+      :disconnect!, to: :switcher
 
-  def self.setup(configs)
-    @switcher = ConnectionSwitcher.new(configs)
-  end
+    def setup(configs)
+      @configs = configs
+      @switcher = ConnectionSwitcher.new(configs)
+    end
 
-  def self.reset!
-    @switcher = nil
-    Thread.current[OCTOSHARK] = nil
-  end
+    def reset!
+      return unless enabled?
+      disconnect!
+      @confings = nil
+      @switcher = nil
+      Thread.current[OCTOSHARK] = nil
+    end
+
+    def reload!
+      raise_not_configured_error unless @configs
+      disconnect!
+      @switcher = ConnectionSwitcher.new(@configs)
+    end
+
+    def enabled?
+      !@switcher.nil?
+    end
+
+    def switcher
+      @switcher || raise_not_configured_error
+    end
 
-  def self.switcher
-    if @switcher
-      @switcher
-    else
-      raise NotConfiguredError, "Octoshark is not setup. Setup connections with Octoshark.setup(configs)"
+    private
+    def raise_not_configured_error
+      raise NotConfiguredError, "Octoshark is not setup"
     end
   end
 end

data/lib/octoshark/active_record_extensions.rb

@@ -0,0 +1,20 @@
+module Octoshark
+  module ActiveRecordExtensions
+    extend ActiveSupport::Concern
+
+    included do
+      class << self
+        alias_method_chain :establish_connection, :octoshark
+      end
+    end
+
+    module ClassMethods
+      def establish_connection_with_octoshark(*args)
+        establish_connection_without_octoshark(*args)
+        Octoshark.reload! if Octoshark.enabled?
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.send(:include, Octoshark::ActiveRecordExtensions)

data/lib/octoshark/connection_switcher.rb

@@ -16,11 +16,11 @@ module Octoshark
     end
 
     def current_connection
-      Thread.current[OCTOSHARK] || raise(NoCurrentConnectionError, "No current connection.")
+      Thread.current[OCTOSHARK] || raise(NoCurrentConnectionError, "No current connection")
     end
 
-    def connection(name)
-      Thread.current[OCTOSHARK] = find_connection_pool(name).connection
+    def current_or_default_connection
+      Thread.current[OCTOSHARK] || @default_pool.connection
     end
 
     def with_connection(name, &block)
@@ -40,12 +40,12 @@ module Octoshark
     end
 
     def find_connection_pool(name, &block)
-      connection_pool = @connection_pools[name]
+      @connection_pools[name] || raise(NoConnectionError, "No such database connection '#{name}'")
+    end
 
-      if connection_pool
-        connection_pool
-      else
-        raise NoConnectionError, "No such database connection '#{name}'"
+    def disconnect!
+      @connection_pools.values.each do |connection_pool|
+        connection_pool.disconnect!
       end
     end
   end

data/lib/octoshark/version.rb

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

data/octoshark.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   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.homepage      = "https://github.com/dalibor/octoshark"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0")
@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_runtime_dependency "activerecord", ">= 4.0"
+  spec.add_runtime_dependency "activerecord", ">= 3.0"
 
   spec.add_development_dependency "bundler",  "~> 1.5"
   spec.add_development_dependency "rake"

data/spec/octoshark/active_record_extensions_spec.rb

@@ -0,0 +1,17 @@
+require 'spec_helper'
+
+describe Octoshark::ActiveRecordExtensions do
+
+  it "reloads Octoshark when re-establishing new connection" do
+    Octoshark.setup(configs)
+    spec = ActiveRecord::Base.remove_connection
+
+    expect { Octoshark.with_connection(:default) {} }.to raise_error(ActiveRecord::ConnectionNotEstablished)
+    expect { Octoshark.with_connection(:db1) {} }.not_to raise_error
+
+    ActiveRecord::Base.establish_connection(spec)
+
+    expect { Octoshark.with_connection(:default) {} }.not_to raise_error
+    expect { Octoshark.with_connection(:db1) {} }.not_to raise_error
+  end
+end

data/spec/octoshark/connection_switcher_spec.rb

@@ -1,15 +1,6 @@
 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
@@ -20,7 +11,7 @@ describe Octoshark::ConnectionSwitcher do
     end
 
     it "can initialize connection switcher with custom connections" do
-      switcher = Octoshark::ConnectionSwitcher.new(config)
+      switcher = Octoshark::ConnectionSwitcher.new(configs)
 
       expect(switcher.connection_pools.length).to eq(3)
       expect(switcher.connection_pools[:default]).to be_an_instance_of(ActiveRecord::ConnectionAdapters::ConnectionPool)
@@ -30,10 +21,10 @@ describe Octoshark::ConnectionSwitcher do
 
   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)
+      switcher = Octoshark::ConnectionSwitcher.new(configs)
+      switcher.with_connection(:db1) do |connection|
+        expect(switcher.current_connection).to eq(connection)
+      end
     end
 
     it "raises error when no current connection" do
@@ -41,12 +32,27 @@ describe Octoshark::ConnectionSwitcher do
 
       expect { switcher.current_connection }.to raise_error(Octoshark::NoCurrentConnectionError)
     end
+  end
 
+  describe "#current_or_default_connection" do
+    it "returns current connection" do
+      switcher = Octoshark::ConnectionSwitcher.new(configs)
+      switcher.with_connection(:db1) do |connection|
+        expect(switcher.current_or_default_connection).to eq(connection)
+      end
+    end
+
+    it "returns default connection when no current connection" do
+      switcher = Octoshark::ConnectionSwitcher.new
+      connection = switcher.find_connection_pool(:default).connection
+
+      expect(switcher.current_or_default_connection).to eq(connection)
+    end
   end
 
   describe '#find_connection_pool' do
     it "can find connection pool by name" do
-      switcher = Octoshark::ConnectionSwitcher.new(config)
+      switcher = Octoshark::ConnectionSwitcher.new(configs)
       expect(switcher.find_connection_pool(:db1)).to be_an_instance_of(ActiveRecord::ConnectionAdapters::ConnectionPool)
     end
 
@@ -56,56 +62,42 @@ describe Octoshark::ConnectionSwitcher do
     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")
+        expect(db(switcher.current_connection)).to eq("default")
       end
     end
 
     it "can use multiple connections" do
-      switcher = Octoshark::ConnectionSwitcher.new(config)
+      switcher = Octoshark::ConnectionSwitcher.new(configs)
 
       switcher.with_connection(:default) do |connection|
-        expect(current_database_name(switcher.current_connection)).to eq("default.sqlite")
+        expect(db(switcher.current_connection)).to eq("default")
       end
 
       switcher.with_connection(:db1) do |connection|
-        expect(current_database_name(switcher.current_connection)).to eq("db1.sqlite")
+        expect(db(switcher.current_connection)).to eq("db1")
       end
 
       switcher.with_connection(:db2) do |connection|
-        expect(current_database_name(switcher.current_connection)).to eq("db2.sqlite")
+        expect(db(switcher.current_connection)).to eq("db2")
       end
     end
 
     it "can nest connection" do
-      switcher = Octoshark::ConnectionSwitcher.new(config)
+      switcher = Octoshark::ConnectionSwitcher.new(configs)
 
       switcher.with_connection(:db1) do |connection|
-        expect(current_database_name(switcher.current_connection)).to eq("db1.sqlite")
+        expect(db(switcher.current_connection)).to eq("db1")
 
         switcher.with_connection(:db2) do |connection|
-          expect(current_database_name(switcher.current_connection)).to eq("db2.sqlite")
+          expect(db(switcher.current_connection)).to eq("db2")
         end
 
-        expect(current_database_name(switcher.current_connection)).to eq("db1.sqlite")
+        expect(db(switcher.current_connection)).to eq("db1")
       end
     end
 
@@ -115,4 +107,17 @@ describe Octoshark::ConnectionSwitcher do
       expect { switcher.with_connection(:invalid) }.to raise_error(Octoshark::NoConnectionError)
     end
   end
+
+  describe "#disconnect!" do
+    it "removes all connections from connection pools" do
+      switcher = Octoshark::ConnectionSwitcher.new({})
+
+      switcher.with_connection(:default) { |connection| connection.execute("SELECT 1") }
+      expect(switcher.find_connection_pool(:default)).to be_connected
+
+      switcher.disconnect!
+
+      expect(switcher.find_connection_pool(:default)).to_not be_connected
+    end
+  end
 end

data/spec/octoshark_spec.rb

@@ -2,26 +2,86 @@ require 'spec_helper'
 
 describe Octoshark do
 
-  it "can setup Octoshark with default connection" do
-    Octoshark.setup({})
-    expect(Octoshark.switcher).to_not be_nil
+  describe ".setup" do
+    it "creates connection switcher" do
+      Octoshark.setup({})
+
+      expect(Octoshark.switcher).to_not be_nil
+    end
   end
 
-  it "raises NotConfiguredError exception when not configured" do
-    Octoshark.setup({})
-    Octoshark.reset!
-    expect { Octoshark.switcher }.to raise_error(Octoshark::NotConfiguredError)
+  describe ".reset!" do
+    it "removes connection switcher" do
+      Octoshark.setup({})
+      Octoshark.reset!
+
+      expect { Octoshark.switcher }.to raise_error(Octoshark::NotConfiguredError)
+    end
+
+    it "cleans octoshark thread key" do
+      Octoshark.setup({})
+      Octoshark.reset!
+
+      expect(Thread.current[Octoshark::OCTOSHARK]).to be_nil
+    end
+
+    it "cleans old connections" do
+      check_connections_clean_up { Octoshark.reset! }
+    end
+  end
+
+  describe ".reload!" do
+    it "replaces connection switcher" do
+      Octoshark.setup({})
+      switcher = Octoshark.switcher
+
+      Octoshark.reload!
+
+      expect(Octoshark.switcher).to_not be_nil
+      expect(Octoshark.switcher).to_not eq(switcher)
+    end
+
+    it "clears old switcher connections" do
+      check_connections_clean_up { Octoshark.reload! }
+    end
+  end
+
+  describe ".enabled?" do
+    it "is not enabled by default" do
+      expect(Octoshark.enabled?).to be_falsey
+    end
+
+    it "is enabled when it's setup" do
+      Octoshark.setup({})
+
+      expect(Octoshark.enabled?).to be_truthy
+    end
+  end
+
+  describe ".switcher" do
+    it "returns connection switcher" do
+      Octoshark.setup({})
+
+      expect(Octoshark.switcher).to be_an_instance_of(Octoshark::ConnectionSwitcher)
+    end
+
+    it "raises 'NotConfiguredError' error if not setup" do
+      expect { Octoshark.switcher }.to raise_error(Octoshark::NotConfiguredError)
+    end
   end
 
   [
-    :current_connection, :with_connection, :connection,
+    :current_connection, :with_connection,
+    :connection, :current_or_default_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)
+    describe ".#{method_name}" do
+      it "delegates #{method_name} to connection switcher" do
+        Octoshark.setup({})
+        expect(Octoshark.switcher).to receive(method_name)
 
-      Octoshark.send(method_name)
+        Octoshark.send(method_name)
+      end
     end
   end
 end

data/spec/spec_helper.rb

@@ -1,8 +1,16 @@
 require 'octoshark'
 
+
+# Load support files
+ROOT = File.expand_path('../', File.dirname(__FILE__))
+Dir["#{ROOT}/spec/support/**/*.rb"].each { |f| require f }
+
+
 RSpec.configure do |config|
+  config.include Helpers
+
   config.before :each do
-    ActiveRecord::Base.establish_connection(YAML.load(File.read('spec/config/database.yml')))
+    ActiveRecord::Base.establish_connection({adapter: 'sqlite3', database: 'tmp/default.sqlite'})
     Octoshark.reset!
   end
 end

data/spec/support/helpers.rb

@@ -0,0 +1,28 @@
+module Helpers
+
+  def configs
+    {
+      db1: { adapter: "sqlite3", database: "tmp/db1.sqlite" },
+      db2: { adapter: "sqlite3", database: "tmp/db2.sqlite" }
+    }
+  end
+
+  def db(connection)
+    connection.execute('PRAGMA database_list').
+      first['file'].
+      split('/').last.
+      split('.').first
+  end
+
+  def check_connections_clean_up
+    Octoshark.setup({})
+    switcher = Octoshark.switcher
+
+    Octoshark.with_connection(:default) { |connection| connection.execute("SELECT 1") }
+    expect(switcher.connection_pools.map { |_, c| c.connections.count }.sum).to eq(1)
+
+    yield
+
+    expect(switcher.connection_pools.map { |_, c| c.connections.count }.sum).to eq(0)
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: octoshark
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Dalibor Nasevic
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-17 00:00:00.000000000 Z
+date: 2014-07-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -95,14 +95,16 @@ files:
 - README.md
 - Rakefile
 - lib/octoshark.rb
+- lib/octoshark/active_record_extensions.rb
 - lib/octoshark/connection_switcher.rb
 - lib/octoshark/version.rb
 - octoshark.gemspec
-- spec/config/database.yml
+- spec/octoshark/active_record_extensions_spec.rb
 - spec/octoshark/connection_switcher_spec.rb
 - spec/octoshark_spec.rb
 - spec/spec_helper.rb
-homepage: ''
+- spec/support/helpers.rb
+homepage: https://github.com/dalibor/octoshark
 licenses:
 - MIT
 metadata: {}
@@ -127,8 +129,9 @@ signing_key:
 specification_version: 4
 summary: Octoshark is an ActiveRecord connection switcher
 test_files:
-- spec/config/database.yml
+- spec/octoshark/active_record_extensions_spec.rb
 - spec/octoshark/connection_switcher_spec.rb
 - spec/octoshark_spec.rb
 - spec/spec_helper.rb
+- spec/support/helpers.rb
 has_rdoc: 

data/spec/config/database.yml

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