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


-- | Mid-Level PostgreSQL client library
--   
--   Mid-Level PostgreSQL client library, forked from mysql-simple.
@package postgresql-simple
@version 0.2.4.1


module Database.PostgreSQL.Simple.Time.Internal
getDay :: Parser Day
getDate :: Parser Date
getTimeOfDay :: Parser TimeOfDay
getLocalTime :: Parser LocalTime
getLocalTimestamp :: Parser LocalTimestamp
getTimeZone :: Parser TimeZone
getZonedTime :: Parser ZonedTime
getZonedTimestamp :: Parser ZonedTimestamp
getUTCTime :: Parser UTCTime
getUTCTimestamp :: Parser UTCTimestamp


module Database.PostgreSQL.Simple.SqlQQ

-- | <a>sql</a> is a quasiquoter that eases the syntactic burden of writing
--   big sql statements in Haskell source code. For example:
--   
--   <pre>
--   {-# LANGUAGE QuasiQuotes #-}
--   
--   query conn [sql| SELECT column_a, column_b
--                      FROM table1 NATURAL JOIN table2
--                     WHERE ? &lt;= time AND time &lt; ?
--                       AND name LIKE ?
--                     ORDER BY size DESC
--                     LIMIT 100                        |]
--              (beginTime,endTime,string)
--   </pre>
--   
--   This quasiquoter attempts to mimimize whitespace; otherwise the above
--   query would consist of approximately half whitespace when sent to the
--   database backend.
--   
--   The implementation of the whitespace reducer is currently incomplete.
--   Thus it can mess up your syntax in cases where whitespace should be
--   preserved as-is. It does preserve whitespace inside standard SQL
--   string literals. But it can get confused by the non-standard
--   PostgreSQL string literal syntax (which is the default setting in
--   PostgreSQL 8 and below), the extended escape string syntax, and other
--   similar constructs.
--   
--   Of course, this caveat only applies to text written inside the SQL
--   quasiquoter; whitespace reduction is a compile-time computation and
--   thus will not touch the <tt>string</tt> parameter above, which is a
--   run-time value.
--   
--   Also note that this will not work if the substring <tt>|]</tt> is
--   contained in the query.
sql :: QuasiQuoter


-- | Time types that supports positive and negative infinity. Also includes
--   new time parsers and printers with better performance than GHC's time
--   package.
--   
--   The parsers only understand the specific variant of ISO 8601 that
--   PostgreSQL emits, and the printers attempt to duplicate this syntax.
--   Thus the <tt>datestyle</tt> parameter for the connection must be set
--   to <tt>ISO</tt>.
--   
--   These parsers and printers likely have problems and shortcomings. Some
--   that I know of:
--   
--   1 <tt>TimestampTZ</tt>s before a timezone-dependent point in time
--   cannot be parsed, because the parsers can only handle timezone offsets
--   of a integer number of minutes. However, PostgreSQL will include
--   seconds in the offset, depending on the historical time standards for
--   the city identifying the time zone.
--   
--   This boundary point often marks an event of some interest. In the US
--   for example, <tt>timestamptz</tt>s before <tt>1883-Nov-18
--   12:00:00</tt> local time cannot be parsed. This is the moment Standard
--   Railway Time went live. Concretely, PostgreSQL will emit
--   <tt>1883-11-18 12:03:57-04:56:02</tt> instead of <tt>1883-11-18
--   11:59:59-05</tt> when the <tt>timezone</tt> parameter for the
--   connection is set to <tt>America/New_York</tt>.
--   
--   <ol>
--   <li>Dates and times surrounding <tt>1582-Feb-24</tt>, the date the
--   Gregorian Calendar was introduced, should be investigated for
--   conversion errors.</li>
--   <li>Points in time Before Christ are not also not supported. For
--   example, PostgreSQL will emit <tt>0045-01-01 BC</tt> for a value of a
--   <tt>date</tt> type. This is the year that the Julian Calendar was
--   adopted.</li>
--   </ol>
--   
--   However, it should be noted that the old parsers also had issues 1 and
--   3. Also, the new parsers now correctly handle time zones that include
--   minutes in their offset. Most notably, this includes all of India and
--   parts of Canada and Australia.
--   
--   PostgreSQL uses the zoneinfo database for its time zone information.
--   You can read more about PostgreSQL's date and time types at
--   <a>http://www.postgresql.org/docs/9.1/static/datatype-datetime.html</a>,
--   and zoneinfo at <a>http://en.wikipedia.org/wiki/Tz_database</a>.
module Database.PostgreSQL.Simple.Time
data Unbounded a
NegInfinity :: Unbounded a
Finite :: !a -> Unbounded a
PosInfinity :: Unbounded a
type Date = Unbounded Day
type UTCTimestamp = Unbounded UTCTime
type ZonedTimestamp = Unbounded ZonedTime
type LocalTimestamp = Unbounded LocalTime
parseDay :: ByteString -> Either String Day
parseUTCTime :: ByteString -> Either String UTCTime
parseZonedTime :: ByteString -> Either String ZonedTime
parseLocalTime :: ByteString -> Either String LocalTime
parseTimeOfDay :: ByteString -> Either String TimeOfDay
parseDate :: ByteString -> Either String Date
parseUTCTimestamp :: ByteString -> Either String UTCTimestamp
parseZonedTimestamp :: ByteString -> Either String ZonedTimestamp
parseLocalTimestamp :: ByteString -> Either String LocalTimestamp
dayToBuilder :: Day -> Builder
utcTimeToBuilder :: UTCTime -> Builder
zonedTimeToBuilder :: ZonedTime -> Builder
localTimeToBuilder :: LocalTime -> Builder
timeOfDayToBuilder :: TimeOfDay -> Builder
timeZoneToBuilder :: TimeZone -> Builder
dateToBuilder :: Date -> Builder
utcTimestampToBuilder :: UTCTimestamp -> Builder
zonedTimestampToBuilder :: ZonedTimestamp -> Builder
localTimestampToBuilder :: LocalTimestamp -> Builder
unboundedToBuilder :: (a -> Builder) -> (Unbounded a -> Builder)


