em-pg-client-helper 0.6.0 → 1.0.0

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

@@ -68,6 +68,24 @@ module PG::EM::Client::Helper
 	#   the transaction to complete against, so you don't have to worry about
 	#   that, either.
 	#
+	# @param opts [Hash] Zero or more options which change the behaviour of the
+	#   transaction.
+	#
+	# @option opts [Symbol] :isolation An isolation level for the transaction.
+	#   Valid values are `:serializable`, `:repeatable_read`,
+	#   `:read_committed`, and `:read_uncommitted`.  The last two of these
+	#   are pointless to use and are included only for completeness, as
+	#   PostgreSQL's default isolation level is `:read_committed`, and
+	#   `:read_uncommitted` is equivalent to `:read_committed`.
+	#
+	# @option opts [TrueClass, FalseClass] :retry Whether or not to retry the
+	#   transaction if it fails for one of a number of transaction-internal
+	#   reasons.
+	#
+	# @option opts [TrueClass, FalseClass] :deferrable If set, enables the
+	#   `DEFERRABLE` transaction mode.  For details of what this is, see the
+	#   `SET TRANSACTION` command documentation in the PostgreSQL manual.
+	#
 	# @param blk [Proc] 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
@@ -78,6 +96,9 @@ module PG::EM::Client::Helper
 	#   `#errback` to define what to do when the transaction succeeds or
 	#   fails, respectively.
 	#
+	# @raise [ArgumentError] If an unrecognised value for the `:isolation`
+	#   option is given.
+	#
 	# @note Due to the way that transactions detect when they are completed,
 	#   every deferrable in the scope of the transaction must be generated
 	#   by the transaction.  That is, you cannot use objects other than the

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

@@ -4,28 +4,56 @@ class PG::EM::Client::Helper::Transaction
 
 	# 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)
+	#
+	# @param conn [PG::EM::Connection] The connection to execute all commands
+	#   against.  If using a connection pool, this connection needs to have
+	#   been taken out of the pool (using something like `#hold_deferred`) so
+	#   that no other concurrently-operating code can accidentally send
+	#   queries down the connection (that would be, in a word, *bad*).
+	#
+	# @param opts [Hash] Zero or more optional parameters that adjust the
+	#   initial state of the transaction.  For full details of the available
+	#   options, see {PG::EM::Client::Helper#db_transaction}.
+	#
+	# @raise [ArgumentError] If an unknown isolation level is specified.
+	#
+	def initialize(conn, opts = {}, &blk)
 		@conn       = conn
 		@opts       = opts
 		# This can be `nil` if the txn is in progress, or it will be
 		# true or false to indicate success/failure of the txn
 		@committed  = nil
-		@retryable  = false
+		@retryable  = opts[:retry]
 
 		DeferrableGroup.new do |dg|
 			@dg = dg
 
-			trace_query("BEGIN")
-			@conn.exec_defer("BEGIN").tap do |df|
-				@dg.add(df)
-			end.callback do
+			begin_query = case opts[:isolation]
+				when :serializable
+					"BEGIN TRANSACTION ISOLATION LEVEL SERIALIZABLE"
+				when :repeatable_read
+					"BEGIN TRANSACTION ISOLATION LEVEL REPEATABLE READ"
+				when :read_committed
+					"BEGIN TRANSACTION ISOLATION LEVEL READ COMMITTED"
+				when :read_uncommitted
+					"BEGIN TRANSACTION ISOLATION LEVEL READ UNCOMMITTED"
+				when nil
+					"BEGIN"
+				else
+					raise ArgumentError,
+					      "Unknown value for :isolation option: #{opts[:isolation].inspect}"
+			end
+
+			if opts[:deferrable]
+				begin_query += " DEFERRABLE"
+			end
+
+			exec(begin_query) do
 				begin
 					blk.call(self)
 				rescue StandardError => ex
 					rollback(ex)
 				end
-			end.errback do |ex|
-				rollback(ex)
 			end
 		end.callback do
 			rollback(RuntimeError.new("txn.commit was not called")) unless @committed
@@ -43,18 +71,6 @@ class PG::EM::Client::Helper::Transaction
 		end
 	end
 
