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


-- | 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
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
array_record :: TypeInfo
regprocedure :: TypeInfo
regoper :: TypeInfo
regoperator :: TypeInfo
regclass :: TypeInfo
regtype :: TypeInfo
uuid :: TypeInfo
json :: TypeInfo
jsonb :: TypeInfo
int2vector :: TypeInfo
oidvector :: TypeInfo
array_xml :: TypeInfo
array_json :: TypeInfo
array_line :: TypeInfo
array_cidr :: TypeInfo
array_circle :: TypeInfo
array_money :: TypeInfo
array_bool :: TypeInfo
array_bytea :: TypeInfo
array_char :: TypeInfo
array_name :: TypeInfo
array_int2 :: TypeInfo
array_int2vector :: TypeInfo
array_int4 :: TypeInfo
array_regproc :: TypeInfo
array_text :: TypeInfo
array_tid :: TypeInfo
array_xid :: TypeInfo
array_cid :: TypeInfo
array_oidvector :: TypeInfo
array_bpchar :: TypeInfo
array_varchar :: TypeInfo
array_int8 :: TypeInfo
array_point :: TypeInfo
array_lseg :: TypeInfo
array_path :: TypeInfo
array_box :: TypeInfo
array_float4 :: TypeInfo
array_float8 :: TypeInfo
array_polygon :: TypeInfo
array_oid :: TypeInfo
array_macaddr :: TypeInfo
array_inet :: TypeInfo
array_timestamp :: TypeInfo
array_date :: TypeInfo
array_time :: TypeInfo
array_timestamptz :: TypeInfo
array_interval :: TypeInfo
array_numeric :: TypeInfo
array_timetz :: TypeInfo
array_bit :: TypeInfo
array_varbit :: TypeInfo
array_refcursor :: TypeInfo
array_regprocedure :: TypeInfo
array_regoper :: TypeInfo
array_regoperator :: TypeInfo
array_regclass :: TypeInfo
array_regtype :: TypeInfo
array_uuid :: TypeInfo
array_jsonb :: TypeInfo
int4range :: TypeInfo
_int4range :: TypeInfo
numrange :: TypeInfo
_numrange :: TypeInfo
tsrange :: TypeInfo
_tsrange :: TypeInfo
tstzrange :: TypeInfo
_tstzrange :: TypeInfo
daterange :: TypeInfo
_daterange :: TypeInfo
int8range :: TypeInfo
_int8range :: TypeInfo


-- | 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 GHC.Classes.Ord Database.PostgreSQL.Simple.Arrays.ArrayFormat
instance GHC.Show.Show Database.PostgreSQL.Simple.Arrays.ArrayFormat
instance GHC.Classes.Eq Database.PostgreSQL.Simple.Arrays.ArrayFormat


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

-- | Two <a>Errors</a> cases are considered equal, regardless of what the
--   list of exceptions looks like.

-- | a way to reify a list of exceptions into a single exception
newtype ManyErrors
ManyErrors :: [SomeException] -> ManyErrors
instance GHC.Show.Show Database.PostgreSQL.Simple.Ok.ManyErrors
instance GHC.Base.Functor Database.PostgreSQL.Simple.Ok.Ok
instance GHC.Show.Show a => GHC.Show.Show (Database.PostgreSQL.Simple.Ok.Ok a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Database.PostgreSQL.Simple.Ok.Ok a)
instance GHC.Base.Applicative Database.PostgreSQL.Simple.Ok.Ok
instance GHC.Base.Alternative Database.PostgreSQL.Simple.Ok.Ok
instance GHC.Base.MonadPlus Database.PostgreSQL.Simple.Ok.Ok
instance GHC.Base.Monad Database.PostgreSQL.Simple.Ok.Ok
instance GHC.Exception.Exception Database.PostgreSQL.Simple.Ok.ManyErrors


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

-- | Wrap text for use as sql identifier, i.e. a table or column name.
newtype Identifier
Identifier :: Text -> Identifier
[fromIdentifier] :: Identifier -> Text

-- | Wrap text for use as (maybe) qualified identifier, i.e. a table with
--   schema, or column with table.
data QualifiedIdentifier
QualifiedIdentifier :: (Maybe Text) -> Text -> QualifiedIdentifier

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

-- | Represents a <tt>VALUES</tt> table literal, usable as an alternative
--   to <tt>executeMany</tt> and <tt>returning</tt>. The main advantage is
--   that you can parametrize more than just a single <tt>VALUES</tt>
--   expression. For example, here's a query to insert a thing into one
--   table and some attributes of that thing into another, returning the
--   new id generated by the database:
--   
--   <pre>
--   query c [sql|
--       WITH new_thing AS (
--         INSERT INTO thing (name) VALUES (?) RETURNING id
--       ), new_attributes AS (
--         INSERT INTO thing_attributes
--            SELECT new_thing.id, attrs.*
--              FROM new_thing JOIN ? attrs
--       ) SELECT * FROM new_thing
--    |] ("foo", Values [  "int4", "text"    ]
--                      [ ( 1    , "hello" )
--                      , ( 2    , "world" ) ])
--   </pre>
--   
--   (Note this example uses writable common table expressions, which were
--   added in PostgreSQL 9.1)
--   
--   The second parameter gets expanded into the following SQL syntax:
--   
--   <pre>
--   (VALUES (1::"int4",'hello'::"text"),(2,'world'))
--   </pre>
--   
--   When the list of attributes is empty, the second parameter expands to:
--   
--   <pre>
--   (VALUES (null::"int4",null::"text") LIMIT 0)
--   </pre>
--   
--   By contrast, <tt>executeMany</tt> and <tt>returning</tt> don't issue
--   the query in the empty case, and simply return <tt>0</tt> and
--   <tt>[]</tt> respectively. This behavior is usually correct given their
--   intended use cases, but would certainly be wrong in the example above.
--   
--   The first argument is a list of postgresql type names. Because this is
--   turned into a properly quoted identifier, the type name is case
--   sensitive and must be as it appears in the <tt>pg_type</tt> table.
--   Thus, you must write <tt>timestamptz</tt> instead of <tt>timestamp
--   with time zone</tt>, <tt>int4</tt> instead of <tt>integer</tt>,
--   <tt>_int8</tt> instead of <tt>bigint[]</tt>, etcetera.
--   
--   You may omit the type names, however, if you do so the list of values
--   must be non-empty, and postgresql must be able to infer the types of
--   the columns from the surrounding context. If the first condition is
--   not met, postgresql-simple will throw an exception without issuing the
--   query. In the second case, the postgres server will return an error
--   which will be turned into a <tt>SqlError</tt> exception.
--   
--   See <a>http://www.postgresql.org/docs/9.3/static/sql-values.html</a>
--   for more information.
data Values a
Values :: [QualifiedIdentifier] -> [a] -> Values a
instance GHC.Read.Read a => GHC.Read.Read (Database.PostgreSQL.Simple.Types.Values a)
instance GHC.Show.Show a => GHC.Show.Show (Database.PostgreSQL.Simple.Types.Values a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Database.PostgreSQL.Simple.Types.Values a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Database.PostgreSQL.Simple.Types.Values a)
instance GHC.Read.Read Database.PostgreSQL.Simple.Types.Savepoint
instance GHC.Show.Show Database.PostgreSQL.Simple.Types.Savepoint
instance GHC.Classes.Ord Database.PostgreSQL.Simple.Types.Savepoint
instance GHC.Classes.Eq Database.PostgreSQL.Simple.Types.Savepoint
instance (GHC.Read.Read h, GHC.Read.Read t) => GHC.Read.Read (h Database.PostgreSQL.Simple.Types.:. t)
instance (GHC.Show.Show h, GHC.Show.Show t) => GHC.Show.Show (h Database.PostgreSQL.Simple.Types.:. t)
instance (GHC.Classes.Ord h, GHC.Classes.Ord t) => GHC.Classes.Ord (h Database.PostgreSQL.Simple.Types.:. t)
instance (GHC.Classes.Eq h, GHC.Classes.Eq t) => GHC.Classes.Eq (h Database.PostgreSQL.Simple.Types.:. t)
instance GHC.Base.Functor Database.PostgreSQL.Simple.Types.PGArray
instance GHC.Show.Show a => GHC.Show.Show (Database.PostgreSQL.Simple.Types.PGArray a)
instance GHC.Read.Read a => GHC.Read.Read (Database.PostgreSQL.Simple.Types.PGArray a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Database.PostgreSQL.Simple.Types.PGArray a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Database.PostgreSQL.Simple.Types.PGArray a)
instance GHC.Show.Show Database.PostgreSQL.Simple.Types.QualifiedIdentifier
instance GHC.Read.Read Database.PostgreSQL.Simple.Types.QualifiedIdentifier
instance GHC.Classes.Ord Database.PostgreSQL.Simple.Types.QualifiedIdentifier
instance GHC.Classes.Eq Database.PostgreSQL.Simple.Types.QualifiedIdentifier
instance Data.String.IsString Database.PostgreSQL.Simple.Types.Identifier
instance GHC.Show.Show Database.PostgreSQL.Simple.Types.Identifier
instance GHC.Read.Read Database.PostgreSQL.Simple.Types.Identifier
instance GHC.Classes.Ord Database.PostgreSQL.Simple.Types.Identifier
instance GHC.Classes.Eq Database.PostgreSQL.Simple.Types.Identifier
instance GHC.Base.Functor Database.PostgreSQL.Simple.Types.Binary
instance GHC.Show.Show a => GHC.Show.Show (Database.PostgreSQL.Simple.Types.Binary a)
instance GHC.Read.Read a => GHC.Read.Read (Database.PostgreSQL.Simple.Types.Binary a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Database.PostgreSQL.Simple.Types.Binary a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Database.PostgreSQL.Simple.Types.Binary a)
instance GHC.Base.Functor Database.PostgreSQL.Simple.Types.In
instance GHC.Show.Show a => GHC.Show.Show (Database.PostgreSQL.Simple.Types.In a)
instance GHC.Read.Read a => GHC.Read.Read (Database.PostgreSQL.Simple.Types.In a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Database.PostgreSQL.Simple.Types.In a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Database.PostgreSQL.Simple.Types.In a)
instance GHC.Base.Functor Database.PostgreSQL.Simple.Types.Only
instance GHC.Show.Show a => GHC.Show.Show (Database.PostgreSQL.Simple.Types.Only a)
instance GHC.Read.Read a => GHC.Read.Read (Database.PostgreSQL.Simple.Types.Only a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Database.PostgreSQL.Simple.Types.Only a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Database.PostgreSQL.Simple.Types.Only a)
instance GHC.Classes.Ord Database.PostgreSQL.Simple.Types.Query
instance GHC.Classes.Eq Database.PostgreSQL.Simple.Types.Query
instance GHC.Show.Show Database.PostgreSQL.Simple.Types.Default
instance GHC.Read.Read Database.PostgreSQL.Simple.Types.Default
instance GHC.Show.Show Database.PostgreSQL.Simple.Types.Null
instance GHC.Read.Read Database.PostgreSQL.Simple.Types.Null
instance GHC.Classes.Eq Database.PostgreSQL.Simple.Types.Null
instance GHC.Show.Show Database.PostgreSQL.Simple.Types.Query
instance GHC.Read.Read Database.PostgreSQL.Simple.Types.Query
instance Data.String.IsString Database.PostgreSQL.Simple.Types.Query
instance GHC.Base.Monoid Database.PostgreSQL.Simple.Types.Query
instance Data.Hashable.Class.Hashable Database.PostgreSQL.Simple.Types.Identifier
instance Data.Hashable.Class.Hashable Database.PostgreSQL.Simple.Types.QualifiedIdentifier
instance Data.String.IsString Database.PostgreSQL.Simple.Types.QualifiedIdentifier


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


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 returns a literal string expression of type
--   <a>Query</a>, and 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 "--".
--   
--   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


