activerecord-futures 0.0.1 → 0.1.0

data/.travis.yml

@@ -0,0 +1,20 @@
+language: ruby
+rvm:
+  - 1.9.3
+env:
+  - ADAPTER=future_enabled_mysql2 activerecord=3.2.11
+  - ADAPTER=future_enabled_mysql2 activerecord=3.2.12
+  - ADAPTER=future_enabled_mysql2 activerecord=3.2.13
+  - ADAPTER=mysql2 activerecord=3.2.11
+  - ADAPTER=mysql2 activerecord=3.2.12
+  - ADAPTER=mysql2 activerecord=3.2.13
+  - ADAPTER=future_enabled_postgresql activerecord=3.2.11
+  - ADAPTER=future_enabled_postgresql activerecord=3.2.12
+  - ADAPTER=future_enabled_postgresql activerecord=3.2.13
+  - ADAPTER=postgresql activerecord=3.2.11
+  - ADAPTER=postgresql activerecord=3.2.12
+  - ADAPTER=postgresql activerecord=3.2.13
+
+before_script:
+  - mysql -e 'create database activerecord_futures_test;'
+  - psql -c 'create database activerecord_futures_test;' -U postgres

data/Gemfile

@@ -1,4 +1,14 @@
-source 'https://rubygems.org'
+source 'http://rubygems.org'
 
 # Specify your gem's dependencies in activerecord-futures.gemspec
 gemspec
+
+group :test do
+  gem 'rake'
+end
+
+gem 'coveralls', require: false
+
+if ENV['activerecord']
+  gem "activerecord", ENV['activerecord']
+end

data/README.md

@@ -1,7 +1,21 @@
 # ActiveRecord::Futures
 
