ensql 0.6.0 → 0.6.5

data/lib/ensql/adapter.rb

@@ -1,8 +1,49 @@
 # frozen_string_literal: true
 
-require_relative "../ensql"
+require_relative "error"
 
 module Ensql
+  class << self
+    # Get the current connection adapter. If not specified, it will try to
+    # autoload an adapter based on the availability of Sequel or ActiveRecord,
+    # in that order.
+    #
+    # @example
+    #     require 'sequel'
+    #     Ensql.adapter # => Ensql::SequelAdapter.new
+    #     Ensql.adapter = Ensql::ActiveRecordAdapter.new # override adapter
+    #     Ensql.adapter = my_tsql_adapter # supply your own adapter
+    #
+    def adapter
+      Thread.current[:ensql_adapter] || Thread.main[:ensql_adapter] ||= autoload_adapter
+    end
+
+    # Set the connection adapter to use. Must implement the interface defined in
+    # {Ensql::Adapter}. This uses a thread-local variable so adapters can be
+    # switched safely in a multi-threaded web server.
+    def adapter=(adapter)
+      if adapter.is_a?(Module) && (adapter.name == "Ensql::SequelAdapter" || adapter.name == "Ensql::ActiveRecordAdapter")
+        warn "Using `#{adapter}` as an adapter is deprecated, use `#{adapter}.new`.", uplevel: 1
+      end
+
+      Thread.current[:ensql_adapter] = adapter
+    end
+
+    private
+
+    def autoload_adapter
+      if defined? Sequel
+        require_relative "sequel_adapter"
+        SequelAdapter.new
+      elsif defined? ActiveRecord
+        require_relative "active_record_adapter"
+        ActiveRecordAdapter.new
+      else
+        raise Error, "Couldn't autodetect an adapter, please specify manually."
+      end
+    end
+  end
+
   #
   # @abstract Do not use this module directly.
   #
@@ -11,7 +52,6 @@ module Ensql
   # that can be improved in the adapters.
   #
   module Adapter
-
     # @!group 1. Interface Methods
 
     # @!method literalize(value)
@@ -41,6 +81,13 @@ module Ensql
     #
     # @return [Array<Hash>] rows as hashes keyed by column name
 
+    # @!method fetch_each_row(sql)
+    #
+    # Execute the query and yield each resulting row. This should provide a more
+    # efficient method of iterating through large datasets.
+    #
+    # @yield <Hash> row
+
     # @!method fetch_count(sql)
     #
     # Execute the statement and return the number of rows affected. Typically
@@ -58,18 +105,10 @@ module Ensql
 
     # @!group 2. Predefined Methods
 
-    # Execute the query and yield each resulting row. This should provide a more
-    # efficient method of iterating through large datasets.
-    #
-    # @yield <Hash> row
-    def fetch_each_row(sql, &block)
-      fetch_rows(sql).each(&block)
-    end
-
     # Execute the query and return only the first row of the result.
     # @return <Hash>
     def fetch_first_row(sql)
-      fetch_rows(sql).first
+      fetch_each_row(sql).first
     end
 
     # Execute the query and return only the first column of the result.
@@ -82,6 +121,5 @@ module Ensql
     def fetch_first_field(sql)
       fetch_first_row(sql)&.values&.first
     end
-
   end
 end

data/lib/ensql/error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Ensql
+  # Wrapper for errors raised by Ensql
+  class Error < StandardError; end
+end

data/lib/ensql/load_sql.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "sql"
+require_relative "error"
+
+module Ensql
+  class << self
+    # Path to search for *.sql queries in, defaults to "sql/". For example, if
+    # {sql_path} is set to 'app/queries', `load_sql('users/active')` will read
+    # 'app/queries/users/active.sql'.
+    # @see .load_sql
+    #
+    # @example
+    #   Ensql.sql_path = Rails.root.join('app/queries')
+    #
+    def sql_path
+      @sql_path ||= "sql"
+    end
+    attr_writer :sql_path
+
+    # Load SQL from a file within {sql_path}. This is the recommended way to
+    # manage SQL in a non-trivial project. For details of how to write
+    # interpolation placeholders, see {SQL}.
+    #
+    # @see .sql_path=
+    # @return [Ensql::SQL]
+    #
+    # @example
+    #   Ensql.load_sql('users/activity', report_params)
+    #   Ensql.load_sql(:upsert_users, imported_users_attrs)
+    #
+    def load_sql(name, params = {})
+      path = File.join(sql_path, "#{name}.sql")
+      SQL.new(File.read(path), params, name)
+    rescue Errno::ENOENT
+      raise Error, "couldn't load SQL from file '#{path}' (sql_path: '#{sql_path}')"
+    end
+  end
+end