-	# Mark the transaction as requiring the serializable isolation level.
-	#
-	# @param retryable [TrueClass, FalseClass] Whether or not the transaction
-	#   should be retried if some sort of transaction-level failure occurs.
-	#   Be careful enabling this, as the entire block will be re-run, including
-	#   any code that creates side-effects elsewhere.
-	#
-	def serializable(retryable = false, &blk)
-		@retryable = retryable
-		exec("SET TRANSACTION ISOLATION LEVEL SERIALIZABLE", &blk)
-	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
@@ -64,13 +80,15 @@ class PG::EM::Client::Helper::Transaction
 	def commit
 		if @committed.nil?
 			trace_query("COMMIT")
-			@conn.exec_defer("COMMIT").tap do |df|
+			@conn.exec_defer("COMMIT", []).tap do |df|
 				@dg.add(df)
 			end.callback do
 				@committed = true
 				@dg.close
 			end.errback do |ex|
-				rollback(ex)
+				@committed = false
+				@dg.fail(ex)
+				@dg.close
 			end
 		end
 	end
@@ -82,10 +100,7 @@ class PG::EM::Client::Helper::Transaction
 	#
 	def rollback(ex)
 		if @committed.nil?
-			trace_query("ROLLBACK")
-			@conn.exec_defer("ROLLBACK").tap do |df|
-				@dg.add(df)
-			end.callback do
+			exec("ROLLBACK") do
 				@committed = false
 				@dg.fail(ex)
 				@dg.close

data/spec/db_transaction_spec.rb

@@ -3,12 +3,12 @@ require_relative './spec_helper'
 describe "PG::EM::Client::Helper#db_transaction" do
 	let(:mock_conn) { double(PG::EM::Client) }
 
-	def expect_query_failure(q, args=nil, err=nil, exec_time = 0.001)
+	def expect_query_failure(q, args=[], err=nil, exec_time = 0.001)
 		err ||= RuntimeError.new("Dummy failure")
 		expect_query(q, args, exec_time, :fail, err)
 	end
 
-	def expect_query(q, args=nil, exec_time = 0.001, disposition = :succeed, *disp_opts)
+	def expect_query(q, args=[], exec_time = 0.001, disposition = :succeed, *disp_opts)
 		df = EM::DefaultDeferrable.new
 
 		expect(mock_conn)
@@ -22,8 +22,8 @@ describe "PG::EM::Client::Helper#db_transaction" do
 		end
 	end
 
-	def in_transaction(&blk)
-		db_transaction(mock_conn, &blk).callback { EM.stop }.errback { EM.stop }
+	def in_transaction(*args, &blk)
+		db_transaction(mock_conn, *args, &blk).callback { EM.stop }.errback { EM.stop }
 	end
 
 	def in_em
@@ -53,11 +53,10 @@ describe "PG::EM::Client::Helper#db_transaction" do
 		end
 	end
 
-	it "rolls back if COMMIT fails" do
+	it "doesn't roll back if COMMIT fails" do
 		in_em do
 			expect_query("BEGIN")
 			expect_query_failure("COMMIT")
-			expect_query("ROLLBACK")
 			in_transaction do |txn|
 				txn.commit
 			end
@@ -135,6 +134,30 @@ describe "PG::EM::Client::Helper#db_transaction" do
 		end
 	end
 
+	it "is robust against having an unrelated deferrable in the chain" do
+		in_em do
+			expect_query("BEGIN")
+			expect_query('INSERT INTO "foo" ("bar") VALUES ($1)', ['baz'])
+			expect_query('INSERT INTO "foo" ("bar") VALUES ($1)', ['wombat'])
+			expect_query('INSERT INTO "foo" ("bar") VALUES ($1)', ['quux'])
+			expect_query("COMMIT")
+
+			in_transaction do |txn|
+				txn.insert("foo", :bar => 'baz') do
+					txn.insert("foo", :bar => 'wombat') do
+						df = ::EM::DefaultDeferrable.new
+						df.callback do
+							txn.insert("foo", :bar => 'quux') do
+								txn.commit
+							end
+						end
+						df.succeed
+					end
+				end
+			end
+		end
+	end
+
 	it "doesn't COMMIT if we rolled back" do
 		in_em do
 			expect_query("BEGIN")