+[![Build Status](https://travis-ci.org/leoasis/activerecord-futures.png)](https://travis-ci.org/leoasis/activerecord-futures)
+[![Code Climate](https://codeclimate.com/github/leoasis/activerecord-futures.png)](https://codeclimate.com/github/leoasis/activerecord-futures)
+[![Coverage Status](https://coveralls.io/repos/leoasis/activerecord-futures/badge.png?branch=master)](https://coveralls.io/r/leoasis/activerecord-futures)
+
+
 Define future queries in ActiveRecord that will get executed in a single round trip to the database.
 
+This gem allows to easily optimize an application using activerecord. All
+independent queries can be marked as futures, so that when you execute any of
+them at a later time, all the other ones will be executed as well, but the query
+of all of them will be executed in a single round trip to the database. That way,
+when you access the other results, they'll already be there, not needing to go
+to the database again.
+
+The idea is heavily inspired from [NHibernate's future queries](http://ayende.com/blog/3979/nhibernate-futures)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -18,13 +32,11 @@ Or install it yourself as:
 
 ## Usage
 
-Currently, the only database supported is MySQL, and with a special adapter, provided by the gem.
-
-Set your config/database.yml file to use the given adapter:
+Once the gem is installed, set your config/database.yml file to use a future enabled adapter:
 
 ```yml
 development: &development
-  adapter: future_enabled_mysql2 # set this adapter for futures to work!
+  adapter: future_enabled_mysql2 # or "future_enabled_postgresql"
   username: your_username
   password: your_password
   database: your_database
@@ -34,19 +46,24 @@ development: &development
 Now let's see what this does, consider a model `User`, with a `:name` attribute:
 
 ```ruby
+
 # Build the queries and mark them as futures
-users = User.where("name like 'John%'").future # becomes a future relation, does not execute the query.
-count = User.where("name like 'John%'").future_count # becomes a future calculation, does not execute the query.
+users = User.where("name like 'John%'")
+user_list = users.future # becomes a future relation, does not execute the query.
+count = users.future_count # becomes a future calculation, does not execute the query.
 
 # Execute any of the futures
 count = count.value # trigger the future execution, both queries will get executed in one round trip!
 #=> User Load (fetching Futures) (0.6ms)  SELECT `users`.* FROM `users` WHERE (name like 'John%');SELECT COUNT(*) FROM `users` WHERE (name like 'John%')
 
 # Access the other results
-users = users.to_a # does not execute the query, results from previous query get loaded
+user_list.to_a # does not execute the query, results from previous query get loaded
 ```
 
-Any amount of futures can be prepared, and the will get executed as soon as one of them needs to be evaluated.
+Any amount of futures can be prepared, and they will get executed as soon as one of them needs to be evaluated.
+
+This makes this especially useful for pagination queries, since you can execute
+both count and page queries at once.
 
 ### Methods
 
@@ -55,28 +72,37 @@ executed whenever `#to_a` gets executed. Note that, as ActiveRecord does, enumer
 so things like `#each`, `#map`, `#collect` all trigger the future.
 
 Also, ActiveRecord::Relation instances get all the calculation methods provided by the ActiveRecord::Calculations module
-"futurized", that means, for `#count` you get `#future_count`, for `#sum` you get `#future_sum` and so on. These future
-calculations are triggered by executing the `#value` method, which also return the actual result of the calculation.
+"futurized", that means, for `#count` you get `#future_count`, for `#sum` you get `#future_sum` and so on. If the calculation
+returns a list of values, for example with a `#future_pluck` or a grouped `#future_count`, the future will be triggered with
+the `#to_a` method (or any of the methods that delegate to `#to_a`). If it returns a single value, the future will be 
+triggered when you execute the `#value` method.
 
 ## Database support
 
 ### SQlite
 
-SQlite doesn't support multiple statement queries. Currently this gem doesn't fall back to the normal behavior if the
-adapter does not support futures, but this is in the road map :)
+SQlite doesn't support multiple statement queries. ActiveRecord::Futures will fall back to normal query execution, that is,
+it will execute the future's query whenever the future is triggered, but it will not execute the other futures' queries.
 
 ### MySQL
 
 Multi statement queries are supported by the mysql2 gem since version 0.3.12b1, so you'll need to use that one or a newer
 one.
-Currently the adapter provided is the same as the built-in in Rails, but it also sets the MULTI_STATEMENTS flag to allow
-multiple queries in a single command. It also has a special way to
-execute the queries in order to fetch the results correctly. You
-can check the code if you're curious!
+Currently the adapter provided inherits the built-in one in Rails, and it also sets the MULTI_STATEMENTS flag to allow 
+multiple queries in a single command.
+If you have an older version of the gem, ActiveRecord::Futures will fall back to normal query execution.
 
 ### Postgres
 
-Coming soon!
+The pg gem supports multiple statement queries by using the `send_query` method
+and retrieving the results via `get_result`.
+
+### Other databases
+
+In general, ActiveRecord::Futures will look for a method `#supports_futures?` in the adapter. So any adapter that returns
+false when calling the method, or does not respond to it, will fall back to normal query execution.
+If you want to have support for ActiveRecord::Futures with your database, feel free to create a pull request with it, or
+create your own gem, or just create an issue.
 
 ## Contributing
 
@@ -85,9 +111,3 @@ Coming soon!
 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
-
-## Roadmap
-
-1. Support for postgres
-2. Fallback to normal queries when adapter does not support futures
-3. Think of a way to use the normal adapters

data/Rakefile

@@ -1 +1,18 @@
 require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+ADAPTERS = %w(future_enabled_mysql2 future_enabled_postgresql postgresql mysql2)
+
+desc "Runs the specs with all databases"
+task :all do
+  success = true
+  ADAPTERS.each do |adapter|
+    status = system({ "ADAPTER" => adapter }, "bundle exec rspec")
+    success &&= status
+  end
+  abort unless success
+end

data/activerecord-futures.gemspec

@@ -17,7 +17,9 @@ Gem::Specification.new do |gem|
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
 
-  gem.add_dependency 'activerecord', '>= 3.2.13'
+  gem.add_dependency 'activerecord', '>= 3.2.11'
   gem.add_development_dependency 'rspec'
   gem.add_development_dependency 'rspec-spies'
+  gem.add_development_dependency 'mysql2', '>= 0.3.12.b1'
+  gem.add_development_dependency 'pg'
 end

data/lib/active_record/connection_adapters/future_enabled.rb

@@ -0,0 +1,34 @@
+module ActiveRecord
+  module ConnectionAdapters
+    module FutureEnabled
+      def supports_futures?
+        true
+      end
+
+      def exec_query(sql, name = 'SQL', binds = [])
+        my_future = Futures::Future.current
+
+        # default behavior if not a current future or not executing
+        # the current future's sql (some adapters like PostgreSQL
+        # may execute some attribute queries during a relation evaluation)
+        return super unless my_future && my_future.to_sql == sql
+
+        # return fulfilled result, if exists, to load the relation
+        return my_future.result if my_future.fulfilled?
+
+        futures = Futures::Future.all
+        futures_sql = futures.map(&:to_sql).join(';')
+        name = "#{name} (fetching Futures)"
+
+        result = future_execute(futures_sql, name)
+
+        futures.each do |future|
+          future.fulfill(build_active_record_result(result))
+          result = next_result
+        end
+
+        my_future.result
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/future_enabled_mysql2_adapter.rb

@@ -1,5 +1,5 @@
 require "active_record/connection_adapters/mysql2_adapter"
-
+require "active_record/connection_adapters/future_enabled"
 module ActiveRecord
   class Base
     def self.future_enabled_mysql2_connection(config)
@@ -18,33 +18,34 @@ module ActiveRecord
 
   module ConnectionAdapters
     class FutureEnabledMysql2Adapter < Mysql2Adapter
+      include FutureEnabled
+
+      def initialize(*args)
+        super
+        unless supports_futures?
+          logger.warn("ActiveRecord::Futures - You're using the mysql2 future "\
+            "enabled adapter with an old version of the mysql2 gem. You must "\
+            "use a mysql2 gem version higher than or equal to 0.3.12b1 to take "\
+            "advantage of futures.\nFalling back to normal query execution behavior.")
+        end
+      end
 
       def supports_futures?
-        true
+        # Support only if the mysql client allows fetching multiple statements
+        # results
+        @connection.respond_to?(:store_result)
       end
 
-      def exec_query(sql, name = 'SQL', binds = [])
-        my_future = Futures::Future.current
-
-        # default behavior if not a current future
-        return super unless my_future
-
-        # return fulfilled result, if exists, to load the relation
-        return my_future.result if my_future.fulfilled?
-
-        futures = Futures::Future.all
-
-        futures_sql = futures.map(&:to_sql).join(';')
-        name = "#{name} (fetching Futures)"
-
-        result = execute(futures_sql, name)
+      def future_execute(sql, name)
+        execute(sql, name)
+      end
 
-        futures.each do |future|
-          future.fulfill(ActiveRecord::Result.new(result.fields, result.to_a))
-          result = @connection.store_result if @connection.next_result
-        end
+      def build_active_record_result(raw_result)
+        ActiveRecord::Result.new(raw_result.fields, raw_result.to_a)
+      end
 
-        my_future.result
+      def next_result
+        @connection.store_result if @connection.next_result
       end
     end
   end

data/lib/active_record/connection_adapters/future_enabled_postgresql_adapter.rb

@@ -0,0 +1,52 @@
+require 'active_record/connection_adapters/postgresql_adapter'
+require "active_record/connection_adapters/future_enabled"
+
+module ActiveRecord
+  class Base
+    # Establishes a connection to the database that's used by all Active Record objects
+    def self.future_enabled_postgresql_connection(config) # :nodoc:
+      config = config.symbolize_keys
+      host     = config[:host]
+      port     = config[:port] || 5432
+      username = config[:username].to_s if config[:username]
+      password = config[:password].to_s if config[:password]
+
+      if config.key?(:database)
+        database = config[:database]
+      else
+        raise ArgumentError, "No database specified. Missing argument: database."
+      end
+
+      # The postgres drivers don't allow the creation of an unconnected PGconn object,
+      # so just pass a nil connection object for the time being.
+      ConnectionAdapters::FutureEnabledPostgreSQLAdapter.new(nil, logger, [host, port, nil, nil, database, username, password], config)
+    end
+  end
+
+  module ConnectionAdapters
+    class FutureEnabledPostgreSQLAdapter < PostgreSQLAdapter
+      include FutureEnabled
+
+      def future_execute(sql, name)
+        log(sql, name) do
+          # Clear the queue
+          @connection.get_last_result
+          @connection.send_query(sql)
+          @connection.block
+          @connection.get_result
+        end
+      end
+
+      def build_active_record_result(raw_result)
+        return if raw_result.nil?
+        result =  ActiveRecord::Result.new(raw_result.fields, result_as_array(raw_result))
+        raw_result.clear
+        result
+      end
+
+      def next_result
+        @connection.get_result
+      end
+    end
+  end
+end

data/lib/active_record/futures.rb

@@ -3,7 +3,7 @@ module ActiveRecord
     include QueryRecording
 
     def self.original_calculation_methods
-      ActiveRecord::Calculations.public_instance_methods
+      [:count, :average, :minimum, :maximum, :sum, :calculate, :pluck]
     end
 
     def self.future_calculation_methods
@@ -11,12 +11,7 @@ module ActiveRecord
     end
 
     def future
-      supports_futures = connection.respond_to?(:supports_futures?) &&
-                         connection.supports_futures?
-
-      # simply pass through if the connection adapter does not support
-      # futures
-      supports_futures ? FutureRelation.new(self) : self
+      FutureRelation.new(self)
     end
 
     method_table = Hash[future_calculation_methods.zip(original_calculation_methods)]
@@ -26,8 +21,14 @@ module ActiveRecord
     method_table.each do |future_method, method|
       define_method(future_method) do |*args, &block|
         exec = lambda { send(method, *args, &block) }
-        query = record_query(&exec)
-        FutureCalculation.new(query, exec)
+        query, type = record_query(&exec)
+
+        case type
+        when :value
+          FutureCalculationValue.new(self, query, exec)
+        when :all
+          FutureCalculationArray.new(self, query, exec)
+        end
       end
     end
   end

data/lib/active_record/futures/delegation.rb

@@ -2,6 +2,7 @@ module ActiveRecord
   module Futures
     module Delegation
       delegate :future, to: :scoped
+      delegate :future_pluck, to: :scoped
       delegate *Futures.future_calculation_methods, to: :scoped
     end
   end

data/lib/active_record/futures/future.rb

@@ -27,12 +27,23 @@ module ActiveRecord
           self.futures.each(&:load)
           clear
         end
+
+      private
+        def fetch_with(method)
+          define_method(method) do
+            # Flush all the futures upon first attempt to exec a future
+            Future.flush unless executed?
+            execute
+          end
+        end
       end
 
 
-      attr_reader :result
+      attr_reader :result, :relation
+      private :relation
 
-      def initialize
+      def initialize(relation)
+        @relation = relation
         Future.register(self)
       end
 
@@ -45,15 +56,15 @@ module ActiveRecord
       end
 
       def load
+        # Only perform a load if the adapter supports futures.
+        # This allows to fallback to normal query execution in futures
+        # when the adapter does not support futures.
+        return unless connection_supports_futures?
         Future.current = self
         execute
         Future.current = nil
       end
 
-      def inspect
-        to_a.inspect
-      end
-
       def to_sql
       end
       undef_method :to_sql
@@ -67,6 +78,11 @@ module ActiveRecord
       end
       undef_method :executed?
 
+      def connection_supports_futures?
+        conn = relation.connection
+        conn.respond_to?(:supports_futures?) && conn.supports_futures?
+      end
+
     end
   end
 end