Merge pull request #8 from helium/feature/query-only

Fix parameter order and bump to 1.0.0.

Author: patrickt

postgresql-transactional.cabal

@@ -1,5 +1,5 @@
 name:                postgresql-transactional
-version:             0.2.0.0
+version:             1.0.0
 synopsis:            a transactional monad on top of postgresql-simple
 license:             MIT
 license-file:        LICENSE
@@ -9,15 +9,21 @@ copyright:           2015 Helium
 category:            Database
 build-type:          Simple
 cabal-version:       >=1.10
+description:
+  This package is a simple monadic wrapper around the SQL primitives
+  provided by the postgresql-simple package. It provides simple and
+  predictable semantics for database options, enforces awareness of
+  Postgres's transactional nature at API boundaries, and obviates
+  the need for SQL boilerplate in transactional queries.
 
 source-repository head
     type: git
     location: https://github.com/helium/postgresql-transactional.git
 
 library
-  exposed-modules:     Database.PostgreSQL.TransactionalStore
+  exposed-modules:     Database.PostgreSQL.Transaction
   hs-source-dirs: src
-  ghc-options: -Wall -Werror
+  ghc-options: -Wall
   -- other-extensions:
   build-depends:       base >= 4 && < 5
                      , postgresql-simple >= 0.4

src/Database/PostgreSQL/TransactionalStore.hs renamed to src/Database/PostgreSQL/Transaction.hs

