em-pg-client-helper 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2a783cd49553e23ba7a8c35e1b1d23414fa9610c
-  data.tar.gz: 36f31e34a174a42f42a584d4d9e3a3db3b19ecd9
+  metadata.gz: f507ec3c80d6ed2c58575898e2132bfa3e05ac36
+  data.tar.gz: 5c311e9a44d3274689c4c6f12dfc028a3e721328
 SHA512:
-  metadata.gz: bd1b02760aabac6d0a688e6b548a4b845be2e7c779cb3282c3158bc82abe04bf9a29764d74a5d1b84e8cc81bee679a92191e6a80eb93e4a1bf80edf063bd5b78
-  data.tar.gz: e747e1fea3787a2836268da4708cdcfa7233f9a3ffbed67147a74096b7c9a0fd3c83b3ea4c8dd444125b9232effd92ccccda93082769f3cf13da46a19936c10a
+  metadata.gz: 6b39ee8f0cdce4de503b1793ca26f13b0bd493cd53b80390a95a65018252af5d30c837f733013fb07678a8aab32caa62fceab8d0f6a26b8c70494df3185c2173
+  data.tar.gz: 0af1627ff7f3bac097818c5a91f5c71467f32aadfb18fef17dd939db9e360e1a20a8559a68421b5ae24f0d74153907ca9af62c3d3d5347ebf18fda5662239cf0

data/README.md