-- | Basic types.
module Database.PostgreSQL.Simple.Types

-- | A placeholder for the SQL <tt>NULL</tt> value.
data Null
Null :: Null

-- | A single-value "collection".
--   
--   This is useful if you need to supply a single parameter to a SQL
--   query, or extract a single column from a SQL result.
--   
--   Parameter example:
--   
--   <pre>
--   query c "select x from scores where x &gt; ?" (<a>Only</a> (42::Int))
--   </pre>
--   
--   Result example:
--   
--   <pre>
--   xs &lt;- query_ c "select id from users"
--   forM_ xs $ \(<a>Only</a> id) -&gt; {- ... -}
--   </pre>
newtype Only a
Only :: a -> Only a
fromOnly :: Only a -> a

-- | Wrap a list of values for use in an <tt>IN</tt> clause. Replaces a
--   single "<tt>?</tt>" character with a parenthesized list of rendered
--   values.
--   
--   Example:
--   
--   <pre>
--   query c "select * from whatever where id in ?" (Only (In [3,4,5]))
--   </pre>
newtype In a
In :: a -> In a

-- | Wrap binary data for use as a <tt>bytea</tt> value.
newtype Binary a
Binary :: a -> Binary a

-- | A query string. This type is intended to make it difficult to
--   construct a SQL query by concatenating string fragments, as that is an
--   extremely common way to accidentally introduce SQL injection
--   vulnerabilities into an application.
--   
--   This type is an instance of <a>IsString</a>, so the easiest way to
--   construct a query is to enable the <tt>OverloadedStrings</tt> language
--   extension and then simply write the query in double quotes.
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   import Database.PostgreSQL.Simple
--   
--   q :: Query
--   q = "select ?"
--   </pre>
--   
--   The underlying type is a <a>ByteString</a>, and literal Haskell
--   strings that contain Unicode characters will be correctly transformed
--   to UTF-8.
newtype Query
Query :: ByteString -> Query
fromQuery :: Query -> ByteString
newtype Oid :: *
Oid :: CUInt -> Oid

-- | A composite type to parse your custom data structures without having
--   to define dummy newtype wrappers every time.
--   
--   <pre>
--   instance FromRow MyData where ...
--   </pre>
--   
--   <pre>
--   instance FromRow MyData2 where ...
--   </pre>
--   
--   then I can do the following for free:
--   
--   <pre>
--   res &lt;- query' c <a>...</a>
--   forM res $ \(MyData{..} :. MyData2{..}) -&gt; do
--     ....
--   </pre>
data (:.) h t
(:.) :: h -> t -> :. h t
instance Typeable Null
instance Typeable Query
instance Typeable1 Only
instance Typeable1 In
instance Typeable1 Binary
instance Typeable2 :.
instance Read Null
instance Show Null
instance Eq Query
instance Ord Query
instance Eq a => Eq (Only a)
instance Ord a => Ord (Only a)
instance Read a => Read (Only a)
instance Show a => Show (Only a)
instance Functor Only
instance Eq a => Eq (In a)
instance Ord a => Ord (In a)
instance Read a => Read (In a)
instance Show a => Show (In a)
instance Functor In
instance Eq a => Eq (Binary a)
instance Ord a => Ord (Binary a)
instance Read a => Read (Binary a)
instance Show a => Show (Binary a)
instance Functor Binary
instance (Eq h, Eq t) => Eq (h :. t)
instance (Ord h, Ord t) => Ord (h :. t)
instance (Show h, Show t) => Show (h :. t)
instance (Read h, Read t) => Read (h :. t)
instance Monoid Query
instance IsString Query
instance Read Query
instance Show Query
instance Eq Null


-- | The <a>ToField</a> typeclass, for rendering a parameter to a SQL
--   query.
module Database.PostgreSQL.Simple.ToField

-- | How to render an element when substituting it into a query.
data Action

-- | Render without escaping or quoting. Use for non-text types such as
--   numbers, when you are <i>certain</i> that they will not introduce
--   formatting vulnerabilities via use of characters such as spaces or
--   "<tt>'</tt>".
Plain :: Builder -> Action

-- | Escape and enclose in quotes before substituting. Use for all
--   text-like types, and anything else that may contain unsafe characters
--   when rendered.
Escape :: ByteString -> Action

-- | Escape binary data for use as a <tt>bytea</tt> literal. Include
--   surrounding quotes. This is used by the <a>Binary</a> newtype wrapper.
EscapeByteA :: ByteString -> Action

-- | Concatenate a series of rendering actions.
Many :: [Action] -> Action

-- | A type that may be used as a single parameter to a SQL query.
class ToField a
toField :: ToField a => a -> Action

-- | Surround a string with single-quote characters: "<tt>'</tt>"
--   
--   This function <i>does not</i> perform any other escaping.
inQuotes :: Builder -> Builder
instance Typeable Action
instance ToField Date
instance ToField LocalTimestamp
instance ToField ZonedTimestamp
instance ToField UTCTimestamp
instance ToField TimeOfDay
instance ToField Day
instance ToField LocalTime
instance ToField ZonedTime
instance ToField UTCTime
instance ToField Text
instance ToField [Char]
instance ToField Text
instance ToField ByteString
instance ToField ByteString
instance ToField (Binary ByteString)
instance ToField (Binary ByteString)
instance ToField Double
instance ToField Float
instance ToField Oid
instance ToField Word64
instance ToField Word
instance ToField Word32
instance ToField Word16
instance ToField Word8
instance ToField Integer
instance ToField Int64
instance ToField Int
instance ToField Int32
instance ToField Int16
instance ToField Int8
instance ToField Bool
instance ToField Null
instance ToField a => ToField (In [a])
instance ToField a => ToField (Maybe a)
instance ToField Action
instance Show Action


