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


-- | A PostgreSQL access library with compile-time SQL type inference
--   
--   TemplatePG provides PostgreSQL access from Haskell via the PostgreSQL
--   protocol. It also provides a higher-level Template Haskell interface.
--   It eliminates a class of runtime errors by checking queries against a
--   PostgreSQL database at compile-time. This also reduces boilerplate
--   code for dealing with query results, as the type and number of result
--   columns are known at compile-time.
@package templatepg
@version 0.2.5


-- | All type conversion to and from the PostgreSQL server is handled here.
module Database.TemplatePG.Types

-- | TemplatePG currenly only supports a handful of types. It also doesn't
--   distinguish between numeric types with different ranges. More types
--   are the most likely feature of future TemplatePG releases.
data PGType

-- | bool
PGBoolean :: PGType

-- | integer
PGInteger :: PGType

-- | float
PGReal :: PGType

-- | text/varchar
PGText :: PGType

-- | timestamptz (timestamp with time zone)
PGTimestampTZ :: PGType

-- | date (day without time)
PGDate :: PGType

-- | interval (a time interval), send-only
PGInterval :: PGType

-- | Convert a type OID from PostgreSQL's catalog to a TemplatePG
--   representation. To get a list of types: <tt>SELECT typname, oid FROM
--   pg_type</tt> Note that I have assumed, but not tested, that type OIDs
--   for these basic types are consistent across installations. If not, I'm
--   going to have to switch to using the text descriptions
pgTypeFromOID :: Int -> PGType

-- | Convert a string from PostgreSQL of the given type into an appropriate
--   Haskell value. Or, more accurately, given a PostgreSQL type, create a
--   function for converting a string of that type into a compatible
--   Haskell value. <tt>pgStringToType :: PGType -&gt; (String -&gt;
--   ?)</tt>
pgStringToType :: PGType -> Q Exp

-- | Convert a Haskell value to a string of the given PostgreSQL type. Or,
--   more accurately, given a PostgreSQL type, create a function for
--   converting compatible Haskell values into a string of that type.
--   <tt>pgTypeToString :: PGType -&gt; (? -&gt; String)</tt>
pgTypeToString :: PGType -> Q Exp
instance Eq PGType
instance Show PGType


-- | The Protocol module allows for direct, low-level communication with a
--   PostgreSQL server over TCP/IP. You probably don't want to use this
--   module directly.
module Database.TemplatePG.Protocol

-- | PGException is thrown upon encountering an <a>ErrorResponse</a> with
--   severity of ERROR, FATAL, or PANIC. It holds the SQLSTATE and message
--   of the error.
data PGException
PGException :: String -> String -> PGException

-- | Connect to a PostgreSQL server.
pgConnect :: HostName -> PortID -> String -> String -> String -> IO Handle

-- | Disconnect from a PostgreSQL server. Note that this currently doesn't
--   send a close message.
pgDisconnect :: Handle -> IO ()

-- | Describe a SQL statement/query. A statement description consists of 0
--   or more parameter descriptions (a PostgreSQL type) and zero or more
--   result field descriptions (for queries) (consist of the name of the
--   field, the type of the field, and a nullability indicator).
describeStatement :: Handle -> String -> IO ([PGType], [(String, PGType, Bool)])

-- | A simple query is one which requires sending only a single
--   <a>SimpleQuery</a> message to the PostgreSQL server. The query is sent
--   as a single string; you cannot bind parameters. Note that queries can
--   return 0 results (an empty list).
executeSimpleQuery :: String -> Handle -> IO ([[Maybe ByteString]])

-- | While not strictly necessary, this can make code a little bit clearer.
--   It executes a <a>SimpleQuery</a> but doesn't look for results.
executeSimpleStatement :: String -> Handle -> IO ()
instance Typeable PGException
instance Show PGException
instance Binary PGMessage
instance Exception PGException


-- | This module exposes the high-level Template Haskell interface for
--   querying and manipulating the PostgreSQL server.
--   
--   All SQL string arguments support expression interpolation. Just
--   enclose your expression in <tt>{}</tt> in the SQL string.
--   
--   Note that transactions are messy and untested. Attempt to use them at
--   your own risk.
module Database.TemplatePG.SQL

-- | <pre>
--   queryTuples :: String -&gt; (Handle -&gt; IO [(column1, column2, ...)])
--   </pre>
--   
--   Query a PostgreSQL server and return the results as a list of tuples.
--   
--   Example (where <tt>h</tt> is a handle from <a>pgConnect</a>):
--   
--   <pre>
--   $(queryTuples "SELECT usesysid, usename FROM pg_user") h
--   
--   =&gt; IO [(Maybe String, Maybe Integer)]
--   </pre>
queryTuples :: String -> Q Exp