@@ -3,7 +3,7 @@ nice solution to the problem of accessing a PostgreSQL database from within
 [EventMachine](http://rubyeventmachine.com/), it is somewhat... spartan. 
 ORMs have spoiled us somewhat, and so the appeal of hand-writing SQL and
 dealing with the finer details of error handling has faded.  Hence the
-creation of the `EM::PG::Client::Helper` module.  It contains a collection
+creation of the {PG::EM::Client::Helper} module.  It contains a collection
 of useful helper methods that make it somewhat easier to perform common
 operations against PgSQL databases.
 
@@ -32,7 +32,7 @@ Then add this line in any classes you wish to use the helper methods in:
 
     include PG::EM::Client::Helper
 
-The module documentation for EM::PG::Client::Helper has more information on
+The module documentation for {PG::EM::Client::Helper} has more information on
 the available methods and how to use them.
 
 

data/em-pg-client-helper.gemspec

@@ -15,8 +15,9 @@ Gem::Specification.new do |s|
 	s.extra_rdoc_files = ["README.md"]
 	s.files = `git ls-files`.split("\n")
 
+	s.add_runtime_dependency "em-pg-client",     "~> 0.3"
 	s.add_runtime_dependency "git-version-bump", "~> 0.10"
-	s.add_runtime_dependency "em-pg-client", "~> 0.3"
+	s.add_runtime_dependency "sequel",           "~> 4.0"
 
 	s.add_development_dependency 'bundler'
 	s.add_development_dependency 'eventmachine'

data/lib/em-pg-client-helper.rb

@@ -1,11 +1,159 @@
 require 'pg/em'
 require 'pg/em/connection_pool'
+require 'sequel'
 
 # Some helper methods to make working with em-pg-client slightly less like
 # trying to build a house with a packet of seeds and a particle
 # accelerator...  backwards.
 #
 module PG::EM::Client::Helper
+	# Sequel-based SQL generation.
+	#
+	# While we could spend a lot of time writing code to generate various
+	# kinds of SQL "by hand", it would be wasted effort, since the Sequel
+	# database toolkit gives us a complete, and *extremely* powerful, SQL
+	# generation system, which is already familiar to a great many
+	# programmers (or, at least, many great programmers).
+	#
+	# Hence, rather than reinvent the wheel, we simply drop Sequel in.
+	#
+	# Anything you can do with an instance of `Sequel::Database` that
+	# produces a single SQL query, you can almost certainly do with this
+	# method.
+	#
+	# Usage is quite simple: calling this method will yield a pseudo-database
+	# object to the block you pass.  You can then call whatever methods you
+	# like against the database object, and when you're done and the block
+	# you passed completes, we'll return the SQL that Sequel generated.
+	#
+	# @yield [sqldb] to allow you to call whatever Sequel methods you like to
+	#   generate the desired SQL.
+	#
+	# @yieldparam [Sequel::Database] call whatever you like against this to
+	#   cause Sequel to generate the result you want.
+	#
+	# @return [String] the generated SQL.
+	#
+	# @raise [PG::EM::Client::Helper::BadSequelError] if your calls against
+	#   the yielded database object would result in no SQL being generated,
+	#   or more than one SQL statement.
+	#
+	# @example A simple select
+	#   sequel(db) do |sqldb|
+	#     sqldb[:artists]
+	#   end
+	#   # => "SELECT * FROM artists"
+	#
+	# @example Delete some rows
+	#   sequel(db) do |sqldb|
+	#     sqldb[:foo].where { { col.sql_number % 3 => 0 } }.delete
+	#   end.callback do |res|
+	#     logger.info "Deleted #{res.cmd_tuples}"
+	#   end
+	#   # => "DELETE FROM foo WHERE col % 3 = 0"
+	#
+	# @example A very complicated select
+	#   sequel do |sqldb|
+	#     sqldb[:posts].select_all(:posts).
+	#       select_append(
+	#         Sequel.
+	#           function(:array_agg, :campaigns__name).
+	#           distinct.
+	#           as(:campaigns_names)
+	#         ).
+	#       join(:posts_terms, :post_id => :posts__id).
+	#       join(:terms, :id => :posts_terms__term_id).
+	#       join(:categories_terms, :term_id => :terms__id).
+	#       join(:campaigns_categories, :category_id => :categories_terms__category_id).
+	#       join(:campaigns, :id => :campaigns_categories__campaign_id).
+	#       group_by(:posts__id)
+	#   end
+	#   # ... you don't want to know.
+	#
+	def sequel_sql
+		sqldb = Sequel.connect("mock://postgres")
+		ret = yield sqldb if block_given?
+		sqls = sqldb.sqls
+
+		if sqls.empty?
+			sqls = [ret.sql] rescue []
+		end
+
+		if sqls.empty?
+			raise PG::EM::Client::Helper::BadSequelError,
+			      "Your block did not generate an SQL statement"
+		end
+
+		if sqls.length > 1
+			raise PG::EM::Client::Helper::BadSequelError,
+			      "Your block generated multiple SQL statements"
+		end
+
+		sqls.first
+	end
+
+	# Generate Sequel, and run it against the database connection provided.
+	#
+	# This is the all-singing variant of {#sequel_sql} -- in addition to
+	# generating the SQL, we also run the result against the database
+	# connection you pass.
+	#
+	# @see {#sequel_sql}
+	#
+	# @yield [sqldb] to allow you to call whatever sequel methods you like to
+	#   generate the desired SQL.
+	#
+	# @yieldparam [Sequel::Database] call whatever you like against this to
+	#   cause Sequel to generate the result you want.
+	#
+	# @return [EM::Deferrable] the callbacks attached to this deferrable will
+	#   receive a `PG::Result` when the query completes successfully, or else
+	#   the errbacks on this deferrable will be called in the event of an
+	#   error.
+	#
+	# @raise [PG::EM::Client::Helper::BadSequelError] if your calls against
+	#   the yielded database object would result in no SQL being generated,
+	#   or more than one SQL statement.
+	#
+	# @example A simple select
+	#   sequel(db) do |sqldb|
+	#     sqldb[:artists]
+	#   end.callback do |res|
+	#     ...
+	#   end.errback do |ex|
+	#     logger.error "Query failed (#{ex.class}): #{ex.message}"
+	#   end
+	#
+	# @example A very complicated select
+	#   sequel do |sqldb|
+	#     sqldb[:posts].select_all(:posts).
+	#       select_append(
+	#         Sequel.
+	#           function(:array_agg, :campaigns__name).
+	#           distinct.
+	#           as(:campaigns_names)
+	#         ).
+	#       join(:posts_terms, :post_id => :posts__id).
+	#       join(:terms, :id => :posts_terms__term_id).
+	#       join(:categories_terms, :term_id => :terms__id).
+	#       join(:campaigns_categories, :category_id => :categories_terms__category_id).
+	#       join(:campaigns, :id => :campaigns_categories__campaign_id).
+	#       group_by(:posts__id)
+	#   end.callback do |res|
+	#     ...
+	#   end
+	#
+	# @example Delete some rows
+	#   sequel(db) do |sqldb|
+	#     sqldb[:foo].where { { col.sql_number % 3 => 0 } }.delete
+	#   end.callback do |res|
+	#     logger.info "Deleted #{res.cmd_tuples}"
+	#   end
+	#
+	def db_sequel(db, &blk)
+		db.exec_defer(sequel_sql(&blk))
+	end
+
 	# Generate SQL for an insert statement into `tbl`, with the fields and
 	# data given by the keys and values, respectively, of `params`.  Returns
 	# a two-element array consisting of the parameterised SQL as the first
@@ -47,7 +195,7 @@ module PG::EM::Client::Helper
 		db.exec_defer(*insert_sql(tbl, params))
 	end
 
-	# @macro upsert_params
+	# @!macro upsert_params
 	#
 	#   @param tbl [#to_s] The name of the table on which to operate.
 	#
@@ -62,8 +210,7 @@ module PG::EM::Client::Helper
 	#
 	#   @raise [ArgumentError] if a field is specified in `key` but which
 	#     does not exist in `data`.
-	#
-	#
+
 	# An "upsert" is a kind of crazy hybrid "update if the record exists,
 	# insert it if it doesn't" query.  It isn't part of the SQL standard,
 	# but it is such a common idiom that we're keen to support it.
@@ -77,7 +224,7 @@ module PG::EM::Client::Helper
 	# As an added bonus, the SQL that this method generates will, when executed,
 	# return the complete row that has been inserted or updated.
 	#
-	# @!macro upsert_params
+	# @macro upsert_params
 	#
 	# @return [Array<String, Array<Object>>] A two-element array, the first
 	#   of which is a string containing the literal SQL to be executed, while
@@ -128,7 +275,7 @@ module PG::EM::Client::Helper
 	# @param db [PG::EM::Client, PG::EM::ConnectionPool] the connection
 	#   against which all database operations will be run.
 	#
-	# @!macro upsert_params
+	# @macro upsert_params
 	#
 	# @return [EM::Deferrable] the deferrable in which the query is being
 	#   called; this means you should attach the code to run after the query
@@ -236,6 +383,13 @@ module PG::EM::Client::Helper
 	def quote_identifier(id)
 		"\"#{id.gsub(/"/, '""')}\""
 	end
