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


-- | A PostgreSQL access library with compile-time SQL type inference
--   
--   Automatically type-check SQL statements at compile time. Uses Template
--   Haskell and the raw PostgreSQL protocol to describe SQL statements at
--   compile time and provide appropriate type marshalling for both
--   parameters and results. Allows not only syntax verification of your
--   SQL but also full type safety between your SQL and Haskell. Supports
--   many built-in PostgreSQL types already, including arrays and ranges,
--   and can be easily extended in user code to support any other types.
--   Originally based on Chris Forno's templatepg library.
@package postgresql-typed
@version 0.3.0


-- | Representaion of PostgreSQL's range type. There are a number of
--   existing range data types, but PostgreSQL's is rather particular. This
--   tries to provide a one-to-one mapping.
module Database.PostgreSQL.Typed.Range
data Bound a
Unbounded :: Bound a
Bounded :: Bool -> a -> Bound a
newtype LowerBound a
Lower :: (Bound a) -> LowerBound a
newtype UpperBound a
Upper :: (Bound a) -> UpperBound a
data Range a
Empty :: Range a
Range :: (LowerBound a) -> (UpperBound a) -> Range a
bound :: Bound a -> Maybe a
boundClosed :: Bound a -> Bool
makeBound :: Bool -> Maybe a -> Bound a
lowerClosed :: Range a -> Bool
upperClosed :: Range a -> Bool
isEmpty :: Ord a => Range a -> Bool
full :: Range a
isFull :: Range a -> Bool
point :: Eq a => a -> Range a
getPoint :: Eq a => Range a -> Maybe a
range :: Ord a => Bound a -> Bound a -> Range a
normal :: Ord a => Maybe a -> Maybe a -> Range a
bounded :: Ord a => a -> a -> Range a
normalize :: Ord a => Range a -> Range a

-- | <a>normalize</a> for discrete (non-continuous) range types, using the
--   <a>Enum</a> instance
normalize' :: (Ord a, Enum a) => Range a -> Range a
(@>) :: Ord a => Range a -> Range a -> Bool
(<@) :: Ord a => Range a -> Range a -> Bool
(@>.) :: Ord a => Range a -> a -> Bool
intersect :: Ord a => Range a -> Range a -> Range a
instance Eq a => Eq (Bound a)
instance Eq a => Eq (LowerBound a)
instance Eq a => Eq (UpperBound a)
instance Eq a => Eq (Range a)
instance Show a => Show (Range a)
instance Functor Range
instance Ord a => Ord (UpperBound a)
instance Functor UpperBound
instance Ord a => Ord (LowerBound a)
instance Functor LowerBound
instance Functor Bound


-- | Classes to support type inference, value encoding/decoding, and
--   instances to support built-in PostgreSQL types.
module Database.PostgreSQL.Typed.Types
type OID = Word32

-- | A value passed to or from PostgreSQL in raw format.
data PGValue
PGNullValue :: PGValue

-- | The standard text encoding format (also used for unknown formats)
PGTextValue :: PGTextValue -> PGValue

-- | Special binary-encoded data. Not supported in all cases.
PGBinaryValue :: PGBinaryValue -> PGValue

-- | A list of (nullable) data values, e.g. a single row or query
--   parameters.
type PGValues = [PGValue]

-- | Produce a SQL string literal by wrapping (and escaping) a string with
--   single quotes.
pgQuote :: String -> String

-- | A proxy type for PostgreSQL types. The type argument should be an
--   (internal) name of a database type (see <tt>\dT+</tt>).
data PGTypeName (t :: Symbol)
PGTypeProxy :: PGTypeName

-- | Parameters that affect how marshalling happens. Currenly we force all
--   other relevant parameters at connect time.
data PGTypeEnv
PGTypeEnv :: Bool -> PGTypeEnv

-- | If <tt>integer_datetimes</tt> is <tt>on</tt>; only relevant for binary
--   encoding.
pgIntegerDatetimes :: PGTypeEnv -> Bool

-- | A <tt>PGParameter t a</tt> instance describes how to encode a
--   PostgreSQL type <tt>t</tt> from <tt>a</tt>.
class KnownSymbol t => PGParameter (t :: Symbol) a where pgLiteral t = pgQuote . toString . pgEncode t
pgEncode :: PGParameter t a => PGTypeName t -> a -> PGTextValue
pgLiteral :: PGParameter t a => PGTypeName t -> a -> String
class (PGParameter t a, PGBinaryType t) => PGBinaryParameter t a