-- | This module provides time types that supports positive and negative
--   infinity, as well as some functions for converting to and from
--   strings.
--   
--   Also, this module also contains commentary regarding postgresql's
--   timestamp types, civil timekeeping in general, and how it relates to
--   postgresql-simple. 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 the IANA time zone database at
--   <a>https://en.wikipedia.org/wiki/Tz_database</a>.
--   
--   Stack Overflow also has some excellent commentary on time, if it is a
--   wiki page or a highly upvoted question and answer. If the answer
--   regarding time has not received about a hundred upvotes at least, then
--   the answer is almost invariably completely and painfully wrong, even
--   if it's the chosen answer or the most highly upvoted answer to a
--   question.
--   
--   PostgreSQL's <tt>timestamp with time zone</tt> (hereafter,
--   <tt>timestamptz</tt>) can be converted to Haskell's <a>UTCTime</a> and
--   <a>ZonedTime</a> types, because values of these types represent a
--   self-contained, unambiguous point in time. PostgreSQL's <tt>timestamp
--   without time zone</tt> (hereafter, <tt>timestamp</tt>) can be
--   converted to Haskell's <a>LocalTime</a>, because values of these types
--   are ambiguous by themselves, and require context to disambiguate.
--   
--   While this behavior may be superficially counterintuitive because the
--   names might suggest otherwise, this behavior is correct. In fact, the
--   "timezone" language in both the postgresql and haskell types would be
--   better read as "offset (from UTC)", thus we have postgresql's
--   "timestamp with offset" corresponding to Haskell's "time with the
--   offset 'zero'" and Haskell's "time with an offset (that might be
--   nonzero)". Similarly, postgresql's "timestamp without an offset"
--   corresponds to Haskell's "local time (without an offset)".
--   
--   It's important to distinguish between an offset, a standard time, and
--   a time zone. An offset is simply a difference of a local time from
--   UTC, such as <tt>+00</tt>, <tt>-05</tt>, or <tt>+05:30</tt>. A
--   standard time specifies an offset (which may vary throughout the year,
--   due to daylight savings) that a region follows, such as Universal
--   Coordinated Time (UTC), Eastern Standard Time/Eastern Daylight Time
--   (EST/EDT), or India Standard Time (IST). And a time zone, much like a
--   standard time, is a function from timestamps to offsets.
--   
--   A time zone is different from a standard time because different
--   regions inside a standard time can be governed by different civil
--   authorities with different laws and thus have different histories of
--   civil time. An IANA time zone is any region of the world that has had
--   the same history of civil time since <tt>1970-01-01 00:00+00</tt>.
--   
--   For example, as of today, both <tt>America/New_York</tt> and
--   <tt>America/Indiana/Indianapolis</tt> are on the EST/EDT time
--   standard, but Indiana used to be on Central Standard Time until 1942,
--   and did not observe daylight savings time (EST only) until 2006. Thus,
--   the choice between these two time zones still matters if you are
--   dealing with timestamps prior to 2006, and could become relevant again
--   if (most of) Indiana moves back to Central Time. (Of course, if the
--   Central to Eastern switch was the only difference, then these two time
--   zones would be the same in IANA's eyes, due to their cutoff date of
--   1970-01-01.)
--   
--   Getting back to practicalities, PostgreSQL's <tt>timestamptz</tt> type
--   does not actually store an offset; rather, it uses the offset provided
--   to calculate UTC, and stores the timestamp as UTC. If an offset is not
--   provided, the given timestamp is assumed to be a local time for
--   whatever the <tt>timezone</tt> variable is set to, and the IANA TZ
--   database is consulted to calculate an offset from UTC for the time in
--   question.
--   
--   Note that while most (local timestamp, time zone) pairs correspond to
--   exactly one UTC timestamp, some correspond to two UTC timestamps,
--   while others correspond to none at all. The ambiguous case occurs when
--   the civil time is rolled back, making a calendar day longer than 24
--   hours. In this case, PostgreSQL silently chooses the second, later
--   possibility. The inconsistent case occurs when the civil time is moved
--   forward, making a calendar day less than 24 hours. In this case,
--   PostgreSQL silently assumes the local time was read off a clock that
--   had not been moved forward at the prescribed time, and moves the clock
--   forward for you. Thus, converting from local time to UTC need not be
--   monotonic, if these inconsistent cases are allowed.
--   
--   When retrieving a <tt>timestamptz</tt>, the backend looks at the
--   <tt>time zone</tt> connection variable and then consults the IANA TZ
--   database to calculate an offset for the timestamp in the given time
--   zone.
--   
--   Note that while some of the information contained in the IANA TZ
--   database is a bit of a standardized fiction, the conversion from UTC
--   time to a (local time, offset) pair in a particular time zone is
--   always unambiguous, and the result can always be unambiguously
--   converted back to UTC. Thus, postgresql-simple can interpret such a
--   result as a <a>ZonedTime</a>, or use the offset to convert back to
--   <a>UTCTime</a>.
--   
--   By contrast, the <tt>timestamp</tt> type ignores any offsets provided
--   to it, and never sends back an offset. Thus, postgresql-simple equates
--   this with <a>LocalTime</a>, which has no concept of an offset. One can
--   convert between <tt>timestamptz</tt> and <tt>timestamp</tt> using the
--   <tt>AT TIME ZONE</tt> operator, whose semantics also demonstrates that
--   <tt>timestamptz</tt> is <a>UTCTime</a> whereas <tt>timestamp</tt> is
--   <a>LocalTime</a>.
--   
--   PostgreSQL's <tt>timezone</tt> is a per-connection variable that by
--   default is initialized to <tt>'localtime'</tt>, which normally
--   corresponds to the server's time zone. However, this default can be
--   modified on the server side for an entire cluster, or on a per-user or
--   per-database basis. Moreover, a client can modify their instance of
--   the variable at any time, and can apply that change to the remaining
--   duration of the connection, the current transaction, or the execution
--   context of a server-side function. In addition, upon connection
--   initialization, the libpq client checks for the existence of the
--   <tt>PGTZ</tt> environment variable, and if it exists, modifies
--   <tt>timezone</tt> accordingly.
--   
--   With a few caveats, postgresql-simple is designed so that you can both
--   send and receive timestamps with the server and get a correct result,
--   no matter what the <tt>timezone</tt> setting is. But it is important
--   to understand the caveats:
--   
--   <ol>
--   <li>The correctness of server-side computations can depend on the
--   <tt>timezone</tt> setting. Examples include adding an
--   <tt>interval</tt> to a <tt>timestamptz</tt>, or type casting between
--   <tt>timestamp</tt> and <tt>timestamptz</tt>, or applying the
--   <tt>DATE</tt> function to a <tt>timestamptz</tt>.</li>
--   <li>The (localtime, offset) pair contained in a <a>ZonedTime</a>
--   result will depend on the <tt>timezone</tt> setting, although the
--   result will always represent the same instant in time regardless of
--   the time zone.</li>
--   <li>Sending a <a>LocalTime</a> and interpreting it as a
--   <tt>timestamptz</tt> can be useful, as it will be converted to UTC via
--   the tz database, but correctness will depend on the <tt>timezone</tt>
--   setting. You may prefer to use an explicit <tt>AT TIME ZONE</tt>
--   conversion instead, which would avoid this contextual dependence.</li>
--   </ol>
--   
--   Furthermore, although these following points don't involve the
--   <tt>timezone</tt> setting, they are related to the last point above:
--   
--   <ol>
--   <li>Sending a <a>UTCTime</a> and interpreting it as a
--   <tt>timestamp</tt> can be useful. In practice, the most common context
--   used to disambiguate <tt>timestamp</tt> is that it represents UTC, and
--   this coding technique will work as expected in this situation.</li>
--   <li>Sending a <a>ZonedTime</a> and interpreting it as a
--   <tt>timestamp</tt> is almost always the wrong thing to do, as the
--   offset will be ignored and discarded. This is likely to lead to
--   inconsistencies in the database, and may lead to partial data
--   loss.</li>
--   </ol>
--   
--   When dealing with local timestamps that refer to the future, it is
--   often useful to store it as a local time in a <tt>timestamp</tt>
--   column and store the time zone in a second column. One reason to do
--   this is so that you can convert to UTC on the fly as needed, and be
--   protected against future changes to the TZ database due to changes in
--   local time standards. In any case, <a>ZonedTime</a> is not suitable
--   for this application, because despite its name, it represents an
--   offset and not a time zone. Time zones can change; offsets do not. In
--   reality, we can't convert a local timestamp that occurs sufficiently
--   far in the future to UTC, because we don't know how to do it yet.
--   
--   There are a few limitations and caveats that one might need to be
--   aware of with the current implementation when dealing with older
--   timestamps:
--   
--   For sufficiently old timestamps in almost all time zones, the IANA TZ
--   database specifies offsets from UTC that is not an integral number of
--   minutes. This corresponds to local mean time; that is, astronomical
--   time in the city that defines the time zone. Different time zones
--   moved away from local mean time to a standard time at different points
--   in history, so "sufficiently old" depends on the time zone in
--   question.
--   
--   Thus, when retrieving a <tt>timestamptz</tt> postgresql will in some
--   cases provide seconds in the offset. For example:
--   
--   <pre>
--   $ psql
--   psql (9.4.5)
--   Type "help" for help.
--   
--   lpsmith=&gt; SET timezone TO 'America/New_York';
--   SET
--   lpsmith=&gt; VALUES ('1883-11-18 16:59:59+00'::timestamptz),
--                    ('1883-11-18 17:00:00+00'::timestamptz);
--              column1
--   ------------------------------
--    1883-11-18 12:03:57-04:56:02
--    1883-11-18 12:00:00-05
--   (2 rows)
--   </pre>
--   
--   Both of these timestamps can be parsed as a <a>UTCTime</a> type,
--   however <a>ZonedTime</a> will fail on the former timestamp. Because
--   <a>ZonedTime</a> assumes that offsets are an integer number of
--   minutes, there isn't an particularly good solution here.
--   
--   PostgreSQL, like most software, uses the proleptic Gregorian calendar
--   for its date calculations, extending the Gregorian calendar backwards
--   in time before its introduction and pretending that the Julian
--   calendar does not exist. For most purposes, the adoption of the
--   Gregorian calendar ranges from <tt>1582-10-15</tt> to
--   <tt>1923-03-01</tt>, depending on location and sometimes even
--   political allegiances within a single location.
--   
--   Timestamps BCE are not supported. For example, PostgreSQL will emit
--   "<tt>0045-01-01 BC</tt>" for the first proleptic Gregorian day of the
--   year the Roman Empire adopted the Julian Calendar, but
--   postgresql-simple does not (yet?) have the ability to either parse or
--   generate this syntax. Unfortunately this syntax isn't convenient to
--   print or especially parse.
--   
--   Also, postgresql itself cannot parse or print dates before
--   <tt>4714-11-24 BC</tt>, which is the Julian date on the proleptic
--   Gregorian Calendar. Although postgresql's timestamp types are
--   perfectly capable of representing timestamps nearly 300,000 years in
--   the past, using this would require postgresql-simple and other client
--   programs to support binary parameters and results.
--   
--   Dealing with years BCE is also complicated slightly by the fact that
--   Haskell's time library has a year "0000", which is a convention often
--   used by astronomers, while postgresql adopts the more historically
--   accurate convention that there is no year zero, but rather "1 BCE" was
--   immediately followed by "1 CE".
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)
nominalDiffTimeToBuilder :: NominalDiffTime -> Builder


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