+
+	# Indicates that the sequel mock-database was not manipulated in such a way
+	# as to produce exactly one SQL statement.
+	#
+	# @see {#sequel_sql}
+	#
+	class BadSequelError < StandardError; end
 end
 
 require 'em-pg-client-helper/transaction'

data/lib/em-pg-client-helper/transaction.rb

@@ -1,3 +1,6 @@
+# Represents a database transaction, and contains all of the methods which
+# can be used to execute queries within the transaction connection.
+#
 class PG::EM::Client::Helper::Transaction
 	include ::PG::EM::Client::Helper
 	include ::EventMachine::Deferrable
@@ -108,6 +111,17 @@ class PG::EM::Client::Helper::Transaction
 		end
 	end
 
+	# Generate SQL statements via Sequel, and run the result against the
+	# database.  Very chic.
+	#
+	# @see {PG::EM::Client::Helper#sequel_sql}
+	#
+	# @return [EM::Deferrable]
+	#
+	def sequel(&blk)
+		exec(sequel_sql(&blk))
+	end
+
 	# Insert a row of data into the database table `tbl`, using the keys
 	# from the `params` hash as the field names, and the values from the
 	# `params` hash as the field data.  Once the query has completed,
@@ -139,7 +153,7 @@ class PG::EM::Client::Helper::Transaction
 	# given block will be called if and when the query completes
 	# successfully.
 	#