-- | A <tt>PGColumn t a</tt> instance describes how te decode a PostgreSQL
--   type <tt>t</tt> to <tt>a</tt>.
class KnownSymbol t => PGColumn (t :: Symbol) a
pgDecode :: PGColumn t a => PGTypeName t -> PGTextValue -> a
class KnownSymbol t => PGBinaryType t

-- | Final parameter encoding function used when a (nullable) parameter is
--   passed to a prepared query.
pgEncodeParameter :: PGParameterNull t a => PGTypeEnv -> PGTypeName t -> a -> PGValue

-- | Final parameter encoding function used when a (nullable) parameter is
--   passed to a prepared query accepting binary-encoded data.
pgEncodeBinaryParameter :: PGBinaryParameterNull t a => PGTypeEnv -> PGTypeName t -> a -> PGValue

-- | Final parameter escaping function used when a (nullable) parameter is
--   passed to be substituted into a simple query.
pgEscapeParameter :: PGParameterNull t a => PGTypeEnv -> PGTypeName t -> a -> String

-- | Final column decoding function used for a nullable result value.
pgDecodeColumn :: PGColumnNotNull t (Maybe a) => PGTypeEnv -> PGTypeName t -> PGValue -> Maybe a

-- | Final column decoding function used for a non-nullable result value.
pgDecodeColumnNotNull :: PGColumnNotNull t a => PGTypeEnv -> PGTypeName t -> PGValue -> a

-- | Final column decoding function used for a nullable binary-encoded
--   result value.
pgDecodeBinaryColumn :: PGBinaryColumn t a => PGTypeEnv -> PGTypeName t -> PGValue -> Maybe a

-- | Final column decoding function used for a non-nullable binary-encoded
--   result value.
pgDecodeBinaryColumnNotNull :: (PGColumnNotNull t a, PGBinaryColumn t a) => PGTypeEnv -> PGTypeName t -> PGValue -> a

-- | Class indicating that the first PostgreSQL type is an array of the
--   second. This implies <a>PGParameter</a> and <a>PGColumn</a> instances
--   that will work for any type using comma as a delimiter (i.e., anything
--   but <tt>box</tt>). This will only work with 1-dimensional arrays.
class (KnownSymbol ta, KnownSymbol t) => PGArrayType ta t | ta -> t, t -> ta where pgArrayElementType PGTypeProxy = PGTypeProxy pgArrayDelim _ = ','