-- | Escape before substituting. Use for all sql identifiers like table,
--   column names, etc. This is used by the <a>Identifier</a> newtype
--   wrapper.
EscapeIdentifier :: 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

-- | Prepare a value for substitution into a query string.
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 GHC.Show.Show Database.PostgreSQL.Simple.ToField.Action
instance Database.PostgreSQL.Simple.ToField.ToField Database.PostgreSQL.Simple.ToField.Action
instance Database.PostgreSQL.Simple.ToField.ToField a => Database.PostgreSQL.Simple.ToField.ToField (GHC.Base.Maybe a)
instance Database.PostgreSQL.Simple.ToField.ToField a => Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Types.In [a])
instance Database.PostgreSQL.Simple.ToField.ToField Database.PostgreSQL.Simple.Types.Null
instance Database.PostgreSQL.Simple.ToField.ToField Database.PostgreSQL.Simple.Types.Default
instance Database.PostgreSQL.Simple.ToField.ToField GHC.Types.Bool
instance Database.PostgreSQL.Simple.ToField.ToField GHC.Int.Int8
instance Database.PostgreSQL.Simple.ToField.ToField GHC.Int.Int16
instance Database.PostgreSQL.Simple.ToField.ToField GHC.Int.Int32
instance Database.PostgreSQL.Simple.ToField.ToField GHC.Types.Int
instance Database.PostgreSQL.Simple.ToField.ToField GHC.Int.Int64
instance Database.PostgreSQL.Simple.ToField.ToField GHC.Integer.Type.Integer
instance Database.PostgreSQL.Simple.ToField.ToField GHC.Word.Word8
instance Database.PostgreSQL.Simple.ToField.ToField GHC.Word.Word16
instance Database.PostgreSQL.Simple.ToField.ToField GHC.Word.Word32
instance Database.PostgreSQL.Simple.ToField.ToField GHC.Types.Word
instance Database.PostgreSQL.Simple.ToField.ToField GHC.Word.Word64
instance Database.PostgreSQL.Simple.ToField.ToField Database.PostgreSQL.LibPQ.Oid
instance Database.PostgreSQL.Simple.ToField.ToField GHC.Types.Float
instance Database.PostgreSQL.Simple.ToField.ToField GHC.Types.Double
instance Database.PostgreSQL.Simple.ToField.ToField Data.Scientific.Scientific
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Types.Binary Data.ByteString.Internal.ByteString)
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Types.Binary Data.ByteString.Lazy.Internal.ByteString)
instance Database.PostgreSQL.Simple.ToField.ToField Database.PostgreSQL.Simple.Types.Identifier
instance Database.PostgreSQL.Simple.ToField.ToField Database.PostgreSQL.Simple.Types.QualifiedIdentifier
instance Database.PostgreSQL.Simple.ToField.ToField Data.ByteString.Internal.ByteString
instance Database.PostgreSQL.Simple.ToField.ToField Data.ByteString.Lazy.Internal.ByteString
instance Database.PostgreSQL.Simple.ToField.ToField Data.Text.Internal.Text
instance Database.PostgreSQL.Simple.ToField.ToField [GHC.Types.Char]
instance Database.PostgreSQL.Simple.ToField.ToField Data.Text.Internal.Lazy.Text
instance Database.PostgreSQL.Simple.ToField.ToField Data.Time.Clock.UTC.UTCTime
instance Database.PostgreSQL.Simple.ToField.ToField Data.Time.LocalTime.LocalTime.ZonedTime
instance Database.PostgreSQL.Simple.ToField.ToField Data.Time.LocalTime.LocalTime.LocalTime
instance Database.PostgreSQL.Simple.ToField.ToField Data.Time.Calendar.Days.Day
instance Database.PostgreSQL.Simple.ToField.ToField Data.Time.LocalTime.TimeOfDay.TimeOfDay
instance Database.PostgreSQL.Simple.ToField.ToField Database.PostgreSQL.Simple.Time.Implementation.UTCTimestamp
instance Database.PostgreSQL.Simple.ToField.ToField Database.PostgreSQL.Simple.Time.Implementation.ZonedTimestamp
instance Database.PostgreSQL.Simple.ToField.ToField Database.PostgreSQL.Simple.Time.Implementation.LocalTimestamp
instance Database.PostgreSQL.Simple.ToField.ToField Database.PostgreSQL.Simple.Time.Implementation.Date
instance Database.PostgreSQL.Simple.ToField.ToField Data.Time.Clock.UTC.NominalDiffTime
instance Database.PostgreSQL.Simple.ToField.ToField a => Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Types.PGArray a)
instance Database.PostgreSQL.Simple.ToField.ToField a => Database.PostgreSQL.Simple.ToField.ToField (Data.Vector.Vector a)
instance Database.PostgreSQL.Simple.ToField.ToField Data.UUID.Types.Internal.UUID
instance Database.PostgreSQL.Simple.ToField.ToField Data.Aeson.Types.Internal.Value
instance Database.PostgreSQL.Simple.ToRow.ToRow a => Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Types.Values a)


