-- 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.7.0.0
-- | 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 FromField 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 Ok type is a simple error handler, basically equivalent to
-- Either [SomeException]. 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
-- Either SomeException had not been provided an instance for
-- Alternative, and it would have been a bad idea to provide an
-- orphaned instance for a commonly-used type and typeclass included in
-- base.
--
-- Extending the failure case to a list of SomeExceptions enables
-- a more sensible Alternative instance definitions:
-- <|> concatenates the list of exceptions when both cases
-- fail, and empty is defined as 'Errors []'. Though
-- <|> one could pick one of two exceptions, and throw away
-- the other, and have empty provide a generic exception, this
-- avoids cases where empty overrides a more informative exception
-- and allows you to see all the different ways your computation has
-- failed.
module Database.PostgreSQL.Simple.Ok
data Ok a
Errors :: [SomeException] -> Ok a
Ok :: !a -> Ok a
-- | a way to reify a list of exceptions into a single exception
newtype ManyErrors
ManyErrors :: [SomeException] -> ManyErrors
instance GHC.Base.Functor Database.PostgreSQL.Simple.Ok.Ok
instance GHC.Show.Show a => GHC.Show.Show (Database.PostgreSQL.Simple.Ok.Ok a)
instance GHC.Show.Show Database.PostgreSQL.Simple.Ok.ManyErrors
instance GHC.Exception.Type.Exception Database.PostgreSQL.Simple.Ok.ManyErrors
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 Control.Monad.Fail.MonadFail Database.PostgreSQL.Simple.Ok.Ok
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 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
-- https://www.postgresql.org/docs/9.5/static/datatype-datetime.html,
-- and the IANA time zone database at
-- https://en.wikipedia.org/wiki/Tz_database.
--
-- 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 timestamp with time zone (hereafter,
-- timestamptz) can be converted to Haskell's UTCTime and
-- ZonedTime types, because values of these types represent a
-- self-contained, unambiguous point in time. PostgreSQL's timestamp
-- without time zone (hereafter, timestamp) can be
-- converted to Haskell's LocalTime, 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 +00, -05, or +05:30. 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 1970-01-01 00:00+00.
--
-- For example, as of today, both America/New_York and
-- America/Indiana/Indianapolis 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 timestamptz 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 timezone 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 timestamptz, the backend looks at the
-- time zone 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 ZonedTime, or use the offset to convert back to
-- UTCTime.
--
-- By contrast, the timestamp type ignores any offsets provided
-- to it, and never sends back an offset. Thus, postgresql-simple equates
-- this with LocalTime, which has no concept of an offset. One can
-- convert between timestamptz and timestamp using the
-- AT TIME ZONE operator, whose semantics also demonstrates that
-- timestamptz is UTCTime whereas timestamp is
-- LocalTime.
--
-- PostgreSQL's timezone is a per-connection variable that by
-- default is initialized to 'localtime', 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
-- PGTZ environment variable, and if it exists, modifies
-- timezone 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 timezone setting is. But it is important
-- to understand the caveats:
--
--
-- - The correctness of server-side computations can depend on the
-- timezone setting. Examples include adding an
-- interval to a timestamptz, or type casting between
-- timestamp and timestamptz, or applying the
-- DATE function to a timestamptz.
-- - The (localtime, offset) pair contained in a ZonedTime
-- result will depend on the timezone setting, although the
-- result will always represent the same instant in time regardless of
-- the time zone.
-- - Sending a LocalTime and interpreting it as a
-- timestamptz can be useful, as it will be converted to UTC via
-- the tz database, but correctness will depend on the timezone
-- setting. You may prefer to use an explicit AT TIME ZONE
-- conversion instead, which would avoid this contextual dependence.
--
--
-- Furthermore, although these following points don't involve the
-- timezone setting, they are related to the last point above:
--
--
-- - Sending a UTCTime and interpreting it as a
-- timestamp can be useful. In practice, the most common context
-- used to disambiguate timestamp is that it represents UTC, and
-- this coding technique will work as expected in this situation.
-- - Sending a ZonedTime and interpreting it as a
-- timestamp 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.
--
--
-- When dealing with local timestamps that refer to the future, it is
-- often useful to store it as a local time in a timestamp
-- 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, ZonedTime 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 timestamptz postgresql will in some
-- cases provide seconds in the offset. For example:
--
--
-- $ psql
-- psql (9.4.5)
-- Type "help" for help.
--
-- lpsmith=> SET timezone TO 'America/New_York';
-- SET
-- lpsmith=> 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)
--
--
-- Both of these timestamps can be parsed as a UTCTime type,
-- however ZonedTime will fail on the former timestamp. Because
-- ZonedTime 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 1582-10-15 to
-- 1923-03-01, depending on location and sometimes even
-- political allegiances within a single location.
--
-- Timestamps BCE are not supported. For example, PostgreSQL will emit
-- "0045-01-01 BC" 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
-- 4714-11-24 BC, 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
parseCalendarDiffTime :: ByteString -> Either String CalendarDiffTime
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
calendarDiffTimeToBuilder :: CalendarDiffTime -> Builder
-- | This module contains portions of the pg_type 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 pg_type 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
boolOid :: Oid
bytea :: TypeInfo
byteaOid :: Oid
char :: TypeInfo
charOid :: Oid
name :: TypeInfo
nameOid :: Oid
int8 :: TypeInfo
int8Oid :: Oid
int2 :: TypeInfo
int2Oid :: Oid
int4 :: TypeInfo
int4Oid :: Oid
regproc :: TypeInfo
regprocOid :: Oid
text :: TypeInfo
textOid :: Oid
oid :: TypeInfo
oidOid :: Oid
tid :: TypeInfo
tidOid :: Oid
xid :: TypeInfo
xidOid :: Oid
cid :: TypeInfo
cidOid :: Oid
xml :: TypeInfo
xmlOid :: Oid
point :: TypeInfo
pointOid :: Oid
lseg :: TypeInfo
lsegOid :: Oid
path :: TypeInfo
pathOid :: Oid
box :: TypeInfo
boxOid :: Oid
polygon :: TypeInfo
polygonOid :: Oid
line :: TypeInfo
lineOid :: Oid
cidr :: TypeInfo
cidrOid :: Oid
float4 :: TypeInfo
float4Oid :: Oid
float8 :: TypeInfo
float8Oid :: Oid
unknown :: TypeInfo
unknownOid :: Oid
circle :: TypeInfo
circleOid :: Oid
money :: TypeInfo
moneyOid :: Oid
macaddr :: TypeInfo
macaddrOid :: Oid
inet :: TypeInfo
inetOid :: Oid
bpchar :: TypeInfo
bpcharOid :: Oid
varchar :: TypeInfo
varcharOid :: Oid
date :: TypeInfo
dateOid :: Oid
time :: TypeInfo
timeOid :: Oid
timestamp :: TypeInfo
timestampOid :: Oid
timestamptz :: TypeInfo
timestamptzOid :: Oid
interval :: TypeInfo
intervalOid :: Oid
timetz :: TypeInfo
timetzOid :: Oid
bit :: TypeInfo
bitOid :: Oid
varbit :: TypeInfo
varbitOid :: Oid
numeric :: TypeInfo
numericOid :: Oid
refcursor :: TypeInfo
refcursorOid :: Oid
record :: TypeInfo
recordOid :: Oid
void :: TypeInfo
voidOid :: Oid
array_record :: TypeInfo
array_recordOid :: Oid
regprocedure :: TypeInfo
regprocedureOid :: Oid
regoper :: TypeInfo
regoperOid :: Oid
regoperator :: TypeInfo
regoperatorOid :: Oid
regclass :: TypeInfo
regclassOid :: Oid
regtype :: TypeInfo
regtypeOid :: Oid
uuid :: TypeInfo
uuidOid :: Oid
json :: TypeInfo
jsonOid :: Oid
jsonb :: TypeInfo
jsonbOid :: Oid
int2vector :: TypeInfo
int2vectorOid :: Oid
oidvector :: TypeInfo
oidvectorOid :: Oid
array_xml :: TypeInfo
array_xmlOid :: Oid
array_json :: TypeInfo
array_jsonOid :: Oid
array_line :: TypeInfo
array_lineOid :: Oid
array_cidr :: TypeInfo
array_cidrOid :: Oid
array_circle :: TypeInfo
array_circleOid :: Oid
array_money :: TypeInfo
array_moneyOid :: Oid
array_bool :: TypeInfo
array_boolOid :: Oid
array_bytea :: TypeInfo
array_byteaOid :: Oid
array_char :: TypeInfo
array_charOid :: Oid
array_name :: TypeInfo
array_nameOid :: Oid
array_int2 :: TypeInfo
array_int2Oid :: Oid
array_int2vector :: TypeInfo
array_int2vectorOid :: Oid
array_int4 :: TypeInfo
array_int4Oid :: Oid
array_regproc :: TypeInfo
array_regprocOid :: Oid
array_text :: TypeInfo
array_textOid :: Oid
array_tid :: TypeInfo
array_tidOid :: Oid
array_xid :: TypeInfo
array_xidOid :: Oid
array_cid :: TypeInfo
array_cidOid :: Oid
array_oidvector :: TypeInfo
array_oidvectorOid :: Oid
array_bpchar :: TypeInfo
array_bpcharOid :: Oid
array_varchar :: TypeInfo
array_varcharOid :: Oid
array_int8 :: TypeInfo
array_int8Oid :: Oid
array_point :: TypeInfo
array_pointOid :: Oid
array_lseg :: TypeInfo
array_lsegOid :: Oid
array_path :: TypeInfo
array_pathOid :: Oid
array_box :: TypeInfo
array_boxOid :: Oid
array_float4 :: TypeInfo
array_float4Oid :: Oid
array_float8 :: TypeInfo
array_float8Oid :: Oid
array_polygon :: TypeInfo
array_polygonOid :: Oid
array_oid :: TypeInfo
array_oidOid :: Oid
array_macaddr :: TypeInfo
array_macaddrOid :: Oid
array_inet :: TypeInfo
array_inetOid :: Oid
array_timestamp :: TypeInfo
array_timestampOid :: Oid
array_date :: TypeInfo
array_dateOid :: Oid
array_time :: TypeInfo
array_timeOid :: Oid
array_timestamptz :: TypeInfo
array_timestamptzOid :: Oid
array_interval :: TypeInfo
array_intervalOid :: Oid
array_numeric :: TypeInfo
array_numericOid :: Oid
array_timetz :: TypeInfo
array_timetzOid :: Oid
array_bit :: TypeInfo
array_bitOid :: Oid
array_varbit :: TypeInfo
array_varbitOid :: Oid
array_refcursor :: TypeInfo
array_refcursorOid :: Oid
array_regprocedure :: TypeInfo
array_regprocedureOid :: Oid
array_regoper :: TypeInfo
array_regoperOid :: Oid
array_regoperator :: TypeInfo
array_regoperatorOid :: Oid
array_regclass :: TypeInfo
array_regclassOid :: Oid
array_regtype :: TypeInfo
array_regtypeOid :: Oid
array_uuid :: TypeInfo
array_uuidOid :: Oid
array_jsonb :: TypeInfo
array_jsonbOid :: Oid
int4range :: TypeInfo
int4rangeOid :: Oid
_int4range :: TypeInfo
_int4rangeOid :: Oid
numrange :: TypeInfo
numrangeOid :: Oid
_numrange :: TypeInfo
_numrangeOid :: Oid
tsrange :: TypeInfo
tsrangeOid :: Oid
_tsrange :: TypeInfo
_tsrangeOid :: Oid
tstzrange :: TypeInfo
tstzrangeOid :: Oid
_tstzrange :: TypeInfo
_tstzrangeOid :: Oid
daterange :: TypeInfo
daterangeOid :: Oid
_daterange :: TypeInfo
_daterangeOid :: Oid
int8range :: TypeInfo
int8rangeOid :: Oid
_int8range :: TypeInfo
_int8rangeOid :: Oid
-- | Basic types.
module Database.PostgreSQL.Simple.Types
-- | A placeholder for the SQL NULL value.
data Null
Null :: Null
-- | A placeholder for the PostgreSQL DEFAULT value.
data Default
Default :: Default
-- | The 1-tuple type or single-value "collection".
--
-- This type is structurally equivalent to the Identity type, but
-- its intent is more about serving as the anonymous 1-tuple type missing
-- from Haskell for attaching typeclass instances.
--
-- Parameter usage example:
--
--
-- encodeSomething (Only (42::Int))
--
--
-- Result usage example:
--
--
-- xs <- decodeSomething
-- forM_ xs $ \(Only id) -> {- ... -}
--
newtype Only a
Only :: a -> Only a
[fromOnly] :: Only a -> a
-- | Wrap a list of values for use in an IN clause. Replaces a
-- single "?" character with a parenthesized list of rendered
-- values.
--
-- Example:
--
--
-- query c "select * from whatever where id in ?" (Only (In [3,4,5]))
--
--
-- Note that In [] expands to (null), which works as
-- expected in the query above, but evaluates to the logical null value
-- on every row instead of TRUE. This means that changing the
-- query above to ... id NOT in ? and supplying the empty list
-- as the parameter returns zero rows, instead of all of them as one
-- would expect.
--
-- Since postgresql doesn't seem to provide a syntax for actually
-- specifying an empty list, which could solve this completely, there are
-- two workarounds particularly worth mentioning, namely:
--
--
-- - Use postgresql-simple's Values type instead, which can
-- handle the empty case correctly. Note however that while specifying
-- the postgresql type "int4" is mandatory in the empty case,
-- specifying the haskell type Values (Only Int) would not
-- normally be needed in realistic use cases.
query c "select * from
-- whatever where id not in ?" (Only (Values ["int4"] [] :: Values (Only
-- Int)))
-- - Use sql's COALESCE operator to turn a logical
-- null into the correct boolean. Note however that the correct
-- boolean depends on the use case:
query c "select * from whatever
-- where coalesce(id NOT in ?, TRUE)" (Only (In [] :: In
-- [Int]))
query c "select * from whatever where coalesce(id IN
-- ?, FALSE)" (Only (In [] :: In [Int]))
Note that at as of
-- PostgreSQL 9.4, the query planner cannot see inside the
-- COALESCE operator, so if you have an index on id
-- then you probably don't want to write the last example with
-- COALESCE, which would result in a table scan. There are
-- further caveats if id can be null or you want null treated
-- sensibly as a component of IN or NOT IN.
--
newtype In a
In :: a -> In a
-- | Wrap binary data for use as a bytea 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 IsString, so the easiest way to
-- construct a query is to enable the OverloadedStrings language
-- extension and then simply write the query in double quotes.
--
--
-- {-# LANGUAGE OverloadedStrings #-}
--
-- import Database.PostgreSQL.Simple
--
-- q :: Query
-- q = "select ?"
--
--
-- The underlying type is a ByteString, 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.
--
--
-- instance FromRow MyData where ...
--
--
--
-- instance FromRow MyData2 where ...
--
--
-- then I can do the following for free:
--
--
-- res <- query' c "..."
-- forM res $ \(MyData{..} :. MyData2{..}) -> do
-- ....
--
data h :. t
(:.) :: h -> t -> (:.) h t
infixr 3 :.
infixr 3 :.
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 VALUES table literal, usable as an alternative
-- to executeMany and returning. The main advantage is that
-- you can parametrize more than just a single VALUES
-- 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:
--
--
-- 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 ON TRUE
-- ) SELECT * FROM new_thing
-- |] ("foo", Values [ "int4", "text" ]
-- [ ( 1 , "hello" )
-- , ( 2 , "world" ) ])
--
--
-- (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:
--
--
-- (VALUES (1::"int4",'hello'::"text"),(2,'world'))
--
--
-- When the list of attributes is empty, the second parameter expands to:
--
--
-- (VALUES (null::"int4",null::"text") LIMIT 0)
--
--
-- By contrast, executeMany and returning don't issue
-- the query in the empty case, and simply return 0 and
-- [] 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 pg_type table.
-- Thus, you must write timestamptz instead of timestamp
-- with time zone, int4 instead of integer or
-- serial, _int8 instead of bigint[],
-- 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 SqlError exception.
--
-- See https://www.postgresql.org/docs/9.5/static/sql-values.html
-- for more information.
data Values a
Values :: [QualifiedIdentifier] -> [a] -> Values a
instance GHC.Show.Show Database.PostgreSQL.Simple.Types.Null
instance GHC.Read.Read Database.PostgreSQL.Simple.Types.Null
instance GHC.Show.Show Database.PostgreSQL.Simple.Types.Default
instance GHC.Read.Read Database.PostgreSQL.Simple.Types.Default
instance GHC.Classes.Ord Database.PostgreSQL.Simple.Types.Query
instance GHC.Classes.Eq Database.PostgreSQL.Simple.Types.Query
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.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 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.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 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.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.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 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 Data.Hashable.Class.Hashable Database.PostgreSQL.Simple.Types.QualifiedIdentifier
instance Data.String.IsString Database.PostgreSQL.Simple.Types.QualifiedIdentifier
instance Data.Hashable.Class.Hashable Database.PostgreSQL.Simple.Types.Identifier
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.Semigroup Database.PostgreSQL.Simple.Types.Query
instance GHC.Base.Monoid Database.PostgreSQL.Simple.Types.Query
-- | 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 Oid ->
-- Bool, true if the oid is equal to any one of the
-- typoids of the given TypeInfos.
mkCompats :: [TypeInfo] -> ExpQ
-- | Literally substitute the typoid of a TypeInfo
-- expression. Returns an expression of type Oid. Useful because
-- GHC tends not to fold constants.
inlineTypoid :: TypeInfo -> ExpQ
-- | The ToField 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 certain that they will not introduce
-- formatting vulnerabilities via use of characters such as spaces or
-- "'".
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 bytea literal. Include
-- surrounding quotes. This is used by the Binary newtype wrapper.
EscapeByteA :: ByteString -> Action
-- | Escape before substituting. Use for all sql identifiers like table,
-- column names, etc. This is used by the Identifier 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 JSON using toEncoding.
--
-- This can be used as the default implementation for the toField
-- method for Haskell types that have a JSON representation in
-- PostgreSQL.
toJSONField :: ToJSON a => a -> Action
-- | Surround a string with single-quote characters: "'"
--
-- This function does not perform any other escaping.
inQuotes :: Builder -> Builder
instance Database.PostgreSQL.Simple.ToField.ToField Database.PostgreSQL.Simple.ToField.Action
instance forall k a (b :: k). Database.PostgreSQL.Simple.ToField.ToField a => Database.PostgreSQL.Simple.ToField.ToField (Data.Functor.Const.Const a b)
instance Database.PostgreSQL.Simple.ToField.ToField a => Database.PostgreSQL.Simple.ToField.ToField (Data.Functor.Identity.Identity a)
instance Database.PostgreSQL.Simple.ToField.ToField a => Database.PostgreSQL.Simple.ToField.ToField (GHC.Maybe.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.Num.Integer.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.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.CaseInsensitive.Internal.CI Data.Text.Internal.Text)
instance Database.PostgreSQL.Simple.ToField.ToField (Data.CaseInsensitive.Internal.CI Data.Text.Internal.Lazy.Text)
instance Database.PostgreSQL.Simple.ToField.ToField Data.Time.Clock.Internal.UTCTime.UTCTime
instance Database.PostgreSQL.Simple.ToField.ToField Data.Time.LocalTime.Internal.ZonedTime.ZonedTime
instance Database.PostgreSQL.Simple.ToField.ToField Data.Time.LocalTime.Internal.LocalTime.LocalTime
instance Database.PostgreSQL.Simple.ToField.ToField Data.Time.Calendar.Days.Day
instance Database.PostgreSQL.Simple.ToField.ToField Data.Time.LocalTime.Internal.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.Internal.NominalDiffTime.NominalDiffTime
instance Database.PostgreSQL.Simple.ToField.ToField Data.Time.LocalTime.Internal.CalendarDiffTime.CalendarDiffTime
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)
instance GHC.Show.Show Database.PostgreSQL.Simple.ToField.Action
-- | The ToRow 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
-- Actions.
--
-- Instances should use the toField method of the ToField
-- class to perform conversion of each element of the collection.
--
-- You can derive ToRow for your data type using GHC generics,
-- like this:
--
--
-- {-# LANGUAGE DeriveAnyClass #-}
-- {-# LANGUAGE DeriveGeneric #-}
--
-- import GHC.Generics (Generic)
-- import Database.PostgreSQL.Simple (ToRow)
--
-- data User = User { name :: String, fileQuota :: Int }
-- deriving (Generic, ToRow)
--
--
-- Note that this only works for product types (e.g. records) and does
-- not support sum types or recursive types.
class ToRow a
toRow :: ToRow a => a -> [Action]
toRow :: (ToRow a, Generic a, GToRow (Rep a)) => a -> [Action]
instance Database.PostgreSQL.Simple.ToRow.ToRow ()
instance Database.PostgreSQL.Simple.ToField.ToField a => Database.PostgreSQL.Simple.ToRow.ToRow (Data.Tuple.Only.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.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.ToField.ToField k) => Database.PostgreSQL.Simple.ToRow.ToRow (a, b, c, d, e, f, g, h, i, j, k)
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.ToField.ToField k, Database.PostgreSQL.Simple.ToField.ToField l) => Database.PostgreSQL.Simple.ToRow.ToRow (a, b, c, d, e, f, g, h, i, j, k, l)
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.ToField.ToField k, Database.PostgreSQL.Simple.ToField.ToField l, Database.PostgreSQL.Simple.ToField.ToField m) => Database.PostgreSQL.Simple.ToRow.ToRow (a, b, c, d, e, f, g, h, i, j, k, l, m)
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.ToField.ToField k, Database.PostgreSQL.Simple.ToField.ToField l, Database.PostgreSQL.Simple.ToField.ToField m, Database.PostgreSQL.Simple.ToField.ToField n) => Database.PostgreSQL.Simple.ToRow.ToRow (a, b, c, d, e, f, g, h, i, j, k, l, m, n)
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.ToField.ToField k, Database.PostgreSQL.Simple.ToField.ToField l, Database.PostgreSQL.Simple.ToField.ToField m, Database.PostgreSQL.Simple.ToField.ToField n, Database.PostgreSQL.Simple.ToField.ToField o) => Database.PostgreSQL.Simple.ToRow.ToRow (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o)
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.ToField.ToField k, Database.PostgreSQL.Simple.ToField.ToField l, Database.PostgreSQL.Simple.ToField.ToField m, Database.PostgreSQL.Simple.ToField.ToField n, Database.PostgreSQL.Simple.ToField.ToField o, Database.PostgreSQL.Simple.ToField.ToField p) => Database.PostgreSQL.Simple.ToRow.ToRow (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p)
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.ToField.ToField k, Database.PostgreSQL.Simple.ToField.ToField l, Database.PostgreSQL.Simple.ToField.ToField m, Database.PostgreSQL.Simple.ToField.ToField n, Database.PostgreSQL.Simple.ToField.ToField o, Database.PostgreSQL.Simple.ToField.ToField p, Database.PostgreSQL.Simple.ToField.ToField q) => Database.PostgreSQL.Simple.ToRow.ToRow (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q)
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.ToField.ToField k, Database.PostgreSQL.Simple.ToField.ToField l, Database.PostgreSQL.Simple.ToField.ToField m, Database.PostgreSQL.Simple.ToField.ToField n, Database.PostgreSQL.Simple.ToField.ToField o, Database.PostgreSQL.Simple.ToField.ToField p, Database.PostgreSQL.Simple.ToField.ToField q, Database.PostgreSQL.Simple.ToField.ToField r) => Database.PostgreSQL.Simple.ToRow.ToRow (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r)
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.ToField.ToField k, Database.PostgreSQL.Simple.ToField.ToField l, Database.PostgreSQL.Simple.ToField.ToField m, Database.PostgreSQL.Simple.ToField.ToField n, Database.PostgreSQL.Simple.ToField.ToField o, Database.PostgreSQL.Simple.ToField.ToField p, Database.PostgreSQL.Simple.ToField.ToField q, Database.PostgreSQL.Simple.ToField.ToField r, Database.PostgreSQL.Simple.ToField.ToField s) => Database.PostgreSQL.Simple.ToRow.ToRow (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s)
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.ToField.ToField k, Database.PostgreSQL.Simple.ToField.ToField l, Database.PostgreSQL.Simple.ToField.ToField m, Database.PostgreSQL.Simple.ToField.ToField n, Database.PostgreSQL.Simple.ToField.ToField o, Database.PostgreSQL.Simple.ToField.ToField p, Database.PostgreSQL.Simple.ToField.ToField q, Database.PostgreSQL.Simple.ToField.ToField r, Database.PostgreSQL.Simple.ToField.ToField s, Database.PostgreSQL.Simple.ToField.ToField t) => Database.PostgreSQL.Simple.ToRow.ToRow (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t)
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
module Database.PostgreSQL.Simple.SqlQQ
-- | sql is a quasiquoter that eases the syntactic burden of writing
-- big sql statements in Haskell source code. For example:
--
--
-- {-# LANGUAGE QuasiQuotes #-}
--
-- query conn [sql| SELECT column_a, column_b
-- FROM table1 NATURAL JOIN table2
-- WHERE ? <= time AND time < ?
-- AND name LIKE ?
-- ORDER BY size DESC
-- LIMIT 100 |]
-- (beginTime,endTime,string)
--
--
-- This quasiquoter returns a literal string expression of type
-- Query, and attempts to minimize 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 string parameter above, which is a
-- run-time value.
--
-- Also note that this will not work if the substring |] is
-- contained in the query.
sql :: QuasiQuoter
-- | 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 PQftype.
[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
-- | Superclass for postgresql exceptions
data SomePostgreSqlException
SomePostgreSqlException :: e -> SomePostgreSqlException
postgresqlExceptionToException :: Exception e => e -> SomeException
postgresqlExceptionFromException :: Exception e => SomeException -> Maybe e
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 query is used to perform an
-- INSERT-like operation, or execute is used to perform
-- a SELECT-like operation.
data QueryError
QueryError :: String -> Query -> QueryError
[qeMessage] :: QueryError -> String
[qeQuery] :: QueryError -> Query
-- | Exception thrown if a Query could not be formatted correctly.
-- This may occur if the number of '?' 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:
--
--
-- - Server on localhost
-- - Port on 5432
-- - User postgres
-- - No password
-- - Database postgres
--
--
-- Use as in the following example:
--
--
-- connect defaultConnectInfo { connectHost = "db.example.com" }
--
defaultConnectInfo :: ConnectInfo
-- | Connect with the given username to the given database. Will throw an
-- exception if it cannot connect.
connect :: ConnectInfo -> IO Connection
-- | Memory bracket around connect and close.
withConnect :: ConnectInfo -> (Connection -> IO c) -> IO c
-- | Attempt to make a connection based on a libpq connection string. See
-- https://www.postgresql.org/docs/9.5/static/libpq-connect.html#LIBPQ-CONNSTRING
-- 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
-- https://www.postgresql.org/docs/9.5/static/libpq-envars.html
-- for details. Here is an example with some of the most commonly used
-- parameters:
--
--
-- host='db.somedomain.com' port=5432 ...
--
--
-- This attempts to connect to db.somedomain.com:5432. 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 DEFAULT_PGSOCKET_DIR constant defined
-- in the pg_config_manual.h header file. Connecting via unix
-- sockets tends to use the peer 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 localhost.
--
--
-- ... dbname='postgres' user='postgres' password='secret \' \\ pw'
--
--
-- This attempts to connect to a database named postgres with
-- user postgres and password secret ' \ pw. Backslash
-- characters will have to be double-quoted in literal Haskell strings,
-- of course. Omitting dbname and user will both
-- default to the system username that the client process is running as.
--
-- Omitting password will default to an appropriate password
-- found in the pgpass file, or no password at all if a matching
-- line is not found. The path of the pgpass file may be
-- specified by setting the PGPASSFILE environment variable. See
-- https://www.postgresql.org/docs/9.5/static/libpq-pgpass.html
-- 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 pg_hba.conf to
-- specify the use of the trust authentication method for the
-- connection, which may not be appropriate for multiuser or production
-- machines, or you will need to use a pgpass file with the
-- password or md5 authentication methods.
--
-- See
-- https://www.postgresql.org/docs/9.5/static/client-authentication.html
-- 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 connection parameters. In
-- particular, sslmode needs to be set to require,
-- verify-ca, or verify-full in order to perform
-- certificate validation. When sslmode is require,
-- then you will also need to specify a sslrootcert file,
-- otherwise no validation of the server's identity will be performed.
-- Client authentication via certificates is also possible via the
-- sslcert and sslkey parameters. See
-- https://www.postgresql.org/docs/9.5/static/libpq-ssl.html for
-- detailed information regarding libpq and SSL.
connectPostgreSQL :: ByteString -> IO Connection
connectdb :: ByteString -> IO Connection
-- | Turns a ConnectInfo data structure into a libpq connection
-- string.
postgreSQLConnectionString :: ConnectInfo -> ByteString
oid2int :: Oid -> Int
exec :: Connection -> ByteString -> IO Result
-- | A version of execute 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 FormatError
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)
breakOnSingleQuestionMark :: ByteString -> (ByteString, ByteString)
instance GHC.Show.Show Database.PostgreSQL.Simple.Internal.SqlError
instance GHC.Classes.Eq Database.PostgreSQL.Simple.Internal.SqlError
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.FormatError
instance GHC.Classes.Eq Database.PostgreSQL.Simple.Internal.FormatError
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.Generics.Generic Database.PostgreSQL.Simple.Internal.ConnectInfo
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.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
instance GHC.Exception.Type.Exception Database.PostgreSQL.Simple.Internal.FormatError
instance GHC.Exception.Type.Exception Database.PostgreSQL.Simple.Internal.QueryError
instance GHC.Exception.Type.Exception Database.PostgreSQL.Simple.Internal.SqlError
instance GHC.Show.Show Database.PostgreSQL.Simple.Internal.SomePostgreSqlException
instance GHC.Exception.Type.Exception Database.PostgreSQL.Simple.Internal.SomePostgreSqlException
instance GHC.Classes.Eq Database.PostgreSQL.Simple.Internal.Connection
-- | Support for receiving asynchronous notifications via PostgreSQL's
-- Listen/Notify mechanism. See
-- https://www.postgresql.org/docs/9.5/static/sql-notify.html for
-- more information.
--
-- Note that on Windows, getNotification 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.
--
-- https://hackage.haskell.org/trac/ghc/ticket/7353
module Database.PostgreSQL.Simple.Notification
data Notification
Notification :: {-# UNPACK #-} !CPid -> {-# UNPACK #-} !ByteString -> {-# UNPACK #-} !ByteString -> Notification
[notificationPid] :: Notification -> {-# UNPACK #-} !CPid
[notificationChannel] :: Notification -> {-# UNPACK #-} !ByteString
[notificationData] :: Notification -> {-# UNPACK #-} !ByteString
-- | Returns a single notification. If no notifications are available,
-- getNotification blocks until one arrives.
--
-- It is safe to call getNotification on a connection that is
-- concurrently being used for other purposes, note however that
-- PostgreSQL does not deliver notifications while a connection is inside
-- a transaction.
getNotification :: Connection -> IO Notification
-- | Non-blocking variant of getNotification. Returns a single
-- notification, if available. If no notifications are available, returns
-- Nothing.
getNotificationNonBlocking :: Connection -> IO (Maybe Notification)
-- | Returns the process CPid 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
instance GHC.Classes.Eq Database.PostgreSQL.Simple.Notification.Notification
instance GHC.Show.Show Database.PostgreSQL.Simple.Notification.Notification
-- | Support for PostgreSQL's Large Objects; see
-- https://www.postgresql.org/docs/9.5/static/largeobjects.html
-- 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 loCreat, loCreate, and loUnlink, you will
-- need to run the entire sequence of functions in a transaction. As
-- loImport and loExport are simply C functions that call
-- loCreat, loOpen, loRead, and loWrite, 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 openFile
data IOMode
ReadMode :: IOMode
WriteMode :: IOMode
AppendMode :: IOMode
ReadWriteMode :: IOMode
-- | A mode that determines the effect of hSeek hdl mode i.
data SeekMode
-- | the position of hdl is set to i.
AbsoluteSeek :: SeekMode
-- | the position of hdl is set to offset i from the
-- current position.
RelativeSeek :: SeekMode
-- | the position of hdl is set to offset i from the end
-- of the file.
SeekFromEnd :: SeekMode
-- | | Module for parsing errors from postgresql error messages. Currently
-- only parses integrity violation errors (class 23).
--
-- Note: Success of parsing may depend on language settings.
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 SqlError to ConstrainViolation,
-- checks sqlState and succeeds only if able to parse sqlErrorMsg.
--
--
-- createUser = handleJust constraintViolation handler $ execute conn ...
-- where
-- handler (UniqueViolation "user_login_key") = ...
-- handler _ = ...
--
constraintViolation :: SqlError -> Maybe ConstraintViolation
-- | Like constraintViolation, but also packs original SqlError.
--
--
-- createUser = handleJust constraintViolationE handler $ execute conn ...
-- where
-- handler (_, UniqueViolation "user_login_key") = ...
-- handler (e, _) = throwIO e
--
constraintViolationE :: SqlError -> Maybe (SqlError, ConstraintViolation)
-- | Catches SqlError, tries to convert to ConstraintViolation, re-throws
-- on fail. Provides alternative interface to handleJust
--
--
-- createUser = catchViolation catcher $ execute conn ...
-- where
-- catcher _ (UniqueViolation "user_login_key") = ...
-- catcher e _ = throwIO e
--
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.Type.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 "begin
-- transaction" statement, then executes the supplied action. If the
-- action succeeds, the transaction will be completed with commit
-- before this function returns.
--
-- If the action throws any kind of exception (not just a
-- PostgreSQL-related exception), the transaction will be rolled back
-- using rollback, then the exception will be rethrown.
--
-- For nesting transactions, see withSavepoint.
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
-- | withTransactionModeRetry' but with the exception type pinned to
-- SqlError.
withTransactionModeRetry :: TransactionMode -> (SqlError -> Bool) -> Connection -> IO a -> IO a
-- | Like withTransactionMode, but also takes a custom callback to
-- determine if a transaction should be retried if an exception occurs.
-- If the callback returns True, then the transaction will be
-- retried. If the callback returns False, or an exception other
-- than an e occurs then the transaction will be rolled back and
-- the exception rethrown.
--
-- This is used to implement withTransactionSerializable.
withTransactionModeRetry' :: forall a e. Exception e => TransactionMode -> (e -> Bool) -> Connection -> IO a -> IO a
-- | Execute an action inside of a Serializable 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 Serializable 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 retry.
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
-- https://www.postgresql.org/docs/9.5/static/transaction-iso.html
-- for more information. Note that prior to PostgreSQL 9.0,
-- RepeatableRead was equivalent to Serializable.
data IsolationLevel
-- | the isolation level will be taken from PostgreSQL's per-connection
-- default_transaction_isolation variable, which is initialized
-- according to the server's config. The default configuration is
-- ReadCommitted.
DefaultIsolationLevel :: IsolationLevel
ReadCommitted :: IsolationLevel
RepeatableRead :: IsolationLevel
Serializable :: IsolationLevel
data ReadWriteMode
-- | the read-write mode will be taken from PostgreSQL's per-connection
-- default_transaction_read_only variable, which is initialized
-- according to the server's config. The default configuration is
-- ReadWrite.
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
-- https://www.postgresql.org/docs/9.5/static/sql-savepoint.html
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 SqlError matching
-- isFailedTransactionError if the transaction is aborted due to
-- an error. commit 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
-- rollbackToSavepoint followed by releaseSavepoint, but
-- avoids a round trip to the database server.
rollbackToAndReleaseSavepoint :: Connection -> Savepoint -> IO ()
isSerializationError :: SqlError -> Bool
isNoActiveTransactionError :: SqlError -> Bool
isFailedTransactionError :: SqlError -> Bool
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
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.Classes.Eq Database.PostgreSQL.Simple.Transaction.TransactionMode
instance GHC.Show.Show Database.PostgreSQL.Simple.Transaction.TransactionMode
-- | 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 IsString, so the easiest way to
-- construct a query is to enable the OverloadedStrings language
-- extension and then simply write the query in double quotes.
--
--
-- {-# LANGUAGE OverloadedStrings #-}
--
-- import Database.PostgreSQL.Simple
--
-- q :: Query
-- q = "select ?"
--
--
-- The underlying type is a ByteString, 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
-- Actions.
--
-- Instances should use the toField method of the ToField
-- class to perform conversion of each element of the collection.
--
-- You can derive ToRow for your data type using GHC generics,
-- like this:
--
--
-- {-# LANGUAGE DeriveAnyClass #-}
-- {-# LANGUAGE DeriveGeneric #-}
--
-- import GHC.Generics (Generic)
-- import Database.PostgreSQL.Simple (ToRow)
--
-- data User = User { name :: String, fileQuota :: Int }
-- deriving (Generic, ToRow)
--
--
-- Note that this only works for product types (e.g. records) and does
-- not support sum types or recursive types.
class ToRow a
-- | A collection type that can be converted from a sequence of fields.
-- Instances are provided for tuples up to 10 elements and lists of any
-- length.
--
-- Note that instances can be defined outside of postgresql-simple, which
-- is often useful. For example, here's an instance for a user-defined
-- pair:
--
--
-- data User = User { name :: String, fileQuota :: Int }
--
-- instance FromRow User where
-- fromRow = User <$> field <*> field
--
--
-- The number of calls to field must match the number of fields
-- returned in a single row of the query result. Otherwise, a
-- ConversionFailed exception will be thrown.
--
-- You can also derive FromRow for your data type using GHC
-- generics, like this:
--
--
-- {-# LANGUAGE DeriveAnyClass #-}
-- {-# LANGUAGE DeriveGeneric #-}
--
-- import GHC.Generics (Generic)
-- import Database.PostgreSQL.Simple (FromRow)
--
-- data User = User { name :: String, fileQuota :: Int }
-- deriving (Generic, FromRow)
--
--
-- Note that this only works for product types (e.g. records) and does
-- not support sum types or recursive types.
--
-- Note that field evaluates its 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 fromField.
class FromRow a
-- | Wrap a list of values for use in an IN clause. Replaces a
-- single "?" character with a parenthesized list of rendered
-- values.
--
-- Example:
--
--
-- query c "select * from whatever where id in ?" (Only (In [3,4,5]))
--
--
-- Note that In [] expands to (null), which works as
-- expected in the query above, but evaluates to the logical null value
-- on every row instead of TRUE. This means that changing the
-- query above to ... id NOT in ? and supplying the empty list
-- as the parameter returns zero rows, instead of all of them as one
-- would expect.
--
-- Since postgresql doesn't seem to provide a syntax for actually
-- specifying an empty list, which could solve this completely, there are
-- two workarounds particularly worth mentioning, namely:
--
--
-- - Use postgresql-simple's Values type instead, which can
-- handle the empty case correctly. Note however that while specifying
-- the postgresql type "int4" is mandatory in the empty case,
-- specifying the haskell type Values (Only Int) would not
-- normally be needed in realistic use cases.
query c "select * from
-- whatever where id not in ?" (Only (Values ["int4"] [] :: Values (Only
-- Int)))
-- - Use sql's COALESCE operator to turn a logical
-- null into the correct boolean. Note however that the correct
-- boolean depends on the use case:
query c "select * from whatever
-- where coalesce(id NOT in ?, TRUE)" (Only (In [] :: In
-- [Int]))
query c "select * from whatever where coalesce(id IN
-- ?, FALSE)" (Only (In [] :: In [Int]))
Note that at as of
-- PostgreSQL 9.4, the query planner cannot see inside the
-- COALESCE operator, so if you have an index on id
-- then you probably don't want to write the last example with
-- COALESCE, which would result in a table scan. There are
-- further caveats if id can be null or you want null treated
-- sensibly as a component of IN or NOT IN.
--
newtype In a
In :: a -> In a
-- | Wrap binary data for use as a bytea value.
newtype Binary a
Binary :: a -> Binary a
[fromBinary] :: Binary a -> a
-- | The 1-tuple type or single-value "collection".
--
-- This type is structurally equivalent to the Identity type, but
-- its intent is more about serving as the anonymous 1-tuple type missing
-- from Haskell for attaching typeclass instances.
--
-- Parameter usage example:
--
--
-- encodeSomething (Only (42::Int))
--
--
-- Result usage example:
--
--
-- xs <- decodeSomething
-- forM_ xs $ \(Only id) -> {- ... -}
--
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.
--
--
-- instance FromRow MyData where ...
--
--
--
-- instance FromRow MyData2 where ...
--
--
-- then I can do the following for free:
--
--
-- res <- query' c "..."
-- forM res $ \(MyData{..} :. MyData2{..}) -> do
-- ....
--
data h :. t
(:.) :: h -> t -> (:.) h t
infixr 3 :.
infixr 3 :.
-- | Superclass for postgresql exceptions
data SomePostgreSqlException
SomePostgreSqlException :: e -> SomePostgreSqlException
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
-- | Copy In/Out data transfer started.
CopyBoth :: 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
-- | The PGresult contains a single result tuple from the current command.
-- This status occurs only when single-row mode has been selected for the
-- query.
SingleTuple :: ExecStatus
-- | Exception thrown if a Query could not be formatted correctly.
-- This may occur if the number of '?' 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 query is used to perform an
-- INSERT-like operation, or execute is used to perform
-- a SELECT-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 NULL 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
-- https://www.postgresql.org/docs/9.5/static/libpq-connect.html#LIBPQ-CONNSTRING
-- 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
-- https://www.postgresql.org/docs/9.5/static/libpq-envars.html
-- for details. Here is an example with some of the most commonly used
-- parameters:
--
--
-- host='db.somedomain.com' port=5432 ...
--
--
-- This attempts to connect to db.somedomain.com:5432. 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 DEFAULT_PGSOCKET_DIR constant defined
-- in the pg_config_manual.h header file. Connecting via unix
-- sockets tends to use the peer 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 localhost.
--
--
-- ... dbname='postgres' user='postgres' password='secret \' \\ pw'
--
--
-- This attempts to connect to a database named postgres with
-- user postgres and password secret ' \ pw. Backslash
-- characters will have to be double-quoted in literal Haskell strings,
-- of course. Omitting dbname and user will both
-- default to the system username that the client process is running as.
--
-- Omitting password will default to an appropriate password
-- found in the pgpass file, or no password at all if a matching
-- line is not found. The path of the pgpass file may be
-- specified by setting the PGPASSFILE environment variable. See
-- https://www.postgresql.org/docs/9.5/static/libpq-pgpass.html
-- 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 pg_hba.conf to
-- specify the use of the trust authentication method for the
-- connection, which may not be appropriate for multiuser or production
-- machines, or you will need to use a pgpass file with the
-- password or md5 authentication methods.
--
-- See
-- https://www.postgresql.org/docs/9.5/static/client-authentication.html
-- 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 connection parameters. In
-- particular, sslmode needs to be set to require,
-- verify-ca, or verify-full in order to perform
-- certificate validation. When sslmode is require,
-- then you will also need to specify a sslrootcert file,
-- otherwise no validation of the server's identity will be performed.
-- Client authentication via certificates is also possible via the
-- sslcert and sslkey parameters. See
-- https://www.postgresql.org/docs/9.5/static/libpq-ssl.html for
-- detailed information regarding libpq and SSL.
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
-- | Memory bracket around connect and close.
withConnect :: ConnectInfo -> (Connection -> IO c) -> IO c
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:
--
--
-- - Server on localhost
-- - Port on 5432
-- - User postgres
-- - No password
-- - Database postgres
--
--
-- Use as in the following example:
--
--
-- connect defaultConnectInfo { connectHost = "db.example.com" }
--
defaultConnectInfo :: ConnectInfo
-- | Turns a ConnectInfo data structure into a libpq connection
-- string.
postgreSQLConnectionString :: ConnectInfo -> ByteString
-- | Perform a SELECT 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 fold instead.
--
-- Exceptions that may be thrown:
--
--
-- - FormatError: the query string could not be formatted
-- correctly.
-- - QueryError: the result contains no columns (i.e. you should
-- be using execute instead of query).
-- - ResultError: result conversion failed.
-- - SqlError: the postgresql backend returned an error, e.g. a
-- syntax or type error, or an incorrect table or column name.
--
query :: (ToRow q, FromRow r) => Connection -> Query -> q -> IO [r]
-- | A version of query that does not perform query substitution.
query_ :: FromRow r => Connection -> Query -> IO [r]
-- | A version of query taking parser as argument
queryWith :: ToRow q => RowParser r -> Connection -> Query -> q -> IO [r]
-- | A version of query_ 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. Automatic 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 Automatic, and TransactionMode
-- ReadCommitted ReadOnly
defaultFoldOptions :: FoldOptions
-- | Perform a SELECT 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 query instead.
--
-- This fold is not 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 ReadCommitted
-- ReadOnly transaction if needed. The cursor is given a unique
-- temporary name, so the consumer may itself call fold.
--
-- Exceptions that may be thrown:
--
--
-- - FormatError: the query string could not be formatted
-- correctly.
-- - QueryError: the result contains no columns (i.e. you should
-- be using execute instead of query).
-- - ResultError: result conversion failed.
-- - SqlError: the postgresql backend returned an error, e.g. a
-- syntax or type error, or an incorrect table or column name.
--
fold :: (FromRow row, ToRow params) => Connection -> Query -> params -> a -> (a -> row -> IO a) -> IO a
-- | The same as fold, 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 transactionMode
-- option is ignored.
foldWithOptions :: (FromRow row, ToRow params) => FoldOptions -> Connection -> Query -> params -> a -> (a -> row -> IO a) -> IO a
-- | A version of fold 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 fold that does not transform a state value.
forEach :: (ToRow q, FromRow r) => Connection -> Query -> q -> (r -> IO ()) -> IO ()
-- | A version of forEach that does not perform query substitution.
forEach_ :: FromRow r => Connection -> Query -> (r -> IO ()) -> IO ()
-- | Execute INSERT ... RETURNING, UPDATE ... RETURNING,
-- or other SQL query that accepts multi-row input and is expected to
-- return results. Note that it is possible to write query
-- conn "INSERT ... RETURNING ..." ... in cases where you are only
-- inserting a single row, and do not need functionality analogous to
-- executeMany.
--
-- If the list of parameters is empty, this function will simply return
-- [] without issuing the query to the backend. If this is not
-- desired, consider using the Values constructor instead.
--
-- Throws FormatError if the query could not be formatted
-- correctly.
returning :: (ToRow q, FromRow r) => Connection -> Query -> [q] -> IO [r]
-- | A version of fold taking a parser as an argument
foldWith :: ToRow params => RowParser row -> Connection -> Query -> params -> a -> (a -> row -> IO a) -> IO a
-- | A version of foldWithOptions 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 fold_ taking a parser as an argument
foldWith_ :: RowParser r -> Connection -> Query -> a -> (a -> r -> IO a) -> IO a
-- | A version of foldWithOptions_ taking a parser as an argument
foldWithOptionsAndParser_ :: FoldOptions -> RowParser r -> Connection -> Query -> a -> (a -> r -> IO a) -> IO a
-- | A version of forEach 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 ()
-- | A version of returning taking parser as argument
returningWith :: ToRow q => RowParser r -> Connection -> Query -> [q] -> IO [r]
-- | Execute an INSERT, UPDATE, or other SQL query that
-- is not expected to return results.
--
-- Returns the number of rows affected.
--
-- Throws FormatError if the query could not be formatted
-- correctly, or a SqlError exception if the backend returns an
-- error.
execute :: ToRow q => Connection -> Query -> q -> IO Int64
-- | A version of execute that does not perform query
-- substitution.
execute_ :: Connection -> Query -> IO Int64
-- | Execute a multi-row INSERT, UPDATE, 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
-- Values constructor instead.
--
-- Throws FormatError if the query could not be formatted
-- correctly, or a SqlError exception if the backend returns an
-- error.
--
-- For example, here's a command that inserts two rows into a table with
-- two columns:
--
--
-- executeMany c [sql|
-- INSERT INTO sometable VALUES (?,?)
-- |] [(1, "hello"),(2, "world")]
--
--
-- Here's an canonical example of a multi-row update command:
--
--
-- executeMany c [sql|
-- UPDATE sometable
-- SET y = upd.y
-- FROM (VALUES (?,?)) as upd(x,y)
-- WHERE sometable.x = upd.x
-- |] [(1, "hello"),(2, "world")]
--
executeMany :: ToRow q => Connection -> Query -> [q] -> IO Int64
-- | Execute an action inside a SQL transaction.
--
-- This function initiates a transaction with a "begin
-- transaction" statement, then executes the supplied action. If the
-- action succeeds, the transaction will be completed with commit
-- before this function returns.
--
-- If the action throws any kind of exception (not just a
-- PostgreSQL-related exception), the transaction will be rolled back
-- using rollback, then the exception will be rethrown.
--
-- For nesting transactions, see withSavepoint.
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
-- https://www.postgresql.org/docs/9.5/static/sql-savepoint.html
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 "VALUES" (case insensitive)
-- followed by an "(" character, a series of one or more
-- "?" characters separated by commas, and a ")"
-- character. White space in a substitution group is permitted.
--
-- Throws FormatError 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 Connection.
--
-- Throws FormatError if the query string could not be formatted
-- correctly.
formatQuery :: ToRow q => Connection -> Query -> q -> IO ByteString
-- | This module provides convenient and efficient access to parts of the
-- pg_type metatable. At the moment, this requires PostgreSQL
-- 8.4 if you need to work with types that do not appear in
-- Static.
--
-- 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) pg_type 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, getTypeInfo first consults postgresql-simple's built-in
-- staticTypeInfo table, then checks the connection's typeinfo
-- cache. Finally, the database's pg_type 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 pg_type 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 FromField 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 FromField 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 Double type is compatible with the PostgreSQL's
-- 32-bit int type because it can represent a int
-- exactly. On the other hand, since a Double might lose precision
-- if representing PostgreSQL's 64-bit bigint, the two are
-- not considered compatible.
--
-- Note that the Float and Double instances use
-- attoparsec's double conversion routine, which sacrifices some
-- accuracy for speed. If you need accuracy, consider first converting
-- data to a Scientific or Rational type, and then
-- converting to a floating-point type. If you are defining your own
-- FromRow instances, this can be achieved simply by
-- fromRational <$> field, although
-- this idiom is additionally compatible with PostgreSQL's int8
-- and numeric types. If this is unacceptable, you may find
-- fieldWith useful.
--
-- Also note that while converting to a Double through the
-- Scientific type is likely somewhat faster than converting
-- through the Rational type, the Scientific type has no
-- way to represent NaN and ±Infinity 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 Rational.
--
-- Because FromField 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 Read class:
--
--
-- 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 -> returnError UnexpectedNull f ""
-- Just dat ->
-- case [ x | (x,t) <- reads dat, ("","") <- lex t ] of
-- [x] -> return x
-- _ -> returnError ConversionFailed f dat
--
--
-- Note that because PostgreSQL's uuid type is built into
-- postgres and is not provided by an extension, the typeOid of
-- uuid 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
-- PostGIS or hstore, then the typeOid is not
-- stable and can vary from database to database. In this case it is
-- recommended that FromField instances use typename 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 ResultError,
-- but may be a UnicodeException.
--
-- Note that retaining any reference to the Field argument causes
-- the entire LibPQ.Result to be retained. Thus,
-- implementations of fromField should return results that do not
-- refer to this value after the result have been evaluated to WHNF.
--
-- Note that as of postgresql-simple-0.4.0.0, the
-- ByteString value has already been copied out of the
-- LibPQ.Result before it has been passed to
-- fromField. 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 NULL 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 ResultError, the field, and
-- an errMessage, this fills in the other fields in the exception
-- value and returns it in a 'Left . SomeException' constructor.
returnError :: forall a err. (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 typname column associated
-- with the type oid in the pg_type 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 pg_type 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 as clause.
name :: Field -> Maybe ByteString
-- | Returns the name of the object id of the table associated
-- with the column, if any. Returns Nothing when there is no such
-- table; for example a computed column does not have a table associated
-- with it. Analogous to libpq's PQftable.
tableOid :: Field -> Maybe Oid
-- | If the column has a table associated with it, this returns the number
-- of the associated table column. Table columns have nonzero numbers.
-- Zero is returned if the specified column is not a simple reference to
-- a table column, or when using pre-3.0 protocol. Analogous to libpq's
-- PQftablecol.
tableColumn :: Field -> Int
-- | This returns whether the data was returned in a binary or textual
-- format. Analogous to libpq's PQfformat.
format :: Field -> Format
-- | This returns the type oid associated with the column. Analogous to
-- libpq's PQftype.
typeOid :: Field -> Oid
newtype Oid
Oid :: CUInt -> Oid
data Format
Text :: Format
Binary :: Format
pgArrayFieldParser :: Typeable a => FieldParser a -> FieldParser (PGArray a)
-- | Construct a field parser from an attoparsec parser. An
-- Incompatible error is thrown if the PostgreSQL oid does not
-- match the specified predicate.
--
--
-- instance FromField Int16 where
-- fromField = attoFieldParser ok16 (signed decimal)
--
attoFieldParser :: forall a. Typeable a => (Oid -> Bool) -> Parser a -> FieldParser a
-- | For dealing with SQL null values outside of the
-- FromField class. Alternatively, one could use optional,
-- but that also turns type and conversion errors into Nothing,
-- whereas this is more specific and turns only null values into
-- Nothing.
optionalField :: FieldParser a -> FieldParser (Maybe a)
-- | Parse a field to a JSON Value and convert that into a Haskell
-- value using the FromJSON instance.
--
-- This can be used as the default implementation for the
-- fromField method for Haskell types that have a JSON
-- representation in PostgreSQL.
--
-- The Typeable constraint is required to show more informative
-- error messages when parsing fails.
--
-- Note that fromJSONField :: FieldParser (Maybe Foo)
-- will return Nothing on the json null value,
-- and return an exception on SQL null value. Alternatively, one
-- could write optionalField fromJSONField that will
-- return Nothing on SQL null, and otherwise will call
-- fromJSONField :: FieldParser Foo and then return
-- Just the result value, or return its exception. If one
-- would like to return Nothing on both the SQL null
-- and json null values, one way to do it would be to write
-- \f mv -> join <$> optionalField
-- fromJSONField f mv
fromJSONField :: (FromJSON a, Typeable a) => FieldParser a
-- | Return the JSON ByteString directly
fromFieldJSONByteString :: Field -> Maybe ByteString -> Conversion ByteString
instance GHC.Show.Show Database.PostgreSQL.Simple.FromField.ResultError
instance GHC.Classes.Eq Database.PostgreSQL.Simple.FromField.ResultError
instance Database.PostgreSQL.Simple.FromField.FromField ()
instance forall k a (b :: k). Database.PostgreSQL.Simple.FromField.FromField a => Database.PostgreSQL.Simple.FromField.FromField (Data.Functor.Const.Const a b)
instance Database.PostgreSQL.Simple.FromField.FromField a => Database.PostgreSQL.Simple.FromField.FromField (Data.Functor.Identity.Identity a)
instance Database.PostgreSQL.Simple.FromField.FromField a => Database.PostgreSQL.Simple.FromField.FromField (GHC.Maybe.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.Num.Integer.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.Num.Integer.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.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.Internal.UTCTime.UTCTime
instance Database.PostgreSQL.Simple.FromField.FromField Data.Time.LocalTime.Internal.ZonedTime.ZonedTime
instance Database.PostgreSQL.Simple.FromField.FromField Data.Time.LocalTime.Internal.LocalTime.LocalTime
instance Database.PostgreSQL.Simple.FromField.FromField Data.Time.Calendar.Days.Day
instance Database.PostgreSQL.Simple.FromField.FromField Data.Time.LocalTime.Internal.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 Data.Time.LocalTime.Internal.CalendarDiffTime.CalendarDiffTime
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)
instance GHC.Exception.Type.Exception Database.PostgreSQL.Simple.FromField.ResultError
-- | The FromRow 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 Maybe types return Nothing
-- 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:
--
--
-- data User = User { name :: String, fileQuota :: Int }
--
-- instance FromRow User where
-- fromRow = User <$> field <*> field
--
--
-- The number of calls to field must match the number of fields
-- returned in a single row of the query result. Otherwise, a
-- ConversionFailed exception will be thrown.
--
-- You can also derive FromRow for your data type using GHC
-- generics, like this:
--
--
-- {-# LANGUAGE DeriveAnyClass #-}
-- {-# LANGUAGE DeriveGeneric #-}
--
-- import GHC.Generics (Generic)
-- import Database.PostgreSQL.Simple (FromRow)
--
-- data User = User { name :: String, fileQuota :: Int }
-- deriving (Generic, FromRow)
--
--
-- Note that this only works for product types (e.g. records) and does
-- not support sum types or recursive types.
--
-- Note that field evaluates its 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 fromField.
class FromRow a
fromRow :: FromRow a => RowParser a
fromRow :: (FromRow a, Generic a, GFromRow (Rep 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 (Data.Tuple.Only.Only a)
instance Database.PostgreSQL.Simple.FromField.FromField a => Database.PostgreSQL.Simple.FromRow.FromRow (GHC.Maybe.Maybe (Data.Tuple.Only.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.Maybe.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.Maybe.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.Maybe.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.Maybe.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.Maybe.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.Maybe.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.Maybe.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.Maybe.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.Maybe.Maybe (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.FromField.FromField k) => Database.PostgreSQL.Simple.FromRow.FromRow (a, b, c, d, e, f, g, h, i, j, k)
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.FromField.FromField k) => Database.PostgreSQL.Simple.FromRow.FromRow (GHC.Maybe.Maybe (a, b, c, d, e, f, g, h, i, j, k))
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.FromField.FromField k, Database.PostgreSQL.Simple.FromField.FromField l) => Database.PostgreSQL.Simple.FromRow.FromRow (a, b, c, d, e, f, g, h, i, j, k, l)
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.FromField.FromField k, Database.PostgreSQL.Simple.FromField.FromField l) => Database.PostgreSQL.Simple.FromRow.FromRow (GHC.Maybe.Maybe (a, b, c, d, e, f, g, h, i, j, k, l))
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.FromField.FromField k, Database.PostgreSQL.Simple.FromField.FromField l, Database.PostgreSQL.Simple.FromField.FromField m) => Database.PostgreSQL.Simple.FromRow.FromRow (a, b, c, d, e, f, g, h, i, j, k, l, m)
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.FromField.FromField k, Database.PostgreSQL.Simple.FromField.FromField l, Database.PostgreSQL.Simple.FromField.FromField m) => Database.PostgreSQL.Simple.FromRow.FromRow (GHC.Maybe.Maybe (a, b, c, d, e, f, g, h, i, j, k, l, m))
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.FromField.FromField k, Database.PostgreSQL.Simple.FromField.FromField l, Database.PostgreSQL.Simple.FromField.FromField m, Database.PostgreSQL.Simple.FromField.FromField n) => Database.PostgreSQL.Simple.FromRow.FromRow (a, b, c, d, e, f, g, h, i, j, k, l, m, n)
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.FromField.FromField k, Database.PostgreSQL.Simple.FromField.FromField l, Database.PostgreSQL.Simple.FromField.FromField m, Database.PostgreSQL.Simple.FromField.FromField n) => Database.PostgreSQL.Simple.FromRow.FromRow (GHC.Maybe.Maybe (a, b, c, d, e, f, g, h, i, j, k, l, m, n))
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.FromField.FromField k, Database.PostgreSQL.Simple.FromField.FromField l, Database.PostgreSQL.Simple.FromField.FromField m, Database.PostgreSQL.Simple.FromField.FromField n, Database.PostgreSQL.Simple.FromField.FromField o) => Database.PostgreSQL.Simple.FromRow.FromRow (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o)
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.FromField.FromField k, Database.PostgreSQL.Simple.FromField.FromField l, Database.PostgreSQL.Simple.FromField.FromField m, Database.PostgreSQL.Simple.FromField.FromField n, Database.PostgreSQL.Simple.FromField.FromField o) => Database.PostgreSQL.Simple.FromRow.FromRow (GHC.Maybe.Maybe (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o))
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.FromField.FromField k, Database.PostgreSQL.Simple.FromField.FromField l, Database.PostgreSQL.Simple.FromField.FromField m, Database.PostgreSQL.Simple.FromField.FromField n, Database.PostgreSQL.Simple.FromField.FromField o, Database.PostgreSQL.Simple.FromField.FromField p) => Database.PostgreSQL.Simple.FromRow.FromRow (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p)
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.FromField.FromField k, Database.PostgreSQL.Simple.FromField.FromField l, Database.PostgreSQL.Simple.FromField.FromField m, Database.PostgreSQL.Simple.FromField.FromField n, Database.PostgreSQL.Simple.FromField.FromField o, Database.PostgreSQL.Simple.FromField.FromField p) => Database.PostgreSQL.Simple.FromRow.FromRow (GHC.Maybe.Maybe (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p))
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.FromField.FromField k, Database.PostgreSQL.Simple.FromField.FromField l, Database.PostgreSQL.Simple.FromField.FromField m, Database.PostgreSQL.Simple.FromField.FromField n, Database.PostgreSQL.Simple.FromField.FromField o, Database.PostgreSQL.Simple.FromField.FromField p, Database.PostgreSQL.Simple.FromField.FromField q) => Database.PostgreSQL.Simple.FromRow.FromRow (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q)
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.FromField.FromField k, Database.PostgreSQL.Simple.FromField.FromField l, Database.PostgreSQL.Simple.FromField.FromField m, Database.PostgreSQL.Simple.FromField.FromField n, Database.PostgreSQL.Simple.FromField.FromField o, Database.PostgreSQL.Simple.FromField.FromField p, Database.PostgreSQL.Simple.FromField.FromField q) => Database.PostgreSQL.Simple.FromRow.FromRow (GHC.Maybe.Maybe (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q))
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.FromField.FromField k, Database.PostgreSQL.Simple.FromField.FromField l, Database.PostgreSQL.Simple.FromField.FromField m, Database.PostgreSQL.Simple.FromField.FromField n, Database.PostgreSQL.Simple.FromField.FromField o, Database.PostgreSQL.Simple.FromField.FromField p, Database.PostgreSQL.Simple.FromField.FromField q, Database.PostgreSQL.Simple.FromField.FromField r) => Database.PostgreSQL.Simple.FromRow.FromRow (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r)
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.FromField.FromField k, Database.PostgreSQL.Simple.FromField.FromField l, Database.PostgreSQL.Simple.FromField.FromField m, Database.PostgreSQL.Simple.FromField.FromField n, Database.PostgreSQL.Simple.FromField.FromField o, Database.PostgreSQL.Simple.FromField.FromField p, Database.PostgreSQL.Simple.FromField.FromField q, Database.PostgreSQL.Simple.FromField.FromField r) => Database.PostgreSQL.Simple.FromRow.FromRow (GHC.Maybe.Maybe (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r))
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.FromField.FromField k, Database.PostgreSQL.Simple.FromField.FromField l, Database.PostgreSQL.Simple.FromField.FromField m, Database.PostgreSQL.Simple.FromField.FromField n, Database.PostgreSQL.Simple.FromField.FromField o, Database.PostgreSQL.Simple.FromField.FromField p, Database.PostgreSQL.Simple.FromField.FromField q, Database.PostgreSQL.Simple.FromField.FromField r, Database.PostgreSQL.Simple.FromField.FromField s) => Database.PostgreSQL.Simple.FromRow.FromRow (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s)
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.FromField.FromField k, Database.PostgreSQL.Simple.FromField.FromField l, Database.PostgreSQL.Simple.FromField.FromField m, Database.PostgreSQL.Simple.FromField.FromField n, Database.PostgreSQL.Simple.FromField.FromField o, Database.PostgreSQL.Simple.FromField.FromField p, Database.PostgreSQL.Simple.FromField.FromField q, Database.PostgreSQL.Simple.FromField.FromField r, Database.PostgreSQL.Simple.FromField.FromField s) => Database.PostgreSQL.Simple.FromRow.FromRow (GHC.Maybe.Maybe (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s))
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.FromField.FromField k, Database.PostgreSQL.Simple.FromField.FromField l, Database.PostgreSQL.Simple.FromField.FromField m, Database.PostgreSQL.Simple.FromField.FromField n, Database.PostgreSQL.Simple.FromField.FromField o, Database.PostgreSQL.Simple.FromField.FromField p, Database.PostgreSQL.Simple.FromField.FromField q, Database.PostgreSQL.Simple.FromField.FromField r, Database.PostgreSQL.Simple.FromField.FromField s, Database.PostgreSQL.Simple.FromField.FromField t) => Database.PostgreSQL.Simple.FromRow.FromRow (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t)
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.FromField.FromField k, Database.PostgreSQL.Simple.FromField.FromField l, Database.PostgreSQL.Simple.FromField.FromField m, Database.PostgreSQL.Simple.FromField.FromField n, Database.PostgreSQL.Simple.FromField.FromField o, Database.PostgreSQL.Simple.FromField.FromField p, Database.PostgreSQL.Simple.FromField.FromField q, Database.PostgreSQL.Simple.FromField.FromField r, Database.PostgreSQL.Simple.FromField.FromField s, Database.PostgreSQL.Simple.FromField.FromField t) => Database.PostgreSQL.Simple.FromRow.FromRow (GHC.Maybe.Maybe (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t))
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.Maybe.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.Maybe.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
module Database.PostgreSQL.Simple.Cursor
-- | Cursor within a transaction.
data Cursor
-- | Declare a temporary cursor. The cursor is given a unique name for the
-- given connection.
declareCursor :: Connection -> Query -> IO Cursor
-- | Close the given cursor.
closeCursor :: Cursor -> IO ()
-- | Fold over a chunk of rows, calling the supplied fold-like function on
-- each row as it is received. In case the cursor is exhausted, a
-- Left value is returned, otherwise a Right value is
-- returned.
foldForward :: FromRow r => Cursor -> Int -> (a -> r -> IO a) -> a -> IO (Either a a)
-- | Fold over a chunk of rows from the given cursor, calling the supplied
-- fold-like function on each row as it is received. In case the cursor
-- is exhausted, a Left value is returned, otherwise a
-- Right value is returned.
foldForwardWithParser :: Cursor -> RowParser r -> Int -> (a -> r -> IO a) -> a -> IO (Either a a)
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 True, then the
-- contains predicate will always return False. However, if
-- this returns False, it is not necessarily true that there
-- exists a point for which contains returns True. Consider
-- PGRange (Excludes 2) (Excludes 3) ::
-- PGRange Int, 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
-- UTCTime for example, which has a resolution of a picosecond,
-- whereas postgresql's timestamptz 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
fromFieldRange :: Typeable a => FieldParser a -> FieldParser (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.Base.Functor Database.PostgreSQL.Simple.Range.PGRange
instance GHC.Show.Show a => GHC.Show.Show (Database.PostgreSQL.Simple.Range.PGRange 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.Num.Integer.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.Internal.UTCTime.UTCTime)
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Range.PGRange Data.Time.LocalTime.Internal.ZonedTime.ZonedTime)
instance Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Range.PGRange Data.Time.LocalTime.Internal.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.Internal.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.Internal.NominalDiffTime.NominalDiffTime)
-- | Module with newtypes suitable to usage with DerivingVia or
-- standalone.
--
-- The newtypes are named after packages they wrap.
module Database.PostgreSQL.Simple.Newtypes
-- | A newtype wrapper with ToField and FromField instances
-- based on ToJSON and FromJSON type classes from
-- aeson.
--
-- Example using DerivingVia:
--
--
-- data Foo = Foo Int String
-- deriving stock (Eq, Show, Generic) -- GHC built int
-- deriving anyclass (FromJSON, ToJSON) -- Derived using GHC Generics
-- deriving (ToField, FromField) via Aeson Foo -- DerivingVia
--
--
-- Example using Aeson newtype directly, for more ad-hoc queries
--
--
-- execute conn "INSERT INTO tbl (fld) VALUES (?)" (Only (Aeson x))
--
newtype Aeson a
Aeson :: a -> Aeson a
getAeson :: Aeson a -> a
instance GHC.Base.Functor Database.PostgreSQL.Simple.Newtypes.Aeson
instance GHC.Read.Read a => GHC.Read.Read (Database.PostgreSQL.Simple.Newtypes.Aeson a)
instance GHC.Show.Show a => GHC.Show.Show (Database.PostgreSQL.Simple.Newtypes.Aeson a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Database.PostgreSQL.Simple.Newtypes.Aeson a)
instance Data.Aeson.Types.ToJSON.ToJSON a => Database.PostgreSQL.Simple.ToField.ToField (Database.PostgreSQL.Simple.Newtypes.Aeson a)
instance (Data.Aeson.Types.FromJSON.FromJSON a, Data.Typeable.Internal.Typeable a) => Database.PostgreSQL.Simple.FromField.FromField (Database.PostgreSQL.Simple.Newtypes.Aeson a)
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)
-- | Parsers and printers for hstore, a extended type bundled with
-- PostgreSQL providing finite maps from text strings to text strings.
-- See https://www.postgresql.org/docs/9.5/static/hstore.html 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 CREATE EXTENSION
-- hstore. See
-- https://www.postgresql.org/docs/9.5/static/contrib.html 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
-- | mid-level support for COPY IN and COPY OUT. See
-- https://www.postgresql.org/docs/9.5/static/sql-copy.html for
-- more information.
--
-- To use this binding, first call copy with an appropriate query
-- as documented in the link above. Then, in the case of a COPY TO
-- STDOUT query, call getCopyData repeatedly until it returns
-- CopyOutDone. In the case of a COPY FROM STDIN query,
-- call putCopyData repeatedly and then finish by calling either
-- putCopyEnd to proceed or putCopyError 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 getNotification on a connection while it is
-- in a CopyIn or CopyOut 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 COPY FROM STDIN or COPY TO STDOUT query. In
-- the former case, the connection's state will change to
-- CopyIn; in the latter, CopyOut. The connection must
-- be in the ready state in order to call this function. Performs
-- parameter substitution.
copy :: ToRow params => Connection -> Query -> params -> IO ()
-- | Issue a COPY FROM STDIN or COPY TO STDOUT query. In
-- the former case, the connection's state will change to
-- CopyIn; in the latter, CopyOut. 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
-- | Fold over COPY TO STDOUT query passing each copied row to an
-- accumulator and calling a post-process at the end. A connection must
-- be in the CopyOut state in order to call this function.
--
-- Example
--
--
-- (acc, count) <- foldCopyData conn
-- (\acc row -> return (row:acc))
-- (\acc count -> return (acc, count))
-- []
--
foldCopyData :: Connection -> (a -> ByteString -> IO a) -> (a -> Int64 -> IO b) -> a -> IO b
-- | Retrieve some data from a COPY TO STDOUT query. A connection
-- must be in the CopyOut state in order to call this function.
-- If this returns a CopyOutRow, the connection remains in the
-- CopyOut state, if it returns CopyOutDone, then the
-- connection has reverted to the ready state.
getCopyData :: Connection -> IO CopyOutResult
-- | Feed some data to a COPY FROM STDIN query. Note that the data
-- does not need to represent a single row, or even an integral number of
-- rows. The net result of putCopyData conn a >> putCopyData
-- conn b is the same as putCopyData conn c whenever c
-- == BS.append a b.
--
-- A connection must be in the CopyIn state in order to call
-- this function, otherwise a SqlError exception will result. The
-- connection remains in the CopyIn state after this function is
-- called.
putCopyData :: Connection -> ByteString -> IO ()
-- | Completes a COPY FROM STDIN query. Returns the number of rows
-- processed.
--
-- A connection must be in the CopyIn state in order to call
-- this function, otherwise a SqlError exception will result. The
-- connection's state changes back to ready after this function is
-- called.
putCopyEnd :: Connection -> IO Int64
-- | Aborts a COPY FROM STDIN 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 CopyIn state in order to call
-- this function, otherwise a SqlError 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
-- | query variants returning Vector.
module Database.PostgreSQL.Simple.Vector
-- | Perform a SELECT or other SQL query that is expected to
-- return results. All results are retrieved and converted before this
-- function returns.
query :: (ToRow q, FromRow r) => Connection -> Query -> q -> IO (Vector r)
-- | A version of query that does not perform query substitution.
query_ :: FromRow r => Connection -> Query -> IO (Vector r)
-- | A version of query taking parser as argument
queryWith :: ToRow q => RowParser r -> Connection -> Query -> q -> IO (Vector r)
-- | A version of query_ taking parser as argument
queryWith_ :: RowParser r -> Connection -> Query -> IO (Vector r)
-- | Execute INSERT ... RETURNING, UPDATE ... RETURNING,
-- or other SQL query that accepts multi-row input and is expected to
-- return results.
returning :: (ToRow q, FromRow r) => Connection -> Query -> [q] -> IO (Vector r)
-- | A version of returning taking parser as argument
returningWith :: ToRow q => RowParser r -> Connection -> Query -> [q] -> IO (Vector r)
module Database.PostgreSQL.Simple.Vector.Unboxed
-- | Perform a SELECT or other SQL query that is expected to
-- return results. All results are retrieved and converted before this
-- function returns.
query :: (ToRow q, FromRow r, Unbox r) => Connection -> Query -> q -> IO (Vector r)
-- | A version of query that does not perform query substitution.
query_ :: (FromRow r, Unbox r) => Connection -> Query -> IO (Vector r)
-- | A version of query taking parser as argument
queryWith :: (ToRow q, Unbox r) => RowParser r -> Connection -> Query -> q -> IO (Vector r)
-- | A version of query_ taking parser as argument
queryWith_ :: Unbox r => RowParser r -> Connection -> Query -> IO (Vector r)
-- | Execute INSERT ... RETURNING, UPDATE ... RETURNING,
-- or other SQL query that accepts multi-row input and is expected to
-- return results.
returning :: (ToRow q, FromRow r, Unbox r) => Connection -> Query -> [q] -> IO (Vector r)
-- | A version of returning taking parser as argument
returningWith :: (ToRow q, Unbox r) => RowParser r -> Connection -> Query -> [q] -> IO (Vector r)