-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A minimalistic general high level API for relational databases
--   
--   A robust and concise yet powerful API for communication with arbitrary
--   relational databases using SQL.
--   
--   Features:
--   
--   <ul>
--   <li>Concise and crisp API. Just a few functions and two monads doing
--   all the boilerplate job for you.</li>
--   <li>A powerful transaction abstraction, which provides an automated
--   resolution of conflicts. The API ensures that you're only able to
--   perform a specific set of actions in the transaction context, which
--   allows Hasql to safely resolve conflicting transactions by
--   automatically retrying them. This is much inspired by STM and ST.</li>
--   <li>Support for cursors. Allows to fetch virtually limitless result
--   sets in a constant memory using streaming.</li>
--   <li>Employment of prepared statements. Every statement you emit gets
--   prepared and cached. This raises the performance of the backend.</li>
--   <li>Automated management of resources related to connections,
--   transactions and cursors.</li>
--   <li>A built-in connection pool.</li>
--   <li>Compile-time generation of templates. You just can't write a
--   statement with an incorrect number of placeholders.</li>
--   <li>Ability to map to any types actually supported by the
--   backend.</li>
--   </ul>
--   
--   Links:
--   
--   <ul>
--   <li><a>Benchmarks analysis</a>.</li>
--   <li><a>Basic tutorial-demo</a>.</li>
--   <li><a>PostgreSQL backend</a>.</li>
--   </ul>
@package hasql
@version 0.7.2


-- | This is the API of the "hasql" library. For an introduction to the
--   package and links to more documentation please refer to <a>the
--   package's index page</a>.
--   
--   This API is completely disinfected from exceptions. All
--   error-reporting is explicit and is presented using the <a>Either</a>
--   type.
module Hasql

-- | A connection pool.
data Pool c

-- | Given backend-specific connection settings and pool settings, acquire
--   a backend connection pool, which can then be used to work with the DB.
--   
--   When combining Hasql with other libraries, which throw exceptions it
--   makes sence to utilize <tt>Control.Exception.<a>bracket</a></tt> like
--   this:
--   
--   <pre>
--   bracket (acquirePool bkndStngs poolStngs) (releasePool) $ \pool -&gt; do
--     session pool $ do
--       ...
--     ... any other IO code
--   </pre>
acquirePool :: Cx c => CxSettings c -> PoolSettings -> IO (Pool c)

-- | Release all connections acquired by the pool.
releasePool :: Pool c -> IO ()

-- | Settings of a pool.
data PoolSettings

-- | A smart constructor for pool settings.
poolSettings :: Int -> Int -> Maybe PoolSettings

-- | A convenience wrapper around <a>ReaderT</a>, which provides a shared
--   context for execution and error-handling of transactions.
data Session c m r

-- | Execute a session using an established connection pool.
--   
--   This is merely a wrapper around <a>runReaderT</a>, so you can run it
--   around every transaction, if you want.
session :: Pool c -> Session c m a -> m (Either (SessionError c) a)
data SessionError c

-- | A backend-specific connection acquisition error. E.g., a failure to
--   establish a connection.
CxError :: (CxError c) -> SessionError c

-- | A backend-specific transaction error. It should cover all possible
--   failures related to an established connection, including the loss of
--   connection, query errors and database failures.
TxError :: (TxError c) -> SessionError c

-- | Attempt to parse a result into an incompatible type. Indicates either
--   a mismatching schema or an incorrect query.
ResultError :: Text -> SessionError c

-- | A statement template packed with its values and settings.
data Stmt c :: * -> *

-- | Produces a lambda-expression, which takes as many parameters as there
--   are placeholders in the quoted text and results in a <a>Stmt</a>.
--   
--   E.g.:
--   
--   <pre>
--   selectSum :: Int -&gt; Int -&gt; Stmt c
--   selectSum = [stmt|SELECT (? + ?)|]
--   </pre>
--   
--   It also allows to directly refer to free variables like so:
--   
--   <pre>
--   selectSum :: Int -&gt; Int -&gt; Stmt c
--   selectSum a b = [stmt|SELECT ($a + $b)|]
--   </pre>
stmt :: QuasiQuoter

-- | Statement executor.
--   
--   Just an alias to a function, which executes a statement in <a>Tx</a>.
type Ex c s r = Stmt c -> Tx c s r

-- | Execute a statement without processing the result.
unitEx :: Ex c s ()

-- | Execute a statement and count the amount of affected rows. Useful for
--   resolving how many rows were updated or deleted.
countEx :: CxValue c Word64 => Ex c s Word64

-- | Execute a statement, which produces exactly one result row. E.g.,
--   <tt>INSERT</tt>, which returns an autoincremented identifier, or
--   <tt>SELECT COUNT</tt>, or <tt>SELECT EXISTS</tt>.
--   
--   Please note that using this executor for selecting rows is
--   conceptually wrong, since in that case the results are always
--   optional. Use <a>maybeEx</a>, <a>listEx</a> or <a>vectorEx</a>
--   instead.
--   
--   If the result is empty this executor will raise <a>ResultError</a>.
singleEx :: CxRow c r => Ex c s r