-- | 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 <a>toField</a> method of the <a>ToField</a>
--   class to perform conversion of each element of the collection.
class ToRow a where toRow = gtoRow . from
toRow :: ToRow a => a -> [Action]
instance Database.PostgreSQL.Simple.ToRow.ToRow ()
instance Database.PostgreSQL.Simple.ToField.ToField a => Database.PostgreSQL.Simple.ToRow.ToRow (Database.PostgreSQL.Simple.Types.Only a)
instance (Database.PostgreSQL.Simple.ToField.ToField a, Database.PostgreSQL.Simple.ToField.ToField b) => Database.PostgreSQL.Simple.ToRow.ToRow (a, b)
instance (Database.PostgreSQL.Simple.ToField.ToField a, Database.PostgreSQL.Simple.ToField.ToField b, Database.PostgreSQL.Simple.ToField.ToField c) => Database.PostgreSQL.Simple.ToRow.ToRow (a, b, c)
instance (Database.PostgreSQL.Simple.ToField.ToField a, Database.PostgreSQL.Simple.ToField.ToField b, Database.PostgreSQL.Simple.ToField.ToField c, Database.PostgreSQL.Simple.ToField.ToField d) => Database.PostgreSQL.Simple.ToRow.ToRow (a, b, c, d)
instance (Database.PostgreSQL.Simple.ToField.ToField a, Database.PostgreSQL.Simple.ToField.ToField b, Database.PostgreSQL.Simple.ToField.ToField c, Database.PostgreSQL.Simple.ToField.ToField d, Database.PostgreSQL.Simple.ToField.ToField e) => Database.PostgreSQL.Simple.ToRow.ToRow (a, b, c, d, e)
instance (Database.PostgreSQL.Simple.ToField.ToField a, Database.PostgreSQL.Simple.ToField.ToField b, Database.PostgreSQL.Simple.ToField.ToField c, Database.PostgreSQL.Simple.ToField.ToField d, Database.PostgreSQL.Simple.ToField.ToField e, Database.PostgreSQL.Simple.ToField.ToField f) => Database.PostgreSQL.Simple.ToRow.ToRow (a, b, c, d, e, f)
instance (Database.PostgreSQL.Simple.ToField.ToField a, Database.PostgreSQL.Simple.ToField.ToField b, Database.PostgreSQL.Simple.ToField.ToField c, Database.PostgreSQL.Simple.ToField.ToField d, Database.PostgreSQL.Simple.ToField.ToField e, Database.PostgreSQL.Simple.ToField.ToField f, Database.PostgreSQL.Simple.ToField.ToField g) => Database.PostgreSQL.Simple.ToRow.ToRow (a, b, c, d, e, f, g)
instance (Database.PostgreSQL.Simple.ToField.ToField a, Database.PostgreSQL.Simple.ToField.ToField b, Database.PostgreSQL.Simple.ToField.ToField c, Database.PostgreSQL.Simple.ToField.ToField d, Database.PostgreSQL.Simple.ToField.ToField e, Database.PostgreSQL.Simple.ToField.ToField f, Database.PostgreSQL.Simple.ToField.ToField g, Database.PostgreSQL.Simple.ToField.ToField h) => Database.PostgreSQL.Simple.ToRow.ToRow (a, b, c, d, e, f, g, h)
instance (Database.PostgreSQL.Simple.ToField.ToField a, Database.PostgreSQL.Simple.ToField.ToField b, Database.PostgreSQL.Simple.ToField.ToField c, Database.PostgreSQL.Simple.ToField.ToField d, Database.PostgreSQL.Simple.ToField.ToField e, Database.PostgreSQL.Simple.ToField.ToField f, Database.PostgreSQL.Simple.ToField.ToField g, Database.PostgreSQL.Simple.ToField.ToField h, Database.PostgreSQL.Simple.ToField.ToField i) => Database.PostgreSQL.Simple.ToRow.ToRow (a, b, c, d, e, f, g, h, i)
instance (Database.PostgreSQL.Simple.ToField.ToField a, Database.PostgreSQL.Simple.ToField.ToField b, Database.PostgreSQL.Simple.ToField.ToField c, Database.PostgreSQL.Simple.ToField.ToField d, Database.PostgreSQL.Simple.ToField.ToField e, Database.PostgreSQL.Simple.ToField.ToField f, Database.PostgreSQL.Simple.ToField.ToField g, Database.PostgreSQL.Simple.ToField.ToField h, Database.PostgreSQL.Simple.ToField.ToField i, Database.PostgreSQL.Simple.ToField.ToField j) => Database.PostgreSQL.Simple.ToRow.ToRow (a, b, c, d, e, f, g, h, i, j)
instance Database.PostgreSQL.Simple.ToField.ToField a => Database.PostgreSQL.Simple.ToRow.ToRow [a]
instance (Database.PostgreSQL.Simple.ToRow.ToRow a, Database.PostgreSQL.Simple.ToRow.ToRow b) => Database.PostgreSQL.Simple.ToRow.ToRow (a Database.PostgreSQL.Simple.Types.:. b)
instance Database.PostgreSQL.Simple.ToRow.GToRow f => Database.PostgreSQL.Simple.ToRow.GToRow (GHC.Generics.M1 c i f)
instance (Database.PostgreSQL.Simple.ToRow.GToRow f, Database.PostgreSQL.Simple.ToRow.GToRow g) => Database.PostgreSQL.Simple.ToRow.GToRow (f GHC.Generics.:*: g)
instance Database.PostgreSQL.Simple.ToField.ToField a => Database.PostgreSQL.Simple.ToRow.GToRow (GHC.Generics.K1 GHC.Generics.R a)
instance Database.PostgreSQL.Simple.ToRow.GToRow GHC.Generics.U1


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

-- | 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
FormatError :: String -> Query -> [ByteString] -> FormatError
[fmtMessage] :: FormatError -> String
[fmtQuery] :: FormatError -> Query
[fmtParams] :: FormatError -> [ByteString]
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.3/static/libpq-connect.html#LIBPQ-CONNSTRING</a>
--   for more information. Also note that environment variables also affect
--   parameters not provided, parameters provided as the empty string, and
--   a few other things; see
--   <a>http://www.postgresql.org/docs/9.3/static/libpq-envars.html</a> for
--   details. Here is an example with some of the most commonly used
--   parameters:
--   
--   <pre>
--   host='db.somedomain.com' port=5432 ...
--   </pre>
--   
--   This attempts to connect to <tt>db.somedomain.com:5432</tt>. Omitting
--   the port will normally default to 5432.
--   
--   On systems that provide unix domain sockets, omitting the host
--   parameter will cause libpq to attempt to connect via unix domain
--   sockets. The default filesystem path to the socket is constructed from
--   the port number and the <tt>DEFAULT_PGSOCKET_DIR</tt> constant defined
--   in the <tt>pg_config_manual.h</tt> header file. Connecting via unix
--   sockets tends to use the <tt>peer</tt> authentication method, which is
--   very secure and does not require a password.
--   
--   On Windows and other systems without unix domain sockets, omitting the
--   host will default to <tt>localhost</tt>.
--   
--   <pre>
--   ... dbname='postgres' user='postgres' password='secret \' \\ pw'
--   </pre>
--   
--   This attempts to connect to a database named <tt>postgres</tt> with
--   user <tt>postgres</tt> and password <tt>secret ' \ pw</tt>. Backslash
--   characters will have to be double-quoted in literal Haskell strings,
--   of course. Omitting <tt>dbname</tt> and <tt>user</tt> will both
--   default to the system username that the client process is running as.
--   
--   Omitting <tt>password</tt> will default to an appropriate password
--   found in the <tt>pgpass</tt> file, or no password at all if a matching
--   line is not found. See
--   <a>http://www.postgresql.org/docs/9.3/static/libpq-pgpass.html</a> for
--   more information regarding this file.
--   
--   As all parameters are optional and the defaults are sensible, the
--   empty connection string can be useful for development and exploratory
--   use, assuming your system is set up appropriately.
--   
--   On Unix, such a setup would typically consist of a local postgresql
--   server listening on port 5432, as well as a system user, database
--   user, and database sharing a common name, with permissions granted to
--   the user on the database.
--   
--   On Windows, in addition you will either need <tt>pg_hba.conf</tt> to
--   specify the use of the <tt>trust</tt> authentication method for the
--   connection, which may not be appropriate for multiuser or production
--   machines, or you will need to use a <tt>pgpass</tt> file with the
--   <tt>password</tt> or <tt>md5</tt> authentication methods.
--   
--   See
--   <a>http://www.postgresql.org/docs/9.3/static/client-authentication.html</a>
--   for more information regarding the authentication process.
--   
--   SSL/TLS will typically "just work" if your postgresql server supports
--   or requires it. However, note that libpq is trivially vulnerable to a
--   MITM attack without setting additional SSL parameters in the
--   connection string. In particular, <tt>sslmode</tt> needs to be set to
--   <tt>require</tt>, <tt>verify-ca</tt>, or <tt>verify-full</tt> in order
--   to perform certificate validation. When <tt>sslmode</tt> is
--   <tt>require</tt>, then you will also need to specify a
--   <tt>sslrootcert</tt> file, otherwise no validation of the server's
--   identity will be performed. Client authentication via certificates is
--   also possible via the <tt>sslcert</tt> and <tt>sslkey</tt> parameters.
connectPostgreSQL :: ByteString -> IO Connection
connectdb :: 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
libPQError :: ByteString -> IOError
throwLibPQError :: Connection -> ByteString -> IO a
fmtError :: String -> Query -> [Action] -> a
fmtErrorBs :: Query -> [Action] -> ByteString -> a

