ensql 0.6.0 → 0.6.5

data/lib/ensql/sql.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
-require_relative "../ensql"
+require_relative "adapter"
+require_relative "error"
 
 module Ensql
   #
-  # Encapsulates a plain-text SQL statement and optional parameters to interpolate. Interpolation is indicated by one
-  # of the four placeholder formats:
+  # Encapsulates a plain-text SQL statement and optional parameters to interpolate. Interpolation is indicated by one of
+  # the four placeholder formats:
   #
   # 1. **Literal:** `%{param}`
   #    - Interpolates `param` as a quoted string or a numeric literal depending on the class.
@@ -31,6 +32,7 @@ module Ensql
   #    - Allows composition of SQL via subqueries.
   #
   # Any placeholders in the SQL must be present in the params hash or a KeyError will be raised during interpolation.
+  # Interpolation occurs just before the SQL is executed.
   #
   # @example
   #   # Interpolate a literal
@@ -52,9 +54,8 @@ module Ensql
   #   # SELECT * FROM users ORDER BY name asc
   #
   class SQL
-
     # @!visibility private
-    def initialize(sql, params={}, name='SQL')
+    def initialize(sql, params = {}, name = "SQL")
       @sql = sql
       @name = name.to_s
       @params = params
@@ -94,6 +95,7 @@ module Ensql
     # (see Adapter.fetch_each_row)
     def each_row(&block)
       adapter.fetch_each_row(to_sql, &block)
+      nil
     end
 
     # Interpolate the params into the SQL statement.
@@ -104,14 +106,14 @@ module Ensql
       interpolate(sql, params)
     end
 
-  private
+    private
 
     attr_reader :sql, :params, :name
 
-    NESTED_LIST  = /%{(\w+)\((.+)\)}/m
-    LIST         = /%{\((\w+)\)}/
+    NESTED_LIST = /%{(\w+)\((.+)\)}/m
+    LIST = /%{\((\w+)\)}/
     SQL_FRAGMENT = /%{!(\w+)}/
-    LITERAL      = /%{(\w+)}/
+    LITERAL = /%{(\w+)}/
 
     def interpolate(sql, params)
       params = params.transform_keys(&:to_s)
@@ -130,13 +132,13 @@ module Ensql
       Array(array)
         .map { |attrs| interpolate(nested_sql, Hash(attrs)) }
         .map { |sql| "(#{sql})" }
-        .join(', ')
+        .join(", ")
     end
 
     def interpolate_list(array)
-      return '(NULL)' if Array(array).empty?
+      return "(NULL)" if Array(array).empty?
 
-      '(' + Array(array).map { |v| literalize v }.join(', ') + ')'
+      "(" + Array(array).map { |v| literalize v }.join(", ") + ")"
     end
 
     def interpolate_sql(sql)
@@ -156,6 +158,5 @@ module Ensql
     def adapter
       Ensql.adapter
     end
-
   end
 end

data/lib/ensql/transaction.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "error"
+require_relative "adapter"
+
+module Ensql
+  class << self
+    # Wrap a block with a transaction. Uses the well supported
+    # SQL-standard commands for controlling a transaction by default, however database
+    # specific statements can be supplied. Any exceptions inside the block will
+    # trigger a rollback and be reraised. Alternatively, you can call
+    # {rollback!} to immediately exit the block and rollback the transaction.
+    # Returns the result of the block. If the block returns `:rollback`, the
+    # transaction will also be rolled back.
+    #
+    #     # If `do_thing1` or `do_thing2` raise an error, no statements are committed.
+    #     Ensql.transaction { do_thing1; do_thing2 }
+    #
+    #     # If `do_thing2` is falsey, `do_thing1` is rolled back and `do_thing3` is skipped.
+    #     Ensql.transaction { do_thing1; do_thing2 or Ensql.rollback!; do_thing3 }
+    #
+    #     # Nest transactions with savepoints.
+    #     Ensql.transaction do
+    #       do_thing1
+    #       Ensql.transaction(start: 'SAVEPOINT my_savepoint', commit: 'RELEASE SAVEPOINT my_savepoint', rollback: 'ROLLBACK TO SAVEPOINT my_savepoint') do
+    #         do_thing2
+    #         do_thing3
+    #       end
+    #     end
+    #
+    #     # Use database-specific transaction semantics.
+    #     Ensql.transaction(start: 'BEGIN TRANSACTION ISOLATION LEVEL SERIALIZABLE READ ONLY DEFERRABLE') { }
+    #
+    # @see rollback!
+    # @param start the SQL to begin the transaction.
+    # @param commit the SQL to commit the transaction if successful.
+    # @param rollback the SQL to rollback the transaction if an error is raised.
+    def transaction(start: "START TRANSACTION", commit: "COMMIT", rollback: "ROLLBACK", &block)
+      adapter.run(start)
+      result = catch(:rollback, &block)
+      adapter.run(result == :rollback ? rollback : commit)
+      result
+    # # We need to try rollback on _any_ exception. Since we reraise, rescuing this is safe.
+    rescue Exception # rubocop:disable Lint/RescueException
+      adapter.run(rollback)
+      raise
+    end
+
+    # Immediately rollback and exit the current transaction block. See
+    # {transaction}.
+    def rollback!
+      throw :rollback, :rollback
+    rescue UncaughtThrowError
+      raise Error, "not in a transaction block, can't rollback"
+    end
+  end
+end