-- | Class indicating that the first PostgreSQL type is a range of the
--   second. This implies <a>PGParameter</a> and <a>PGColumn</a> instances
--   that will work for any type.
class (KnownSymbol tr, KnownSymbol t) => PGRangeType tr t | tr -> t where pgRangeElementType PGTypeProxy = PGTypeProxy
instance [overlap ok] Show PGValue
instance [overlap ok] Eq PGValue
instance [overlap ok] PGBinaryColumn "uuid" UUID
instance [overlap ok] PGBinaryParameter "uuid" UUID
instance [overlap ok] PGBinaryType "uuid"
instance [overlap ok] PGBinaryColumn "boolean" Bool
instance [overlap ok] PGBinaryParameter "boolean" Bool
instance [overlap ok] PGBinaryType "boolean"
instance [overlap ok] PGBinaryColumn "interval" DiffTime
instance [overlap ok] PGBinaryParameter "interval" DiffTime
instance [overlap ok] PGBinaryType "interval"
instance [overlap ok] PGBinaryColumn "timestamp with time zone" UTCTime
instance [overlap ok] PGBinaryParameter "timestamp with time zone" UTCTime
instance [overlap ok] PGBinaryType "timestamp with time zone"
instance [overlap ok] PGBinaryColumn "timestamp without time zone" LocalTime
instance [overlap ok] PGBinaryParameter "timestamp without time zone" LocalTime
instance [overlap ok] PGBinaryType "timestamp without time zone"
instance [overlap ok] PGBinaryColumn "time without time zone" TimeOfDay
instance [overlap ok] PGBinaryParameter "time without time zone" TimeOfDay
instance [overlap ok] PGBinaryType "time without time zone"
instance [overlap ok] PGBinaryColumn "date" Day
instance [overlap ok] PGBinaryParameter "date" Day
instance [overlap ok] PGBinaryType "date"
instance [overlap ok] PGBinaryColumn "bytea" ByteString
instance [overlap ok] PGBinaryParameter "bytea" ByteString
instance [overlap ok] PGBinaryColumn "bytea" ByteString
instance [overlap ok] PGBinaryParameter "bytea" ByteString
instance [overlap ok] PGBinaryType "bytea"
instance [overlap ok] (PGStringType t, PGBinaryType t) => PGBinaryColumn t String
instance [overlap ok] (PGStringType t, PGBinaryType t) => PGBinaryParameter t String
instance [overlap ok] (PGStringType t, PGBinaryType t) => PGBinaryColumn t ByteString
instance [overlap ok] (PGStringType t, PGBinaryType t) => PGBinaryParameter t ByteString
instance [overlap ok] (PGStringType t, PGBinaryType t) => PGBinaryColumn t ByteString
instance [overlap ok] (PGStringType t, PGBinaryType t) => PGBinaryParameter t ByteString
instance [overlap ok] (PGStringType t, PGBinaryType t) => PGBinaryColumn t Text
instance [overlap ok] (PGStringType t, PGBinaryType t) => PGBinaryParameter t Text
instance [overlap ok] (PGStringType t, PGBinaryType t) => PGBinaryColumn t Text
instance [overlap ok] (PGStringType t, PGBinaryType t) => PGBinaryParameter t Text
instance [overlap ok] PGBinaryType "name"
instance [overlap ok] PGBinaryType "bpchar"
instance [overlap ok] PGBinaryType "character varying"
instance [overlap ok] PGBinaryType "text"
instance [overlap ok] PGBinaryColumn "\"char\"" Char
instance [overlap ok] PGBinaryParameter "\"char\"" Char
instance [overlap ok] PGBinaryType "\"char\""
instance [overlap ok] PGBinaryColumn "numeric" Rational
instance [overlap ok] PGBinaryParameter "numeric" Rational
instance [overlap ok] PGBinaryColumn "numeric" Scientific
instance [overlap ok] PGBinaryParameter "numeric" Scientific
instance [overlap ok] PGBinaryType "numeric"
instance [overlap ok] PGBinaryColumn "double precision" Double
instance [overlap ok] PGBinaryParameter "double precision" Double
instance [overlap ok] PGBinaryType "double precision"
instance [overlap ok] PGBinaryColumn "real" Float
instance [overlap ok] PGBinaryParameter "real" Float
instance [overlap ok] PGBinaryType "real"
instance [overlap ok] PGBinaryColumn "bigint" Int64
instance [overlap ok] PGBinaryParameter "bigint" Int64
instance [overlap ok] PGBinaryType "bigint"
instance [overlap ok] PGBinaryColumn "integer" Int32
instance [overlap ok] PGBinaryParameter "integer" Int32
instance [overlap ok] PGBinaryType "integer"
instance [overlap ok] PGBinaryColumn "smallint" Int16
instance [overlap ok] PGBinaryParameter "smallint" Int16
instance [overlap ok] PGBinaryType "smallint"
instance [overlap ok] PGBinaryColumn "oid" OID
instance [overlap ok] PGBinaryParameter "oid" OID
instance [overlap ok] PGBinaryType "oid"
instance [overlap ok] PGColumn "uuid" UUID
instance [overlap ok] PGParameter "uuid" UUID
instance [overlap ok] PGRangeType "int8range" "bigint"
instance [overlap ok] PGRangeType "daterange" "date"
instance [overlap ok] PGRangeType "tstzrange" "timestamp with time zone"
instance [overlap ok] PGRangeType "tsrange" "timestamp without time zone"
instance [overlap ok] PGRangeType "numrange" "numeric"
instance [overlap ok] PGRangeType "int4range" "integer"
instance [overlap ok] (PGRangeType tr t, PGColumn t a) => PGColumn tr (Range a)
instance [overlap ok] (PGRangeType tr t, PGParameter t a) => PGParameter tr (Range a)
instance [overlap ok] PGArrayType "int8range[]" "int8range"
instance [overlap ok] PGArrayType "daterange[]" "daterange"
instance [overlap ok] PGArrayType "tstzrange[]" "tstzrange"
instance [overlap ok] PGArrayType "tsrange[]" "tsrange"
instance [overlap ok] PGArrayType "numrange[]" "numrange"
instance [overlap ok] PGArrayType "int4range[]" "int4range"
instance [overlap ok] PGArrayType "regdictionary[]" "regdictionary"
instance [overlap ok] PGArrayType "regconfig[]" "regconfig"
instance [overlap ok] PGArrayType "gtsvector[]" "gtsvector"
instance [overlap ok] PGArrayType "tsquery[]" "tsquery"
instance [overlap ok] PGArrayType "tsvector[]" "tsvector"
instance [overlap ok] PGArrayType "txid_snapshot[]" "txid_snapshot"
instance [overlap ok] PGArrayType "uuid[]" "uuid"
instance [overlap ok] PGArrayType "cstring[]" "cstring"
instance [overlap ok] PGArrayType "record[]" "record"
instance [overlap ok] PGArrayType "regtype[]" "regtype"
instance [overlap ok] PGArrayType "regclass[]" "regclass"
instance [overlap ok] PGArrayType "regoperator[]" "regoperator"
instance [overlap ok] PGArrayType "regoper[]" "regoper"
instance [overlap ok] PGArrayType "regprocedure[]" "regprocedure"
instance [overlap ok] PGArrayType "refcursor[]" "refcursor"
instance [overlap ok] PGArrayType "numeric[]" "numeric"
instance [overlap ok] PGArrayType "varbit[]" "varbit"
instance [overlap ok] PGArrayType "bit[]" "bit"
instance [overlap ok] PGArrayType "time with time zone[]" "time with time zone"
instance [overlap ok] PGArrayType "interval[]" "interval"
instance [overlap ok] PGArrayType "timestamp with time zone[]" "timestamp with time zone"
instance [overlap ok] PGArrayType "timestamp without time zone[]" "timestamp without time zone"
instance [overlap ok] PGArrayType "time without time zone[]" "time without time zone"
instance [overlap ok] PGArrayType "date[]" "date"
instance [overlap ok] PGArrayType "character varying[]" "character varying"
instance [overlap ok] PGArrayType "bpchar[]" "bpchar"
instance [overlap ok] PGArrayType "aclitem[]" "aclitem"
instance [overlap ok] PGArrayType "inet[]" "inet"
instance [overlap ok] PGArrayType "macaddr[]" "macaddr"
instance [overlap ok] PGArrayType "money[]" "money"
instance [overlap ok] PGArrayType "circle[]" "circle"
instance [overlap ok] PGArrayType "tinterval[]" "tinterval"
instance [overlap ok] PGArrayType "reltime[]" "reltime"
instance [overlap ok] PGArrayType "abstime[]" "abstime"
instance [overlap ok] PGArrayType "double precision[]" "double precision"
instance [overlap ok] PGArrayType "real[]" "real"
instance [overlap ok] PGArrayType "cidr[]" "cidr"
instance [overlap ok] PGArrayType "line[]" "line"
instance [overlap ok] PGArrayType "polygon[]" "polygon"
instance [overlap ok] PGArrayType "box[]" "box"
instance [overlap ok] PGArrayType "path[]" "path"
instance [overlap ok] PGArrayType "lseg[]" "lseg"
instance [overlap ok] PGArrayType "point[]" "point"
instance [overlap ok] PGArrayType "xml[]" "xml"
instance [overlap ok] PGArrayType "json[]" "json"
instance [overlap ok] PGArrayType "oidvector[]" "oidvector"
instance [overlap ok] PGArrayType "cid[]" "cid"
instance [overlap ok] PGArrayType "xid[]" "xid"
instance [overlap ok] PGArrayType "tid[]" "tid"
instance [overlap ok] PGArrayType "oid[]" "oid"
instance [overlap ok] PGArrayType "text[]" "text"
instance [overlap ok] PGArrayType "regproc[]" "regproc"
instance [overlap ok] PGArrayType "integer[]" "integer"
instance [overlap ok] PGArrayType "int2vector[]" "int2vector"
instance [overlap ok] PGArrayType "smallint[]" "smallint"
instance [overlap ok] PGArrayType "bigint[]" "bigint"
instance [overlap ok] PGArrayType "name[]" "name"
instance [overlap ok] PGArrayType "\"char\"[]" "\"char\""
instance [overlap ok] PGArrayType "bytea[]" "bytea"
instance [overlap ok] PGArrayType "boolean[]" "boolean"
instance [overlap ok] (PGArrayType ta t, PGColumn t a) => PGColumn ta (PGArray a)
instance [overlap ok] (PGArrayType ta t, PGParameter t a) => PGParameter ta (PGArray a)
instance [overlap ok] PGLiteralType "numeric" Scientific
instance [overlap ok] PGColumn "numeric" Rational
instance [overlap ok] PGParameter "numeric" Rational
instance [overlap ok] PGColumn "interval" DiffTime
instance [overlap ok] PGParameter "interval" DiffTime
instance [overlap ok] PGColumn "timestamp with time zone" UTCTime
instance [overlap ok] PGParameter "timestamp with time zone" UTCTime
instance [overlap ok] PGColumn "timestamp without time zone" LocalTime
instance [overlap ok] PGParameter "timestamp without time zone" LocalTime
instance [overlap ok] PGColumn "time without time zone" TimeOfDay
instance [overlap ok] PGParameter "time without time zone" TimeOfDay
instance [overlap ok] PGColumn "date" Day
instance [overlap ok] PGParameter "date" Day
instance [overlap ok] PGColumn "bytea" ByteString
instance [overlap ok] PGParameter "bytea" ByteString
instance [overlap ok] PGColumn "bytea" ByteString
instance [overlap ok] PGParameter "bytea" ByteString
instance [overlap ok] PGStringType "bpchar"
instance [overlap ok] PGStringType "name"
instance [overlap ok] PGStringType "character varying"
instance [overlap ok] PGStringType "text"
instance [overlap ok] PGStringType t => PGColumn t Text
instance [overlap ok] PGStringType t => PGParameter t Text
instance [overlap ok] PGStringType t => PGColumn t Text
instance [overlap ok] PGStringType t => PGParameter t Text
instance [overlap ok] PGStringType t => PGColumn t ByteString
instance [overlap ok] PGStringType t => PGParameter t ByteString
instance [overlap ok] PGStringType t => PGColumn t ByteString
instance [overlap ok] PGStringType t => PGParameter t ByteString
instance [overlap ok] PGStringType t => PGColumn t String
instance [overlap ok] PGStringType t => PGParameter t String
instance [overlap ok] PGColumn "\"char\"" Char
instance [overlap ok] PGParameter "\"char\"" Char
instance [overlap ok] PGLiteralType "double precision" Double
instance [overlap ok] PGLiteralType "real" Float
instance [overlap ok] PGLiteralType "bigint" Int64
instance [overlap ok] PGLiteralType "integer" Int32
instance [overlap ok] PGLiteralType "smallint" Int16
instance [overlap ok] PGLiteralType "oid" OID
instance [overlap ok] PGColumn "boolean" Bool
instance [overlap ok] PGParameter "boolean" Bool
instance [overlap ok] PGLiteralType t a => PGColumn t a
instance [overlap ok] PGLiteralType t a => PGParameter t a
instance [overlap ok] PGColumn t a => PGColumnNotNull t (Maybe a)
instance [overlap ok] PGColumn t a => PGColumnNotNull t a
instance [overlap ok] PGBinaryParameter t a => PGBinaryParameterNull t (Maybe a)
instance [overlap ok] PGBinaryParameter t a => PGBinaryParameterNull t a
instance [overlap ok] PGParameter t a => PGParameterNull t (Maybe a)
instance [overlap ok] PGParameter t a => PGParameterNull t a