data/lib/ensql/pool_wrapper.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Ensql
+  # Wrap a 3rd-party connection pool with a standard interface. Connections can be checked out by {with}
+  class PoolWrapper
+    # Wraps a block for accessing a connection from a pool.
+    #
+    #     PoolWrapper.new do |client_block|
+    #       my_connection_pool.with_connection(&client_block)
+    #     end
+    def initialize(&connection_block)
+      @connection_block = connection_block
+    end
+
+    # Get a connection from our source pool
+    # @yield [connection] the database-specific connection
+    def with(&client_block)
+      @connection_block.call(client_block)
+    end
+  end
+end

data/lib/ensql/postgres_adapter.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require_relative "version"
+require_relative "adapter"
+
+gem "pg", Ensql::SUPPORTED_PG_VERSIONS
+require "pg"
+require "connection_pool"
+
+module Ensql
+  # Wraps a pool of PG connections to implement the {Adapter} interface. The
+  # adapter can use a 3rd-party pool (e.g. from ActiveRecord of Sequel) or
+  # manage its own using the simple
+  # [connection_pool gem](https://github.com/mperham/connection_pool).
+  #
+  # This adapter is much faster and offers much better PostgreSQL specific
+  # parameter interpolation than the framework adapters. See {query_type_map}
+  # for options.
+  #
+  # @example
+  #     # Use with ActiveRecord's connection pool
+  #     Ensql.adapter = Ensql::PostgresAdapter.new(Ensql::ActiveRecordAdapter.pool)
+  #
+  #     # Use with Sequel's connection pool
+  #     DB = Sequel.connect(ENV['DATABASE_URL'])
+  #     Ensql.adapter = Ensql::PostgresAdapter.new(Ensql::SequelAdapter.pool(DB))
+  #
+  #     # Use with our own thread-safe connection pool
+  #     Ensql.adapter = Ensql::PostgresAdapter.pool { PG.connect ENV['DATABASE_URL'] }
+  #     Ensql.adapter = Ensql::PostgresAdapter.pool(size: 5) { PG.connect ENV['DATABASE_URL'] }
+  #
+  # @see SUPPORTED_PG_VERSIONS
+  #
+  class PostgresAdapter
+    include Adapter
+
+    # Set up a connection pool using the supplied block to initialise connections.
+    #
+    #     PostgresAdapter.pool(size: 20) { PG.connect ENV['DATABASE_URL'] }
+    #
+    # @param pool_opts are sent straight to the ConnectionPool initializer.
+    # @option pool_opts [Integer] timeout (5) number of seconds to wait for a connection if none currently available.
+    # @option pool_opts [Integer] size (5) number of connections to pool.
+    # @yieldreturn [PG::Connection] a new connection.
+    def self.pool(**pool_opts, &connection_block)
+      new ConnectionPool.new(**pool_opts, &connection_block)
+    end
+
+    # @param pool [PoolWrapper, ConnectionPool, #with] a object that yields a PG::Connection using `#with`
+    def initialize(pool)
+      @pool = pool
+      @quoter = PG::TextEncoder::QuotedLiteral.new
+    end
+
+    # A map for encoding Ruby objects into PostgreSQL literals based on their
+    # class. You can add additional class mappings to suit your needs. See
+    # https://rubydoc.info/gems/pg/PG/BasicTypeRegistry for details of adding
+    # your own encoders and decoders.
+    #
+    #     # Encode any `IPAddr` objects for interpolation using the `InetEncoder`.
+    #     Ensql.adapter.query_type_map[IPAddr] = InetEncoder.new
+    #
+    #     # Deserialize `inet` columns as IPAddr objects.
+    #     PG::BasicTypeRegistry.register_type(0, 'inet', InetEncoder, InetDecoder)
+    #
+    # @return [PG::TypeMapByClass]
+    def query_type_map
+      @query_type_map ||= @pool.with do |connection|
+        map = PG::BasicTypeMapForQueries.new(connection)
+        # Ensure encoders are set up for old versions of the pg gem
+        map[Date] ||= PG::TextEncoder::Date.new
+        map[Time] ||= PG::TextEncoder::TimestampWithoutTimeZone.new
+        map[Hash] ||= PG::TextEncoder::JSON.new
+        map[BigDecimal] ||= NumericEncoder.new
+        map
+      end
+    end
+
+    # @visibility private
+    def run(sql)
+      execute(sql) { nil }
+    end
+
+    # @visibility private
+    def literalize(value)
+      case value
+      when NilClass then "NULL"
+      when Numeric, TrueClass, FalseClass then value.to_s
+      when String then @quoter.encode(value)
+      else
+        @quoter.encode(serialize(value))
+      end
+    end
+
+    # @visibility private
+    def fetch_count(sql)
+      execute(sql, &:cmd_tuples)
+    end
+
+    # @visibility private
+    def fetch_first_field(sql)
+      fetch_result(sql) { |res| res.getvalue(0, 0) if res.ntuples > 0 && res.nfields > 0 }
+    end
+
+    # @visibility private
+    def fetch_first_row(sql)
+      fetch_result(sql) { |res| res[0] if res.ntuples > 0 }
+    end
+
+    # @visibility private
+    def fetch_first_column(sql)
+      # Return an array of nils if we don't have a column
+      fetch_result(sql) { |res| res.nfields > 0 ? res.column_values(0) : Array.new(res.ntuples) }
+    end
+
+    # @visibility private
+    def fetch_each_row(sql, &block)
+      return to_enum(:fetch_each_row, sql) unless block
+
+      fetch_result(sql) { |res| res.each(&block) }
+    end
+
+    # @visibility private
+    def fetch_rows(sql)
+      fetch_result(sql, &:to_a)
+    end
+
+    private
+
+    def fetch_result(sql)
+      execute(sql) do |res|
+        res.type_map = result_type_map
+        yield res
+      end
+    end
+
+    def execute(sql, &block)
+      @pool.with { |c| c.async_exec(sql, &block) }
+    end
+
+    # Use PG's built-in type mapping to serialize objects into SQL strings.
+    def serialize(value)
+      (coder = encoder_for(value)) || raise(TypeError, "No SQL serializer for #{value.class}")
+      coder.encode(value)
+    end
+
+    def encoder_for(value)
+      coder = query_type_map[value.class]
+      # Handle the weird case where coder can be a method name
+      coder.is_a?(Symbol) ? query_type_map.send(coder, value) : coder
+    end
+
+    def result_type_map
+      @result_type_map ||= @pool.with { |c| PG::BasicTypeMapForResults.new(c) }
+    end
+  end
+
+  # PG < 1.1.0 doesn't have a numeric decoder
+  # This is copied from https://github.com/ged/ruby-pg/commit/d4ae41bb8fd447c92ef9c8810ec932acd03e0293
+  # :nocov:
+  unless defined? PG::TextEncoder::Numeric
+    class NumericDecoder < PG::SimpleDecoder
+      def decode(string, tuple = nil, field = nil)
+        BigDecimal(string)
+      end
+    end
+
+    class NumericEncoder < PG::SimpleEncoder
+      def encode(decimal)
+        decimal.to_s("F")
+      end
+    end
+    private_constant :NumericDecoder, :NumericEncoder
+    PG::BasicTypeRegistry.register_type(0, "numeric", NumericEncoder, NumericDecoder)
+  end
+  # :nocov:
+end