-- | Quote bytestring or throw <a>FormatError</a>
quote :: Query -> [Action] -> Either ByteString ByteString -> Builder
buildAction :: Connection -> Query -> [Action] -> Action -> IO Builder
checkError :: Connection -> Maybe a -> IO (Either ByteString a)
escapeWrap :: (Connection -> ByteString -> IO (Maybe ByteString)) -> Connection -> ByteString -> IO (Either ByteString ByteString)
escapeStringConn :: Connection -> ByteString -> IO (Either ByteString ByteString)
escapeIdentifier :: Connection -> ByteString -> IO (Either ByteString ByteString)
escapeByteaConn :: Connection -> ByteString -> IO (Either ByteString ByteString)
instance GHC.Base.Monad Database.PostgreSQL.Simple.Internal.RowParser
instance GHC.Base.Alternative Database.PostgreSQL.Simple.Internal.RowParser
instance GHC.Base.Applicative Database.PostgreSQL.Simple.Internal.RowParser
instance GHC.Base.Functor Database.PostgreSQL.Simple.Internal.RowParser
instance GHC.Show.Show Database.PostgreSQL.Simple.Internal.ConnectInfo
instance GHC.Read.Read Database.PostgreSQL.Simple.Internal.ConnectInfo
instance GHC.Classes.Eq Database.PostgreSQL.Simple.Internal.ConnectInfo
instance GHC.Show.Show Database.PostgreSQL.Simple.Internal.FormatError
instance GHC.Classes.Eq Database.PostgreSQL.Simple.Internal.FormatError
instance GHC.Show.Show Database.PostgreSQL.Simple.Internal.QueryError
instance GHC.Classes.Eq Database.PostgreSQL.Simple.Internal.QueryError
instance GHC.Show.Show Database.PostgreSQL.Simple.Internal.SqlError
instance GHC.Classes.Eq Database.PostgreSQL.Simple.Internal.Connection
instance GHC.Exception.Exception Database.PostgreSQL.Simple.Internal.SqlError
instance GHC.Exception.Exception Database.PostgreSQL.Simple.Internal.QueryError
instance GHC.Exception.Exception Database.PostgreSQL.Simple.Internal.FormatError
instance GHC.Base.Functor Database.PostgreSQL.Simple.Internal.Conversion
instance GHC.Base.Applicative Database.PostgreSQL.Simple.Internal.Conversion
instance GHC.Base.Alternative Database.PostgreSQL.Simple.Internal.Conversion
instance GHC.Base.Monad Database.PostgreSQL.Simple.Internal.Conversion
instance GHC.Base.MonadPlus Database.PostgreSQL.Simple.Internal.Conversion


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

-- | Name of the exclusion violation constraint
ExclusionViolation :: 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 GHC.Classes.Ord Database.PostgreSQL.Simple.Errors.ConstraintViolation
instance GHC.Classes.Eq Database.PostgreSQL.Simple.Errors.ConstraintViolation
instance GHC.Show.Show Database.PostgreSQL.Simple.Errors.ConstraintViolation
instance GHC.Exception.Exception Database.PostgreSQL.Simple.Errors.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 GHC.Classes.Eq Database.PostgreSQL.Simple.Transaction.TransactionMode
instance GHC.Show.Show Database.PostgreSQL.Simple.Transaction.TransactionMode
instance GHC.Enum.Bounded Database.PostgreSQL.Simple.Transaction.ReadWriteMode
instance GHC.Enum.Enum Database.PostgreSQL.Simple.Transaction.ReadWriteMode
instance GHC.Classes.Ord Database.PostgreSQL.Simple.Transaction.ReadWriteMode
instance GHC.Classes.Eq Database.PostgreSQL.Simple.Transaction.ReadWriteMode
instance GHC.Show.Show Database.PostgreSQL.Simple.Transaction.ReadWriteMode
instance GHC.Enum.Bounded Database.PostgreSQL.Simple.Transaction.IsolationLevel
instance GHC.Enum.Enum Database.PostgreSQL.Simple.Transaction.IsolationLevel
instance GHC.Classes.Ord Database.PostgreSQL.Simple.Transaction.IsolationLevel
instance GHC.Classes.Eq Database.PostgreSQL.Simple.Transaction.IsolationLevel
instance GHC.Show.Show Database.PostgreSQL.Simple.Transaction.IsolationLevel


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
type TimeZoneHMS = (Int, Int, Int)
getTimeZoneHMS :: Parser TimeZoneHMS
localToUTCTimeOfDayHMS :: TimeZoneHMS -> TimeOfDay -> (Integer, TimeOfDay)


-- | 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.
--   
--   Note that the <a>Float</a> and <a>Double</a> instances use
--   attoparsec's <a>double</a> conversion routine, which sacrifices some
--   accuracy for speed. If you need accuracy, consider first converting
--   data to a <a>Scientific</a> or <a>Rational</a> type, and then
--   converting to a floating-point type. If you are defining your own
--   <a>FromRow</a> instances, this can be achieved simply by
--   <tt><a>fromRational</a> <a>&lt;$&gt;</a> <a>field</a></tt>, although
--   this idiom is additionally compatible with PostgreSQL's <tt>int8</tt>
--   and <tt>numeric</tt> types. If this is unacceptable, you may find
--   <a>fieldWith</a> useful.
--   
--   Also note that while converting to a <a>Double</a> through the
--   <a>Scientific</a> type is likely somewhat faster than converting
--   through the <a>Rational</a> type, the <a>Scientific</a> type has no
--   way to represent <tt>NaN</tt> and <tt>±Infinity</tt> values. Thus, if
--   you need precision conversion of regular floating point values and the
--   possibility of receiving these special values from the backend, stick
--   with <a>Rational</a>.
--   
--   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

-- | Convert a SQL value to a Haskell value.
--   
--   Returns a list of exceptions if the conversion fails. In the case of
--   library instances, this will usually be a single <a>ResultError</a>,
--   but may be a <tt>UnicodeException</tt>.
--   
--   Note that retaining any reference to the <a>Field</a> argument causes
--   the entire <tt>LibPQ.<a>Result</a></tt> to be retained. Thus,
--   implementations of <a>fromField</a> should return results that do not
--   refer to this value after the result have been evaluated to WHNF.
--   
--   Note that as of <tt>postgresql-simple-0.4.0.0</tt>, the
--   <a>ByteString</a> value has already been copied out of the
--   <tt>LibPQ.<a>Result</a></tt> before it has been passed to
--   <a>fromField</a>. This is because for short strings, it's cheaper to
--   copy the string than to set up a finalizer.
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
pgArrayFieldParser :: Typeable a => FieldParser a -> FieldParser (PGArray a)