-- | 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.PostgreSQL.Typed.Protocol

-- | Information for how to connect to a database, to be passed to
--   <a>pgConnect</a>.
data PGDatabase
PGDatabase :: HostName -> PortID -> String -> String -> String -> Bool -> (MessageFields -> IO ()) -> PGDatabase

-- | The hostname (ignored if <a>pgDBPort</a> is <a>UnixSocket</a>)
pgDBHost :: PGDatabase -> HostName

-- | The port, likely either <tt>PortNumber 5432</tt> or <tt>UnixSocket
--   "<i>tmp</i>.s.PGSQL.5432"</tt>
pgDBPort :: PGDatabase -> PortID

-- | The name of the database
pgDBName :: PGDatabase -> String
pgDBUser :: PGDatabase -> String
pgDBPass :: PGDatabase -> String

-- | Log all low-level server messages
pgDBDebug :: PGDatabase -> Bool

-- | How to log server notice messages (e.g., <tt>print . PGError</tt>)
pgDBLogMessage :: PGDatabase -> MessageFields -> IO ()

-- | A database connection with sane defaults: localhost:5432:postgres
defaultPGDatabase :: PGDatabase

-- | An established connection to the PostgreSQL server. These objects are
--   not thread-safe and must only be used for a single request at a time.
data PGConnection

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