@@ -160,22 +183,51 @@ describe "PG::EM::Client::Helper#db_transaction" do
 		end
 	end
 
+	it "uses SERIALIZABLE if we ask nicely" do
+		in_em do
+			expect_query("BEGIN TRANSACTION ISOLATION LEVEL SERIALIZABLE")
+			expect_query("COMMIT")
+
+			in_transaction(:isolation => :serializable) do |txn|
+				txn.commit
+			end
+		end
+	end
+
+	it "uses REPEATABLE READ if we ask nicely" do
+		in_em do
+			expect_query("BEGIN TRANSACTION ISOLATION LEVEL REPEATABLE READ")
+			expect_query("COMMIT")
+
+			in_transaction(:isolation => :repeatable_read) do |txn|
+				txn.commit
+			end
+		end
+	end
+
+	it "uses DEFERRABLE if we ask nicely" do
+		in_em do
+			expect_query("BEGIN DEFERRABLE")
+			expect_query("COMMIT")
+
+			in_transaction(:deferrable => true) do |txn|
+				txn.commit
+			end
+		end
+	end
+
 	it "retries if it gets an error during the transaction" do
 		in_em do
-			expect_query("BEGIN")
-			expect_query("SET TRANSACTION ISOLATION LEVEL SERIALIZABLE", [])
+			expect_query("BEGIN TRANSACTION ISOLATION LEVEL SERIALIZABLE")
 			expect_query_failure('INSERT INTO "foo" ("bar") VALUES ($1)', ["baz"], PG::TRSerializationFailure.new("OMFG!"))
 			expect_query("ROLLBACK")
-			expect_query("BEGIN")
-			expect_query("SET TRANSACTION ISOLATION LEVEL SERIALIZABLE", [])
+			expect_query("BEGIN TRANSACTION ISOLATION LEVEL SERIALIZABLE")
 			expect_query('INSERT INTO "foo" ("bar") VALUES ($1)', ["baz"])
 			expect_query("COMMIT")
 
-			in_transaction do |txn|
-				txn.serializable(true) do
-					txn.insert("foo", :bar => 'baz') do
-						txn.commit
-					end
+			in_transaction(:isolation => :serializable, :retry => true) do |txn|
+				txn.insert("foo", :bar => 'baz') do
+					txn.commit
 				end
 			end
 		end
@@ -183,21 +235,16 @@ describe "PG::EM::Client::Helper#db_transaction" do
 
 	it "retries if it gets an error on commit" do
 		in_em do
-			expect_query("BEGIN")
-			expect_query("SET TRANSACTION ISOLATION LEVEL SERIALIZABLE", [])
+			expect_query("BEGIN TRANSACTION ISOLATION LEVEL SERIALIZABLE")
 			expect_query('INSERT INTO "foo" ("bar") VALUES ($1)', ["baz"])
-			expect_query_failure("COMMIT", nil, PG::TRSerializationFailure.new("OMFG!"))
-			expect_query("ROLLBACK")
-			expect_query("BEGIN")
-			expect_query("SET TRANSACTION ISOLATION LEVEL SERIALIZABLE", [])
+			expect_query_failure("COMMIT", [], PG::TRSerializationFailure.new("OMFG!"))
+			expect_query("BEGIN TRANSACTION ISOLATION LEVEL SERIALIZABLE")
 			expect_query('INSERT INTO "foo" ("bar") VALUES ($1)', ["baz"])
 			expect_query("COMMIT")
 
-			in_transaction do |txn|
-				txn.serializable(true) do
-					txn.insert("foo", :bar => 'baz') do
-						txn.commit
-					end
+			in_transaction(:isolation => :serializable, :retry => true) do |txn|
+				txn.insert("foo", :bar => 'baz') do
+					txn.commit
 				end
 			end
 		end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: em-pg-client-helper
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-21 00:00:00.000000000 Z
+date: 2015-01-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: git-version-bump
@@ -261,7 +261,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3912850109456819706
+      hash: 4034289824364546696
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -270,7 +270,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3912850109456819706
+      hash: 4034289824364546696
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23