-- | 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 GHC.Show.Show Database.PostgreSQL.Simple.FromField.ResultError
instance GHC.Classes.Eq Database.PostgreSQL.Simple.FromField.ResultError
instance GHC.Exception.Exception Database.PostgreSQL.Simple.FromField.ResultError
instance Database.PostgreSQL.Simple.FromField.FromField ()
instance Database.PostgreSQL.Simple.FromField.FromField a => Database.PostgreSQL.Simple.FromField.FromField (GHC.Base.Maybe a)
instance Database.PostgreSQL.Simple.FromField.FromField Database.PostgreSQL.Simple.Types.Null
instance Database.PostgreSQL.Simple.FromField.FromField GHC.Types.Bool
instance Database.PostgreSQL.Simple.FromField.FromField GHC.Types.Char
instance Database.PostgreSQL.Simple.FromField.FromField GHC.Int.Int16
instance Database.PostgreSQL.Simple.FromField.FromField GHC.Int.Int32
instance Database.PostgreSQL.Simple.FromField.FromField GHC.Types.Int
instance Database.PostgreSQL.Simple.FromField.FromField GHC.Int.Int64
instance Database.PostgreSQL.Simple.FromField.FromField GHC.Integer.Type.Integer
instance Database.PostgreSQL.Simple.FromField.FromField GHC.Types.Float
instance Database.PostgreSQL.Simple.FromField.FromField GHC.Types.Double
instance Database.PostgreSQL.Simple.FromField.FromField (GHC.Real.Ratio GHC.Integer.Type.Integer)
instance Database.PostgreSQL.Simple.FromField.FromField Data.Scientific.Scientific
instance Database.PostgreSQL.Simple.FromField.FromField Data.ByteString.Internal.ByteString
instance Database.PostgreSQL.Simple.FromField.FromField Database.PostgreSQL.LibPQ.Oid
instance Database.PostgreSQL.Simple.FromField.FromField Data.ByteString.Lazy.Internal.ByteString
instance Database.PostgreSQL.Simple.FromField.FromField (Database.PostgreSQL.Simple.Types.Binary Data.ByteString.Internal.ByteString)
instance Database.PostgreSQL.Simple.FromField.FromField (Database.PostgreSQL.Simple.Types.Binary Data.ByteString.Lazy.Internal.ByteString)
instance Database.PostgreSQL.Simple.FromField.FromField Data.Text.Internal.Text
instance Database.PostgreSQL.Simple.FromField.FromField Data.Text.Internal.Lazy.Text
instance Database.PostgreSQL.Simple.FromField.FromField (Data.CaseInsensitive.Internal.CI Data.Text.Internal.Text)
instance Database.PostgreSQL.Simple.FromField.FromField (Data.CaseInsensitive.Internal.CI Data.Text.Internal.Lazy.Text)
instance Database.PostgreSQL.Simple.FromField.FromField [GHC.Types.Char]
instance Database.PostgreSQL.Simple.FromField.FromField Data.Time.Clock.UTC.UTCTime
instance Database.PostgreSQL.Simple.FromField.FromField Data.Time.LocalTime.LocalTime.ZonedTime
instance Database.PostgreSQL.Simple.FromField.FromField Data.Time.LocalTime.LocalTime.LocalTime
instance Database.PostgreSQL.Simple.FromField.FromField Data.Time.Calendar.Days.Day
instance Database.PostgreSQL.Simple.FromField.FromField Data.Time.LocalTime.TimeOfDay.TimeOfDay
instance Database.PostgreSQL.Simple.FromField.FromField Database.PostgreSQL.Simple.Time.Implementation.UTCTimestamp
instance Database.PostgreSQL.Simple.FromField.FromField Database.PostgreSQL.Simple.Time.Implementation.ZonedTimestamp
instance Database.PostgreSQL.Simple.FromField.FromField Database.PostgreSQL.Simple.Time.Implementation.LocalTimestamp
instance Database.PostgreSQL.Simple.FromField.FromField Database.PostgreSQL.Simple.Time.Implementation.Date
instance (Database.PostgreSQL.Simple.FromField.FromField a, Database.PostgreSQL.Simple.FromField.FromField b) => Database.PostgreSQL.Simple.FromField.FromField (Data.Either.Either a b)
instance (Database.PostgreSQL.Simple.FromField.FromField a, Data.Typeable.Internal.Typeable a) => Database.PostgreSQL.Simple.FromField.FromField (Database.PostgreSQL.Simple.Types.PGArray a)
instance (Database.PostgreSQL.Simple.FromField.FromField a, Data.Typeable.Internal.Typeable a) => Database.PostgreSQL.Simple.FromField.FromField (Data.Vector.Vector a)
instance (Database.PostgreSQL.Simple.FromField.FromField a, Data.Typeable.Internal.Typeable a) => Database.PostgreSQL.Simple.FromField.FromField (Data.Vector.Mutable.IOVector a)
instance Database.PostgreSQL.Simple.FromField.FromField Data.UUID.Types.Internal.UUID
instance Database.PostgreSQL.Simple.FromField.FromField Data.Aeson.Types.Internal.Value
instance Database.PostgreSQL.Simple.FromField.FromField a => Database.PostgreSQL.Simple.FromField.FromField (GHC.IORef.IORef a)
instance Database.PostgreSQL.Simple.FromField.FromField a => Database.PostgreSQL.Simple.FromField.FromField (GHC.MVar.MVar a)


-- | 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
parseHStoreList :: ByteString -> Either String HStoreList
class ToHStoreText a
toHStoreText :: ToHStoreText a => a -> HStoreText

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


module Database.PostgreSQL.Simple.HStore.Internal

-- | Represents valid hstore syntax.
data HStoreBuilder
Empty :: HStoreBuilder
Comma :: !Builder -> HStoreBuilder

-- | Represents escape text, ready to be the key or value to a hstore value
newtype HStoreText
HStoreText :: Builder -> HStoreText
parseHStore :: Parser (Either UnicodeException HStoreList)
parseHStoreKeyVal :: Parser (Either UnicodeException (Text, Text))
parseHStoreText :: Parser (Either UnicodeException Text)


module Database.PostgreSQL.Simple.Range

-- | Represents boundary of a range
data RangeBound a
NegInfinity :: RangeBound a
Inclusive :: !a -> RangeBound a
Exclusive :: !a -> RangeBound a
PosInfinity :: RangeBound a

-- | Generic range type
data PGRange a
PGRange :: !(RangeBound a) -> !(RangeBound a) -> PGRange a
empty :: PGRange a

-- | Is a range empty? If this returns <a>True</a>, then the
--   <a>contains</a> predicate will always return <a>False</a>. However, if
--   this returns <a>False</a>, it is not necessarily true that there
--   exists a point for which <a>contains</a> returns <a>True</a>. Consider
--   <tt><a>PGRange</a> (<tt>Excludes</tt> 2) (<tt>Excludes</tt> 3) ::
--   PGRange Int</tt>, for example.
isEmpty :: Ord a => PGRange a -> Bool
isEmptyBy :: (a -> a -> Ordering) -> PGRange a -> Bool

-- | Does a range contain a given point? Note that in some cases, this may
--   not correspond exactly with a server-side computation. Consider
--   <tt>UTCTime</tt> for example, which has a resolution of a picosecond,
--   whereas postgresql's <tt>timestamptz</tt> types have a resolution of a
--   microsecond. Putting such Haskell values into the database will result
--   in them being rounded, which can change the value of the containment
--   predicate.
contains :: Ord a => PGRange a -> (a -> Bool)
containsBy :: (a -> a -> Ordering) -> PGRange a -> (a -> Bool)
instance GHC.Base.Functor Database.PostgreSQL.Simple.Range.PGRange
instance GHC.Show.Show a => GHC.Show.Show (Database.PostgreSQL.Simple.Range.PGRange a)
instance GHC.Base.Functor Database.PostgreSQL.Simple.Range.RangeBound
instance GHC.Classes.Eq a => GHC.Classes.Eq (Database.PostgreSQL.Simple.Range.RangeBound a)
instance GHC.Show.Show a => GHC.Show.Show (Database.PostgreSQL.Simple.Range.RangeBound a)
instance GHC.Classes.Ord a => GHC.Classes.Eq (Database.PostgreSQL.Simple.Range.PGRange a)
instance (Database.PostgreSQL.Simple.FromField.FromField a, Data.Typeable.Internal.Typeable a) => Database.PostgreSQL.Simple.FromField.FromField (Database.PostgreSQL.Simple.Range.PGRange a)
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Range.PGRange GHC.Int.Int8)
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Range.PGRange GHC.Int.Int16)
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Range.PGRange GHC.Int.Int32)
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Range.PGRange GHC.Types.Int)
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Range.PGRange GHC.Int.Int64)
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Range.PGRange GHC.Integer.Type.Integer)
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Range.PGRange GHC.Word.Word8)
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Range.PGRange GHC.Word.Word16)
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Range.PGRange GHC.Word.Word32)
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Range.PGRange GHC.Types.Word)
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Range.PGRange GHC.Word.Word64)
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Range.PGRange GHC.Types.Float)
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Range.PGRange GHC.Types.Double)
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Range.PGRange Data.Scientific.Scientific)
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Range.PGRange Data.Time.Clock.UTC.UTCTime)
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Range.PGRange Data.Time.LocalTime.LocalTime.ZonedTime)
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Range.PGRange Data.Time.LocalTime.LocalTime.LocalTime)
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Range.PGRange Data.Time.Calendar.Days.Day)
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Range.PGRange Data.Time.LocalTime.TimeOfDay.TimeOfDay)
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Range.PGRange Database.PostgreSQL.Simple.Time.Implementation.UTCTimestamp)
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Range.PGRange Database.PostgreSQL.Simple.Time.Implementation.ZonedTimestamp)
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Range.PGRange Database.PostgreSQL.Simple.Time.Implementation.LocalTimestamp)
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Range.PGRange Database.PostgreSQL.Simple.Time.Implementation.Date)
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Range.PGRange Data.Time.Clock.UTC.NominalDiffTime)