-- | The <a>ToRow</a> typeclass, for rendering a collection of parameters
--   to a SQL query.
--   
--   Predefined instances are provided for tuples containing up to ten
--   elements.
module Database.PostgreSQL.Simple.ToRow

-- | A collection type that can be turned into a list of rendering
--   <a>Action</a>s.
--   
--   Instances should use the <tt>render</tt> method of the <tt>Param</tt>
--   class to perform conversion of each element of the collection.
class ToRow a
toRow :: ToRow a => a -> [Action]
instance (ToRow a, ToRow b) => ToRow (a :. b)
instance ToField a => ToRow [a]
instance (ToField a, ToField b, ToField c, ToField d, ToField e, ToField f, ToField g, ToField h, ToField i, ToField j) => ToRow (a, b, c, d, e, f, g, h, i, j)
instance (ToField a, ToField b, ToField c, ToField d, ToField e, ToField f, ToField g, ToField h, ToField i) => ToRow (a, b, c, d, e, f, g, h, i)
instance (ToField a, ToField b, ToField c, ToField d, ToField e, ToField f, ToField g, ToField h) => ToRow (a, b, c, d, e, f, g, h)
instance (ToField a, ToField b, ToField c, ToField d, ToField e, ToField f, ToField g) => ToRow (a, b, c, d, e, f, g)
instance (ToField a, ToField b, ToField c, ToField d, ToField e, ToField f) => ToRow (a, b, c, d, e, f)
instance (ToField a, ToField b, ToField c, ToField d, ToField e) => ToRow (a, b, c, d, e)
instance (ToField a, ToField b, ToField c, ToField d) => ToRow (a, b, c, d)
instance (ToField a, ToField b, ToField c) => ToRow (a, b, c)
instance (ToField a, ToField b) => ToRow (a, b)
instance ToField a => ToRow (Only a)
instance ToRow ()


-- | The <a>Ok</a> type is a simple error handler, basically equivalent to
--   <tt>Either [SomeException]</tt>. This type (without the list) was used
--   to handle conversion errors in early versions of postgresql-simple.
--   
--   One of the primary reasons why this type was introduced is that
--   <tt>Either SomeException</tt> had not been provided an instance for
--   <a>Alternative</a>, and it would have been a bad idea to provide an
--   orphaned instance for a commonly-used type and typeclass included in
--   <tt>base</tt>.
--   
--   Extending the failure case to a list of <a>SomeException</a>s enables
--   a more sensible <a>Alternative</a> instance definitions:
--   <a>&lt;|&gt;</a> concatinates the list of exceptions when both cases
--   fail, and <a>empty</a> is defined as 'Errors []'. Though
--   <a>&lt;|&gt;</a> one could pick one of two exceptions, and throw away
--   the other, and have <a>empty</a> provide a generic exception, this
--   avoids cases where <a>empty</a> overrides a more informative exception
--   and allows you to see all the different ways your computation has
--   failed.
module Database.PostgreSQL.Simple.Ok
data Ok a
Errors :: [SomeException] -> Ok a
Ok :: !a -> Ok a

-- | a way to reify a list of exceptions into a single exception
newtype ManyErrors
ManyErrors :: [SomeException] -> ManyErrors
instance Typeable1 Ok
instance Typeable ManyErrors
instance Show a => Show (Ok a)
instance Functor Ok
instance Show ManyErrors
instance Exception ManyErrors
instance Monad Ok
instance MonadPlus Ok
instance Alternative Ok
instance Applicative Ok
instance Eq a => Eq (Ok a)


module Database.PostgreSQL.Simple.BuiltinTypes
data BuiltinType
Bool :: BuiltinType
ByteA :: BuiltinType
Char :: BuiltinType
Name :: BuiltinType
Int8 :: BuiltinType
Int2 :: BuiltinType
Int4 :: BuiltinType
RegProc :: BuiltinType
Text :: BuiltinType
Oid :: BuiltinType
Tid :: BuiltinType
Xid :: BuiltinType
Cid :: BuiltinType
Xml :: BuiltinType
Point :: BuiltinType
LSeg :: BuiltinType
Path :: BuiltinType
Box :: BuiltinType
Polygon :: BuiltinType
Line :: BuiltinType
Cidr :: BuiltinType
Float4 :: BuiltinType
Float8 :: BuiltinType
AbsTime :: BuiltinType
RelTime :: BuiltinType
TInterval :: BuiltinType
Unknown :: BuiltinType
Circle :: BuiltinType
Money :: BuiltinType
MacAddr :: BuiltinType
Inet :: BuiltinType
BpChar :: BuiltinType
VarChar :: BuiltinType
Date :: BuiltinType
Time :: BuiltinType
Timestamp :: BuiltinType
TimestampTZ :: BuiltinType
Interval :: BuiltinType
TimeTZ :: BuiltinType
Bit :: BuiltinType
VarBit :: BuiltinType
Numeric :: BuiltinType
RefCursor :: BuiltinType
Record :: BuiltinType
Void :: BuiltinType
UUID :: BuiltinType
builtin2oid :: BuiltinType -> Oid
oid2builtin :: Oid -> Maybe BuiltinType
builtin2typname :: BuiltinType -> ByteString
oid2typname :: Oid -> Maybe ByteString
instance Typeable BuiltinType
instance Eq BuiltinType
instance Ord BuiltinType
instance Enum BuiltinType
instance Bounded BuiltinType
instance Read BuiltinType
instance Show BuiltinType


-- | Internal bits. This interface is less stable and can change at any
--   time. In particular this means that while the rest of the
--   postgresql-simple package endeavors to follow the package versioning
--   policy, this module does not. Also, at the moment there are things in
--   here that aren't particularly internal and are exported elsewhere;
--   these will eventually disappear from this module.
module Database.PostgreSQL.Simple.Internal

