-- 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 connections 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.4.1


-- | 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>.
module Hasql

-- | A monad transformer, which executes transactions.
--   
--   <ul>
--   <li><tt>b</tt> is a backend.</li>
--   <li><tt>s</tt> is an anonymous variable, used to associate
--   <a>sessionUnlifter</a> with a specific session.</li>
--   <li><tt>m</tt> is an inner (transformed) monad.</li>
--   <li><tt>r</tt> is a result.</li>
--   </ul>
data Session b s m r

-- | Given backend settings, session settings, and a session monad
--   transformer, execute it in the inner monad.
--   
--   It uses the same trick as <a>ST</a> with the anonymous <tt>s</tt> type
--   argument to prohibit the use of the result of <a>sessionUnlifter</a>
--   outside of its creator session.
session :: (Backend b, MonadBaseControl IO m) => b -> SessionSettings -> (forall s. Session b s m r) -> m r

-- | Get a session unlifting function, which allows to execute a session in
--   the inner monad using the resources of the current session.
--   
--   Using this function in combination with <a>lift</a> you can interleave
--   <a>Session</a> with other monad transformers.
--   
--   This function has the following property:
--   
--   <pre>
--   (sessionUnlifter &gt;&gt;= \unlift -&gt; lift (unlift m)) ≡ m
--   </pre>
sessionUnlifter :: MonadBaseControl IO m => Session b s m (Session b s m r -> m r)

-- | Settings of a session.
data SessionSettings

-- | A smart constructor for session settings.
sessionSettings :: Word32 -> NominalDiffTime -> Maybe SessionSettings

-- | A transaction specialized for a backend <tt>b</tt>, associated with
--   its intermediate results using an anonymous type-argument <tt>s</tt>
--   (same as in <a>ST</a>) and producing a result <tt>r</tt>.
data Tx b s r

-- | Execute a transaction in a session.
--   
--   This function ensures on the type level, that it's impossible to
--   return <tt><a>TxListT</a> s m r</tt> from it.
tx :: (Backend b, MonadBase IO m) => Mode -> (forall s. Tx b s r) -> Session b s m r

-- | A transaction 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 boolean, defining, whether it would perform any modification
--   operations.</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 Mode = Maybe (IsolationLevel, Bool)

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

-- | Produces a lambda-expression, which takes as many parameters as there
--   are placeholders in the quoted text and results in a <a>Statement</a>.
--   
--   E.g.:
--   
--   <pre>
--   selectFive :: Statement b
--   selectFive = [q|SELECT (? + ?)|] 2 3
--   </pre>
q :: QuasiQuoter

-- | Execute a statement, which produces no result.
unit :: Backend b => Statement b -> Tx b s ()

-- | Execute a statement and count the amount of affected rows. Useful for
--   resolving how many rows were updated or deleted.
count :: (Backend b, Mapping b Word64) => Statement b -> Tx b s Word64

-- | Execute a statement, which produces a single result row: a
--   <tt>SELECT</tt> or an <tt>INSERT</tt>, which produces a generated
--   value (e.g., an auto-incremented id).
single :: (Backend b, RowParser b r) => Statement b -> Tx b s (Maybe r)

-- | Execute a <tt>SELECT</tt> statement, and produce a list of results.
list :: (Backend b, RowParser b r) => Statement b -> Tx b s [r]

-- | Execute a <tt>SELECT</tt> statement with a cursor, and produce a
--   results stream.
--   
--   Cursor allows you to fetch virtually limitless results in a constant
--   memory at a cost of a small overhead. Note that in most databases
--   cursors require establishing a database transaction, so a
--   <a>NotInTransaction</a> error will be raised if you run it improperly.
stream :: (Backend b, RowParser b r) => Statement b -> TxListT s (Tx b s) r

-- | A stream of results, which fetches only those that you reach.
--   
--   It's a wrapper around <a>ListT</a>, which uses the same trick as the
--   <a>ST</a> monad to associate with the context transaction and become
--   impossible to be used outside of it. This lets the library ensure that
--   it is safe to automatically release all the resources 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 TxListT s m r
class RowParser b r
parseRow :: RowParser b r => Vector (Result b) -> Either Text r

-- | The only exception type that this API can raise.
data Error

-- | Cannot connect to a server.
CantConnect :: Text -> Error

-- | The connection got interrupted.
ConnectionLost :: Text -> Error

-- | An error returned from the database.
ErroneousResult :: Text -> Error

-- | Unexpected result structure. Indicates usage of inappropriate
--   statement executor.
UnexpectedResult :: Text -> Error

-- | Incorrect statement template.
UnparsableTemplate :: Text -> Error

-- | An operation, which requires a database transaction was executed
--   without one.
NotInTransaction :: Error

-- | Attempt to parse a row into an incompatible type. Indicates either a
--   mismatching schema or an incorrect query.
UnparsableRow :: Text -> Error
instance Typeable Error
instance Functor m => Functor (Session b s m)
instance Applicative m => Applicative (Session b s m)
instance Monad m => Monad (Session b s m)
instance MonadTrans (Session b s)
instance MonadIO m => MonadIO (Session b s m)
instance Show Error
instance Eq Error
instance Ord Error
instance Functor (Tx b s)
instance Applicative (Tx b s)
instance Monad (Tx b s)
instance Functor m => Functor (TxListT s m)
instance (Monad m, Functor m) => Applicative (TxListT s m)
instance (Monad m, Functor m) => Alternative (TxListT s m)
instance Monad m => Monad (TxListT s m)
instance MonadTrans (TxListT s)
instance Monad m => MonadPlus (TxListT s m)
instance Monad m => Monoid (TxListT s m r)
instance Monad m => MonadCons (TxListT s m)
instance MonadTransUncons (TxListT s)
instance Exception Error
instance MonadBaseControl IO m => MonadBaseControl IO (Session b s m)
instance MonadBase IO m => MonadBase IO (Session b s m)
instance MonadTransControl (Session b s)