-- | 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 where fromRow = to <$> gfromRow
fromRow :: FromRow a => RowParser a
data RowParser a
field :: FromField a => RowParser a
fieldWith :: FieldParser a -> RowParser a
numFieldsRemaining :: RowParser Int
instance Database.PostgreSQL.Simple.FromField.FromField a => Database.PostgreSQL.Simple.FromRow.FromRow (Database.PostgreSQL.Simple.Types.Only a)
instance Database.PostgreSQL.Simple.FromField.FromField a => Database.PostgreSQL.Simple.FromRow.FromRow (GHC.Base.Maybe (Database.PostgreSQL.Simple.Types.Only a))
instance (Database.PostgreSQL.Simple.FromField.FromField a, Database.PostgreSQL.Simple.FromField.FromField b) => Database.PostgreSQL.Simple.FromRow.FromRow (a, b)
instance (Database.PostgreSQL.Simple.FromField.FromField a, Database.PostgreSQL.Simple.FromField.FromField b) => Database.PostgreSQL.Simple.FromRow.FromRow (GHC.Base.Maybe (a, b))
instance (Database.PostgreSQL.Simple.FromField.FromField a, Database.PostgreSQL.Simple.FromField.FromField b, Database.PostgreSQL.Simple.FromField.FromField c) => Database.PostgreSQL.Simple.FromRow.FromRow (a, b, c)
instance (Database.PostgreSQL.Simple.FromField.FromField a, Database.PostgreSQL.Simple.FromField.FromField b, Database.PostgreSQL.Simple.FromField.FromField c) => Database.PostgreSQL.Simple.FromRow.FromRow (GHC.Base.Maybe (a, b, c))
instance (Database.PostgreSQL.Simple.FromField.FromField a, Database.PostgreSQL.Simple.FromField.FromField b, Database.PostgreSQL.Simple.FromField.FromField c, Database.PostgreSQL.Simple.FromField.FromField d) => Database.PostgreSQL.Simple.FromRow.FromRow (a, b, c, d)
instance (Database.PostgreSQL.Simple.FromField.FromField a, Database.PostgreSQL.Simple.FromField.FromField b, Database.PostgreSQL.Simple.FromField.FromField c, Database.PostgreSQL.Simple.FromField.FromField d) => Database.PostgreSQL.Simple.FromRow.FromRow (GHC.Base.Maybe (a, b, c, d))
instance (Database.PostgreSQL.Simple.FromField.FromField a, Database.PostgreSQL.Simple.FromField.FromField b, Database.PostgreSQL.Simple.FromField.FromField c, Database.PostgreSQL.Simple.FromField.FromField d, Database.PostgreSQL.Simple.FromField.FromField e) => Database.PostgreSQL.Simple.FromRow.FromRow (a, b, c, d, e)
instance (Database.PostgreSQL.Simple.FromField.FromField a, Database.PostgreSQL.Simple.FromField.FromField b, Database.PostgreSQL.Simple.FromField.FromField c, Database.PostgreSQL.Simple.FromField.FromField d, Database.PostgreSQL.Simple.FromField.FromField e) => Database.PostgreSQL.Simple.FromRow.FromRow (GHC.Base.Maybe (a, b, c, d, e))
instance (Database.PostgreSQL.Simple.FromField.FromField a, Database.PostgreSQL.Simple.FromField.FromField b, Database.PostgreSQL.Simple.FromField.FromField c, Database.PostgreSQL.Simple.FromField.FromField d, Database.PostgreSQL.Simple.FromField.FromField e, Database.PostgreSQL.Simple.FromField.FromField f) => Database.PostgreSQL.Simple.FromRow.FromRow (a, b, c, d, e, f)
instance (Database.PostgreSQL.Simple.FromField.FromField a, Database.PostgreSQL.Simple.FromField.FromField b, Database.PostgreSQL.Simple.FromField.FromField c, Database.PostgreSQL.Simple.FromField.FromField d, Database.PostgreSQL.Simple.FromField.FromField e, Database.PostgreSQL.Simple.FromField.FromField f) => Database.PostgreSQL.Simple.FromRow.FromRow (GHC.Base.Maybe (a, b, c, d, e, f))
instance (Database.PostgreSQL.Simple.FromField.FromField a, Database.PostgreSQL.Simple.FromField.FromField b, Database.PostgreSQL.Simple.FromField.FromField c, Database.PostgreSQL.Simple.FromField.FromField d, Database.PostgreSQL.Simple.FromField.FromField e, Database.PostgreSQL.Simple.FromField.FromField f, Database.PostgreSQL.Simple.FromField.FromField g) => Database.PostgreSQL.Simple.FromRow.FromRow (a, b, c, d, e, f, g)
instance (Database.PostgreSQL.Simple.FromField.FromField a, Database.PostgreSQL.Simple.FromField.FromField b, Database.PostgreSQL.Simple.FromField.FromField c, Database.PostgreSQL.Simple.FromField.FromField d, Database.PostgreSQL.Simple.FromField.FromField e, Database.PostgreSQL.Simple.FromField.FromField f, Database.PostgreSQL.Simple.FromField.FromField g) => Database.PostgreSQL.Simple.FromRow.FromRow (GHC.Base.Maybe (a, b, c, d, e, f, g))
instance (Database.PostgreSQL.Simple.FromField.FromField a, Database.PostgreSQL.Simple.FromField.FromField b, Database.PostgreSQL.Simple.FromField.FromField c, Database.PostgreSQL.Simple.FromField.FromField d, Database.PostgreSQL.Simple.FromField.FromField e, Database.PostgreSQL.Simple.FromField.FromField f, Database.PostgreSQL.Simple.FromField.FromField g, Database.PostgreSQL.Simple.FromField.FromField h) => Database.PostgreSQL.Simple.FromRow.FromRow (a, b, c, d, e, f, g, h)
instance (Database.PostgreSQL.Simple.FromField.FromField a, Database.PostgreSQL.Simple.FromField.FromField b, Database.PostgreSQL.Simple.FromField.FromField c, Database.PostgreSQL.Simple.FromField.FromField d, Database.PostgreSQL.Simple.FromField.FromField e, Database.PostgreSQL.Simple.FromField.FromField f, Database.PostgreSQL.Simple.FromField.FromField g, Database.PostgreSQL.Simple.FromField.FromField h) => Database.PostgreSQL.Simple.FromRow.FromRow (GHC.Base.Maybe (a, b, c, d, e, f, g, h))
instance (Database.PostgreSQL.Simple.FromField.FromField a, Database.PostgreSQL.Simple.FromField.FromField b, Database.PostgreSQL.Simple.FromField.FromField c, Database.PostgreSQL.Simple.FromField.FromField d, Database.PostgreSQL.Simple.FromField.FromField e, Database.PostgreSQL.Simple.FromField.FromField f, Database.PostgreSQL.Simple.FromField.FromField g, Database.PostgreSQL.Simple.FromField.FromField h, Database.PostgreSQL.Simple.FromField.FromField i) => Database.PostgreSQL.Simple.FromRow.FromRow (a, b, c, d, e, f, g, h, i)
instance (Database.PostgreSQL.Simple.FromField.FromField a, Database.PostgreSQL.Simple.FromField.FromField b, Database.PostgreSQL.Simple.FromField.FromField c, Database.PostgreSQL.Simple.FromField.FromField d, Database.PostgreSQL.Simple.FromField.FromField e, Database.PostgreSQL.Simple.FromField.FromField f, Database.PostgreSQL.Simple.FromField.FromField g, Database.PostgreSQL.Simple.FromField.FromField h, Database.PostgreSQL.Simple.FromField.FromField i) => Database.PostgreSQL.Simple.FromRow.FromRow (GHC.Base.Maybe (a, b, c, d, e, f, g, h, i))
instance (Database.PostgreSQL.Simple.FromField.FromField a, Database.PostgreSQL.Simple.FromField.FromField b, Database.PostgreSQL.Simple.FromField.FromField c, Database.PostgreSQL.Simple.FromField.FromField d, Database.PostgreSQL.Simple.FromField.FromField e, Database.PostgreSQL.Simple.FromField.FromField f, Database.PostgreSQL.Simple.FromField.FromField g, Database.PostgreSQL.Simple.FromField.FromField h, Database.PostgreSQL.Simple.FromField.FromField i, Database.PostgreSQL.Simple.FromField.FromField j) => Database.PostgreSQL.Simple.FromRow.FromRow (a, b, c, d, e, f, g, h, i, j)
instance (Database.PostgreSQL.Simple.FromField.FromField a, Database.PostgreSQL.Simple.FromField.FromField b, Database.PostgreSQL.Simple.FromField.FromField c, Database.PostgreSQL.Simple.FromField.FromField d, Database.PostgreSQL.Simple.FromField.FromField e, Database.PostgreSQL.Simple.FromField.FromField f, Database.PostgreSQL.Simple.FromField.FromField g, Database.PostgreSQL.Simple.FromField.FromField h, Database.PostgreSQL.Simple.FromField.FromField i, Database.PostgreSQL.Simple.FromField.FromField j) => Database.PostgreSQL.Simple.FromRow.FromRow (GHC.Base.Maybe (a, b, c, d, e, f, g, h, i, j))
instance Database.PostgreSQL.Simple.FromField.FromField a => Database.PostgreSQL.Simple.FromRow.FromRow [a]
instance Database.PostgreSQL.Simple.FromField.FromField a => Database.PostgreSQL.Simple.FromRow.FromRow (GHC.Base.Maybe [a])
instance Database.PostgreSQL.Simple.FromField.FromField a => Database.PostgreSQL.Simple.FromRow.FromRow (Data.Vector.Vector a)
instance Database.PostgreSQL.Simple.FromField.FromField a => Database.PostgreSQL.Simple.FromRow.FromRow (GHC.Base.Maybe (Data.Vector.Vector a))
instance (Database.PostgreSQL.Simple.FromRow.FromRow a, Database.PostgreSQL.Simple.FromRow.FromRow b) => Database.PostgreSQL.Simple.FromRow.FromRow (a Database.PostgreSQL.Simple.Types.:. b)
instance Database.PostgreSQL.Simple.FromRow.GFromRow f => Database.PostgreSQL.Simple.FromRow.GFromRow (GHC.Generics.M1 c i f)
instance (Database.PostgreSQL.Simple.FromRow.GFromRow f, Database.PostgreSQL.Simple.FromRow.GFromRow g) => Database.PostgreSQL.Simple.FromRow.GFromRow (f GHC.Generics.:*: g)
instance Database.PostgreSQL.Simple.FromField.FromField a => Database.PostgreSQL.Simple.FromRow.GFromRow (GHC.Generics.K1 GHC.Generics.R a)
instance Database.PostgreSQL.Simple.FromRow.GFromRow GHC.Generics.U1