-- | A Field represents metadata about a particular field
--   
--   You don't particularly want to retain these structures for a long
--   period of time, as they will retain the entire query result, not just
--   the field metadata
data Field
Field :: !Result -> {-# UNPACK #-} !Column -> !ByteString -> Field
result :: Field -> !Result
column :: Field -> {-# UNPACK #-} !Column
typename :: Field -> !ByteString
name :: Field -> Maybe ByteString
tableOid :: Field -> Oid
tableColumn :: Field -> Int
format :: Field -> Format
typeOid :: Field -> Oid
data Connection
Connection :: {-# UNPACK #-} !(MVar Connection) -> {-# UNPACK #-} !(MVar (IntMap ByteString)) -> Connection
connectionHandle :: Connection -> {-# UNPACK #-} !(MVar Connection)
connectionObjects :: Connection -> {-# UNPACK #-} !(MVar (IntMap ByteString))
data SqlType
Builtin :: BuiltinType -> SqlType
Other :: Oid -> SqlType
data SqlError
SqlError :: ByteString -> Int -> ByteString -> SqlError
sqlState :: SqlError -> ByteString
sqlNativeError :: SqlError -> Int
sqlErrorMsg :: SqlError -> ByteString

-- | Exception thrown if <tt>query</tt> is used to perform an
--   <tt>INSERT</tt>-like operation, or <tt>execute</tt> is used to perform
--   a <tt>SELECT</tt>-like operation.
data QueryError
QueryError :: String -> Query -> QueryError
qeMessage :: QueryError -> String
qeQuery :: QueryError -> Query
data ConnectInfo
ConnectInfo :: String -> Word16 -> String -> String -> String -> ConnectInfo
connectHost :: ConnectInfo -> String
connectPort :: ConnectInfo -> Word16
connectUser :: ConnectInfo -> String
connectPassword :: ConnectInfo -> String
connectDatabase :: ConnectInfo -> String

-- | Default information for setting up a connection.
--   
--   Defaults are as follows:
--   
--   <ul>
--   <li>Server on <tt>localhost</tt></li>
--   <li>Port on <tt>5432</tt></li>
--   <li>User <tt>postgres</tt></li>
--   <li>No password</li>
--   <li>Database <tt>postgres</tt></li>
--   </ul>
--   
--   Use as in the following example:
--   
--   <pre>
--   connect defaultConnectInfo { connectHost = "db.example.com" }
--   </pre>
defaultConnectInfo :: ConnectInfo

-- | Connect with the given username to the given database. Will throw an
--   exception if it cannot connect.
connect :: ConnectInfo -> IO Connection

-- | Attempt to make a connection based on a libpq connection string. See
--   <a>http://www.postgresql.org/docs/9.1/static/libpq-connect.html</a>
--   for more information.
connectPostgreSQL :: ByteString -> IO Connection

-- | Turns a <a>ConnectInfo</a> data structure into a libpq connection
--   string.
postgreSQLConnectionString :: ConnectInfo -> ByteString
oid2int :: Oid -> Int
exec :: Connection -> ByteString -> IO Result

-- | A version of <tt>execute</tt> that does not perform query
--   substitution.
execute_ :: Connection -> Query -> IO Int64
finishExecute :: Connection -> Query -> Result -> IO Int64
throwResultError :: ByteString -> Result -> ExecStatus -> IO a
disconnectedError :: SqlError

-- | Atomically perform an action with the database handle, if there is
--   one.
withConnection :: Connection -> (Connection -> IO a) -> IO a
close :: Connection -> IO ()
newNullConnection :: IO Connection
data Row
Row :: {-# UNPACK #-} !Row -> !(Vector ByteString) -> !Result -> Row
row :: Row -> {-# UNPACK #-} !Row
typenames :: Row -> !(Vector ByteString)
rowresult :: Row -> !Result
newtype RowParser a
RP :: ReaderT Row (StateT Column Ok) a -> RowParser a
unRP :: RowParser a -> ReaderT Row (StateT Column Ok) a
getvalue :: Result -> Row -> Column -> Maybe ByteString
nfields :: Result -> Column
instance Typeable SqlError
instance Typeable QueryError
instance Typeable ConnectInfo
instance Show SqlError
instance Eq QueryError
instance Show QueryError
instance Eq ConnectInfo
instance Read ConnectInfo
instance Show ConnectInfo
instance Functor RowParser
instance Applicative RowParser
instance Alternative RowParser
instance Monad RowParser
instance Exception QueryError
instance Exception SqlError


-- | The <a>FromField</a> typeclass, for converting a single value in a row
--   returned by a SQL query into a more useful Haskell representation.
--   
--   A Haskell numeric type is considered to be compatible with all
--   PostgreSQL numeric types that are less accurate than it. For instance,
--   the Haskell <a>Double</a> type is compatible with the PostgreSQL's
--   32-bit <tt>Int</tt> type because it can represent a <tt>Int</tt>
--   exactly. On the other hand, since a <a>Double</a> might lose precision
--   if representing a 64-bit <tt>BigInt</tt>, the two are <i>not</i>
--   considered compatible.
module Database.PostgreSQL.Simple.FromField

-- | A type that may be converted from a SQL type.
class FromField a
fromField :: FromField a => FieldParser a
type FieldParser a = Field -> Maybe ByteString -> Ok a

-- | Exception thrown if conversion from a SQL value to a Haskell value
--   fails.
data ResultError

-- | The SQL and Haskell types are not compatible.
Incompatible :: String -> String -> String -> ResultError
errSQLType :: ResultError -> String
errHaskellType :: ResultError -> String
errMessage :: ResultError -> String

-- | A SQL <tt>NULL</tt> was encountered when the Haskell type did not
--   permit it.
UnexpectedNull :: String -> String -> String -> ResultError
errSQLType :: ResultError -> String
errHaskellType :: ResultError -> String
errMessage :: ResultError -> String

-- | The SQL value could not be parsed, or could not be represented as a
--   valid Haskell value, or an unexpected low-level error occurred (e.g.
--   mismatch between metadata and actual data in a row).
ConversionFailed :: String -> String -> String -> ResultError
errSQLType :: ResultError -> String
errHaskellType :: ResultError -> String
errMessage :: ResultError -> String

-- | Given one of the constructors from <a>ResultError</a>, the field, and
--   an <a>errMessage</a>, this fills in the other fields in the exception
--   value and returns it in a 'Left . SomeException' constructor.
returnError :: (Typeable a, Exception err) => (String -> String -> String -> err) -> Field -> String -> Ok a

-- | A Field represents metadata about a particular field
--   
--   You don't particularly want to retain these structures for a long
--   period of time, as they will retain the entire query result, not just
--   the field metadata
data Field
typename :: Field -> ByteString
name :: Field -> Maybe ByteString
tableOid :: Field -> Oid
tableColumn :: Field -> Int
format :: Field -> Format
typeOid :: Field -> Oid
newtype Oid :: *
Oid :: CUInt -> Oid
data Format :: *
Text :: Format
Binary :: Format
instance Typeable ResultError
instance Eq ResultError
instance Show ResultError
instance (FromField a, FromField b) => FromField (Either a b)
instance FromField Date
instance FromField LocalTimestamp
instance FromField ZonedTimestamp
instance FromField UTCTimestamp
instance FromField TimeOfDay
instance FromField Day
instance FromField LocalTime
instance FromField ZonedTime
instance FromField UTCTime
instance FromField [Char]
instance FromField Text
instance FromField Text
instance FromField (Binary ByteString)
instance FromField (Binary ByteString)
instance FromField ByteString
instance FromField Oid
instance FromField ByteString
instance FromField (Ratio Integer)
instance FromField Double
instance FromField Float
instance FromField Integer
instance FromField Int64
instance FromField Int
instance FromField Int32
instance FromField Int16
instance FromField Bool
instance FromField Null
instance FromField a => FromField (Maybe a)
instance Exception ResultError


-- | The <a>FromRow</a> typeclass, for converting a row of results returned
--   by a SQL query into a more useful Haskell representation.
--   
--   Predefined instances are provided for tuples containing up to ten
--   elements.
module Database.PostgreSQL.Simple.FromRow

-- | A collection type that can be converted from a sequence of fields.
--   Instances are provided for tuples up to 10 elements and lists of any
--   length.
--   
--   Note that instances can defined outside of postgresql-simple, which is
--   often useful. For example, here's an instance for a user-defined pair:
--   
--   <pre>
--   data User = User { name :: String, fileQuota :: Int }
--   
--   instance <a>FromRow</a> User where
--        fromRow = User &lt;$&gt; <a>field</a> &lt;*&gt; <a>field</a>
--   </pre>
--   
--   The number of calls to <a>field</a> must match the number of fields
--   returned in a single row of the query result. Otherwise, a
--   <a>ConversionFailed</a> exception will be thrown.
--   
--   Note that <a>field</a> evaluates it's result to WHNF, so the caveats
--   listed in previous versions of postgresql-simple no longer apply.
--   Instead, look at the caveats associated with user-defined
--   implementations of <a>fromRow</a>.
class FromRow a
fromRow :: FromRow a => RowParser a
data RowParser a
field :: FromField a => RowParser a
fieldWith :: FieldParser a -> RowParser a
numFieldsRemaining :: RowParser Int
instance (FromRow a, FromRow b) => FromRow (a :. b)
instance FromField a => FromRow [a]
instance (FromField a, FromField b, FromField c, FromField d, FromField e, FromField f, FromField g, FromField h, FromField i, FromField j) => FromRow (a, b, c, d, e, f, g, h, i, j)
instance (FromField a, FromField b, FromField c, FromField d, FromField e, FromField f, FromField g, FromField h, FromField i) => FromRow (a, b, c, d, e, f, g, h, i)
instance (FromField a, FromField b, FromField c, FromField d, FromField e, FromField f, FromField g, FromField h) => FromRow (a, b, c, d, e, f, g, h)
instance (FromField a, FromField b, FromField c, FromField d, FromField e, FromField f, FromField g) => FromRow (a, b, c, d, e, f, g)
instance (FromField a, FromField b, FromField c, FromField d, FromField e, FromField f) => FromRow (a, b, c, d, e, f)
instance (FromField a, FromField b, FromField c, FromField d, FromField e) => FromRow (a, b, c, d, e)
instance (FromField a, FromField b, FromField c, FromField d) => FromRow (a, b, c, d)
instance (FromField a, FromField b, FromField c) => FromRow (a, b, c)
instance (FromField a, FromField b) => FromRow (a, b)
instance FromField a => FromRow (Only a)


-- | Support for PostgreSQL's Large Objects; see
--   <a>http://www.postgresql.org/docs/9.1/static/largeobjects.html</a> for
--   more information.
--   
--   Note that Large Object File Descriptors are only valid within a single
--   database transaction, so if you are interested in using anything
--   beyond <a>loCreat</a>, <a>loImport</a>, <a>loExport</a>, and
--   <a>loUnlink</a>, you will need to run the entire sequence of functions
--   in a transaction.
module Database.PostgreSQL.Simple.LargeObjects
loCreat :: Connection -> IO Oid
loCreate :: Connection -> Oid -> IO Oid
loImport :: Connection -> FilePath -> IO Oid
loImportWithOid :: Connection -> FilePath -> Oid -> IO Oid
loExport :: Connection -> Oid -> FilePath -> IO ()
loOpen :: Connection -> Oid -> IOMode -> IO LoFd
loWrite :: Connection -> LoFd -> ByteString -> IO Int
loRead :: Connection -> LoFd -> Int -> IO ByteString
loSeek :: Connection -> LoFd -> SeekMode -> Int -> IO Int
loTell :: Connection -> LoFd -> IO Int
loTruncate :: Connection -> LoFd -> Int -> IO ()
loClose :: Connection -> LoFd -> IO ()
loUnlink :: Connection -> Oid -> IO ()
newtype Oid :: *
Oid :: CUInt -> Oid

-- | LoFd is a Large Object (pseudo) File Descriptor. It is understood by
--   libpq but not by operating system calls.
data LoFd :: *

-- | See <a>openFile</a>
data IOMode :: *
ReadMode :: IOMode
WriteMode :: IOMode
AppendMode :: IOMode
ReadWriteMode :: IOMode

-- | A mode that determines the effect of <tt>hSeek</tt> <tt>hdl mode
--   i</tt>.
data SeekMode :: *

-- | the position of <tt>hdl</tt> is set to <tt>i</tt>.
AbsoluteSeek :: SeekMode

-- | the position of <tt>hdl</tt> is set to offset <tt>i</tt> from the
--   current position.
RelativeSeek :: SeekMode

-- | the position of <tt>hdl</tt> is set to offset <tt>i</tt> from the end
--   of the file.
SeekFromEnd :: SeekMode


-- | Support for receiving asynchronous notifications via PostgreSQL's
--   Listen/Notify mechanism. See
--   <a>http://www.postgresql.org/docs/9.1/static/sql-notify.html</a> for
--   more information.
module Database.PostgreSQL.Simple.Notification
data Notification
Notification :: !CPid -> !ByteString -> !ByteString -> Notification
notificationPid :: Notification -> !CPid
notificationChannel :: Notification -> !ByteString
notificationData :: Notification -> !ByteString

-- | Returns a single notification. If no notifications are available,
--   <a>getNotification</a> blocks until one arrives.
getNotification :: Connection -> IO Notification

-- | Non-blocking variant of <a>getNotification</a>. Returns a single
--   notification, if available. If no notifications are available, returns
--   <a>Nothing</a>.
getNotificationNonBlocking :: Connection -> IO (Maybe Notification)


-- | A mid-level client library for the PostgreSQL database, aimed at ease
--   of use and high performance.
module Database.PostgreSQL.Simple
data ConnectInfo
ConnectInfo :: String -> Word16 -> String -> String -> String -> ConnectInfo
connectHost :: ConnectInfo -> String
connectPort :: ConnectInfo -> Word16
connectUser :: ConnectInfo -> String
connectPassword :: ConnectInfo -> String
connectDatabase :: ConnectInfo -> String
data Connection

-- | A query string. This type is intended to make it difficult to
--   construct a SQL query by concatenating string fragments, as that is an
--   extremely common way to accidentally introduce SQL injection
--   vulnerabilities into an application.
--   
--   This type is an instance of <a>IsString</a>, so the easiest way to
--   construct a query is to enable the <tt>OverloadedStrings</tt> language
--   extension and then simply write the query in double quotes.
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   import Database.PostgreSQL.Simple
--   
--   q :: Query
--   q = "select ?"
--   </pre>
--   
--   The underlying type is a <a>ByteString</a>, and literal Haskell
--   strings that contain Unicode characters will be correctly transformed
--   to UTF-8.
data Query

-- | A collection type that can be turned into a list of rendering
--   <a>Action</a>s.
--   
--   Instances should use the <tt>render</tt> method of the <tt>Param</tt>
--   class to perform conversion of each element of the collection.
class ToRow a

-- | A collection type that can be converted from a sequence of fields.
--   Instances are provided for tuples up to 10 elements and lists of any
--   length.
--   
--   Note that instances can defined outside of postgresql-simple, which is
--   often useful. For example, here's an instance for a user-defined pair:
--   
--   <pre>
--   data User = User { name :: String, fileQuota :: Int }
--   
--   instance <a>FromRow</a> User where
--        fromRow = User &lt;$&gt; <a>field</a> &lt;*&gt; <a>field</a>
--   </pre>
--   
--   The number of calls to <a>field</a> must match the number of fields
--   returned in a single row of the query result. Otherwise, a
--   <a>ConversionFailed</a> exception will be thrown.
--   
--   Note that <a>field</a> evaluates it's result to WHNF, so the caveats
--   listed in previous versions of postgresql-simple no longer apply.
--   Instead, look at the caveats associated with user-defined
--   implementations of <a>fromRow</a>.
class FromRow a

-- | Wrap a list of values for use in an <tt>IN</tt> clause. Replaces a
--   single "<tt>?</tt>" character with a parenthesized list of rendered
--   values.
--   
--   Example:
--   
--   <pre>
--   query c "select * from whatever where id in ?" (Only (In [3,4,5]))
--   </pre>
newtype In a
In :: a -> In a

-- | Wrap binary data for use as a <tt>bytea</tt> value.
newtype Binary a
Binary :: a -> Binary a

-- | A single-value "collection".
--   
--   This is useful if you need to supply a single parameter to a SQL
--   query, or extract a single column from a SQL result.
--   
--   Parameter example:
--   
--   <pre>
--   query c "select x from scores where x &gt; ?" (<a>Only</a> (42::Int))
--   </pre>
--   
--   Result example:
--   
--   <pre>
--   xs &lt;- query_ c "select id from users"
--   forM_ xs $ \(<a>Only</a> id) -&gt; {- ... -}
--   </pre>
newtype Only a
Only :: a -> Only a
fromOnly :: Only a -> a

-- | A composite type to parse your custom data structures without having
--   to define dummy newtype wrappers every time.
--   
--   <pre>
--   instance FromRow MyData where ...
--   </pre>
--   
--   <pre>
--   instance FromRow MyData2 where ...
--   </pre>
--   
--   then I can do the following for free:
--   
--   <pre>
--   res &lt;- query' c <a>...</a>
--   forM res $ \(MyData{..} :. MyData2{..}) -&gt; do
--     ....
--   </pre>
data (:.) h t
(:.) :: h -> t -> :. h t
data SqlError
SqlError :: ByteString -> Int -> ByteString -> SqlError
sqlState :: SqlError -> ByteString
sqlNativeError :: SqlError -> Int
sqlErrorMsg :: SqlError -> ByteString

-- | Exception thrown if a <a>Query</a> could not be formatted correctly.
--   This may occur if the number of '<tt>?</tt>' characters in the query
--   string does not match the number of parameters provided.
data FormatError

-- | Exception thrown if <tt>query</tt> is used to perform an
--   <tt>INSERT</tt>-like operation, or <tt>execute</tt> is used to perform
--   a <tt>SELECT</tt>-like operation.
data QueryError

-- | Exception thrown if conversion from a SQL value to a Haskell value
--   fails.
data ResultError

-- | Connect with the given username to the given database. Will throw an
--   exception if it cannot connect.
connect :: ConnectInfo -> IO Connection

-- | Attempt to make a connection based on a libpq connection string. See
--   <a>http://www.postgresql.org/docs/9.1/static/libpq-connect.html</a>
--   for more information.
connectPostgreSQL :: ByteString -> IO Connection

-- | Turns a <a>ConnectInfo</a> data structure into a libpq connection
--   string.
postgreSQLConnectionString :: ConnectInfo -> ByteString

-- | Default information for setting up a connection.
--   
--   Defaults are as follows:
--   
--   <ul>
--   <li>Server on <tt>localhost</tt></li>
--   <li>Port on <tt>5432</tt></li>
--   <li>User <tt>postgres</tt></li>
--   <li>No password</li>
--   <li>Database <tt>postgres</tt></li>
--   </ul>
--   
--   Use as in the following example:
--   
--   <pre>
--   connect defaultConnectInfo { connectHost = "db.example.com" }
--   </pre>
defaultConnectInfo :: ConnectInfo
close :: Connection -> IO ()

-- | Perform a <tt>SELECT</tt> or other SQL query that is expected to
--   return results. All results are retrieved and converted before this
--   function returns.
--   
--   When processing large results, this function will consume a lot of
--   client-side memory. Consider using <a>fold</a> instead.
--   
--   Exceptions that may be thrown:
--   
--   <ul>
--   <li><a>FormatError</a>: the query string could not be formatted
--   correctly.</li>
--   <li><a>QueryError</a>: the result contains no columns (i.e. you should
--   be using <a>execute</a> instead of <a>query</a>).</li>
--   <li><a>ResultError</a>: result conversion failed.</li>
--   </ul>
query :: (ToRow q, FromRow r) => Connection -> Query -> q -> IO [r]

-- | A version of <a>query</a> that does not perform query substitution.
query_ :: FromRow r => Connection -> Query -> IO [r]
data FoldOptions
FoldOptions :: !FetchQuantity -> !TransactionMode -> FoldOptions
fetchQuantity :: FoldOptions -> !FetchQuantity
transactionMode :: FoldOptions -> !TransactionMode
data FetchQuantity
Automatic :: FetchQuantity
Fixed :: !Int -> FetchQuantity
defaultFoldOptions :: FoldOptions

-- | Perform a <tt>SELECT</tt> or other SQL query that is expected to
--   return results. Results are streamed incrementally from the server,
--   and consumed via a left fold.
--   
--   When dealing with small results, it may be simpler (and perhaps
--   faster) to use <a>query</a> instead.
--   
--   This fold is <i>not</i> strict. The stream consumer is responsible for
--   forcing the evaluation of its result to avoid space leaks.
--   
--   Exceptions that may be thrown:
--   
--   <ul>
--   <li><a>FormatError</a>: the query string could not be formatted
--   correctly.</li>
--   <li><a>QueryError</a>: the result contains no columns (i.e. you should
--   be using <a>execute</a> instead of <a>query</a>).</li>
--   <li><a>ResultError</a>: result conversion failed.</li>
--   </ul>
fold :: (FromRow row, ToRow params) => Connection -> Query -> params -> a -> (a -> row -> IO a) -> IO a
foldWithOptions :: (FromRow row, ToRow params) => FoldOptions -> Connection -> Query -> params -> a -> (a -> row -> IO a) -> IO a

-- | A version of <a>fold</a> that does not perform query substitution.
fold_ :: FromRow r => Connection -> Query -> a -> (a -> r -> IO a) -> IO a
foldWithOptions_ :: FromRow r => FoldOptions -> Connection -> Query -> a -> (a -> r -> IO a) -> IO a

-- | A version of <a>fold</a> that does not transform a state value.
forEach :: (ToRow q, FromRow r) => Connection -> Query -> q -> (r -> IO ()) -> IO ()

-- | A version of <a>forEach</a> that does not perform query substitution.
forEach_ :: FromRow r => Connection -> Query -> (r -> IO ()) -> IO ()

-- | Execute <tt>INSERT ... RETURNING</tt>, <tt>UPDATE ... RETURNING</tt>,
--   or other SQL query that accepts multi-row input and is expected to
--   return results. Note that it is possible to write <tt><a>query</a>
--   conn <a>INSERT ... RETURNING ...</a> ...</tt> in cases where you are
--   only inserting a single row, and do not need functionality analogous
--   to <a>executeMany</a>.
--   
--   Throws <a>FormatError</a> if the query could not be formatted
--   correctly.
returning :: (ToRow q, FromRow r) => Connection -> Query -> [q] -> IO [r]

-- | Execute an <tt>INSERT</tt>, <tt>UPDATE</tt>, or other SQL query that
--   is not expected to return results.
--   
--   Returns the number of rows affected.
--   
--   Throws <a>FormatError</a> if the query could not be formatted
--   correctly.
execute :: ToRow q => Connection -> Query -> q -> IO Int64

-- | A version of <tt>execute</tt> that does not perform query
--   substitution.
execute_ :: Connection -> Query -> IO Int64

-- | Execute a multi-row <tt>INSERT</tt>, <tt>UPDATE</tt>, or other SQL
--   query that is not expected to return results.
--   
--   Returns the number of rows affected.
--   
--   Throws <a>FormatError</a> if the query could not be formatted
--   correctly.
executeMany :: ToRow q => Connection -> Query -> [q] -> IO Int64

-- | Execute an action inside a SQL transaction.
--   
--   This function initiates a transaction with a "<tt>begin
--   transaction</tt>" statement, then executes the supplied action. If the
--   action succeeds, the transaction will be completed with <a>commit</a>
--   before this function returns.
--   
--   If the action throws <i>any</i> kind of exception (not just a
--   PostgreSQL-related exception), the transaction will be rolled back
--   using <a>rollback</a>, then the exception will be rethrown.
withTransaction :: Connection -> IO a -> IO a

-- | Execute an action inside of a <a>Serializable</a> transaction. If a
--   serialization failure occurs, roll back the transaction and try again.
--   Be warned that this may execute the IO action multiple times.
--   
--   A <a>Serializable</a> transaction creates the illusion that your
--   program has exclusive access to the database. This means that, even in
--   a concurrent setting, you can perform queries in sequence without
--   having to worry about what might happen between one statement and the
--   next.
--   
--   Think of it as STM, but without <tt>retry</tt>.
withTransactionSerializable :: Connection -> IO a -> IO a
data TransactionMode
TransactionMode :: !IsolationLevel -> !ReadWriteMode -> TransactionMode
isolationLevel :: TransactionMode -> !IsolationLevel
readWriteMode :: TransactionMode -> !ReadWriteMode

-- | Of the four isolation levels defined by the SQL standard, these are
--   the three levels distinguished by PostgreSQL as of version 9.0. See
--   <a>http://www.postgresql.org/docs/9.1/static/transaction-iso.html</a>
--   for more information. Note that prior to PostgreSQL 9.0,
--   <a>RepeatableRead</a> was equivalent to <a>Serializable</a>.
data IsolationLevel

-- | the isolation level will be taken from PostgreSQL's per-connection
--   <tt>default_transaction_isolation</tt> variable, which is initialized
--   according to the server's config. The default configuration is
--   <a>ReadCommitted</a>.
DefaultIsolationLevel :: IsolationLevel
ReadCommitted :: IsolationLevel
RepeatableRead :: IsolationLevel
Serializable :: IsolationLevel
data ReadWriteMode

-- | the read-write mode will be taken from PostgreSQL's per-connection
--   <tt>default_transaction_read_only</tt> variable, which is initialized
--   according to the server's config. The default configuration is
--   <a>ReadWrite</a>.
DefaultReadWriteMode :: ReadWriteMode
ReadWrite :: ReadWriteMode
ReadOnly :: ReadWriteMode
defaultTransactionMode :: TransactionMode
defaultIsolationLevel :: IsolationLevel
defaultReadWriteMode :: ReadWriteMode

-- | Execute an action inside a SQL transaction with a given isolation
--   level.
withTransactionLevel :: IsolationLevel -> Connection -> IO a -> IO a

-- | Execute an action inside a SQL transaction with a given transaction
--   mode.
withTransactionMode :: TransactionMode -> Connection -> IO a -> IO a

-- | Like <a>withTransactionMode</a>, but if a <a>SqlError</a> arises whose
--   <a>sqlState</a> is <tt>"40001"</tt> (<tt>serialization_failure</tt>),
--   this will issue a <tt>ROLLBACK</tt>, then try the action again. If any
--   other exception arises, this will issue a <tt>ROLLBACK</tt>, but will
--   propagate the exception instead of retrying.
--   
--   This is used to implement <a>withTransactionSerializable</a>.
withTransactionModeRetry :: TransactionMode -> Connection -> IO a -> IO a

-- | Begin a transaction.
begin :: Connection -> IO ()

-- | Begin a transaction with a given isolation level
beginLevel :: IsolationLevel -> Connection -> IO ()

-- | Begin a transaction with a given transaction mode
beginMode :: TransactionMode -> Connection -> IO ()

-- | Commit a transaction.
commit :: Connection -> IO ()

-- | Rollback a transaction.
rollback :: Connection -> IO ()

-- | Format a query string with a variable number of rows.
--   
--   This function is exposed to help with debugging and logging. Do not
--   use it to prepare queries for execution.
--   
--   The query string must contain exactly one substitution group,
--   identified by the SQL keyword "<tt>VALUES</tt>" (case insensitive)
--   followed by an "<tt>(</tt>" character, a series of one or more
--   "<tt>?</tt>" characters separated by commas, and a "<tt>)</tt>"
--   character. White space in a substitution group is permitted.
--   
--   Throws <a>FormatError</a> if the query string could not be formatted
--   correctly.
formatMany :: ToRow q => Connection -> Query -> [q] -> IO ByteString

-- | Format a query string.
--   
--   This function is exposed to help with debugging and logging. Do not
--   use it to prepare queries for execution.
--   
--   String parameters are escaped according to the character set in use on
--   the <a>Connection</a>.
--   
--   Throws <a>FormatError</a> if the query string could not be formatted
--   correctly.
formatQuery :: ToRow q => Connection -> Query -> q -> IO ByteString
instance Typeable FormatError
instance Eq FormatError
instance Show FormatError
instance Show IsolationLevel
instance Eq IsolationLevel
instance Ord IsolationLevel
instance Enum IsolationLevel
instance Bounded IsolationLevel
instance Show ReadWriteMode
instance Eq ReadWriteMode
instance Ord ReadWriteMode
instance Enum ReadWriteMode
instance Bounded ReadWriteMode
instance Show TransactionMode
instance Eq TransactionMode
instance Exception FormatError