data/lib/ensql/sequel_adapter.rb

@@ -1,56 +1,105 @@
 # frozen_string_literal: true
 
-require_relative 'version'
-require_relative 'adapter'
+require_relative "version"
+require_relative "adapter"
+require_relative "pool_wrapper"
+require_relative "error"
 
 # Ensure our optional dependency has a compatible version
-gem 'sequel', Ensql::SEQUEL_VERSION
-require 'sequel'
+gem "sequel", Ensql::SUPPORTED_SEQUEL_VERSIONS
+require "sequel"
 
 module Ensql
   #
-  # Implements the {Adapter} interface for Sequel. Requires a Sequel connection to
-  # be established. Uses the first connection found in Sequel::DATABASES. You
-  # may want to utilize the relevant extensions to make the most of the
-  # deserialization.
+  # Wraps a Sequel::Database to implement the {Adapter} interface for Sequel.
+  # You may want to utilize the relevant Sequel extensions to make the most of
+  # database-specific deserialization and other features.  By default, uses the
+  # first database in Sequel::Databases. Other databases can be passed to the
+  # constructor.
   #
-  # @example
-  #   require 'sequel'
-  #   DB = Sequel.connect('postgres://localhost/mydb')
-  #   DB.extend(:pg_json)
-  #   Ensql.adapter = Ensql::SequelAdapter
+  #     require 'sequel'
+  #     DB = Sequel.connect('postgres://localhost/mydb')
+  #     DB.extend(:pg_json)
+  #     Ensql.adapter = Ensql::SequelAdapter.new(DB)
   #