-- | A mid-level client library for the PostgreSQL database, aimed at ease
--   of use and high performance.
module Database.PostgreSQL.Simple
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 <a>toField</a> method of the <a>ToField</a>
--   class to perform conversion of each element of the collection.
class ToRow a where toRow = gtoRow . from

-- | 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 where fromRow = to <$> gfromRow

-- | 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 "..."
--   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
FormatError :: String -> Query -> [ByteString] -> FormatError
[fmtMessage] :: FormatError -> String
[fmtQuery] :: FormatError -> Query
[fmtParams] :: FormatError -> [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

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

-- | Attempt to make a connection based on a libpq connection string. See
--   <a>http://www.postgresql.org/docs/9.3/static/libpq-connect.html#LIBPQ-CONNSTRING</a>
--   for more information. Also note that environment variables also affect
--   parameters not provided, parameters provided as the empty string, and
--   a few other things; see
--   <a>http://www.postgresql.org/docs/9.3/static/libpq-envars.html</a> for
--   details. Here is an example with some of the most commonly used
--   parameters:
--   
--   <pre>
--   host='db.somedomain.com' port=5432 ...
--   </pre>
--   
--   This attempts to connect to <tt>db.somedomain.com:5432</tt>. Omitting
--   the port will normally default to 5432.
--   
--   On systems that provide unix domain sockets, omitting the host
--   parameter will cause libpq to attempt to connect via unix domain
--   sockets. The default filesystem path to the socket is constructed from
--   the port number and the <tt>DEFAULT_PGSOCKET_DIR</tt> constant defined
--   in the <tt>pg_config_manual.h</tt> header file. Connecting via unix
--   sockets tends to use the <tt>peer</tt> authentication method, which is
--   very secure and does not require a password.
--   
--   On Windows and other systems without unix domain sockets, omitting the
--   host will default to <tt>localhost</tt>.
--   
--   <pre>
--   ... dbname='postgres' user='postgres' password='secret \' \\ pw'
--   </pre>
--   
--   This attempts to connect to a database named <tt>postgres</tt> with
--   user <tt>postgres</tt> and password <tt>secret ' \ pw</tt>. Backslash
--   characters will have to be double-quoted in literal Haskell strings,
--   of course. Omitting <tt>dbname</tt> and <tt>user</tt> will both
--   default to the system username that the client process is running as.
--   
--   Omitting <tt>password</tt> will default to an appropriate password
--   found in the <tt>pgpass</tt> file, or no password at all if a matching
--   line is not found. See
--   <a>http://www.postgresql.org/docs/9.3/static/libpq-pgpass.html</a> for
--   more information regarding this file.
--   
--   As all parameters are optional and the defaults are sensible, the
--   empty connection string can be useful for development and exploratory
--   use, assuming your system is set up appropriately.
--   
--   On Unix, such a setup would typically consist of a local postgresql
--   server listening on port 5432, as well as a system user, database
--   user, and database sharing a common name, with permissions granted to
--   the user on the database.
--   
--   On Windows, in addition you will either need <tt>pg_hba.conf</tt> to
--   specify the use of the <tt>trust</tt> authentication method for the
--   connection, which may not be appropriate for multiuser or production
--   machines, or you will need to use a <tt>pgpass</tt> file with the
--   <tt>password</tt> or <tt>md5</tt> authentication methods.
--   
--   See
--   <a>http://www.postgresql.org/docs/9.3/static/client-authentication.html</a>
--   for more information regarding the authentication process.
--   
--   SSL/TLS will typically "just work" if your postgresql server supports
--   or requires it. However, note that libpq is trivially vulnerable to a
--   MITM attack without setting additional SSL parameters in the
--   connection string. In particular, <tt>sslmode</tt> needs to be set to
--   <tt>require</tt>, <tt>verify-ca</tt>, or <tt>verify-full</tt> in order
--   to perform certificate validation. When <tt>sslmode</tt> is
--   <tt>require</tt>, then you will also need to specify a
--   <tt>sslrootcert</tt> file, otherwise no validation of the server's
--   identity will be performed. Client authentication via certificates is
--   also possible via the <tt>sslcert</tt> and <tt>sslkey</tt> parameters.
connectPostgreSQL :: ByteString -> IO Connection
close :: Connection -> IO ()

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

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

-- | 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>
--   <li><a>SqlError</a>: the postgresql backend returned an error, e.g. a
--   syntax or type error, or an incorrect table or column name.</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

-- | Number of rows to fetch at a time. <a>Automatic</a> currently defaults
--   to 256 rows, although it might be nice to make this more intelligent
--   based on e.g. the average size of the rows.
data FetchQuantity
Automatic :: FetchQuantity
Fixed :: !Int -> FetchQuantity

-- | defaults to <a>Automatic</a>, and <a>TransactionMode</a>
--   <a>ReadCommitted</a> <a>ReadOnly</a>
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.
--   
--   This is implemented using a database cursor. As such, this requires a
--   transaction. This function will detect whether or not there is a
--   transaction in progress, and will create a <a>ReadCommitted</a>
--   <a>ReadOnly</a> transaction if needed. The cursor is given a unique
--   temporary name, so the consumer may itself call fold.
--   
--   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>
--   <li><a>SqlError</a>: the postgresql backend returned an error, e.g. a
--   syntax or type error, or an incorrect table or column name.</li>
--   </ul>
fold :: (FromRow row, ToRow params) => Connection -> Query -> params -> a -> (a -> row -> IO a) -> IO a

-- | The same as <a>fold</a>, but this provides a bit more control over
--   lower-level details. Currently, the number of rows fetched per
--   round-trip to the server and the transaction mode may be adjusted
--   accordingly. If the connection is already in a transaction, then the
--   existing transaction is used and thus the <a>transactionMode</a>
--   option is ignored.
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 "INSERT ... RETURNING ..." ...</tt> in cases where you are only
--   inserting a single row, and do not need functionality analogous to
--   <a>executeMany</a>.
--   
--   If the list of parameters is empty, this function will simply return
--   <tt>[]</tt> without issuing the query to the backend. If this is not
--   desired, consider using the <tt>Values</tt> constructor instead.
--   
--   Throws <a>FormatError</a> if the query could not be formatted
--   correctly.
returning :: (ToRow q, FromRow r) => Connection -> Query -> [q] -> IO [r]

-- | A version of <a>fold</a> taking a parser as an argument
foldWith :: (ToRow params) => RowParser row -> Connection -> Query -> params -> a -> (a -> row -> IO a) -> IO a

-- | A version of <a>foldWithOptions</a> taking a parser as an argument
foldWithOptionsAndParser :: (ToRow params) => FoldOptions -> RowParser row -> Connection -> Query -> params -> a -> (a -> row -> IO a) -> IO a

-- | A version of <a>fold_</a> taking a parser as an argument
foldWith_ :: RowParser r -> Connection -> Query -> a -> (a -> r -> IO a) -> IO a

-- | A version of <a>foldWithOptions_</a> taking a parser as an argument
foldWithOptionsAndParser_ :: FoldOptions -> RowParser r -> Connection -> Query -> a -> (a -> r -> IO a) -> IO a

-- | A version of <a>forEach</a> taking a parser as an argument
forEachWith :: (ToRow q) => RowParser r -> Connection -> Query -> q -> (r -> IO ()) -> IO ()
forEachWith_ :: RowParser r -> Connection -> Query -> (r -> IO ()) -> IO ()
returningWith :: (ToRow q) => RowParser 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, or a <a>SqlError</a> exception if the backend returns an
--   error.
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. If the list of parameters is
--   empty, this function will simply return 0 without issuing the query to
--   the backend. If this is not desired, consider using the
--   <tt>Values</tt> constructor instead.
--   
--   Throws <a>FormatError</a> if the query could not be formatted
--   correctly, or a <a>SqlError</a> exception if the backend returns an
--   error.
--   
--   For example, here's a command that inserts two rows into a table with
--   two columns:
--   
--   <pre>
--   executeMany c [sql|
--       INSERT INTO sometable VALUES (?,?)
--    |] [(1, "hello"),(2, "world")]
--   </pre>
--   
--   Here's an canonical example of a multi-row update command:
--   
--   <pre>
--   executeMany c [sql|
--       UPDATE sometable
--          SET sometable.y = upd.y
--         FROM (VALUES (?,?)) as upd(x,y)
--        WHERE sometable.x = upd.x
--    |] [(1, "hello"),(2, "world")]
--   </pre>
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


-- | 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 GHC.Show.Show Database.PostgreSQL.Simple.Copy.CopyOutResult
instance GHC.Classes.Eq Database.PostgreSQL.Simple.Copy.CopyOutResult