data/lib/ensql/version.rb

@@ -2,9 +2,11 @@
 
 module Ensql
   # Gem version
-  VERSION = "0.6.0"
-  # Version of the activerecord gem required to use the {ActiveRecordAdapter}
-  ACTIVERECORD_VERSION = ['>= 5.0', '< 6.2'].freeze
-  # Version of the sequel gem required to use the {SequelAdapter}
-  SEQUEL_VERSION = '~> 5.10'
+  VERSION = "0.6.5"
+  # Versions of activerecord compatible with the {ActiveRecordAdapter}
+  SUPPORTED_ACTIVERECORD_VERSIONS = [">= 5.0", "< 6.2"].freeze
+  # Versions of sequel compatible with the {SequelAdapter}
+  SUPPORTED_SEQUEL_VERSIONS = "~> 5.9"
+  # Versions of pg compatibile with the {PostgresAdapter}
+  SUPPORTED_PG_VERSIONS = [">= 0.19", "< 2"].freeze
 end

data/perf/adapter_benchmark.rb

@@ -0,0 +1,102 @@
+#!/usr/bin/env ruby
+
+# frozen_string_literal: true
+
+#
+# Compare operations performed using each adapter
+#
+
+ENV["TZ"] = "UTC"
+
+require "benchmark/ips"
+
+require_relative "lib/ensql/active_record_adapter"
+require_relative "lib/ensql/sequel_adapter"
+require_relative "lib/ensql/postgres_adapter"
+
+ActiveRecord::Base.establish_connection(adapter: "postgresql")
+DB = Sequel.connect("postgresql:/")
+DB.extension(:pg_json)
+
+adapters = {
+  'pg     ': Ensql::PostgresAdapter.new { PG::Connection.open },
+  'ar     ': Ensql::ActiveRecordAdapter.new(ActiveRecord::Base.connection_pool),
+  'seq    ': Ensql::SequelAdapter.new(DB),
+  'pg-ar  ': Ensql::PostgresAdapter.new(Ensql::ActiveRecordAdapter.pool),
+  'pg-seq ': Ensql::PostgresAdapter.new(Ensql::SequelAdapter.pool(DB))
+}
+
+ADAPTER = adapters.values.first
+
+ADAPTER.run("drop table if exists number_benchmark")
+ADAPTER.run("create table number_benchmark as select generate_series(1,100) as number")
+
+adapter_tests = {
+  'literalize (String)': [:literalize, "It's quoted"],
+  'literalize (Long String)': [:literalize, "It's quoted" * 1000],
+  'literalize (Time)': [:literalize, Time.now],
+  'literalize (Int)': [:literalize, 1234],
+  'literalize (bool)': [:literalize, true],
+  'run INSERT': [:run, "insert into number_benchmark values (999)"],
+  'run SET': [:run, "set time zone UTC"],
+  'run SELECT': [:run, "select generate_series(1,100)"],
+  'count UPDATE': [:fetch_count, "update number_benchmark set number = number + 1"],
+  'count SELECT': [:fetch_count, "select generate_series(1,100)"],
+  'first column': [:fetch_first_column, "select generate_series(1,100)"],
+  'first column (of many)': [:fetch_first_column, "select *, now() from generate_series(1,100) as number"],
+  'first field': [:fetch_first_field, "select 1"],
+  'first field with cast': [:fetch_first_field, "select cast('2021-01-01' as timestamp)"],
+  'first field (of many)': [:fetch_first_field, "select generate_series(1,100)"],
+  'first row': [:fetch_first_row, "select 1, 2, 3"],
+  'first row (cast)': [:fetch_first_row, "select cast('2021-01-01' as timestamp), cast('[1,2,3]' as json)"],
+  'first row (of many)': [:fetch_first_row, "select generate_series(1, 100)"],
+  'rows (1)': [:fetch_rows, "select 1, 1"],
+  'rows (100)': [:fetch_rows, "select 1, 1, generate_series(1, 100)"],
+  'rows (100,cast)': [:fetch_rows, "select cast('2021-01-01' as timestamp), cast('[1,2,3]' as json), generate_series(1, 100)"],
+  'rows (100000)': [:fetch_rows, "select 1, 1, generate_series(1, 100000)"]
+}
+
+fetch_each_row_tests = {
+  'each_row (1)': [:fetch_each_row, "select 1, 1"],
+  'each_row (100)': [:fetch_each_row, "select 1, 1, generate_series(1, 100)"],
+  'each_row (100,cast)': [:fetch_each_row, "select cast('2021-01-01' as timestamp), cast('[1,2,3]' as json), generate_series(1, 100)"],
+  'each_row (100000)': [:fetch_each_row, "select 1, 1, generate_series(1, 100000)"]
+}
+
+# Verify results are the same
+adapter_tests.each do |name, args|
+  results = adapters.map { |n, a| [n, a.send(*args)] }.uniq { |n, result| result }
+  next if results.count == 1
+
+  warn "Differing results for #{name}: #{args}"
+  results.each { |n, result| warn "  #{n} =>  #{result.inspect[0..500]}" }
+end
+
+# Compare times
+adapter_tests.each do |test_name, args|
+  puts args.map { |a| a.inspect[0..100] }.join(" ")
+
+  Benchmark.ips(quiet: true) do |x|
+    x.config(stats: :bootstrap, confidence: 95, warmup: 0.2, time: 0.5)
+
+    adapters.each do |name, adapter|
+      x.report("#{test_name} - #{name}") { adapter.send(*args) }
+    end
+
+    x.compare!
+  end
+end
+
+fetch_each_row_tests.each do |test_name, args|
+  Benchmark.ips(quiet: true) do |x|
+    x.config(stats: :bootstrap, confidence: 95, warmup: 0.2, time: 0.5)
+
+    adapters.each do |name, adapter|
+      x.report("#{test_name} - #{name}") { adapter.send(*args) { |r| r } }
+    end
+
+    x.compare!
+  end
+end
+
+ADAPTER.run("drop table number_benchmark")