@@ -4,10 +4,10 @@
 {-# LANGUAGE GeneralizedNewtypeDeriving #-}
 {-# LANGUAGE MultiParamTypeClasses      #-}
 
-module Database.PostgreSQL.TransactionalStore
+module Database.PostgreSQL.Transaction
     ( PGTransaction
-    , runPGTransaction
-    , runPGTransaction'
+    , runPGTransactionT
+    , runPGTransactionT'
     , runPGTransactionIO
     , query
     , query_
@@ -16,6 +16,7 @@ module Database.PostgreSQL.TransactionalStore
     , executeMany
     , returning
     , queryHead
+    , queryOnly
     , formatQuery
     ) where
 
@@ -26,6 +27,7 @@ import           Control.Monad.Reader
 import           Control.Monad.Trans.Control
 import           Data.Int
 import qualified Database.PostgreSQL.Simple             as Postgres
+import           Database.PostgreSQL.Simple.FromField
 import           Database.PostgreSQL.Simple.FromRow
 import           Database.PostgreSQL.Simple.ToRow
 import qualified Database.PostgreSQL.Simple.Transaction as Postgres.Transaction
@@ -43,36 +45,41 @@ newtype PGTransactionT m a =
 
 type PGTransaction = PGTransactionT IO
 
-runPGTransaction' :: MonadBaseControl IO m
-                  => Postgres.Transaction.IsolationLevel
-                  -> PGTransactionT m a
-                  -> Postgres.Connection -> m a
-runPGTransaction' isolation (PGTransactionT pgTrans) conn =
+runPGTransactionT' :: MonadBaseControl IO m
+                   => Postgres.Transaction.IsolationLevel
+                   -> PGTransactionT m a
+                   -> Postgres.Connection
+                   -> m a
+runPGTransactionT' isolation (PGTransactionT pgTrans) conn =
     let runTransaction run =
           Postgres.Transaction.withTransactionLevel isolation conn (run pgTrans)
     in control runTransaction `runReaderT` conn
 
-runPGTransaction :: MonadBaseControl IO m
-                 => PGTransactionT m a
-                 -> Postgres.Connection
-                 -> m a
-runPGTransaction = runPGTransaction' Postgres.Transaction.DefaultIsolationLevel
+runPGTransactionT :: MonadBaseControl IO m
+                  => PGTransactionT m a
+                  -> Postgres.Connection
+                  -> m a
+runPGTransactionT = runPGTransactionT' Postgres.Transaction.DefaultIsolationLevel
 
 
 -- | Convenience function when there are no embedded monadic effects, only IO.
 runPGTransactionIO :: MonadIO m
                    => PGTransaction a
                    -> Postgres.Connection
                    -> m a
-runPGTransactionIO = (liftIO .) . runPGTransaction
+runPGTransactionIO = (liftIO .) . runPGTransactionT
 
 
 -- | Issue an SQL query, taking a 'ToRow' input and yielding 'FromRow' outputs.
+-- Please note that the parameter order is different from that in the parent
+-- postgresql-simple library; this is an intentional choice to improve the aesthetics
+-- when using the SQL quasiquoter (making the query parameters come first means that
+-- there is more room for the query string).
 query :: (ToRow input, FromRow output, MonadIO m)
-      => Postgres.Query
-      -> input
+      => input
+      -> Postgres.Query
       -> PGTransactionT m [output]
-query q params = ask >>= (\conn -> liftIO $ Postgres.query conn q params)
+query params q = ask >>= (\conn -> liftIO $ Postgres.query conn q params)
 
 -- | As 'query', but for queries that take no arguments.
 query_ :: (FromRow output, MonadIO m)
@@ -82,30 +89,30 @@ query_ q = ask >>= liftIO . (`Postgres.query_` q)
 
 -- | Run a single SQL action and return success.
 execute :: (ToRow input, MonadIO m)
-        => Postgres.Query
-        -> input
+        => input
+        -> Postgres.Query
         -> PGTransactionT m Int64
-execute q params = ask >>= (\conn -> liftIO $ Postgres.execute conn q params)
+execute params q = ask >>= (\conn -> liftIO $ Postgres.execute conn q params)
 
 executeMany :: (ToRow input, MonadIO m)
-            => Postgres.Query
-            -> [input]
+            => [input]
+            -> Postgres.Query
             -> PGTransactionT m Int64
-executeMany q params = ask >>= (\conn -> liftIO $ Postgres.executeMany conn q params)
+executeMany params q = ask >>= (\conn -> liftIO $ Postgres.executeMany conn q params)
 
 returning :: (ToRow input, FromRow output, MonadIO m)
-          => Postgres.Query
-          -> [input]
+          => [input]
+          -> Postgres.Query
           -> PGTransactionT m [output]
-returning q params = ask >>= (\conn -> liftIO $ Postgres.returning conn q params)
+returning params q = ask >>= (\conn -> liftIO $ Postgres.returning conn q params)
 
 -- | Run a query and return 'Just' the first result found or 'Nothing'.
 queryHead :: (ToRow input, FromRow output, MonadIO m)
           => input
           -> Postgres.Query
           -> PGTransactionT m (Maybe output)
 queryHead params q = do
-  results <- query q params
+  results <- query params q
   return $ case results of
     (a:_) -> Just a
     _     -> Nothing
@@ -115,14 +122,19 @@ executeOne :: (ToRow input, MonadIO m)
            => input
            -> Postgres.Query
            -> PGTransactionT m Bool
-executeOne params q = do
-  results <- execute q params
-  return (results == 1)
+executeOne params q = (== 1) <$> execute params q
+
+-- | Lookup a single FromField value. This takes care of handling 'Only' for you.
+queryOnly :: (ToRow input, FromField f, MonadIO m)
+          => input
+          -> Postgres.Query
+          -> PGTransactionT m (Maybe f)
+queryOnly params q = fmap Postgres.fromOnly <$> queryHead params q
 
-formatQuery :: (ToRow q, MonadIO m)
-            => Postgres.Query
-            -> q
+formatQuery :: (ToRow input, MonadIO m)
+            => input
+            -> Postgres.Query
             -> PGTransactionT m Postgres.Query
-formatQuery q params = do
+formatQuery params q = do
     conn <- ask
     liftIO (PGTypes.Query <$> Postgres.formatQuery conn q params)