em-pg-client-helper 0.1.0

data/README.md

@@ -0,0 +1,45 @@
+While [`em-pg-client`](https://github.com/royaltm/ruby-em-pg-client) is a
+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
+of useful helper methods that make it somewhat easier to perform common
+operations against PgSQL databases.
+
+
+# Installation
+
+It's a gem:
+
+    gem install em-pg-client-helper
+
+If you're the sturdy type that likes to run from git:
+
+    rake build; gem install pkg/em-pg-client-helper-<whatever>.gem
+
+Or, if you've eschewed the convenience of Rubygems, then you presumably know
+what to do already.
+
+
+# Usage
+
+To use any of these methods, you will want to add the following require:
+
+    require 'em-pg-client-helper'
+
+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 available methods and how to use them.
+
+
+# Contributing
+
+Bug reports should be sent to the [Github issue
+tracker](https://github.com/mpalmer/em-pg-client-helper/issues), or
+[e-mailed](mailto:theshed+em-pg-client-helper@hezmatt.org).  Patches can be
+sent as a Github pull request, or
+[e-mailed](mailto:theshed+em-pg-client-helper@hezmatt.org).

data/Rakefile

@@ -0,0 +1,41 @@
+require 'rubygems'
+require 'bundler'
+
+task :default => :test
+
+begin
+	Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+	$stderr.puts e.message
+	$stderr.puts "Run `bundle install` to install missing gems"
+	exit e.status_code
+end
+
+Bundler::GemHelper.install_tasks
+
+task :release do
+	sh "git release"
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new do |rd|
+	rd.main = "README.md"
+	rd.title = 'em-pg-client-helper'
+	rd.markup = "markdown"
+	rd.rdoc_files.include("README.md", "lib/**/*.rb")
+end
+
+desc "Run guard"
+task :guard do
+	require 'guard'
+	::Guard.start(:clear => true)
+	while ::Guard.running do
+		sleep 0.5
+	end
+end
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new :test do |t|
+	t.pattern = "spec/**/*_spec.rb"
+end

data/em-pg-client-helper.gemspec

@@ -0,0 +1,32 @@
+require 'git-version-bump'
+
+Gem::Specification.new do |s|
+	s.name = "em-pg-client-helper"
+
+	s.version = GVB.version
+	s.date    = GVB.date
+
+	s.platform = Gem::Platform::RUBY
+
+	s.homepage = "http://github.com/mpalmer/em-pg-client-helper"
+	s.summary = "Simplify common operations using em-pg-client"
+	s.authors = ["Matt Palmer"]
+
+	s.extra_rdoc_files = ["README.md"]
+	s.files = `git ls-files`.split("\n")
+
+	s.add_runtime_dependency "git-version-bump", "~> 0.10"
+	s.add_runtime_dependency "em-pg-client", "~> 0.3"
+
+	s.add_development_dependency 'bundler'
+	s.add_development_dependency 'eventmachine'
+	s.add_development_dependency 'github-release'
+	s.add_development_dependency 'guard-spork'
+	s.add_development_dependency 'guard-rspec'
+	# Needed for guard
+	s.add_development_dependency 'rb-inotify', '~> 0.9'
+	s.add_development_dependency 'pry-debugger'
+	s.add_development_dependency 'rake'
+	s.add_development_dependency 'rdoc'
+	s.add_development_dependency 'rspec'
+end

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

@@ -0,0 +1,148 @@
+require 'pg/em'
+require 'pg/em/connection_pool'
+
+# 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
+	# 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
+	# element, and the array of parameters as the second element.
+	#
+	def insert_sql(tbl, params)
+		keys = params.keys.map { |k| quote_identifier(k.to_s) }.join(',')
+		vals = params.values
+		val_places = (1..vals.length).to_a.map { |i| "$#{i}" }.join(',')
+
+		["INSERT INTO #{quote_identifier(tbl)} (#{keys}) VALUES (#{val_places})", vals]
+	end
+
+	# Run an insert query, without having to write a great pile of SQL all by
+	# yourself.
+	#
+	# Arguments:
+	#
+	#  * `db` -- A PG::EM::Client or PG::EM::ConnectionPool instance, against
+	#    which all database operations will be executed.
+	#
+	#  * `tbl` -- The name of the table into which you wish to insert your data.
+	#    This parameter will be automatically quoted, if necessary.
+	#
+	#  * `params` -- A hash containing the fields you wish to insert into
+	#    (the keys of the hash) and the values to insert into each field (the
+	#    values of the hash).  All field names and data will be automatically
+	#    quoted and made safe, so you're automatically SQL injection-proof!
+	#
+	# This method returns the deferrable in which the query is being called;
+	# this means you should attach the code to run after the query completes
+	# with `#callback`, and you can attach an error handler with `#errback`
+	# if you like.
+	#
+	def db_insert(db, tbl, params)
+		db.exec_defer(*insert_sql(tbl, params))
+	end
+
+	# Execute code in a transaction.
+	#
+	# Arguments:
+	#
+	#  * `db` -- A PG::EM::Client or PG::EM::ConnectionPool instance, against
+	#    which all database operations will be executed.  If you pass a
+	#    ConnectionPool, we will automatically hold a single connection for
+	#    the transaction to complete against, so you don't have to worry
+	#    about that, either.
+	#
+	#  * `blk` -- A block of code which will be executed within the context
+	#    of the transaction.  This block will be passed a
+	#    `PG::EM::Client::Helper::Transaction` instance, which has methods to
+	#    allow you to commit or rollback the transaction, and execute SQL
+	#    statements within the context of the transaction.
+	#
+	# Returns a deferrable object, on which you can call `#callback` and
+	# `#errback` to define what to do when the transaction succeeds or fails,
+	# respectively.
+	#
+	def db_transaction(db, opts = {}, &blk)
+		if db.is_a? PG::EM::ConnectionPool
+			db.__send__(:hold_deferrable) do |conn|
+				::PG::EM::Client::Helper::Transaction.new(conn, opts, &blk)
+			end
+		else
+			::PG::EM::Client::Helper::Transaction.new(db, opts, &blk)
+		end
+	end
+
+	# Take a PgSQL identifier (anything that isn't data, basically) and quote
+	# it so that it will always be valid, no matter what insanity someone's
+	# decided to put in their names.
+	#
+	def quote_identifier(id)
+		'"' + id.gsub(/"/, '""') + '"'
+	end
+
+	class Transaction
+		include ::PG::EM::Client::Helper
+		include ::EventMachine::Deferrable
+		
+		# Create a new transaction.  You shouldn't have to call this yourself;
+		# `db_transaction` should create one and pass it to your block.
+		def initialize(conn, opts, &blk)
+			@conn       = conn
+			@opts       = opts
+			@active     = true
+			
+			conn.exec_defer("BEGIN").callback do
+				blk.call(self)
+				commit if @active
+			end.errback { |ex| rollback(ex) }
+		end
+
+		# Signal the database to commit this transaction.  You must do this
+		# once you've completed your queries, it won't be called automatically
+		# for you.  Once you've committed the transaction, you cannot use it
+		# again; if you execute a query against a committed transaction, an
+		# exception will be raised.
+		#
+		def commit
+			@conn.exec_defer("COMMIT").callback do
+				self.succeed
+				@active = false
+			end.errback { |ex| rollback(ex) }
+		end
+
+		# Signal the database to abort this transaction.  You only need to
+		# call this method if you need to rollback for some business logic
+		# reason -- a rollback will be automatically performed for you in the
+		# event of a database error or other exception.
+		#
+		def rollback(ex)
+			@conn.exec_defer("ROLLBACK") do
+				@active = false
+				self.fail(ex)
+			end
+		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,
+		# `blk` will be called to allow the transaction to continue.
+		#
+		def insert(tbl, params, &blk)
+			exec(*insert_sql(tbl, params), &blk)
+		end
+
+		# Execute an arbitrary block of SQL in `sql` within the transaction. 
+		# If you need to pass dynamic values to the query, those should be
+		# given in `values`, and referenced in `sql` as `$1`, `$2`, etc.  The
+		# given block will be called if and when the query completes
+		# successfully.
+		#
+		def exec(sql, values=[], &blk)
+			df = @conn.exec_defer(sql, values).
+			       errback { |ex| rollback(ex) }
+			df.callback(&blk) if blk
+		end
+	end
+end

data/spec/db_insert_spec.rb

@@ -0,0 +1,14 @@
+require_relative './spec_helper'
+
+describe "PG::EM::Client::Helper#db_insert" do
+	it "Calls the right SQL" do
+		expect(db = double).
+		  to receive(:exec_defer).
+		  with(
+		    'INSERT INTO "foo" ("bar") VALUES ($1)',
+		    ['baz']
+		  )
+		
+		db_insert(db, "foo", :bar => "baz")
+	end
+end

data/spec/db_transaction_spec.rb

@@ -0,0 +1,76 @@
+require_relative './spec_helper'
+
+describe "PG::EM::Client::Helper#db_transaction" do
+	def mock_query_chain(queries, fail_on = -1, &blk)
+		mock_conn = double(PG::EM::Client)
+
+		queries.each_with_index do |q, i|
+			df = EM::DefaultDeferrable.new
+
+			ex = expect(mock_conn).
+			  to receive(:exec_defer).
+			  with(*q).
+			  and_return(df)
+
+			# Rollback expects a yield
+			if q == ["ROLLBACK"]
+				ex.and_yield()
+			end
+			
+			if i == fail_on
+				df.fail
+			else
+				df.succeed
+			end
+		end
+
+		EM.run_block do
+			db_transaction(mock_conn, &blk)
+		end
+	end
+
+	it "runs a BEGIN/COMMIT cycle by default" do
+		mock_query_chain([["BEGIN"], ["COMMIT"]]) do
+			# Nothing
+		end
+	end
+	
+	it "rolls back if BEGIN fails" do
+		mock_query_chain([["BEGIN"], ["ROLLBACK"]], 0) do
+			# Nothing
+		end
+	end
+	
+	it "rolls back if COMMIT fails" do
+		mock_query_chain([["BEGIN"], ["COMMIT"], ["ROLLBACK"]], 1) do
+			# Nothing
+		end
+	end
+
+	it "runs a simple INSERT" do
+		mock_query_chain([
+		  ["BEGIN"],
+		  ['INSERT INTO "foo" ("bar") VALUES ($1)',
+		   ["baz"]
+		  ],
+		  ["COMMIT"]
+		]) do |txn|
+			txn.insert("foo", :bar => 'baz')
+		end
+	end
+
+	it "rolls back after a failed INSERT" do
+		mock_query_chain(
+		  [
+		    ["BEGIN"],
+		    ['INSERT INTO "foo" ("bar") VALUES ($1)',
+		     ["baz"]
+		    ],
+		    ["ROLLBACK"]
+		  ],
+		  1
+		) do |txn|
+			txn.insert("foo", :bar => 'baz')
+		end
+	end
+end

data/spec/insert_sql_spec.rb

@@ -0,0 +1,11 @@
+require_relative './spec_helper'
+
+describe "PG::EM::Client::Helper#insert_sql" do
+	it "assembles a simple query correctly" do
+		expect(insert_sql("foo", :bar => "baz", :wombat => 42)).
+		  to eq([
+		    'INSERT INTO "foo" ("bar","wombat") VALUES ($1,$2)',
+		    ["baz", 42]
+		  ])
+	end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,27 @@
+require 'spork'
+
+Spork.prefork do
+	require 'bundler'
+	Bundler.setup(:default, :test)
+	require 'rspec/core'
+	require 'rspec/mocks'
+
+	require 'pry'
+
+	RSpec.configure do |config|
+		config.fail_fast = true
+#		config.full_backtrace = true
+
+		config.expect_with :rspec do |c|
+			c.syntax = :expect
+		end
+	end
+end
+
+Spork.each_run do
+	require 'em-pg-client-helper'
+	
+	RSpec.configure do |config|
+		config.include ::PG::EM::Client::Helper
+	end
+end

metadata

@@ -0,0 +1,255 @@
+--- !ruby/object:Gem::Specification
+name: em-pg-client-helper
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Matt Palmer
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-10-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: git-version-bump
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: em-pg-client
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: eventmachine
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: github-release
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard-spork
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rb-inotify
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: pry-debugger
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email: 
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- .gitignore
+- Gemfile
+- Guardfile
+- LICENCE
+- README.md
+- Rakefile
+- em-pg-client-helper.gemspec
+- lib/em-pg-client-helper.rb
+- spec/db_insert_spec.rb
+- spec/db_transaction_spec.rb
+- spec/insert_sql_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/mpalmer/em-pg-client-helper
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -3158041732847442492
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -3158041732847442492
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Simplify common operations using em-pg-client
+test_files: []