feat: add connection.transaction method

README.md

@@ -23,6 +23,7 @@ A PostgreSQL client with strict types and assertions.
   * [`maybeOne`](#maybeone)
   * [`one`](#one)
   * [`query`](#query)
+  * [`transaction`](#transaction)
 * [Overriding Error Constructor](#overriding-error-constructor)
 * [Error handling](#error-handling)
   * [Handling `NotFoundError`](#handling-notfounderror)
@@ -293,6 +294,20 @@ The following error types can be overridden:
 
 * `NotFoundError`
 
+### `transaction`
+
+`transaction` method is used wrap execution of queries in `START TRANSACTION` and `COMMIT` or `ROLLBACK`. `COMMIT` is called if the transaction handler returns a promise that resolves; `ROLLBACK` is called otherwise.
+
+`transaction` method can be used together with `createPool` method. When used to create a transaction from an instance of a pool, a new connection is allocated for the duration of the transaction.
+
+```js
+await connection.transaction(async (transactionConnection) => {
+  transactionConnection.query(`INSERT INTO foo (bar) VALUES ('baz')`);
+  transactionConnection.query(`INSERT INTO qux (quux) VALUES ('quuz')`);
+});
+
+```
+
 ## Error handling
 
 ### Handling `NotFoundError`

src/index.js

@@ -30,6 +30,7 @@ import type {
   InternalQueryMaybeOneType,
   InternalQueryOneType,
   InternalQueryType,
+  InternalTransactionType,
   QueryResultRowType,
   TaggledTemplateLiteralInvocationType
 } from './types';
@@ -188,6 +189,20 @@ export const any: InternalQueryAnyType = async (connection, clientConfiguration,
   return rows;
 };
 
+export const transaction: InternalTransactionType = async (connection, handler) => {
+  await query(connection, 'START TRANSACTION');
+
+  try {
+    await handler(connection);
+
+    await connection.query('COMMIT');
+  } catch (error) {
+    await connection.query('ROLLBACK');
+
+    throw error;
+  }
+};
+
 const sql = (parts: $ReadOnlyArray<string>, ...values: AnonymouseValuePlaceholderValuesType): TaggledTemplateLiteralInvocationType => {
   return {
     sql: parts.join('?'),
@@ -221,7 +236,8 @@ const createConnection = async (
     many: mapTaggedTemplateLiteralInvocation(many.bind(null, connection, clientConfiguration)),
     maybeOne: mapTaggedTemplateLiteralInvocation(maybeOne.bind(null, connection, clientConfiguration)),
     one: mapTaggedTemplateLiteralInvocation(one.bind(null, connection, clientConfiguration)),
-    query: mapTaggedTemplateLiteralInvocation(query.bind(null, connection))
+    query: mapTaggedTemplateLiteralInvocation(query.bind(null, connection)),
+    transaction: transaction.bind(null, connection)
   };
 };
 
@@ -231,24 +247,39 @@ const createPool = (
 ): DatabasePoolType => {
   const pool = new pg.Pool(typeof connectionConfiguration === 'string' ? parseConnectionString(connectionConfiguration) : connectionConfiguration);
 
+  const connect = async () => {
+    const connection = await pool.connect();
+
+    return {
+      any: mapTaggedTemplateLiteralInvocation(any.bind(null, connection, clientConfiguration)),
+      many: mapTaggedTemplateLiteralInvocation(many.bind(null, connection, clientConfiguration)),
+      maybeOne: mapTaggedTemplateLiteralInvocation(maybeOne.bind(null, connection, clientConfiguration)),
+      one: mapTaggedTemplateLiteralInvocation(one.bind(null, connection, clientConfiguration)),
+      query: mapTaggedTemplateLiteralInvocation(query.bind(null, connection)),
+      release: connection.release.bind(connection),
+      transaction: transaction.bind(null, connection)
+    };
+  };
+
   return {
     any: mapTaggedTemplateLiteralInvocation(any.bind(null, pool, clientConfiguration)),
-    connect: async () => {
-      const connection = await pool.connect();
-
-      return {
-        any: mapTaggedTemplateLiteralInvocation(any.bind(null, connection, clientConfiguration)),
-        many: mapTaggedTemplateLiteralInvocation(many.bind(null, connection, clientConfiguration)),
-        maybeOne: mapTaggedTemplateLiteralInvocation(maybeOne.bind(null, connection, clientConfiguration)),
-        one: mapTaggedTemplateLiteralInvocation(one.bind(null, connection, clientConfiguration)),
-        query: mapTaggedTemplateLiteralInvocation(query.bind(null, connection)),
-        release: connection.release.bind(connection)
-      };
-    },
+    connect,
     many: mapTaggedTemplateLiteralInvocation(many.bind(null, pool, clientConfiguration)),
     maybeOne: mapTaggedTemplateLiteralInvocation(maybeOne.bind(null, pool, clientConfiguration)),
     one: mapTaggedTemplateLiteralInvocation(one.bind(null, pool, clientConfiguration)),
-    query: mapTaggedTemplateLiteralInvocation(query.bind(null, pool))
+    query: mapTaggedTemplateLiteralInvocation(query.bind(null, pool)),
+    transaction: async (handler) => {
+      debug('allocating a new connection to execute the transaction');
+
+      const connection = await connect();
+
+      try {
+        await connection.transaction(handler);
+      } finally {
+        debug('releasing the connection that was earlier secured to execute the transaction');
+        await connection.release();
+      }
+    }
   };
 };
 

src/types.js

@@ -54,7 +54,8 @@ export type DatabaseConnectionType = {
   +many: QueryManyType<*>,
   +maybeOne: QueryMaybeOneType<*>,
   +one: QueryOneType<*>,
-  +query: QueryType<*>
+  +query: QueryType<*>,
+  +transaction: TransactionType
 };
 
 export type DatabasePoolConnectionType = DatabaseConnectionType & {
@@ -126,10 +127,15 @@ export type InternalQueryOneType = (
   values?: DatabaseQueryValuesType
 ) => Promise<QueryResultRowType>;
 
+export type TransactionHandlerType = (connection: DatabaseConnectionType) => Promise<void>;
+
+export type InternalTransactionType = (connection: InternalDatabaseConnectionType, handler: TransactionHandlerType) => Promise<void>;
+
 export type InternalQueryType<T: QueryResultRowType> = (connection: InternalDatabaseConnectionType, sql: string, values?: DatabaseQueryValuesType) => Promise<QueryResultType<T>>;
 
 export type QueryAnyType<T: QueryResultRowType> = (sql: string | TaggledTemplateLiteralInvocationType, values?: DatabaseQueryValuesType) => Promise<$ReadOnlyArray<T>>;
 export type QueryManyType<T: QueryResultRowType> = (sql: string | TaggledTemplateLiteralInvocationType, values?: DatabaseQueryValuesType) => Promise<$ReadOnlyArray<T>>;
 export type QueryMaybeOneType<T: QueryResultRowType | null> = (sql: string | TaggledTemplateLiteralInvocationType, values?: DatabaseQueryValuesType) => Promise<T>;
 export type QueryOneType<T: QueryResultRowType> = (sql: string | TaggledTemplateLiteralInvocationType, values?: DatabaseQueryValuesType) => Promise<T>;
 export type QueryType<T: QueryResultRowType> = (sql: string | TaggledTemplateLiteralInvocationType, values?: DatabaseQueryValuesType) => Promise<QueryResultType<T>>;
+export type TransactionType = (handler: TransactionHandlerType) => Promise<void>;

test/mightyql/transaction.js

@@ -0,0 +1,59 @@
+// @flow
+
+/* eslint-disable flowtype/no-weak-types */
+
+import test from 'ava';
+import sinon from 'sinon';
+import {
+  transaction
+} from '../../src';
+
+test('commits successful transaction', async (t) => {
+  const query = sinon.stub();
+
+  query.returns({});
+
+  const connection = {
+    query
+  };
+
+  await transaction(connection, async () => {
+    await query('FOO');
+  });
+
+  t.true(query.args[0].length === 1);
+  t.true(query.args[0][0] === 'START TRANSACTION');
+
+  t.true(query.args[1].length === 1);
+  t.true(query.args[1][0] === 'FOO');
+
+  t.true(query.args[2].length === 1);
+  t.true(query.args[2][0] === 'COMMIT');
+});
+
+test('rollbacks unsuccessful transaction', async (t) => {
+  const query = sinon.stub();
+
+  query.returns({});
+
+  const connection = {
+    query
+  };
+
+  const transactionExecution = transaction(connection, async () => {
+    await query('FOO');
+
+    throw new Error();
+  });
+
+  await t.throws(transactionExecution);
+
+  t.true(query.args[0].length === 1);
+  t.true(query.args[0][0] === 'START TRANSACTION');
+
+  t.true(query.args[1].length === 1);
+  t.true(query.args[1][0] === 'FOO');
+
+  t.true(query.args[2].length === 1);
+  t.true(query.args[2][0] === 'ROLLBACK');
+});