-  # @see Adapter
-  # @see SEQUEL_VERSION Required gem version
+  # To stream rows, configure streaming on the connection and use
+  # {SQL.each_row}
   #
-  module SequelAdapter
-    extend Adapter
+  #      DB = Sequel.connect('postgresql:/')
+  #      DB.extension(:pg_streaming)
+  #      DB.stream_all_queries = true
+  #      Ensql.adapter = Ensql::SequelAdapter.new(DB)
+  #      Ensql.sql("select * from large_table").each_row do  |row|
+  #        # This now yields each row in single-row mode.
+  #        # The connection cannot be used for other queries while this is streaming.
+  #      end
+  #
+  # @see SUPPORTED_SEQUEL_VERSIONS
+  #
+  class SequelAdapter
+    include Adapter
+
+    # Support deprecated class method interface
+    class << self
+      require "forwardable"
+      extend Forwardable
+
+      delegate [:literalize, :run, :fetch_count, :fetch_each_row, :fetch_rows, :fetch_first_column, :fetch_first_field, :fetch_first_row] => :new
+    end
+
+    # Wrap the raw connections from a Sequel::Database connection pool. This
+    # allows us to safely checkout the underlying database connection for use in
+    # a database specific adapter.
+    #
+    #     Ensql.adapter = MySqliteAdapter.new(SequelAdapter.pool)
+    #
+    # @param db [Sequel::Database]
+    # @return [PoolWrapper] a pool adapter for raw connections
+    def self.pool(db)
+      PoolWrapper.new do |client_block|
+        db.pool.hold(&client_block)
+      end
+    end
 
-    # @!visibility private
-    def self.fetch_rows(sql)
-      db.fetch(sql).map { |r| r.transform_keys(&:to_s) }
+    # @param db [Sequel::Database]
+    def initialize(db = first_configured_database)
+      @db = db
     end
 
-    # @!visibility private
-    def self.fetch_count(sql)
+    # @visibility private
+    def fetch_rows(sql)
+      fetch_each_row(sql).to_a
+    end
+
+    # @visibility private
+    def fetch_each_row(sql)
+      return to_enum(:fetch_each_row, sql) unless block_given?
+
+      db.fetch(sql) { |r| yield r.transform_keys(&:to_s) }
+    end
+
+    # @visibility private
+    def fetch_count(sql)
       db.execute_dui(sql)
     end
 
-    # @!visibility private
-    def self.run(sql)
+    # @visibility private
+    def run(sql)
       db << sql
+      nil
     end
 
-    # @!visibility private
-    def self.literalize(value)
+    # @visibility private
+    def literalize(value)
       db.literal(value)
     end
 
-    def self.db
-      Sequel::DATABASES.first or raise Error, "no connection found in Sequel::DATABASES"
-    end
+    private
 
-    private_class_method :db
+    attr_reader :db
 
+    def first_configured_database
+      Sequel::DATABASES.first || raise(Error, "no database found in Sequel::DATABASES")
+    end
   end
 end