-- | <pre>
--   queryTuple :: String -&gt; (Handle -&gt; IO (Maybe (column1, column2, ...)))
--   </pre>
--   
--   Convenience function to query a PostgreSQL server and return the first
--   result as a tuple. If the query produces no results, return
--   <a>Nothing</a>.
--   
--   Example (where <tt>h</tt> is a handle from <a>pgConnect</a>):
--   
--   <pre>
--   let sysid = 10::Integer;
--   
--   $(queryTuple "SELECT usesysid, usename FROM pg_user WHERE usesysid = {sysid}") h
--   
--   =&gt; IO (Maybe (Maybe String, Maybe Integer))
--   </pre>
queryTuple :: String -> Q Exp

-- | <pre>
--   execute :: String -&gt; (Handle -&gt; IO ())
--   </pre>
--   
--   Convenience function to execute a statement on the PostgreSQL server.
--   
--   Example (where <tt>h</tt> is a handle from <a>pgConnect</a>):
--   
--   <pre>
--   let rolename = "BOfH"
--   
--   $(execute "CREATE ROLE {rolename}") h
--   </pre>
execute :: String -> Q Exp

-- | Ignore duplicate key errors. This is also limited to the <a>IO</a>
--   Monad.
insertIgnore :: IO () -> IO ()

-- | Run a sequence of IO actions (presumably SQL statements) wrapped in a
--   transaction. Unfortunately you're restricted to using this in the
--   <a>IO</a> Monad for now due to the use of <a>onException</a>. I'm
--   debating adding a <tt>MonadPeelIO</tt> version.
withTransaction :: Handle -> IO a -> IO a

-- | Roll back a transaction.
rollback :: Handle -> IO ()

module Database.TemplatePG

-- | PGException is thrown upon encountering an <a>ErrorResponse</a> with
--   severity of ERROR, FATAL, or PANIC. It holds the SQLSTATE and message
--   of the error.
data PGException
PGException :: String -> String -> PGException

-- | Connect to a PostgreSQL server.
pgConnect :: HostName -> PortID -> String -> String -> String -> IO Handle

-- | Disconnect from a PostgreSQL server. Note that this currently doesn't
--   send a close message.
pgDisconnect :: Handle -> IO ()

-- | <pre>
--   queryTuples :: String -&gt; (Handle -&gt; IO [(column1, column2, ...)])
--   </pre>
--   
--   Query a PostgreSQL server and return the results as a list of tuples.
--   
--   Example (where <tt>h</tt> is a handle from <a>pgConnect</a>):
--   
--   <pre>
--   $(queryTuples "SELECT usesysid, usename FROM pg_user") h
--   
--   =&gt; IO [(Maybe String, Maybe Integer)]
--   </pre>
queryTuples :: String -> Q Exp

-- | <pre>
--   queryTuple :: String -&gt; (Handle -&gt; IO (Maybe (column1, column2, ...)))
--   </pre>
--   
--   Convenience function to query a PostgreSQL server and return the first
--   result as a tuple. If the query produces no results, return
--   <a>Nothing</a>.
--   
--   Example (where <tt>h</tt> is a handle from <a>pgConnect</a>):
--   
--   <pre>
--   let sysid = 10::Integer;
--   
--   $(queryTuple "SELECT usesysid, usename FROM pg_user WHERE usesysid = {sysid}") h
--   
--   =&gt; IO (Maybe (Maybe String, Maybe Integer))
--   </pre>
queryTuple :: String -> Q Exp

-- | <pre>
--   execute :: String -&gt; (Handle -&gt; IO ())
--   </pre>
--   
--   Convenience function to execute a statement on the PostgreSQL server.
--   
--   Example (where <tt>h</tt> is a handle from <a>pgConnect</a>):
--   
--   <pre>
--   let rolename = "BOfH"
--   
--   $(execute "CREATE ROLE {rolename}") h
--   </pre>
execute :: String -> Q Exp

-- | Run a sequence of IO actions (presumably SQL statements) wrapped in a
--   transaction. Unfortunately you're restricted to using this in the
--   <a>IO</a> Monad for now due to the use of <a>onException</a>. I'm
--   debating adding a <tt>MonadPeelIO</tt> version.
withTransaction :: Handle -> IO a -> IO a

-- | Roll back a transaction.
rollback :: Handle -> IO ()

-- | Ignore duplicate key errors. This is also limited to the <a>IO</a>
--   Monad.
insertIgnore :: IO () -> IO ()