-- 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.
--   
--   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>Type-level generation of templates. You just can't write a
--   statement with an incorrect number of placeholders.</li>
--   <li>Mapping to any types actually supported by the backend.</li>
--   </ul>
--   
--   Links:
--   
--   <ul>
--   <li><a>A basic tutorial-demo</a></li>
--   <li><a>A PostgreSQL backend</a></li>
--   </ul>
@package hasql
@version 0.1.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>.
module Hasql

-- | A monad transformer, which executes transactions.
type Session b = ReaderT (Pool (Connection b))

-- | Given backend settings, session settings, and a session monad
--   transformer, execute it in the inner monad.
session :: Backend b => MonadBaseControl IO m => b -> SessionSettings -> Session b 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 backend <tt>b</tt>, running on an
--   anonymous state-thread <tt>s</tt> and producing a result <tt>r</tt>.
data Tx b s 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

-- | Execute a transaction in a session.
tx :: Backend b => MonadBase IO m => Mode -> (forall s. Tx b s r) -> Session b m r

-- | Produces a lambda-expression, which takes as many parameters as there
--   are placeholders in the quoted text and results in an expression of
--   type <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 vector 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 Show 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 => ListMonad (TxListT s m)
instance ListTrans (TxListT s)
instance Exception Error