-- 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.4.0.2


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. It also recognizes and strips out standard sql
--   comments <a>--</a>.
--   
--   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, quoted
--   identifiers, 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)


-- | This module contains portions of the <tt>pg_type</tt> table that are
--   relevant to postgresql-simple and are believed to not change between
--   PostgreSQL versions.
module Database.PostgreSQL.Simple.TypeInfo.Static

-- | A structure representing some of the metadata regarding a PostgreSQL
--   type, mostly taken from the <tt>pg_type</tt> table.
data TypeInfo
Basic :: {-# UNPACK #-} !Oid -> {-# UNPACK #-} !Char -> {-# UNPACK #-} !Char -> !ByteString -> TypeInfo
typoid :: TypeInfo -> {-# UNPACK #-} !Oid
typcategory :: TypeInfo -> {-# UNPACK #-} !Char
typdelim :: TypeInfo -> {-# UNPACK #-} !Char
typname :: TypeInfo -> !ByteString
Array :: {-# UNPACK #-} !Oid -> {-# UNPACK #-} !Char -> {-# UNPACK #-} !Char -> !ByteString -> !TypeInfo -> TypeInfo
typoid :: TypeInfo -> {-# UNPACK #-} !Oid
typcategory :: TypeInfo -> {-# UNPACK #-} !Char
typdelim :: TypeInfo -> {-# UNPACK #-} !Char
typname :: TypeInfo -> !ByteString
typelem :: TypeInfo -> !TypeInfo
Range :: {-# UNPACK #-} !Oid -> {-# UNPACK #-} !Char -> {-# UNPACK #-} !Char -> !ByteString -> !TypeInfo -> TypeInfo
typoid :: TypeInfo -> {-# UNPACK #-} !Oid
typcategory :: TypeInfo -> {-# UNPACK #-} !Char
typdelim :: TypeInfo -> {-# UNPACK #-} !Char
typname :: TypeInfo -> !ByteString
rngsubtype :: TypeInfo -> !TypeInfo
Composite :: {-# UNPACK #-} !Oid -> {-# UNPACK #-} !Char -> {-# UNPACK #-} !Char -> !ByteString -> {-# UNPACK #-} !Oid -> !(Vector Attribute) -> TypeInfo
typoid :: TypeInfo -> {-# UNPACK #-} !Oid
typcategory :: TypeInfo -> {-# UNPACK #-} !Char
typdelim :: TypeInfo -> {-# UNPACK #-} !Char
typname :: TypeInfo -> !ByteString
typrelid :: TypeInfo -> {-# UNPACK #-} !Oid
attributes :: TypeInfo -> !(Vector Attribute)
staticTypeInfo :: Oid -> Maybe TypeInfo
bool :: TypeInfo
bytea :: TypeInfo
char :: TypeInfo
name :: TypeInfo
int8 :: TypeInfo
int2 :: TypeInfo
int4 :: TypeInfo
regproc :: TypeInfo
text :: TypeInfo
oid :: TypeInfo
tid :: TypeInfo
xid :: TypeInfo
cid :: TypeInfo
xml :: TypeInfo
point :: TypeInfo
lseg :: TypeInfo
path :: TypeInfo
box :: TypeInfo
polygon :: TypeInfo
line :: TypeInfo
cidr :: TypeInfo
float4 :: TypeInfo
float8 :: TypeInfo
abstime :: TypeInfo
reltime :: TypeInfo
tinterval :: TypeInfo
unknown :: TypeInfo
circle :: TypeInfo
money :: TypeInfo
macaddr :: TypeInfo
inet :: TypeInfo
bpchar :: TypeInfo
varchar :: TypeInfo
date :: TypeInfo
time :: TypeInfo
timestamp :: TypeInfo
timestamptz :: TypeInfo
interval :: TypeInfo
timetz :: TypeInfo
bit :: TypeInfo
varbit :: TypeInfo
numeric :: TypeInfo
refcursor :: TypeInfo
record :: TypeInfo
void :: TypeInfo
uuid :: TypeInfo
json :: TypeInfo



-- | <i>Deprecated: Use TypeInfo instead </i>
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
JSON :: 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


-- | A Postgres array parser and pretty-printer.
module Database.PostgreSQL.Simple.Arrays

-- | Parse one of three primitive field formats: array, quoted and plain.
arrayFormat :: Char -> Parser ArrayFormat
data ArrayFormat
Array :: [ArrayFormat] -> ArrayFormat
Plain :: ByteString -> ArrayFormat
Quoted :: ByteString -> ArrayFormat
array :: Char -> Parser [ArrayFormat]

-- | Recognizes a quoted string.
quoted :: Parser ByteString

-- | Recognizes a plain string literal, not containing quotes or brackets
--   and not containing the delimiter character.
plain :: Char -> Parser ByteString

-- | Format an array format item, using the delimiter character if the item
--   is itself an array.
fmt :: Char -> ArrayFormat -> ByteString

-- | Format a list of array format items, inserting the appropriate
--   delimiter between them. When the items are arrays, they will be
--   delimited with commas; otherwise, they are delimited with the
--   passed-in-delimiter.
delimit :: Char -> [ArrayFormat] -> ByteString

-- | Format an array format item, using the delimiter character if the item
--   is itself an array, optionally applying quoting rules. Creates copies
--   for safety when used in <tt>FromField</tt> instances.
fmt' :: Bool -> Char -> ArrayFormat -> ByteString

-- | Escape a string according to Postgres double-quoted string format.
esc :: ByteString -> ByteString
instance Eq ArrayFormat
instance Show ArrayFormat
instance Ord ArrayFormat


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

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

-- | A placeholder for the PostgreSQL <tt>DEFAULT</tt> value.
data Default
Default :: Default

-- | 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
fromBinary :: Binary a -> 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
newtype Savepoint
Savepoint :: Query -> Savepoint

-- | Wrap a list for use as a PostgreSQL array.
newtype PGArray a
PGArray :: [a] -> PGArray a
fromPGArray :: PGArray a -> [a]
instance Typeable Null
instance Typeable Default
instance Typeable Query
instance Typeable1 Only
instance Typeable1 In
instance Typeable1 Binary
instance Typeable1 PGArray
instance Typeable2 :.
instance Typeable Savepoint
instance Read Null
instance Show Null
instance Read Default
instance Show Default
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 a => Eq (PGArray a)
instance Ord a => Ord (PGArray a)
instance Read a => Read (PGArray a)
instance Show a => Show (PGArray a)
instance Functor PGArray
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 Eq Savepoint
instance Ord Savepoint
instance Show Savepoint
instance Read Savepoint
instance Monoid Query
instance IsString Query
instance Read Query
instance Show Query
instance Eq Null


-- | A Template Haskell macro for efficiently checking membership in a set
--   of type oids.
module Database.PostgreSQL.Simple.TypeInfo.Macro

-- | Returns an expression that has type <tt><a>Oid</a> -&gt;
--   <a>Bool</a></tt>, true if the oid is equal to any one of the
--   <a>typoid</a>s of the given <a>TypeInfo</a>s.
mkCompats :: [TypeInfo] -> ExpQ

-- | Literally substitute the <a>typoid</a> of a <a>TypeInfo</a>
--   expression. Returns an expression of type <a>Oid</a>. Useful because
--   GHC tends not to fold constants.
inlineTypoid :: TypeInfo -> ExpQ


-- | 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

-- | Convert a Haskell value to a JSON <a>Value</a> using <a>toJSON</a> and
--   convert that to a field using <a>toField</a>.
--   
--   This can be used as the default implementation for the <a>toField</a>
--   method for Haskell types that have a JSON representation in
--   PostgreSQL.
toJSONField :: ToJSON 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 Value
instance ToField UUID
instance ToField a => ToField (Vector a)
instance ToField a => ToField (PGArray a)
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 Default
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)


-- | 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 -> {-# UNPACK #-} !Oid -> Field
result :: Field -> !Result
column :: Field -> {-# UNPACK #-} !Column

-- | This returns the type oid associated with the column. Analogous to
--   libpq's <tt>PQftype</tt>.
typeOid :: Field -> {-# UNPACK #-} !Oid
type TypeInfoCache = IntMap TypeInfo
data Connection
Connection :: {-# UNPACK #-} !(MVar Connection) -> {-# UNPACK #-} !(MVar TypeInfoCache) -> {-# UNPACK #-} !(IORef Int64) -> Connection
connectionHandle :: Connection -> {-# UNPACK #-} !(MVar Connection)
connectionObjects :: Connection -> {-# UNPACK #-} !(MVar TypeInfoCache)
connectionTempNameCounter :: Connection -> {-# UNPACK #-} !(IORef Int64)
data SqlError
SqlError :: ByteString -> ExecStatus -> ByteString -> ByteString -> ByteString -> SqlError
sqlState :: SqlError -> ByteString
sqlExecStatus :: SqlError -> ExecStatus
sqlErrorMsg :: SqlError -> ByteString
sqlErrorDetail :: SqlError -> ByteString
sqlErrorHint :: SqlError -> ByteString
fatalError :: ByteString -> SqlError

-- | 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 -> !Result -> Row
row :: Row -> {-# UNPACK #-} !Row
rowresult :: Row -> !Result
newtype RowParser a
RP :: ReaderT Row (StateT Column Conversion) a -> RowParser a
unRP :: RowParser a -> ReaderT Row (StateT Column Conversion) a
liftRowParser :: IO a -> RowParser a
newtype Conversion a
Conversion :: (Connection -> IO (Ok a)) -> Conversion a
runConversion :: Conversion a -> Connection -> IO (Ok a)
liftConversion :: IO a -> Conversion a
conversionMap :: (Ok a -> Ok b) -> Conversion a -> Conversion b
conversionError :: Exception err => err -> Conversion a
newTempName :: Connection -> IO Query
fdError :: ByteString -> IOError
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 MonadPlus Conversion
instance Monad Conversion
instance Alternative Conversion
instance Applicative Conversion
instance Functor Conversion
instance Exception QueryError
instance Exception SqlError


-- | 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>loCreate</a>, and <a>loUnlink</a>, you will
--   need to run the entire sequence of functions in a transaction. As
--   <a>loImport</a> and <a>loExport</a> are simply C functions that call
--   <a>loCreat</a>, <a>loOpen</a>, <a>loRead</a>, and <a>loWrite</a>, and
--   do not perform any transaction handling themselves, they also need to
--   be wrapped in an explicit 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.
--   
--   Note that on Windows, <tt>getNotification</tt> currently uses a
--   polling loop of 1 second to check for more notifications, due to some
--   inadequacies in GHC's IO implementation and interface on that
--   platform. See GHC issue #7353 for more information. While this
--   workaround is less than ideal, notifications are still better than
--   polling the database directly. Notifications do not create any extra
--   work for the backend, and are likely cheaper on the client side as
--   well.
--   
--   <a>http://hackage.haskell.org/trac/ghc/ticket/7353</a>
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)

-- | Returns the process <a>CPid</a> of the backend server process handling
--   this connection.
--   
--   The backend PID is useful for debugging purposes and for comparison to
--   NOTIFY messages (which include the PID of the notifying backend
--   process). Note that the PID belongs to a process executing on the
--   database server host, not the local host!
getBackendPID :: Connection -> IO CPid


-- | | Module for parsing errors from postgresql error messages. Currently
--   only parses integrity violation errors (class 23).
--   
--   <i>Note: Success of parsing may depend on language settings.</i>
module Database.PostgreSQL.Simple.Errors
data ConstraintViolation

-- | The field is a column name
NotNullViolation :: ByteString -> ConstraintViolation

-- | Table name and name of violated constraint
ForeignKeyViolation :: ByteString -> ByteString -> ConstraintViolation

-- | Name of violated constraint
UniqueViolation :: ByteString -> ConstraintViolation

-- | Relation name (usually table), constraint name
CheckViolation :: ByteString -> ByteString -> ConstraintViolation

-- | Tries to convert <a>SqlError</a> to <tt>ConstrainViolation</tt>,
--   checks sqlState and succeedes only if able to parse sqlErrorMsg.
--   
--   <pre>
--   createUser = catchJust constraintViolation catcher $ execute conn ...
--     where
--       catcher UniqueViolation "user_login_key" = ...
--       catcher _ = ...
--   </pre>
constraintViolation :: SqlError -> Maybe ConstraintViolation

-- | Like constraintViolation, but also packs original SqlError.
--   
--   <pre>
--   createUser = catchJust constraintViolationE catcher $ execute conn ...
--     where
--       catcher (_, UniqueViolation "user_login_key") = ...
--       catcher (e, _) = throwIO e
--   </pre>
constraintViolationE :: SqlError -> Maybe (SqlError, ConstraintViolation)

-- | Catches SqlError, tries to convert to ConstraintViolation, re-throws
--   on fail. Provides alternative interface to catchJust
--   
--   <pre>
--   createUser = catchViolation catcher $ execute conn ...
--     where
--       catcher _ (UniqueViolation "user_login_key") = ...
--       catcher e _ = throwIO e
--   </pre>
catchViolation :: (SqlError -> ConstraintViolation -> IO a) -> IO a -> IO a
isSerializationError :: SqlError -> Bool
isNoActiveTransactionError :: SqlError -> Bool
isFailedTransactionError :: SqlError -> Bool
instance Typeable ConstraintViolation
instance Show ConstraintViolation
instance Eq ConstraintViolation
instance Ord ConstraintViolation
instance Exception ConstraintViolation

module Database.PostgreSQL.Simple.Transaction

-- | 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.
--   
--   For nesting transactions, see <a>withSavepoint</a>.
withTransaction :: Connection -> IO a -> IO a

-- | 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 also takes a custom callback to
--   determine if a transaction should be retried if an <a>SqlError</a>
--   occurs. If the callback returns True, then the transaction will be
--   retried. If the callback returns False, or an exception other than an
--   <a>SqlError</a> occurs then the transaction will be rolled back and
--   the exception rethrown.
--   
--   This is used to implement <a>withTransactionSerializable</a>.
withTransactionModeRetry :: TransactionMode -> (SqlError -> Bool) -> 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

-- | 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 ()

-- | Create a savepoint, and roll back to it if an error occurs. This may
--   only be used inside of a transaction, and provides a sort of "nested
--   transaction".
--   
--   See
--   <a>http://www.postgresql.org/docs/current/static/sql-savepoint.html</a>
withSavepoint :: Connection -> IO a -> IO a
data Savepoint

-- | Create a new savepoint. This may only be used inside of a transaction.
newSavepoint :: Connection -> IO Savepoint

-- | Destroy a savepoint, but retain its effects.
--   
--   Warning: this will throw a <a>SqlError</a> matching
--   <a>isFailedTransactionError</a> if the transaction is aborted due to
--   an error. <a>commit</a> would merely warn and roll back.
releaseSavepoint :: Connection -> Savepoint -> IO ()

-- | Roll back to a savepoint. This will not release the savepoint.
rollbackToSavepoint :: Connection -> Savepoint -> IO ()

-- | Roll back to a savepoint and release it. This is like calling
--   <a>rollbackToSavepoint</a> followed by <a>releaseSavepoint</a>, but
--   avoids a round trip to the database server.
rollbackToAndReleaseSavepoint :: Connection -> Savepoint -> IO ()
isSerializationError :: SqlError -> Bool
isNoActiveTransactionError :: SqlError -> Bool
isFailedTransactionError :: SqlError -> Bool
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


-- | This module provides convenient and efficient access to parts of the
--   <tt>pg_type</tt> metatable. At the moment, this requires PostgreSQL
--   8.4 if you need to work with types that do not appear in
--   <a>Static</a>.
--   
--   The current scheme could be more efficient, especially for some use
--   cases. In particular, connection pools that use many user-added types
--   and connect to a set of servers with identical (or at least
--   compatible) <tt>pg_type</tt> and associated tables could share a
--   common typeinfo cache, thus saving memory and communication between
--   the client and server.
module Database.PostgreSQL.Simple.TypeInfo

-- | Returns the metadata of the type with a particular oid. To find this
--   data, <a>getTypeInfo</a> first consults postgresql-simple's built-in
--   <a>staticTypeInfo</a> table, then checks the connection's typeinfo
--   cache. Finally, the database's <tt>pg_type</tt> table will be queried
--   only if necessary, and the result will be stored in the connections's
--   cache.
getTypeInfo :: Connection -> Oid -> IO TypeInfo

-- | A structure representing some of the metadata regarding a PostgreSQL
--   type, mostly taken from the <tt>pg_type</tt> table.
data TypeInfo
Basic :: {-# UNPACK #-} !Oid -> {-# UNPACK #-} !Char -> {-# UNPACK #-} !Char -> !ByteString -> TypeInfo
typoid :: TypeInfo -> {-# UNPACK #-} !Oid
typcategory :: TypeInfo -> {-# UNPACK #-} !Char
typdelim :: TypeInfo -> {-# UNPACK #-} !Char
typname :: TypeInfo -> !ByteString
Array :: {-# UNPACK #-} !Oid -> {-# UNPACK #-} !Char -> {-# UNPACK #-} !Char -> !ByteString -> !TypeInfo -> TypeInfo
typoid :: TypeInfo -> {-# UNPACK #-} !Oid
typcategory :: TypeInfo -> {-# UNPACK #-} !Char
typdelim :: TypeInfo -> {-# UNPACK #-} !Char
typname :: TypeInfo -> !ByteString
typelem :: TypeInfo -> !TypeInfo
Range :: {-# UNPACK #-} !Oid -> {-# UNPACK #-} !Char -> {-# UNPACK #-} !Char -> !ByteString -> !TypeInfo -> TypeInfo
typoid :: TypeInfo -> {-# UNPACK #-} !Oid
typcategory :: TypeInfo -> {-# UNPACK #-} !Char
typdelim :: TypeInfo -> {-# UNPACK #-} !Char
typname :: TypeInfo -> !ByteString
rngsubtype :: TypeInfo -> !TypeInfo
Composite :: {-# UNPACK #-} !Oid -> {-# UNPACK #-} !Char -> {-# UNPACK #-} !Char -> !ByteString -> {-# UNPACK #-} !Oid -> !(Vector Attribute) -> TypeInfo
typoid :: TypeInfo -> {-# UNPACK #-} !Oid
typcategory :: TypeInfo -> {-# UNPACK #-} !Char
typdelim :: TypeInfo -> {-# UNPACK #-} !Char
typname :: TypeInfo -> !ByteString
typrelid :: TypeInfo -> {-# UNPACK #-} !Oid
attributes :: TypeInfo -> !(Vector Attribute)
data Attribute
Attribute :: !ByteString -> !TypeInfo -> Attribute
attname :: Attribute -> !ByteString
atttype :: Attribute -> !TypeInfo


-- | The <a>FromField</a> typeclass, for converting a single value in a row
--   returned by a SQL query into a more useful Haskell representation.
--   Note that each instance of <a>FromField</a> is documented by a list of
--   compatible postgresql types.
--   
--   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 PostgreSQL's 64-bit <tt>bigint</tt>, the two are
--   <i>not</i> considered compatible.
--   
--   Because <a>FromField</a> is a typeclass, one may provide conversions
--   to additional Haskell types without modifying postgresql-simple. This
--   is particularly useful for supporting PostgreSQL types that
--   postgresql-simple does not support out-of-box. Here's an example of
--   what such an instance might look like for a UUID type that implements
--   the <tt>Read</tt> class:
--   
--   <pre>
--   import Data.UUID ( UUID )
--   import Database.PostgreSQL.Simple.FromField
--          ( FromField (fromField) , typeOid, returnError, ResultError (..) )
--   import Database.PostgreSQL.Simple.TypeInfo.Static (typoid, uuid)
--   import qualified Data.ByteString.Char8 as B
--   
--   instance FromField UUID where
--      fromField f mdata =
--         if typeOid f /= typoid uuid
--           then returnError Incompatible f ""
--           else case B.unpack `fmap` mdata of
--                  Nothing  -&gt; returnError UnexpectedNull f ""
--                  Just dat -&gt;
--                     case [ x | (x,t) &lt;- reads dat, ("","") &lt;- lex t ] of
--                       [x] -&gt; return x
--                       _   -&gt; returnError ConversionFailed f dat
--   </pre>
--   
--   Note that because PostgreSQL's <tt>uuid</tt> type is built into
--   postgres and is not provided by an extension, the <a>typeOid</a> of
--   <tt>uuid</tt> does not change and thus we can examine it directly. One
--   could hard-code the type oid, or obtain it by other means, but in this
--   case we simply pull it out of the static table provided by
--   postgresql-simple.
--   
--   On the other hand if the type is provided by an extension, such as
--   <tt>PostGIS</tt> or <tt>hstore</tt>, then the <a>typeOid</a> is not
--   stable and can vary from database to database. In this case it is
--   recommended that FromField instances use <a>typename</a> instead.
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 -> Conversion a
data Conversion a
runConversion :: Conversion a -> Connection -> IO (Ok a)
conversionMap :: (Ok a -> Ok b) -> Conversion a -> Conversion b
conversionError :: Exception err => err -> Conversion 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 -> Maybe Oid -> String -> String -> String -> ResultError
errSQLType :: ResultError -> String
errSQLTableOid :: ResultError -> Maybe Oid
errSQLField :: 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 -> Maybe Oid -> String -> String -> String -> ResultError
errSQLType :: ResultError -> String
errSQLTableOid :: ResultError -> Maybe Oid
errSQLField :: 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 -> Maybe Oid -> String -> String -> String -> ResultError
errSQLType :: ResultError -> String
errSQLTableOid :: ResultError -> Maybe Oid
errSQLField :: 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 -> Maybe Oid -> String -> String -> String -> err) -> Field -> String -> Conversion 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

-- | Returns the data type name. This is the preferred way of identifying
--   types that do not have a stable type oid, such as types provided by
--   extensions to PostgreSQL.
--   
--   More concretely, it returns the <tt>typname</tt> column associated
--   with the type oid in the <tt>pg_type</tt> table. First,
--   postgresql-simple will check the built-in, static table. If the type
--   oid is not there, postgresql-simple will check a per-connection cache,
--   and then finally query the database's meta-schema.
typename :: Field -> Conversion ByteString

-- | A structure representing some of the metadata regarding a PostgreSQL
--   type, mostly taken from the <tt>pg_type</tt> table.
data TypeInfo
Basic :: {-# UNPACK #-} !Oid -> {-# UNPACK #-} !Char -> {-# UNPACK #-} !Char -> !ByteString -> TypeInfo
typoid :: TypeInfo -> {-# UNPACK #-} !Oid
typcategory :: TypeInfo -> {-# UNPACK #-} !Char
typdelim :: TypeInfo -> {-# UNPACK #-} !Char
typname :: TypeInfo -> !ByteString
Array :: {-# UNPACK #-} !Oid -> {-# UNPACK #-} !Char -> {-# UNPACK #-} !Char -> !ByteString -> !TypeInfo -> TypeInfo
typoid :: TypeInfo -> {-# UNPACK #-} !Oid
typcategory :: TypeInfo -> {-# UNPACK #-} !Char
typdelim :: TypeInfo -> {-# UNPACK #-} !Char
typname :: TypeInfo -> !ByteString
typelem :: TypeInfo -> !TypeInfo
Range :: {-# UNPACK #-} !Oid -> {-# UNPACK #-} !Char -> {-# UNPACK #-} !Char -> !ByteString -> !TypeInfo -> TypeInfo
typoid :: TypeInfo -> {-# UNPACK #-} !Oid
typcategory :: TypeInfo -> {-# UNPACK #-} !Char
typdelim :: TypeInfo -> {-# UNPACK #-} !Char
typname :: TypeInfo -> !ByteString
rngsubtype :: TypeInfo -> !TypeInfo
Composite :: {-# UNPACK #-} !Oid -> {-# UNPACK #-} !Char -> {-# UNPACK #-} !Char -> !ByteString -> {-# UNPACK #-} !Oid -> !(Vector Attribute) -> TypeInfo
typoid :: TypeInfo -> {-# UNPACK #-} !Oid
typcategory :: TypeInfo -> {-# UNPACK #-} !Char
typdelim :: TypeInfo -> {-# UNPACK #-} !Char
typname :: TypeInfo -> !ByteString
typrelid :: TypeInfo -> {-# UNPACK #-} !Oid
attributes :: TypeInfo -> !(Vector Attribute)
data Attribute
Attribute :: !ByteString -> !TypeInfo -> Attribute
attname :: Attribute -> !ByteString
atttype :: Attribute -> !TypeInfo
typeInfo :: Field -> Conversion TypeInfo
typeInfoByOid :: Oid -> Conversion TypeInfo

-- | Returns the name of the column. This is often determined by a table
--   definition, but it can be set using an <tt>as</tt> clause.
name :: Field -> Maybe ByteString

-- | Returns the name of the object id of the <tt>table</tt> associated
--   with the column, if any. Returns <a>Nothing</a> when there is no such
--   table; for example a computed column does not have a table associated
--   with it. Analogous to libpq's <tt>PQftable</tt>.
tableOid :: Field -> Maybe Oid

-- | If the column has a table associated with it, this returns the number
--   off the associated table column. Numbering starts from 0. Analogous to
--   libpq's <tt>PQftablecol</tt>.
tableColumn :: Field -> Int

-- | This returns whether the data was returned in a binary or textual
--   format. Analogous to libpq's <tt>PQfformat</tt>.
format :: Field -> Format

-- | This returns the type oid associated with the column. Analogous to
--   libpq's <tt>PQftype</tt>.
typeOid :: Field -> Oid
newtype Oid :: *
Oid :: CUInt -> Oid
data Format :: *
Text :: Format
Binary :: Format

-- | Parse a field to a JSON <a>Value</a> and convert that into a Haskell
--   value using <a>fromJSON</a>.
--   
--   This can be used as the default implementation for the
--   <a>fromField</a> method for Haskell types that have a JSON
--   representation in PostgreSQL.
--   
--   The <a>Typeable</a> constraint is required to show more informative
--   error messages when parsing fails.
fromJSONField :: (FromJSON a, Typeable a) => FieldParser a
instance Typeable ResultError
instance Eq ResultError
instance Show ResultError
instance FromField a => FromField (MVar a)
instance FromField a => FromField (IORef a)
instance FromField Value
instance FromField UUID
instance (FromField a, Typeable a) => FromField (IOVector a)
instance (FromField a, Typeable a) => FromField (Vector a)
instance (FromField a, Typeable a) => FromField (PGArray a)
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 Char
instance FromField Bool
instance FromField Null
instance FromField a => FromField (Maybe a)
instance FromField ()
instance Exception ResultError


-- | Parsers and printers for hstore, a extended type bundled with
--   PostgreSQL providing finite maps from text strings to text strings.
--   See <a>http://www.postgresql.org/docs/9.2/static/hstore.html</a> for
--   more information.
--   
--   Note that in order to use this type, a database superuser must install
--   it by running a sql script in the share directory. This can be done on
--   PostgreSQL 9.1 and later with the command <tt>CREATE EXTENSION
--   hstore</tt>. See
--   <a>http://www.postgresql.org/docs/9.2/static/contrib.html</a> for more
--   information.
module Database.PostgreSQL.Simple.HStore
newtype HStoreList
HStoreList :: [(Text, Text)] -> HStoreList
fromHStoreList :: HStoreList -> [(Text, Text)]
newtype HStoreMap
HStoreMap :: Map Text Text -> HStoreMap
fromHStoreMap :: HStoreMap -> Map Text Text
class ToHStore a
toHStore :: ToHStore a => a -> HStoreBuilder

-- | Represents valid hstore syntax.
data HStoreBuilder
toBuilder :: HStoreBuilder -> Builder
toLazyByteString :: HStoreBuilder -> ByteString
hstore :: (ToHStoreText a, ToHStoreText b) => a -> b -> HStoreBuilder
class ToHStoreText a
toHStoreText :: ToHStoreText a => a -> HStoreText

-- | Represents escape text, ready to be the key or value to a hstore value
data HStoreText


-- | 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. The instances for <a>Maybe</a> types return <a>Nothing</a>
--   if all the columns that would have been otherwise consumed are null,
--   otherwise it attempts a regular conversion.
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 be 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 mysql-simple and very early versions of postgresql-simple no
--   longer apply. Instead, look at the caveats associated with
--   user-defined implementations of <a>fromField</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 (Maybe (Vector a))
instance FromField a => FromRow (Vector a)
instance FromField a => FromRow (Maybe [a])
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 (Maybe (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, 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 (Maybe (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, 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 (Maybe (a, b, c, d, e, f, g, h))
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 (Maybe (a, b, c, d, e, f, g))
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 (Maybe (a, b, c, d, e, f))
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 (Maybe (a, b, c, d, e))
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 (Maybe (a, b, c, d))
instance (FromField a, FromField b, FromField c, FromField d) => FromRow (a, b, c, d)
instance (FromField a, FromField b, FromField c) => FromRow (Maybe (a, b, c))
instance (FromField a, FromField b, FromField c) => FromRow (a, b, c)
instance (FromField a, FromField b) => FromRow (Maybe (a, b))
instance (FromField a, FromField b) => FromRow (a, b)
instance FromField a => FromRow (Maybe (Only a))
instance FromField a => FromRow (Only a)


-- | 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 be 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 mysql-simple and very early versions of postgresql-simple no
--   longer apply. Instead, look at the caveats associated with
--   user-defined implementations of <a>fromField</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
fromBinary :: Binary a -> 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 -> ExecStatus -> ByteString -> ByteString -> ByteString -> SqlError
sqlState :: SqlError -> ByteString
sqlExecStatus :: SqlError -> ExecStatus
sqlErrorMsg :: SqlError -> ByteString
sqlErrorDetail :: SqlError -> ByteString
sqlErrorHint :: SqlError -> ByteString
data ExecStatus :: *

-- | The string sent to the server was empty.
EmptyQuery :: ExecStatus

-- | Successful completion of a command returning no data.
CommandOk :: ExecStatus

-- | Successful completion of a command returning data (such as a SELECT or
--   SHOW).
TuplesOk :: ExecStatus

-- | Copy Out (from server) data transfer started.
CopyOut :: ExecStatus

-- | Copy In (to server) data transfer started.
CopyIn :: ExecStatus

-- | The server's response was not understood.
BadResponse :: ExecStatus

-- | A nonfatal error (a notice or warning) occurred.
NonfatalError :: ExecStatus

-- | A fatal error occurred.
FatalError :: ExecStatus

-- | 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]

-- | A version of <a>query</a> taking parser as argument
queryWith :: ToRow q => RowParser r -> Connection -> Query -> q -> IO [r]

-- | A version of <a>query_</a> taking parser as argument
queryWith_ :: RowParser 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.
--   
--   For nesting transactions, see <a>withSavepoint</a>.
withTransaction :: Connection -> IO a -> IO a

-- | Create a savepoint, and roll back to it if an error occurs. This may
--   only be used inside of a transaction, and provides a sort of "nested
--   transaction".
--   
--   See
--   <a>http://www.postgresql.org/docs/current/static/sql-savepoint.html</a>
withSavepoint :: Connection -> IO a -> IO a

-- | Begin a transaction.
begin :: 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 Exception FormatError


-- | mid-level support for COPY IN and COPY OUT. See
--   <a>http://www.postgresql.org/docs/9.2/static/sql-copy.html</a> for
--   more information.
--   
--   To use this binding, first call <a>copy</a> with an appropriate query
--   as documented in the link above. Then, in the case of a <tt>COPY TO
--   STDOUT</tt> query, call <a>getCopyData</a> repeatedly until it returns
--   <a>CopyOutDone</a>. In the case of a <tt>COPY FROM STDIN</tt> query,
--   call <a>putCopyData</a> repeatedly and then finish by calling either
--   <a>putCopyEnd</a> to proceed or <a>putCopyError</a> to abort.
--   
--   You cannot issue another query on the same connection while a copy is
--   ongoing; this will result in an exception. It is harmless to
--   concurrently call <tt>getNotification</tt> on a connection while it is
--   in a <tt>CopyIn</tt> or <tt>CopyOut</tt> state, however be aware that
--   current versions of the PostgreSQL backend will not deliver
--   notifications to a client while a transaction is ongoing.
module Database.PostgreSQL.Simple.Copy

-- | Issue a <tt>COPY FROM STDIN</tt> or <tt>COPY TO STDOUT</tt> query. In
--   the former case, the connection's state will change to
--   <tt>CopyIn</tt>; in the latter, <tt>CopyOut</tt>. The connection must
--   be in the ready state in order to call this function. Performs
--   parameter subsitution.
copy :: ToRow params => Connection -> Query -> params -> IO ()

-- | Issue a <tt>COPY FROM STDIN</tt> or <tt>COPY TO STDOUT</tt> query. In
--   the former case, the connection's state will change to
--   <tt>CopyIn</tt>; in the latter, <tt>CopyOut</tt>. The connection must
--   be in the ready state in order to call this function. Does not perform
--   parameter subsitution.
copy_ :: Connection -> Query -> IO ()
data CopyOutResult

-- | Data representing either exactly one row of the result, or header or
--   footer data depending on format.
CopyOutRow :: !ByteString -> CopyOutResult

-- | No more rows, and a count of the number of rows returned.
CopyOutDone :: {-# UNPACK #-} !Int64 -> CopyOutResult

-- | Retrieve some data from a <tt>COPY TO STDOUT</tt> query. A connection
--   must be in the <tt>CopyOut</tt> state in order to call this function.
--   If this returns a <a>CopyOutRow</a>, the connection remains in the
--   <tt>CopyOut</tt> state, if it returns <a>CopyOutDone</a>, then the
--   connection has reverted to the ready state.
getCopyData :: Connection -> IO CopyOutResult

-- | Feed some data to a <tt>COPY FROM STDIN</tt> query. Note that the data
--   does not need to represent a single row, or even an integral number of
--   rows. The net result of <tt>putCopyData conn a &gt;&gt; putCopyData
--   conn b</tt> is the same as <tt>putCopyData conn c</tt> whenever <tt>c
--   == BS.append a b</tt>.
--   
--   A connection must be in the <tt>CopyIn</tt> state in order to call
--   this function, otherwise a <a>SqlError</a> exception will result. The
--   connection remains in the <tt>CopyIn</tt> state after this function is
--   called.
putCopyData :: Connection -> ByteString -> IO ()

-- | Completes a <tt>COPY FROM STDIN</tt> query. Returns the number of rows
--   processed.
--   
--   A connection must be in the <tt>CopyIn</tt> state in order to call
--   this function, otherwise a <a>SqlError</a> exception will result. The
--   connection's state changes back to ready after this function is
--   called.
putCopyEnd :: Connection -> IO Int64

-- | Aborts a <tt>COPY FROM STDIN</tt> query. The string parameter is
--   simply an arbitrary error message that may show up in the PostgreSQL
--   server's log.
--   
--   A connection must be in the <tt>CopyIn</tt> state in order to call
--   this function, otherwise a <a>SqlError</a> exception will result. The
--   connection's state changes back to ready after this function is
--   called.
putCopyError :: Connection -> ByteString -> IO ()
instance Typeable CopyOutResult
instance Eq CopyOutResult
instance Show CopyOutResult