-- | Message SQLState code. See
--   <a>http://www.postgresql.org/docs/current/static/errcodes-appendix.html</a>.
pgMessageCode :: MessageFields -> String
pgTypeEnv :: PGConnection -> PGTypeEnv

-- | Connect to a PostgreSQL server.
pgConnect :: PGDatabase -> IO PGConnection

-- | Disconnect cleanly from the PostgreSQL server.
pgDisconnect :: PGConnection -> IO ()

-- | Possibly re-open a connection to a different database, either reusing
--   the connection if the given database is already connected or closing
--   it and opening a new one. Regardless, the input connection must not be
--   used afterwards.
pgReconnect :: PGConnection -> PGDatabase -> IO PGConnection

-- | 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).
pgDescribe :: PGConnection -> String -> [OID] -> Bool -> IO ([OID], [(String, OID, 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).
pgSimpleQuery :: PGConnection -> String -> IO (Int, Seq PGValues)

-- | Prepare a statement, bind it, and execute it. If the given statement
--   has already been prepared (and not yet closed) on this connection, it
--   will be re-used.
pgPreparedQuery :: PGConnection -> String -> [OID] -> PGValues -> [Bool] -> IO (Int, Seq PGValues)

-- | Like <a>pgPreparedQuery</a> but requests results lazily in chunks of
--   the given size. Does not use a named portal, so other requests may not
--   intervene.
pgPreparedLazyQuery :: PGConnection -> String -> [OID] -> PGValues -> [Bool] -> Word32 -> IO [PGValues]

-- | Close a previously prepared query (if necessary).
pgCloseStatement :: PGConnection -> String -> [OID] -> IO ()
instance Typeable PGError
instance Show PGState
instance Eq PGState
instance Show ColDescription
instance Show PGFrontendMessage
instance Show PGBackendMessage
instance Exception PGError
instance Show PGError
instance Eq PGDatabase


-- | Support functions for compile-time PostgreSQL connection and state
--   management. You can use these to build your own Template Haskell
--   functions using the PostgreSQL connection.
module Database.PostgreSQL.Typed.TH

-- | Generate a <a>PGDatabase</a> based on the environment variables:
--   <tt>TPG_HOST</tt> (localhost); <tt>TPG_SOCK</tt> or <tt>TPG_PORT</tt>
--   (5432); <tt>TPG_DB</tt> or user; <tt>TPG_USER</tt> or <tt>USER</tt>
--   (postgres); <tt>TPG_PASS</tt> ()
getTPGDatabase :: IO PGDatabase

-- | Run an action using the Template Haskell PostgreSQL connection.
withTPGConnection :: (PGConnection -> IO a) -> IO a

-- | Specify an alternative database to use during compilation. This lets
--   you override the default connection parameters that are based on TPG
--   environment variables. This should be called as a top-level
--   declaration and produces no code. It uses <a>pgReconnect</a> so is
--   safe to call multiple times with the same database.
useTPGDatabase :: PGDatabase -> DecsQ

-- | Force reloading of all types from the database. This may be needed if
--   you make structural changes to the database during compile-time.
reloadTPGTypes :: DecsQ
data TPGValueInfo
TPGValueInfo :: String -> !OID -> TPGType -> Bool -> Bool -> TPGValueInfo
tpgValueName :: TPGValueInfo -> String
tpgValueTypeOID :: TPGValueInfo -> !OID
tpgValueType :: TPGValueInfo -> TPGType
tpgValueBinary :: TPGValueInfo -> Bool
tpgValueNullable :: TPGValueInfo -> Bool

-- | A type-aware wrapper to <a>pgDescribe</a>
tpgDescribe :: String -> [String] -> Bool -> Q ([TPGValueInfo], [TPGValueInfo])

-- | TH expression to encode a <a>PGParameter</a> value to a <a>Maybe</a>
--   <a>ByteString</a>.
tpgTypeEncoder :: Bool -> TPGValueInfo -> Name -> Name -> Exp

-- | TH expression to decode a <a>Maybe</a> <a>ByteString</a> to a
--   (<a>Maybe</a>) <a>PGColumn</a> value.
tpgTypeDecoder :: TPGValueInfo -> Name -> Name -> Exp

module Database.PostgreSQL.Typed.Query
class PGQuery q a | q -> a
pgRunQuery :: PGQuery q a => PGConnection -> q -> IO (Int, Seq a)

-- | A simple one-shot query that simply substitutes literal
--   representations of parameters for placeholders.
type PGSimpleQuery = QueryParser SimpleQuery

-- | A prepared query that automatically is prepared in the database the
--   first time it is run and bound with new parameters each subsequent
--   time.
type PGPreparedQuery = QueryParser PreparedQuery

-- | Make a simple query directly from a query string, with no type
--   inference
rawPGSimpleQuery :: String -> PGSimpleQuery PGValues

-- | Make a prepared query directly from a query string and bind
--   parameters, with no type inference
rawPGPreparedQuery :: String -> PGValues -> PGPreparedQuery PGValues

-- | Flags affecting how and what type of query to build with
--   <tt>makeQuery</tt>.
data QueryFlags
QueryFlags :: Bool -> Maybe [String] -> QueryFlags

-- | Assume all results are nullable and don't try to guess.
flagNullable :: QueryFlags -> Bool

-- | Prepare and re-use query, binding parameters of the given types
--   (inferring the rest, like PREPARE).
flagPrepare :: QueryFlags -> Maybe [String]

-- | <a>QueryFlags</a> for a default (simple) query.
simpleFlags :: QueryFlags

-- | Construct a <a>PGQuery</a> from a SQL string.
makePGQuery :: QueryFlags -> String -> ExpQ

-- | A quasi-quoter for PGSQL queries.
--   
--   Used in expression context, it may contain any SQL statement
--   <tt>[pgSQL|SELECT ...|]</tt>. The statement may contain
--   PostgreSQL-style placeholders (<tt>$1</tt>, <tt>$2</tt>, ...) or
--   in-line placeholders (<tt>${1+1}</tt>) containing any valid Haskell
--   expression (except <tt>{}</tt>). It will be replaced by a
--   <a>PGQuery</a> object that can be used to perform the SQL statement.
--   If there are more <tt>$N</tt> placeholders than expressions, it will
--   instead be a function accepting the additional parameters and
--   returning a <a>PGQuery</a>. Note that all occurrences of <tt>$N</tt>
--   or <tt>${</tt> will be treated as placeholders, regardless of their
--   context in the SQL (e.g., even within SQL strings or other places
--   placeholders are disallowed by PostgreSQL), which may cause invalid
--   SQL or other errors. If you need to pass a literal <tt>$</tt> through
--   in these contexts, you may double it to escape it as <tt>$$N</tt> or
--   <tt>$${</tt>.
--   
--   The statement may start with one of more special flags affecting the
--   interpretation:
--   
--   <ul>
--   <li><i><tt>?</tt></i> To disable nullability inference, treating all
--   result values as nullable, thus returning <a>Maybe</a> values
--   regardless of inferred nullability.</li>
--   <li><i><tt>$</tt></i> To create a <a>PGPreparedQuery</a> rather than a
--   <a>PGSimpleQuery</a>, by default inferring parameter types.</li>
--   <li><i><tt>$(type,...)</tt></i> To specify specific types to a
--   prepared query (see
--   <a>http://www.postgresql.org/docs/current/static/sql-prepare.html</a>
--   for details).</li>
--   </ul>
--   
--   This can also be used at the top-level to execute SQL statements at
--   compile-time (without any parameters and ignoring results). Here the
--   query can only be prefixed with <tt>!</tt> to make errors non-fatal.
pgSQL :: QuasiQuoter

-- | Execute a query that does not return result. Return the number of rows
--   affected (or -1 if not known).
pgExecute :: PGQuery q () => PGConnection -> q -> IO Int

-- | Run a query and return a list of row results.
pgQuery :: PGQuery q a => PGConnection -> q -> IO [a]

-- | Run a prepared query in lazy mode, where only chunk size rows are
--   requested at a time. If you eventually retrieve all the rows this way,
--   it will be far less efficient than using <tt>pgQuery</tt>, since every
--   chunk requires an additional round-trip. Although you may safely stop
--   consuming rows early, currently you may not interleave any other
--   database operation while reading rows. (This limitation could
--   theoretically be lifted if required.)
pgLazyQuery :: PGConnection -> PGPreparedQuery a -> Word32 -> IO [a]
instance Functor (QueryParser q)
instance PGRawQuery q => PGQuery (QueryParser q a) a
instance PGRawQuery PreparedQuery
instance PGQuery PreparedQuery PGValues
instance PGRawQuery SimpleQuery
instance PGQuery SimpleQuery PGValues


-- | Support for PostgreSQL enums.
module Database.PostgreSQL.Typed.Enum

-- | Create a new enum type corresponding to the given PostgreSQL enum
--   type. For example, if you have <tt>CREATE TYPE foo AS ENUM ('abc',
--   'DEF');</tt>, then <tt>makePGEnum "foo" "Foo" ("Foo_"++)</tt> will be
--   equivalent to:
--   
--   <pre>
--   data Foo = Foo_abc | Foo_DEF deriving (Eq, Ord, Enum, Bounded)
--   instance PGType Foo where ...
--   registerPGType "foo" (ConT ''Foo)
--   </pre>
--   
--   Requires language extensions: TemplateHaskell, FlexibleInstances,
--   MultiParamTypeClasses, DataKinds
makePGEnum :: String -> String -> (String -> String) -> DecsQ


-- | 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.PostgreSQL.Typed.TemplatePG

-- | <pre>
--   queryTuples :: String -&gt; (PGConnection -&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 :: IO [(Maybe String, Maybe Integer)]
--   </pre>
queryTuples :: String -> ExpQ

-- | <pre>
--   queryTuple :: String -&gt; (PGConnection -&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>):
--   
--   @let sysid = 10::Integer;
--   
--   $(queryTuple "SELECT usesysid, usename FROM pg_user WHERE usesysid =
--   {sysid}") h :: IO (Maybe (Maybe String, Maybe Integer)) @
queryTuple :: String -> ExpQ

-- | <pre>
--   execute :: String -&gt; (PGConnection -&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>):
--   
--   @let rolename = "BOfH"
--   
--   $(execute "CREATE ROLE {rolename}") h @
execute :: String -> ExpQ

-- | 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 :: PGConnection -> IO a -> IO a

-- | Roll back a transaction.
rollback :: PGConnection -> IO ()
type PGException = PGError
pgConnect :: HostName -> PortID -> String -> String -> String -> IO PGConnection

-- | Disconnect cleanly from the PostgreSQL server.
pgDisconnect :: PGConnection -> IO ()

module Database.PostgreSQL.Typed

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

-- | Information for how to connect to a database, to be passed to
--   <a>pgConnect</a>.
data PGDatabase
PGDatabase :: HostName -> PortID -> String -> String -> String -> Bool -> (MessageFields -> IO ()) -> PGDatabase

-- | The hostname (ignored if <a>pgDBPort</a> is <a>UnixSocket</a>)
pgDBHost :: PGDatabase -> HostName

-- | The port, likely either <tt>PortNumber 5432</tt> or <tt>UnixSocket
--   "<i>tmp</i>.s.PGSQL.5432"</tt>
pgDBPort :: PGDatabase -> PortID

-- | The name of the database
pgDBName :: PGDatabase -> String
pgDBUser :: PGDatabase -> String
pgDBPass :: PGDatabase -> String

-- | Log all low-level server messages
pgDBDebug :: PGDatabase -> Bool

-- | How to log server notice messages (e.g., <tt>print . PGError</tt>)
pgDBLogMessage :: PGDatabase -> MessageFields -> IO ()

-- | A database connection with sane defaults: localhost:5432:postgres
defaultPGDatabase :: PGDatabase

-- | An established connection to the PostgreSQL server. These objects are
--   not thread-safe and must only be used for a single request at a time.
data PGConnection

-- | Connect to a PostgreSQL server.
pgConnect :: PGDatabase -> IO PGConnection

-- | Disconnect cleanly from the PostgreSQL server.
pgDisconnect :: PGConnection -> IO ()

-- | Specify an alternative database to use during compilation. This lets
--   you override the default connection parameters that are based on TPG
--   environment variables. This should be called as a top-level
--   declaration and produces no code. It uses <a>pgReconnect</a> so is
--   safe to call multiple times with the same database.
useTPGDatabase :: PGDatabase -> DecsQ

-- | A quasi-quoter for PGSQL queries.
--   
--   Used in expression context, it may contain any SQL statement
--   <tt>[pgSQL|SELECT ...|]</tt>. The statement may contain
--   PostgreSQL-style placeholders (<tt>$1</tt>, <tt>$2</tt>, ...) or
--   in-line placeholders (<tt>${1+1}</tt>) containing any valid Haskell
--   expression (except <tt>{}</tt>). It will be replaced by a
--   <a>PGQuery</a> object that can be used to perform the SQL statement.
--   If there are more <tt>$N</tt> placeholders than expressions, it will
--   instead be a function accepting the additional parameters and
--   returning a <a>PGQuery</a>. Note that all occurrences of <tt>$N</tt>
--   or <tt>${</tt> will be treated as placeholders, regardless of their
--   context in the SQL (e.g., even within SQL strings or other places
--   placeholders are disallowed by PostgreSQL), which may cause invalid
--   SQL or other errors. If you need to pass a literal <tt>$</tt> through
--   in these contexts, you may double it to escape it as <tt>$$N</tt> or
--   <tt>$${</tt>.
--   
--   The statement may start with one of more special flags affecting the
--   interpretation:
--   
--   <ul>
--   <li><i><tt>?</tt></i> To disable nullability inference, treating all
--   result values as nullable, thus returning <a>Maybe</a> values
--   regardless of inferred nullability.</li>
--   <li><i><tt>$</tt></i> To create a <a>PGPreparedQuery</a> rather than a
--   <a>PGSimpleQuery</a>, by default inferring parameter types.</li>
--   <li><i><tt>$(type,...)</tt></i> To specify specific types to a
--   prepared query (see
--   <a>http://www.postgresql.org/docs/current/static/sql-prepare.html</a>
--   for details).</li>
--   </ul>
--   
--   This can also be used at the top-level to execute SQL statements at
--   compile-time (without any parameters and ignoring results). Here the
--   query can only be prefixed with <tt>!</tt> to make errors non-fatal.
pgSQL :: QuasiQuoter

-- | Run a query and return a list of row results.
pgQuery :: PGQuery q a => PGConnection -> q -> IO [a]

-- | Execute a query that does not return result. Return the number of rows
--   affected (or -1 if not known).
pgExecute :: PGQuery q () => PGConnection -> q -> IO Int