metadata

@@ -1,16 +1,92 @@
 --- !ruby/object:Gem::Specification
 name: ensql
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.5
 platform: ruby
 authors:
 - Daniel Fone
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-02-23 00:00:00.000000000 Z
-dependencies: []
-description: Ditch your ORM and embrace the power and simplicity of writing plain
+date: 2021-03-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: connection_pool
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.3
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.3
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.2
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.26
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.26
+description: Escape your ORM and embrace the power and simplicity of writing plain
   SQL again.
 email:
 - daniel@fone.net.nz
@@ -18,6 +94,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/lint.yml"
+- ".github/workflows/specs.yml"
 - ".gitignore"
 - ".rspec"
 - ".ruby-version"
@@ -32,12 +110,22 @@ files:
 - bin/rspec
 - bin/setup
 - ensql.gemspec
+- gemfiles/maintained.gemfile
+- gemfiles/maintained.gemfile.lock
+- gemfiles/minimum.gemfile
+- gemfiles/minimum.gemfile.lock
 - lib/ensql.rb
 - lib/ensql/active_record_adapter.rb
 - lib/ensql/adapter.rb
+- lib/ensql/error.rb
+- lib/ensql/load_sql.rb
+- lib/ensql/pool_wrapper.rb
+- lib/ensql/postgres_adapter.rb
 - lib/ensql/sequel_adapter.rb
 - lib/ensql/sql.rb
+- lib/ensql/transaction.rb
 - lib/ensql/version.rb
+- perf/adapter_benchmark.rb
 homepage: https://github.com/danielfone/ensql
 licenses:
 - MIT
@@ -57,7 +145,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.9
+rubygems_version: 3.2.14
 signing_key:
 specification_version: 4
 summary: Write SQL the safe and simple way