-	# @returns [EM::Deferrable] A deferrable that will be completed when this
+	# @return [EM::Deferrable] A deferrable that will be completed when this
 	#   specific query finishes.
 	#
 	def exec(sql, values=[], &blk)
@@ -158,6 +172,8 @@ class PG::EM::Client::Helper::Transaction
 	end
 	alias_method :exec_defer, :exec
 
+	# Trace queries as they happen, if `ENV['EM_PG_TXN_TRACE']` is set.
+	#
 	def trace_query(q, v=nil)
 		$stderr.puts "#{@conn.inspect}: #{q} #{v.inspect}" if ENV['EM_PG_TXN_TRACE']
 	end

data/spec/db_transaction_sequel_spec.rb

@@ -0,0 +1,35 @@
+require_relative './spec_helper'
+
+describe "PG::EM::Client::Helper::Transaction#sequel" do
+	let(:mock_conn) { double(PG::EM::Client) }
+
+	it "runs a simple UPSERT correctly" do
+		in_em do
+			expect_query("BEGIN")
+			expect_query("SELECT * FROM \"foo\"")
+			expect_query("COMMIT")
+			in_transaction do |txn|
+				txn.sequel do |db|
+					db[:foo]
+				end.callback do
+					txn.commit
+				end
+			end
+		end
+	end
+
+	it "rolls back after a failed attempt" do
+		in_em do
+			expect_query("BEGIN")
+			expect_query_failure("SELECT * FROM \"foo\"")
+			expect_query("ROLLBACK")
+			in_transaction do |txn|
+				txn.sequel do |db|
+					db[:foo]
+				end.callback do
+					txn.commit
+				end
+			end
+		end
+	end
+end

data/spec/sequel_sql_spec.rb

@@ -0,0 +1,21 @@
+require_relative './spec_helper'
+
+describe "PG::EM::Client::Helper#sequel_sql" do
+	it "assembles a simple post-return query correctly" do
+		expect(sequel_sql { |db| db[:foo] }).
+		  to eq("SELECT * FROM \"foo\"")
+	end
+
+	it "assembles a pre-complete query correctly" do
+		expect(
+		  sequel_sql do |db|
+		    db[:foo].where { id > 20 }.delete
+		  end
+		).to eq("DELETE FROM \"foo\" WHERE (\"id\" > 20)")
+	end
+
+	it "bombs if we don't do anything" do
+		expect { sequel_sql }.
+		  to raise_error(PG::EM::Client::Helper::BadSequelError)
+	end
+end

data/spec/spec_helper.rb

@@ -5,7 +5,7 @@ Spork.prefork do
 	Bundler.setup(:default, :development, :test)
 	require 'rspec/core'
 	require 'rspec/mocks'
-	require 'txn_helper'
+	require_relative './txn_helper'
 
 	require 'pry'
 

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: em-pg-client-helper
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Matt Palmer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-27 00:00:00.000000000 Z
+date: 2015-03-03 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: em-pg-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
 - !ruby/object:Gem::Dependency
   name: git-version-bump
   requirement: !ruby/object:Gem::Requirement
@@ -25,19 +39,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.10'
 - !ruby/object:Gem::Dependency
-  name: em-pg-client
+  name: sequel
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '4.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -217,10 +231,12 @@ files:
 - lib/em-pg-client-helper/deferrable_group.rb
 - lib/em-pg-client-helper/transaction.rb
 - spec/db_insert_spec.rb
+- spec/db_transaction_sequel_spec.rb
 - spec/db_transaction_spec.rb
 - spec/db_transaction_upsert_spec.rb
 - spec/db_upsert_spec.rb
 - spec/insert_sql_spec.rb
+- spec/sequel_sql_spec.rb
 - spec/spec_helper.rb
 - spec/txn_helper.rb
 - spec/upsert_sql_spec.rb