-- | Execute a statement, which optionally produces a single result row.
maybeEx :: CxRow c r => Ex c s (Maybe r)

-- | Execute a statement, and produce a list of results.
listEx :: CxRow c r => Ex c s [r]

-- | Execute a statement, and produce a vector of results.
vectorEx :: CxRow c r => Ex c s (Vector r)

-- | Given a batch size, execute a statement with a cursor, and produce a
--   result stream.
--   
--   The cursor allows you to fetch virtually limitless results in a
--   constant memory at a cost of a small overhead.
--   
--   The batch size parameter controls how many rows will be fetched during
--   every roundtrip to the database. A minimum value of 256 seems to be
--   sane.
--   
--   Note that in most databases cursors require establishing a database
--   transaction, so depending on a backend the transaction may result in
--   an error, if you run it improperly.
streamEx :: CxRow c r => Int -> Ex c s (TxStream c s r)

-- | A transaction specialized for a backend connection <tt>c</tt>,
--   associated with its intermediate results using an anonymous
--   type-argument <tt>s</tt> (same trick as in <a>ST</a>) and producing a
--   result <tt>r</tt>.
--   
--   Running <a>IO</a> in <a>Tx</a> is prohibited. The motivation is
--   identical to <a>STM</a>: the <a>Tx</a> block may get executed multiple
--   times if any transaction conflicts arise. This will result in your
--   effectful <a>IO</a> code being executed an unpredictable amount of
--   times as well, which, chances are, is not what you want.
data Tx c s r

-- | Execute a transaction in a session.
--   
--   This function ensures on the type level, that it's impossible to
--   return <tt><a>TxStreamListT</a> s m r</tt> from it.
tx :: (CxTx c, MonadBaseControl IO m) => TxMode -> (forall s. Tx c s r) -> Session c m r

-- | A mode, defining how a transaction should be executed.
--   
--   <ul>
--   <li><tt>Just (isolationLevel, write)</tt> indicates that a database
--   transaction should be established with a specified isolation level and
--   a write mode.</li>
--   <li><tt>Nothing</tt> indicates that there should be no database
--   transaction established on the backend and therefore it should be
--   executed with no ACID guarantees, but also without any induced
--   overhead.</li>
--   </ul>
type TxMode = Maybe (TxIsolationLevel, TxWriteMode)

-- | For reference see <a>the Wikipedia info</a>.
data TxIsolationLevel :: *
RepeatableReads :: TxIsolationLevel
Serializable :: TxIsolationLevel
ReadCommitted :: TxIsolationLevel
ReadUncommitted :: TxIsolationLevel

-- | <ul>
--   <li><tt>Nothing</tt> indicates a "read" mode.</li>
--   <li><tt>Just True</tt> indicates a "write" mode.</li>
--   <li><tt>Just False</tt> indicates a "write" mode without committing.
--   This is useful for testing, allowing you to modify your database,
--   producing some result based on your changes, and to let Hasql roll all
--   the changes back on the exit from the transaction.</li>
--   </ul>
type TxWriteMode = Maybe Bool

-- | A stream of results, which fetches approximately only those that you
--   reach.
type TxStream c s = TxStreamListT s (Tx c s)

-- | A wrapper around <a>ListT</a>, which uses the same trick as the
--   <a>ST</a> monad to associate with the context monad and become
--   impossible to be returned from it, using the anonymous type parameter
--   <tt>s</tt>. This lets the library ensure that it is safe to
--   automatically release all the connections associated with this stream.
--   
--   All the functions of the "list-t" library are applicable to this type,
--   amongst which are <a>head</a>, <a>toList</a>, <a>fold</a>,
--   <a>traverse_</a>.
data TxStreamListT s m r

-- | This class is only intended to be used with the supplied instances,
--   which should be enough to cover all use cases.
class CxRow c r
instance (Eq (CxError c), Eq (TxError c)) => Eq (SessionError c)
instance (Show (CxError c), Show (TxError c)) => Show (SessionError c)
instance MonadBase IO m => MonadBase IO (Session c m)
instance Show PoolSettings
instance Functor (Tx c s)
instance Applicative (Tx c s)
instance Monad (Tx c s)
instance Monad m => Functor (Session c m)
instance Monad m => Applicative (Session c m)
instance Monad m => Monad (Session c m)
instance MonadIO m => MonadIO (Session c m)
instance Monad m => MonadError (SessionError c) (Session c m)
instance Functor m => Functor (TxStreamListT s m)
instance (Monad m, Functor m) => Applicative (TxStreamListT s m)
instance (Monad m, Functor m) => Alternative (TxStreamListT s m)
instance Monad m => Monad (TxStreamListT s m)
instance MonadTrans (TxStreamListT s)
instance Monad m => MonadPlus (TxStreamListT s m)
instance Monad m => Monoid (TxStreamListT s m r)
instance Monad m => MonadCons (TxStreamListT s m)
instance MonadTransUncons (TxStreamListT s)
instance MonadBaseControl IO m => MonadBaseControl IO (Session c m)
instance MonadTransControl (Session c)
instance MFunctor (Session c)
instance MonadTrans (Session c)
instance Lift PoolSettings