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


-- | Sql interpolating quasiquote plus some kind of primitive ORM
--   using it
--   
--   Sql interpolating quasiquote plus some kind of primitive ORM using it
@package postgresql-query
@version 3.4.0

module Database.PostgreSQL.Query.SqlBuilder.Types

-- | Result if SqlBuilder. Contains separated builder for query and log.
data SqlBuilderResult
SqlBuilderResult :: Builder -> Builder -> SqlBuilderResult
[sbQueryString] :: SqlBuilderResult -> Builder
[sbLogString] :: SqlBuilderResult -> Builder
builderResultPure :: Builder -> SqlBuilderResult

-- | Option for field instructing <a>LogMasker</a> what to do with field
--   when logging
data FieldOption

-- | Do nothing. Field should be pasted as is
FieldDefault :: FieldOption

-- | Mask field in logs with placeholder.
FieldMasked :: FieldOption

-- | Function modifying query parameter value before pasting it to log.
type LogMasker = FieldOption -> Builder -> Builder

-- | Simply replaces masked fields with placeholder.
defaultLogMasker :: LogMasker

-- | Masks fields which size is bigger than given argument in bytes.
hugeFieldsMasker :: Int -> LogMasker
instance Language.Haskell.TH.Syntax.Lift Database.PostgreSQL.Query.SqlBuilder.Types.FieldOption
instance GHC.Generics.Generic Database.PostgreSQL.Query.SqlBuilder.Types.FieldOption
instance GHC.Show.Show Database.PostgreSQL.Query.SqlBuilder.Types.FieldOption
instance GHC.Classes.Ord Database.PostgreSQL.Query.SqlBuilder.Types.FieldOption
instance GHC.Classes.Eq Database.PostgreSQL.Query.SqlBuilder.Types.FieldOption
instance GHC.Generics.Generic Database.PostgreSQL.Query.SqlBuilder.Types.SqlBuilderResult
instance Data.Semigroup.Semigroup Database.PostgreSQL.Query.SqlBuilder.Types.SqlBuilderResult
instance GHC.Base.Monoid Database.PostgreSQL.Query.SqlBuilder.Types.SqlBuilderResult

module Database.PostgreSQL.Query.SqlBuilder.Builder

-- | Builder wich can be effectively concatenated. Requires
--   <a>Connection</a> inside for string quoting implemented in
--   <b>libpq</b>. Builds two strings: query string and log string which
--   may differ.
newtype SqlBuilder
SqlBuilder :: (Connection -> LogMasker -> IO SqlBuilderResult) -> SqlBuilder
[sqlBuild] :: SqlBuilder -> Connection -> LogMasker -> IO SqlBuilderResult

-- | Returns query string with log bytestring
runSqlBuilder :: Connection -> LogMasker -> SqlBuilder -> IO (Query, ByteString)

-- | Typed synonym of <a>mempty</a>
emptyB :: SqlBuilder

-- | Shorthand function to convert single field value to builder
mkValue :: (ToField a) => a -> SqlBuilder

-- | Shorthand function to convert single masked field value (which should
--   not be shown in log)
mkMaskedValue :: (ToField a) => a -> SqlBuilder
sqlBuilderFromField :: (ToField a) => FieldOption -> a -> SqlBuilder

-- | Lift pure bytestring builder to <a>SqlBuilder</a>. This is unsafe to
--   use directly in your code.
sqlBuilderPure :: Builder -> SqlBuilder

-- | Unsafe function to make SqlBuilder from arbitrary ByteString. Does not
--   perform any checks. Dont use it directly in your code unless you know
--   what you are doing.
sqlBuilderFromByteString :: ByteString -> SqlBuilder
instance GHC.Generics.Generic Database.PostgreSQL.Query.SqlBuilder.Builder.SqlBuilder
instance Data.Semigroup.Semigroup Database.PostgreSQL.Query.SqlBuilder.Builder.SqlBuilder
instance GHC.Base.Monoid Database.PostgreSQL.Query.SqlBuilder.Builder.SqlBuilder
instance Data.String.IsString Database.PostgreSQL.Query.SqlBuilder.Builder.SqlBuilder

module Database.PostgreSQL.Query.SqlBuilder.Class

-- | Things which always can be transformed to <a>SqlBuilder</a>
class ToSqlBuilder a
toSqlBuilder :: ToSqlBuilder a => a -> SqlBuilder
instance Database.PostgreSQL.Query.SqlBuilder.Class.ToSqlBuilder Database.PostgreSQL.Query.SqlBuilder.Builder.SqlBuilder
instance Database.PostgreSQL.Query.SqlBuilder.Class.ToSqlBuilder Database.PostgreSQL.Simple.Types.Identifier
instance Database.PostgreSQL.Query.SqlBuilder.Class.ToSqlBuilder Database.PostgreSQL.Simple.Types.QualifiedIdentifier

module Database.PostgreSQL.Query.SqlBuilder

module Database.PostgreSQL.Query.TH.Common

-- | Return constructor name
cName :: (Monad m) => Con -> m Name

-- | Return count of constructor fields
cArgs :: (Monad m) => Con -> m Int

-- | Get field names from record constructor
cFieldNames :: Con -> [Name]
lookupVNameErr :: String -> Q Name
dataConstructors :: Info -> [Con]


-- | Helps to map enum types to postgresql enums.
module Database.PostgreSQL.Query.TH.Enum

-- | derives <a>FromField</a> and <a>ToField</a> instances for a sum-type
--   enum like
--   
--   <pre>
--   data Entity = Red | Green | Blue
--   </pre>
derivePgEnum :: InflectorFunc -> Name -> DecsQ

-- | Function to transform constructor name into its PG enum conterpart.
type InflectorFunc = String -> String

module Database.PostgreSQL.Query.TH.Row

-- | Derive <a>FromRow</a> instance. i.e. you have type like that
--   
--   <pre>
--   data Entity = Entity
--                 { eField :: Text
--                 , eField2 :: Int
--                 , efield3 :: Bool }
--   </pre>
--   
--   then <a>deriveFromRow</a> will generate this instance: instance
--   FromRow Entity where
--   
--   <pre>
--   instance FromRow Entity where
--       fromRow = Entity
--                 &lt;$&gt; field
--                 &lt;*&gt; field
--                 &lt;*&gt; field
--   </pre>
--   
--   Datatype must have just one constructor with arbitrary count of fields
deriveFromRow :: Name -> Q [Dec]

-- | derives <a>ToRow</a> instance for datatype like
--   
--   <pre>
--   data Entity = Entity
--                 { eField :: Text
--                 , eField2 :: Int
--                 , efield3 :: Bool }
--   </pre>
--   
--   it will derive instance like that:
--   
--   <pre>
--   instance ToRow Entity where
--        toRow (Entity e1 e2 e3) =
--            [ toField e1
--            , toField e2
--            , toField e3 ]
--   </pre>
deriveToRow :: Name -> Q [Dec]

module Database.PostgreSQL.Query.TH.SqlExp

-- | Maybe the main feature of all library. Quasiquoter which builds
--   <a>SqlBuilder</a> from string query. Removes line comments and block
--   comments (even nested) and sequences of spaces. Correctly works
--   handles string literals and quoted identifiers. Here is examples of
--   usage
--   
--   <pre>
--   &gt;&gt;&gt; let name = "name"
--   
--   &gt;&gt;&gt; let val = "some 'value'"
--   
--   &gt;&gt;&gt; runSqlBuilder c [sqlExp|SELECT * FROM tbl WHERE ^{mkIdent name} = #{val}|]
--   "SELECT * FROM tbl WHERE \"name\" = 'some ''value'''"
--   </pre>
--   
--   And more comples example:
--   
--   <pre>
--   &gt;&gt;&gt; let name = Just "name"
--   
--   &gt;&gt;&gt; let size = Just 10
--   
--   &gt;&gt;&gt; let active = Nothing :: Maybe Bool
--   
--   &gt;&gt;&gt; let condlist = catMaybes [ fmap (\a -&gt; [sqlExp|name = #{a}|]) name, fmap (\a -&gt; [sqlExp|size = #{a}|]) size, fmap (\a -&gt; [sqlExp|active = #{a}|]) active]
--   
--   &gt;&gt;&gt; let cond = if L.null condlist then mempty else [sqlExp| WHERE ^{mconcat $ L.intersperse " AND " $ condlist} |]
--   
--   &gt;&gt;&gt; runSqlBuilder c [sqlExp|SELECT *   FROM tbl ^{cond} -- line comment|]
--   "SELECT * FROM tbl  WHERE name = 'name' AND size = 10  "
--   </pre>
sqlExp :: QuasiQuoter

-- | Internal type. Result of parsing sql string
data Rope

-- | Part of raw sql
RLit :: Text -> Rope

-- | Sql comment
RComment :: Text -> Rope

-- | Sequence of spaces
RSpaces :: Int -> Rope

-- | String with haskell expression inside <b>#{..}</b> or <b>#?{..}</b>
RInt :: FieldOption -> Text -> Rope

-- | String with haskell expression inside <b>^{..}</b>
RPaste :: Text -> Rope
ropeParser :: Parser [Rope]
parseRope :: String -> [Rope]

-- | Removes sequential occurencies of <a>RLit</a> constructors. Also
--   removes commentaries and squash sequences of spaces to single space
--   symbol
squashRope :: [Rope] -> [Rope]

-- | Build expression of type <a>SqlBuilder</a> from SQL query with
--   interpolation
sqlQExp :: String -> Q Exp

-- | Embed sql template and perform interpolation
--   
--   <pre>
--   let name = "name"
--       foo = "bar"
--       query = $(sqlExpEmbed "sql<i>foo</i>bar.sql") -- using <tt>foo</tt> and <tt>bar</tt> inside
--   </pre>
sqlExpEmbed :: String -> Q Exp

-- | Just like <a>sqlExpEmbed</a> but uses pattern instead of file name.
--   So, code
--   
--   <pre>
--   let query = $(sqlExpFile "foo/bar")
--   </pre>
--   
--   is just the same as
--   
--   <pre>
--   let query = $(sqlExpEmbed "sql<i>foo</i>bar.sql")
--   </pre>
--   
--   This function inspired by Yesod's <tt>widgetFile</tt>
sqlExpFile :: String -> Q Exp
instance GHC.Show.Show Database.PostgreSQL.Query.TH.SqlExp.Rope
instance GHC.Classes.Eq Database.PostgreSQL.Query.TH.SqlExp.Rope
instance GHC.Classes.Ord Database.PostgreSQL.Query.TH.SqlExp.Rope

module Database.PostgreSQL.Query.Types

-- | Instances of this typeclass can acquire connection and pass it to
--   computation. It can be reader of pool of connections or just reader of
--   connection
class (MonadBase IO m) => HasPostgres m
withPGConnection :: HasPostgres m => (Connection -> m a) -> m a
type MonadPostgres m = (HasPostgres m, MonadLogger m)

-- | Empty typeclass signing monad in which transaction is safe. i.e.
--   <a>PgMonadT</a> have this instance, but some other monad giving
--   connection from e.g. connection pool is not.
class TransactionSafe (m :: * -> *)

-- | Reader of connection. Has instance of <a>HasPostgres</a>. So if you
--   have a connection you can run queries in this monad using
--   <a>runPgMonadT</a>. Or you can use this transformer to run sequence of
--   queries using same connection with <a>launchPG</a>.
newtype PgMonadT m a
PgMonadT :: ReaderT Connection m a -> PgMonadT m a
[unPgMonadT] :: PgMonadT m a -> ReaderT Connection m a
runPgMonadT :: Connection -> PgMonadT m a -> m a

-- | If your monad have instance of <a>HasPostgres</a> you maybe dont need
--   this function, unless your instance use <tt>withPGPool</tt> which
--   acquires connection from pool for each query. If you want to run
--   sequence of queries using same connection you need this function
launchPG :: (HasPostgres m) => PgMonadT m a -> m a

-- | Special constructor to perform old-style query interpolation
data Qp
Qp :: Query -> row -> Qp

-- | type to put and get from db <tt>inet</tt> and <tt>cidr</tt> typed
--   postgresql fields. This should be in postgresql-simple in fact.
newtype InetText
InetText :: Text -> InetText
[unInetText] :: InetText -> Text

-- | Dot-separated field name. Each element in nested list will be properly
--   quoted and separated by dot. It also have instance of
--   <a>ToSqlBuilder</a> and <a>IsString</a> so you can:
--   
--   <pre>
--   &gt;&gt;&gt; let a = "hello" :: FN
--   
--   &gt;&gt;&gt; a
--   FN ["hello"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let b = "user.name" :: FN
--   
--   &gt;&gt;&gt; b
--   FN ["user","name"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let n = "u.name" :: FN
--   
--   &gt;&gt;&gt; runSqlBuilder c $ toSqlBuilder n
--   "\"u\".\"name\""
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; ("user" &lt;&gt; "name") :: FN
--   FN ["user","name"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let a = "name" :: FN
--   
--   &gt;&gt;&gt; let b = "email" :: FN
--   
--   &gt;&gt;&gt; runSqlBuilder c [sqlExp|^{"u" &lt;&gt; a} = 'name', ^{"e" &lt;&gt; b} = 'email'|]
--   "\"u\".\"name\" = 'name', \"e\".\"email\" = 'email'"
--   </pre>
newtype FN
FN :: [Text] -> FN

-- | Single field to <a>FN</a>
--   
--   <pre>
--   &gt;&gt;&gt; textFN "hello"
--   FN ["hello"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; textFN "user.name"
--   FN ["user.name"]
--   </pre>
--   
--   Note that it does not split string to parts by point like instance of
--   <a>IsString</a> does
textFN :: Text -> FN

-- | Marked row is list of pairs of field name and some sql expression.
--   Used to generate queries like:
--   
--   <pre>
--   name = <a>name</a> AND size = 10 AND length = 20
--   </pre>
--   
--   or
--   
--   <pre>
--   UPDATE tbl SET name = <a>name</a>, size = 10, lenght = 20
--   </pre>
newtype MarkedRow
MR :: [(FN, SqlBuilder)] -> MarkedRow
[unMR] :: MarkedRow -> [(FN, SqlBuilder)]

-- | Turns marked row to query intercalating it with other builder
--   
--   <pre>
--   &gt;&gt;&gt; runSqlBuilder c $ mrToBuilder "AND" $ MR [("name", mkValue "petr"), ("email", mkValue "foo@bar.com")]
--   " \"name\" = 'petr' AND \"email\" = 'foo@bar.com' "
--   </pre>
mrToBuilder :: SqlBuilder -> MarkedRow -> SqlBuilder
class ToMarkedRow a

-- | generate list of pairs (field name, field value)
toMarkedRow :: ToMarkedRow a => a -> MarkedRow
instance Control.Monad.Logger.MonadLogger m => Control.Monad.Logger.MonadLogger (Database.PostgreSQL.Query.Types.PgMonadT m)
instance Control.Monad.Base.MonadBase b m => Control.Monad.Base.MonadBase b (Database.PostgreSQL.Query.Types.PgMonadT m)
instance Control.Monad.Catch.MonadMask m => Control.Monad.Catch.MonadMask (Database.PostgreSQL.Query.Types.PgMonadT m)
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Database.PostgreSQL.Query.Types.PgMonadT m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Database.PostgreSQL.Query.Types.PgMonadT m)
instance Control.Monad.Cont.Class.MonadCont m => Control.Monad.Cont.Class.MonadCont (Database.PostgreSQL.Query.Types.PgMonadT m)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Database.PostgreSQL.Query.Types.PgMonadT m)
instance GHC.Base.MonadPlus m => GHC.Base.MonadPlus (Database.PostgreSQL.Query.Types.PgMonadT m)
instance Control.Monad.Fix.MonadFix m => Control.Monad.Fix.MonadFix (Database.PostgreSQL.Query.Types.PgMonadT m)
instance GHC.Base.Alternative m => GHC.Base.Alternative (Database.PostgreSQL.Query.Types.PgMonadT m)
instance Control.Monad.Trans.Class.MonadTrans Database.PostgreSQL.Query.Types.PgMonadT
instance Control.Monad.Error.Class.MonadError e m => Control.Monad.Error.Class.MonadError e (Database.PostgreSQL.Query.Types.PgMonadT m)
instance Control.Monad.State.Class.MonadState s m => Control.Monad.State.Class.MonadState s (Database.PostgreSQL.Query.Types.PgMonadT m)
instance Control.Monad.Writer.Class.MonadWriter w m => Control.Monad.Writer.Class.MonadWriter w (Database.PostgreSQL.Query.Types.PgMonadT m)
instance GHC.Base.Monad m => GHC.Base.Monad (Database.PostgreSQL.Query.Types.PgMonadT m)
instance GHC.Base.Applicative m => GHC.Base.Applicative (Database.PostgreSQL.Query.Types.PgMonadT m)
instance GHC.Base.Functor m => GHC.Base.Functor (Database.PostgreSQL.Query.Types.PgMonadT m)
instance GHC.Generics.Generic Database.PostgreSQL.Query.Types.MarkedRow
instance GHC.Base.Monoid Database.PostgreSQL.Query.Types.MarkedRow
instance Control.Monad.Trans.Control.MonadBaseControl b m => Control.Monad.Trans.Control.MonadBaseControl b (Database.PostgreSQL.Query.Types.PgMonadT m)
instance Control.Monad.Trans.Control.MonadTransControl Database.PostgreSQL.Query.Types.PgMonadT
instance Control.Monad.Reader.Class.MonadReader r m => Control.Monad.Reader.Class.MonadReader r (Database.PostgreSQL.Query.Types.PgMonadT m)
instance Control.Monad.HReader.Class.MonadHReader m => Control.Monad.HReader.Class.MonadHReader (Database.PostgreSQL.Query.Types.PgMonadT m)
instance Control.Monad.Base.MonadBase GHC.Types.IO m => Database.PostgreSQL.Query.Types.HasPostgres (Database.PostgreSQL.Query.Types.PgMonadT m)
instance Database.PostgreSQL.Query.Types.TransactionSafe (Database.PostgreSQL.Query.Types.PgMonadT m)
instance Database.PostgreSQL.Query.Types.TransactionSafe m => Database.PostgreSQL.Query.Types.TransactionSafe (Control.Monad.Trans.Except.ExceptT e m)
instance Database.PostgreSQL.Query.Types.TransactionSafe m => Database.PostgreSQL.Query.Types.TransactionSafe (Control.Monad.Trans.Identity.IdentityT m)
instance Database.PostgreSQL.Query.Types.TransactionSafe m => Database.PostgreSQL.Query.Types.TransactionSafe (Control.Monad.Trans.Maybe.MaybeT m)
instance Database.PostgreSQL.Query.Types.TransactionSafe m => Database.PostgreSQL.Query.Types.TransactionSafe (Control.Monad.Trans.Reader.ReaderT r m)
instance Database.PostgreSQL.Query.Types.TransactionSafe m => Database.PostgreSQL.Query.Types.TransactionSafe (Control.Monad.Trans.State.Lazy.StateT s m)
instance Database.PostgreSQL.Query.Types.TransactionSafe m => Database.PostgreSQL.Query.Types.TransactionSafe (Control.Monad.Trans.State.Strict.StateT s m)
instance Database.PostgreSQL.Query.Types.TransactionSafe m => Database.PostgreSQL.Query.Types.TransactionSafe (Control.Monad.Trans.Cont.ContT r m)
instance (Database.PostgreSQL.Query.Types.TransactionSafe m, GHC.Base.Monoid w) => Database.PostgreSQL.Query.Types.TransactionSafe (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance (Database.PostgreSQL.Query.Types.TransactionSafe m, GHC.Base.Monoid w) => Database.PostgreSQL.Query.Types.TransactionSafe (Control.Monad.Trans.Writer.Strict.WriterT w m)
instance Database.PostgreSQL.Query.Types.HasPostgres m => Database.PostgreSQL.Query.Types.HasPostgres (Control.Monad.Trans.Except.ExceptT e m)
instance Database.PostgreSQL.Query.Types.HasPostgres m => Database.PostgreSQL.Query.Types.HasPostgres (Control.Monad.Trans.Identity.IdentityT m)
instance Database.PostgreSQL.Query.Types.HasPostgres m => Database.PostgreSQL.Query.Types.HasPostgres (Control.Monad.Trans.Maybe.MaybeT m)
instance Database.PostgreSQL.Query.Types.HasPostgres m => Database.PostgreSQL.Query.Types.HasPostgres (Control.Monad.Trans.Reader.ReaderT r m)
instance Database.PostgreSQL.Query.Types.HasPostgres m => Database.PostgreSQL.Query.Types.HasPostgres (Control.Monad.Trans.State.Lazy.StateT s m)
instance Database.PostgreSQL.Query.Types.HasPostgres m => Database.PostgreSQL.Query.Types.HasPostgres (Control.Monad.Trans.State.Strict.StateT s m)
instance Database.PostgreSQL.Query.Types.HasPostgres m => Database.PostgreSQL.Query.Types.HasPostgres (Control.Monad.Trans.Cont.ContT r m)
instance (Database.PostgreSQL.Query.Types.HasPostgres m, GHC.Base.Monoid w) => Database.PostgreSQL.Query.Types.HasPostgres (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance (Database.PostgreSQL.Query.Types.HasPostgres m, GHC.Base.Monoid w) => Database.PostgreSQL.Query.Types.HasPostgres (Control.Monad.Trans.Writer.Strict.WriterT w m)
instance (Control.Monad.Base.MonadBase GHC.Types.IO m, Control.Monad.Trans.Control.MonadBaseControl GHC.Types.IO m, Data.HSet.Get.HGettable els (Data.Pool.Pool Database.PostgreSQL.Simple.Internal.Connection)) => Database.PostgreSQL.Query.Types.HasPostgres (Control.Monad.HReader.HReaderT els m)
instance Database.PostgreSQL.Query.Types.ToMarkedRow Database.PostgreSQL.Query.Types.MarkedRow
instance Language.Haskell.TH.Syntax.Lift Database.PostgreSQL.Query.Types.FN
instance Database.PostgreSQL.Query.SqlBuilder.Class.ToSqlBuilder Database.PostgreSQL.Query.Types.FN
instance Data.String.IsString Database.PostgreSQL.Query.Types.FN
instance GHC.Generics.Generic Database.PostgreSQL.Query.Types.FN
instance GHC.Base.Monoid Database.PostgreSQL.Query.Types.FN
instance GHC.Show.Show Database.PostgreSQL.Query.Types.FN
instance GHC.Classes.Eq Database.PostgreSQL.Query.Types.FN
instance GHC.Classes.Ord Database.PostgreSQL.Query.Types.FN
instance Database.PostgreSQL.Simple.ToField.ToField Database.PostgreSQL.Query.Types.InetText
instance GHC.Base.Monoid Database.PostgreSQL.Query.Types.InetText
instance GHC.Show.Show Database.PostgreSQL.Query.Types.InetText
instance GHC.Read.Read Database.PostgreSQL.Query.Types.InetText
instance GHC.Classes.Ord Database.PostgreSQL.Query.Types.InetText
instance GHC.Classes.Eq Database.PostgreSQL.Query.Types.InetText
instance Data.String.IsString Database.PostgreSQL.Query.Types.InetText
instance Database.PostgreSQL.Simple.FromField.FromField Database.PostgreSQL.Query.Types.InetText
instance Database.PostgreSQL.Query.SqlBuilder.Class.ToSqlBuilder Database.PostgreSQL.Query.Types.Qp

module Database.PostgreSQL.Query.Entity.Class

-- | Auxiliary typeclass for data types which can map to rows of some
--   table. This typeclass is used inside functions like
--   <tt>pgSelectEntities</tt> to generate queries.
class Entity a where {
    data family EntityId a :: *;
}

-- | Table name of this entity
tableName :: Entity a => Proxy a -> FN

-- | Field names without <a>id</a> and <tt>created</tt>. The order of field
--   names must match with order of fields in <tt>ToRow</tt> and
--   <tt>FromRow</tt> instances of this type.
fieldNames :: Entity a => Proxy a -> [FN]

-- | Entity with it's id
type Ent a = (EntityId a, a)

module Database.PostgreSQL.Query.TH.Entity

-- | Options for deriving <a>Entity</a>
data EntityOptions
EntityOptions :: (Text -> FN) -> (Text -> FN) -> [Name] -> Name -> EntityOptions

-- | Type name to table name converter
[eoTableName] :: EntityOptions -> Text -> FN

-- | Record field to column name converter
[eoColumnNames] :: EntityOptions -> Text -> FN

-- | Typeclasses to derive for Id
[eoDeriveClasses] :: EntityOptions -> [Name]

-- | Base type for Id
[eoIdType] :: EntityOptions -> Name

-- | Derives instance for <a>Entity</a> using type name and field names.
--   Also generates type synonim for ID. E.g. code like this:
--   
--   <pre>
--   data Agent = Agent
--       { aName          :: !Text
--       , aAttributes    :: !HStoreMap
--       , aLongWeirdName :: !Int
--       } deriving (Ord, Eq, Show)
--   
--   $(deriveEntity
--     def { eoIdType        = ''Id
--         , eoTableName     = textFN . toUnderscore'
--         , eoColumnNames   = textFN . toUnderscore' . drop 1
--         , eoDeriveClasses =
--           [''Show, ''Read, ''Ord, ''Eq
--           , ''FromField, ''ToField, ''PathPiece]
--         }
--     ''Agent )
--   </pre>
--   
--   Will generate code like this:
--   
--   <pre>
--   instance Database.PostgreSQL.Query.Entity Agent where
--       newtype EntityId Agent
--           = AgentId {getAgentId :: Id}
--           deriving (Show, Read, Ord, Eq, FromField, ToField, PathPiece)
--       tableName _ = "agent"
--       fieldNames _ = ["name", "attributes", "long_weird_name"]
--   type AgentId = EntityId Agent
--   </pre>
--   
--   So, you dont need to write it by hands any more.
--   
--   NOTE: <a>toUnderscore</a> is from package <tt>inflections</tt> here
deriveEntity :: EntityOptions -> Name -> Q [Dec]
instance GHC.Generics.Generic Database.PostgreSQL.Query.TH.Entity.EntityOptions
instance Data.Default.Class.Default Database.PostgreSQL.Query.TH.Entity.EntityOptions

module Database.PostgreSQL.Query.TH

-- | Calls sequently <a>deriveFromRow</a> <a>deriveToRow</a>
--   <a>deriveEntity</a>. E.g. code like this:
--   
--   <pre>
--   data Agent = Agent
--       { aName          :: !Text
--       , aAttributes    :: !HStoreMap
--       , aLongWeirdName :: !Int
--       } deriving (Ord, Eq, Show)
--   
--   $(deriveEverything
--     def { eoIdType        = ''Id
--         , eoTableName     = textFN . toUnderscore'
--         , eoColumnNames   = textFN . toUnderscore' . drop 1
--         , eoDeriveClasses =
--           [''Show, ''Read, ''Ord, ''Eq
--           , ''FromField, ''ToField, ''PathPiece]
--         }
--     ''Agent )
--   </pre>
--   
--   will generate that:
--   
--   <pre>
--   instance ToRow Agent where
--       toRow (Agent a_aE3w a_aE3x a_aE3y)
--           = [toField a_aE3w, toField a_aE3x, toField a_aE3y]
--   instance FromRow Agent where
--     fromRow
--         = Agent <a>$</a> Database.PostgreSQL.Simple.FromRow.field
--           <a>*</a> Database.PostgreSQL.Simple.FromRow.field
--           <a>*</a> Database.PostgreSQL.Simple.FromRow.field
--   instance Database.PostgreSQL.Query.Entity Agent where
--       newtype EntityId Agent
--           = AgentId {getAgentId :: Id}
--           deriving (Show, Read, Ord, Eq, FromField, ToField, PathPiece)
--       tableName _ = "agent"
--       fieldNames _ = ["name", "attributes", "long_weird_name"]
--   type AgentId = EntityId Agent
--   </pre>
deriveEverything :: EntityOptions -> Name -> Q [Dec]

module Database.PostgreSQL.Query.Internal

-- | Generates comma separated list of field names
--   
--   <pre>
--   &gt;&gt;&gt; runSqlBuilder con $ buildFields ["u" &lt;&gt; "name", "u" &lt;&gt; "phone", "e" &lt;&gt; "email"]
--   "\"u\".\"name\", \"u\".\"phone\", \"e\".\"email\""
--   </pre>
buildFields :: [FN] -> SqlBuilder

-- | generates <b>UPDATE</b> query
--   
--   <pre>
--   &gt;&gt;&gt; let name = "%vip%"
--   
--   &gt;&gt;&gt; runSqlBuilder con $ updateTable "ships" (MR [("size", mkValue 15)]) [sqlExp|WHERE size &gt; 15 AND name NOT LIKE #{name}|]
--   "UPDATE \"ships\" SET  \"size\" = 15  WHERE size &gt; 15 AND name NOT LIKE '%vip%'"
--   </pre>
updateTable :: (ToSqlBuilder q, ToMarkedRow flds) => FN -> flds -> q -> SqlBuilder

-- | Generate INSERT INTO query for entity
--   
--   <pre>
--   &gt;&gt;&gt; runSqlBuilder con $ insertInto "foo" $ MR [("name", mkValue "vovka"), ("hobby", mkValue "president")]
--   "INSERT INTO \"foo\" (\"name\", \"hobby\") VALUES ('vovka', 'president')"
--   </pre>
insertInto :: (ToMarkedRow b) => FN -> b -> SqlBuilder

module Database.PostgreSQL.Query.Functions

-- | Execute query generated by <a>SqlBuilder</a>. Typical use case:
--   
--   <pre>
--   let userName = "Vovka Erohin" :: Text
--   pgQuery [sqlExp| SELECT id, name FROM users WHERE name = #{userName}|]
--   </pre>
--   
--   Or
--   
--   <pre>
--   let userName = "Vovka Erohin" :: Text
--   pgQuery $ Qp "SELECT id, name FROM users WHERE name = ?" [userName]
--   </pre>
--   
--   Which is almost the same. In both cases proper value escaping is
--   performed so you stay protected from sql injections.
pgQuery :: (HasPostgres m, MonadLogger m, ToSqlBuilder q, FromRow r) => q -> m [r]
pgQueryWithMasker :: (HasPostgres m, MonadLogger m, ToSqlBuilder q, FromRow r) => LogMasker -> q -> m [r]

-- | Execute arbitrary query and return count of affected rows
pgExecute :: (HasPostgres m, MonadLogger m, ToSqlBuilder q) => q -> m Int64
pgExecuteWithMasker :: (HasPostgres m, MonadLogger m, ToSqlBuilder q) => LogMasker -> q -> m Int64

-- | Execute all queries inside one transaction. Rollback transaction on
--   exceptions
pgWithTransaction :: (HasPostgres m, MonadBaseControl IO m, TransactionSafe m) => m a -> m a

-- | Same as <a>pgWithTransaction</a> but executes queries inside savepoint
pgWithSavepoint :: (HasPostgres m, MonadBaseControl IO m, TransactionSafe m) => m a -> m a

-- | Wrapper for <a>withTransactionMode</a>: Execute an action inside a SQL
--   transaction with a given transaction mode.
pgWithTransactionMode :: (HasPostgres m, MonadBaseControl IO m, TransactionSafe m) => TransactionMode -> m a -> m a

-- | Wrapper for <a>withTransactionModeRetry</a>: Like
--   <a>pgWithTransactionMode</a>, but also takes a custom callback to
--   determine if a transaction should be retried if an SqlError occurs. If
--   the callback returns True, then the transaction will be retried. If
--   the callback returns False, or an exception other than an SqlError
--   occurs then the transaction will be rolled back and the exception
--   rethrown.
pgWithTransactionModeRetry :: (HasPostgres m, MonadBaseControl IO m, TransactionSafe m) => TransactionMode -> (SqlError -> Bool) -> m a -> m a

-- | Wrapper for <a>withTransactionSerializable</a>: Execute an action
--   inside of a <a>Serializable</a> transaction. If a serialization
--   failure occurs, roll back the transaction and try again. Be warned
--   that this may execute the IO action multiple times.
--   
--   A 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.
pgWithTransactionSerializable :: (HasPostgres m, MonadBaseControl IO m, TransactionSafe m) => m a -> m a

-- | Perform repsert of the same row, first trying "update where" then
--   "insert" with concatenated fields. Which means that if you run
--   
--   <pre>
--   pgRepsertRow "emails" (MR [("user_id", mkValue uid)]) (MR [("email", mkValue email)])
--   </pre>
--   
--   Then firstly will be performed
--   
--   <pre>
--   UPDATE "emails" SET email = 'foo@bar.com' WHERE "user_id" = 1234
--   </pre>
--   
--   And if no one row is affected (which is returned by <a>pgExecute</a>),
--   then
--   
--   <pre>
--   INSERT INTO "emails" ("user_id", "email") VALUES (1234, 'foo@bar.com')
--   </pre>
--   
--   will be performed
pgRepsertRow :: (MonadPostgres m, MonadLogger m, ToMarkedRow wrow, ToMarkedRow urow) => FN -> wrow -> urow -> m ()

module Database.PostgreSQL.Query.Entity.Internal

-- | Build entity fields
--   
--   <pre>
--   &gt;&gt;&gt; data Foo = Foo { fName :: Text, fSize :: Int }
--   
--   &gt;&gt;&gt; instance Entity Foo where {newtype EntityId Foo = FooId Int ; fieldNames _ = ["name", "size"] ; tableName _ = "foo"}
--   
--   &gt;&gt;&gt; runSqlBuilder con $ entityFields id id (Proxy :: Proxy Foo)
--   "\"name\", \"size\""
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; runSqlBuilder con $ entityFields ("id":) id (Proxy :: Proxy Foo)
--   "\"id\", \"name\", \"size\""
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; runSqlBuilder con $ entityFields (\l -&gt; ("id":l) ++ ["created"]) id (Proxy :: Proxy Foo)
--   "\"id\", \"name\", \"size\", \"created\""
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; runSqlBuilder con $ entityFields id ("f"&lt;&gt;) (Proxy :: Proxy Foo)
--   "\"f\".\"name\", \"f\".\"size\""
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; runSqlBuilder con $ entityFields ("f.id":) ("f"&lt;&gt;) (Proxy :: Proxy Foo)
--   "\"f\".\"id\", \"f\".\"name\", \"f\".\"size\""
--   </pre>
entityFields :: (Entity a) => ([FN] -> [FN]) -> (FN -> FN) -> Proxy a -> SqlBuilder

-- | Same as <a>entityFields</a> but prefixes list of names with <b>id</b>
--   field. This is shorthand function for often usage.
--   
--   <pre>
--   &gt;&gt;&gt; data Foo = Foo { fName :: Text, fSize :: Int }
--   
--   &gt;&gt;&gt; instance Entity Foo where {newtype EntityId Foo = FooId Int ; fieldNames _ = ["name", "size"] ; tableName _ = "foo"}
--   
--   &gt;&gt;&gt; runSqlBuilder con $ entityFieldsId id (Proxy :: Proxy Foo)
--   "\"id\", \"name\", \"size\""
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; runSqlBuilder con $ entityFieldsId ("f"&lt;&gt;) (Proxy :: Proxy Foo)
--   "\"f\".\"id\", \"f\".\"name\", \"f\".\"size\""
--   </pre>
entityFieldsId :: (Entity a) => (FN -> FN) -> Proxy a -> SqlBuilder

-- | Generate SELECT query string for entity
--   
--   <pre>
--   &gt;&gt;&gt; data Foo = Foo { fName :: Text, fSize :: Int }
--   
--   &gt;&gt;&gt; instance Entity Foo where {newtype EntityId Foo = FooId Int ; fieldNames _ = ["name", "size"] ; tableName _ = "foo"}
--   
--   &gt;&gt;&gt; runSqlBuilder con $ selectEntity (entityFieldsId id) (Proxy :: Proxy Foo)
--   "SELECT \"id\", \"name\", \"size\" FROM \"foo\""
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; runSqlBuilder con $ selectEntity (entityFieldsId ("f"&lt;&gt;)) (Proxy :: Proxy Foo)
--   "SELECT \"f\".\"id\", \"f\".\"name\", \"f\".\"size\" FROM \"foo\""
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; runSqlBuilder con $ selectEntity (entityFields id id) (Proxy :: Proxy Foo)
--   "SELECT \"name\", \"size\" FROM \"foo\""
--   </pre>
selectEntity :: (Entity a) => (Proxy a -> SqlBuilder) -> Proxy a -> SqlBuilder

-- | Generates SELECT FROM WHERE query with most used conditions
--   
--   <pre>
--   &gt;&gt;&gt; data Foo = Foo { fName :: Text, fSize :: Int }
--   
--   &gt;&gt;&gt; instance Entity Foo where {newtype EntityId Foo = FooId Int ; fieldNames _ = ["name", "size"] ; tableName _ = "foo"}
--   
--   &gt;&gt;&gt; runSqlBuilder con $ selectEntitiesBy id (Proxy :: Proxy Foo) $ MR []
--   "SELECT \"name\", \"size\" FROM \"foo\""
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; runSqlBuilder con $ selectEntitiesBy id (Proxy :: Proxy Foo) $ MR [("name", mkValue "fooname")]
--   "SELECT \"name\", \"size\" FROM \"foo\" WHERE  \"name\" = 'fooname' "
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; runSqlBuilder con $ selectEntitiesBy id (Proxy :: Proxy Foo) $ MR [("name", mkValue "fooname"), ("size", mkValue 10)]
--   "SELECT \"name\", \"size\" FROM \"foo\" WHERE  \"name\" = 'fooname' AND \"size\" = 10 "
--   </pre>
selectEntitiesBy :: (Entity a, ToMarkedRow b) => ([FN] -> [FN]) -> Proxy a -> b -> SqlBuilder

-- | Generates <b>INSERT INTO</b> query for any instance of <a>Entity</a>
--   and <a>ToRow</a>
--   
--   <pre>
--   &gt;&gt;&gt; data Foo = Foo { fName :: Text, fSize :: Int }
--   
--   &gt;&gt;&gt; instance Entity Foo where {newtype EntityId Foo = FooId Int ; fieldNames _ = ["name", "size"] ; tableName _ = "foo"}
--   
--   &gt;&gt;&gt; instance ToRow Foo where { toRow Foo{..} = [toField fName, toField fSize] }
--   
--   &gt;&gt;&gt; runSqlBuilder con $ insertEntity $ Foo "Enterprise" 910
--   "INSERT INTO \"foo\" (\"name\", \"size\") VALUES ('Enterprise', 910)"
--   </pre>
insertEntity :: forall a. (Entity a, ToRow a) => a -> SqlBuilder

-- | Same as <a>insertEntity</a> but generates query to insert many queries
--   at same time
--   
--   <pre>
--   &gt;&gt;&gt; data Foo = Foo { fName :: Text, fSize :: Int }
--   
--   &gt;&gt;&gt; instance Entity Foo where {newtype EntityId Foo = FooId Int ; fieldNames _ = ["name", "size"] ; tableName _ = "foo"}
--   
--   &gt;&gt;&gt; instance ToRow Foo where { toRow Foo{..} = [toField fName, toField fSize] }
--   
--   &gt;&gt;&gt; runSqlBuilder con $ insertManyEntities $ NL.fromList [Foo "meter" 1, Foo "table" 2, Foo "earth" 151930000000]
--   "INSERT INTO \"foo\" (\"name\",\"size\") VALUES ('meter',1),('table',2),('earth',151930000000)"
--   </pre>
insertManyEntities :: forall a. (Entity a, ToRow a) => NonEmpty a -> SqlBuilder

-- | Convert entity instance to marked row to perform inserts updates and
--   same stuff
--   
--   <pre>
--   &gt;&gt;&gt; data Foo = Foo { fName :: Text, fSize :: Int }
--   
--   &gt;&gt;&gt; instance Entity Foo where {newtype EntityId Foo = FooId Int ; fieldNames _ = ["name", "size"] ; tableName _ = "foo"}
--   
--   &gt;&gt;&gt; instance ToRow Foo where { toRow Foo{..} = [toField fName, toField fSize] }
--   
--   &gt;&gt;&gt; runSqlBuilder con $ mrToBuilder ", " $ entityToMR $ Foo "Enterprise" 610
--   " \"name\" = 'Enterprise' ,  \"size\" = 610 "
--   </pre>
entityToMR :: forall a. (Entity a, ToRow a) => a -> MarkedRow

module Database.PostgreSQL.Query.Entity.Functions

-- | Insert new entity and return it's id
pgInsertEntity :: forall a m. (MonadPostgres m, MonadLogger m, Entity a, ToRow a, FromField (EntityId a)) => a -> m (EntityId a)

-- | Insert many entities without returning list of id like
--   <a>pgInsertManyEntitiesId</a> does
pgInsertManyEntities :: forall a m. (Entity a, MonadPostgres m, MonadLogger m, ToRow a) => [a] -> m Int64

-- | Same as <a>pgInsertEntity</a> but insert many entities at one action.
--   Returns list of id's of inserted entities
pgInsertManyEntitiesId :: forall a m. (Entity a, MonadPostgres m, MonadLogger m, ToRow a, FromField (EntityId a)) => [a] -> m [EntityId a]

-- | Select entities as pairs of (id, entity).
--   
--   <pre>
--   handler :: Handler [Ent a]
--   handler = do
--       now &lt;- liftIO getCurrentTime
--       let back = addUTCTime (days  (-7)) now
--       pgSelectEntities id
--           [sqlExp|WHERE created BETWEEN #{now} AND #{back}
--                  ORDER BY created|]
--   
--   handler2 :: Text -&gt; Handler [Ent Foo]
--   handler2 fvalue = do
--       pgSelectEntities ("t"&lt;&gt;)
--           [sqlExp|AS t INNER JOIN table2 AS t2
--                   ON t.t2_id = t2.id
--                   WHERE t.field = #{fvalue}
--                   ORDER BY t2.field2|]
--      -- Here the query will be: SELECT ... FROM tbl AS t INNER JOIN ...
--   </pre>
pgSelectEntities :: forall m a q. (Functor m, MonadPostgres m, MonadLogger m, Entity a, FromRow a, ToSqlBuilder q, FromField (EntityId a)) => (FN -> FN) -> q -> m [Ent a]

-- | Same as <a>pgSelectEntities</a> but do not select id
pgSelectJustEntities :: forall m a q. (Functor m, MonadPostgres m, MonadLogger m, Entity a, FromRow a, ToSqlBuilder q) => (FN -> FN) -> q -> m [a]

-- | Select entities by condition formed from <a>MarkedRow</a>. Usefull
--   function when you know
pgSelectEntitiesBy :: forall a m b. (Functor m, MonadPostgres m, MonadLogger m, Entity a, ToMarkedRow b, FromRow a, FromField (EntityId a)) => b -> m [Ent a]

-- | Select entity by id
--   
--   <pre>
--   getUser :: EntityId User -&gt;  Handler User
--   getUser uid = do
--       pgGetEntity uid
--           &gt;&gt;= maybe notFound return
--   </pre>
pgGetEntity :: forall m a. (ToField (EntityId a), Entity a, FromRow a, MonadPostgres m, MonadLogger m, Functor m) => EntityId a -> m (Maybe a)

-- | Get entity by some fields constraint
--   
--   <pre>
--   getUser :: UserName -&gt; Handler User
--   getUser name = do
--       pgGetEntityBy
--           (MR [("name", mkValue name),
--                ("active", mkValue True)])
--           &gt;&gt;= maybe notFound return
--   </pre>
--   
--   The query here will be like
--   
--   <pre>
--   pgQuery [sqlExp|SELECT id, name, phone ... FROM users WHERE name = {True}|]
--   </pre>
pgGetEntityBy :: forall m a b. (Entity a, MonadPostgres m, MonadLogger m, ToMarkedRow b, FromField (EntityId a), FromRow a, Functor m) => b -> m (Maybe (Ent a))

-- | Select count of entities with given query
--   
--   <pre>
--   activeUsers :: Handler Integer
--   activeUsers = do
--       pgSelectCount (Proxy :: Proxy User)
--           [sqlExp|WHERE active = #{True}|]
--   </pre>
--   
--   Executes arbitrary query and parses it as entities and their ids
pgQueryEntities :: (ToSqlBuilder q, MonadPostgres m, MonadLogger m, Entity a, FromRow a, FromField (EntityId a)) => q -> m [Ent a]

-- | Delete entity.
--   
--   <pre>
--   rmUser :: EntityId User -&gt; Handler ()
--   rmUser uid = do
--       pgDeleteEntity uid
--   </pre>
--   
--   Return <a>True</a> if row was actually deleted.
pgDeleteEntity :: forall a m. (Entity a, MonadPostgres m, MonadLogger m, ToField (EntityId a), Functor m) => EntityId a -> m Bool

-- | Update entity using <a>ToMarkedRow</a> instanced value. Requires
--   <a>Proxy</a> while <a>EntityId</a> is not a data type.
--   
--   <pre>
--   fixUser :: Text -&gt; EntityId User -&gt; Handler ()
--   fixUser username uid = do
--       pgGetEntity uid
--           &gt;&gt;= maybe notFound run
--     where
--       run user =
--           pgUpdateEntity uid
--           $ MR [("active", mkValue True)
--                 ("name", mkValue username)]
--   </pre>
--   
--   Returns <a>True</a> if record was actually updated and <a>False</a> if
--   there was not row with such id (or was more than 1, in fact)
pgUpdateEntity :: forall a b m. (ToMarkedRow b, Entity a, MonadPostgres m, MonadLogger m, ToField (EntityId a), Functor m, Typeable a, Typeable b) => EntityId a -> b -> m Bool
pgSelectCount :: forall m a q. (Entity a, MonadPostgres m, MonadLogger m, ToSqlBuilder q) => Proxy a -> q -> m Integer

module Database.PostgreSQL.Query.Entity

module Database.PostgreSQL.Query
data Connection :: *

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

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

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

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

-- | A collection type that can be turned into a list of rendering
--   <a>Action</a>s.
--   
--   Instances should use the <a>toField</a> method of the <a>ToField</a>
--   class to perform conversion of each element of the collection.
class ToRow a
toRow :: ToRow a => a -> [Action]

-- | A type that may be converted from a SQL type.
class FromField a

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

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

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

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

-- | Wrap a list of values for use in an <tt>IN</tt> clause. Replaces a
--   single "<tt>?</tt>" character with a parenthesized list of rendered
--   values.
--   
--   Example:
--   
--   <pre>
--   query c "select * from whatever where id in ?" (Only (In [3,4,5]))
--   </pre>
--   
--   Note that <tt>In []</tt> expands to <tt>(null)</tt>, which works as
--   expected in the query above, but evaluates to the logical null value
--   on every row instead of <tt>TRUE</tt>. This means that changing the
--   query above to <tt>... id NOT in ?</tt> 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:
--   
--   <ol>
--   <li>Use postgresql-simple's <a>Values</a> type instead, which can
--   handle the empty case correctly. Note however that while specifying
--   the postgresql type <tt>"int4"</tt> is mandatory in the empty case,
--   specifying the haskell type <tt>Values (Only Int)</tt> would not
--   normally be needed in realistic use cases.<pre>query c "select * from
--   whatever where id not in ?" (Only (Values ["int4"] [] :: Values (Only
--   Int)))</pre></li>
--   <li>Use sql's <tt>COALESCE</tt> operator to turn a logical
--   <tt>null</tt> into the correct boolean. Note however that the correct
--   boolean depends on the use case:<pre>query c "select * from whatever
--   where coalesce(id NOT in ?, TRUE)" (Only (In [] :: In
--   [Int]))</pre><pre>query c "select * from whatever where coalesce(id IN
--   ?, FALSE)" (Only (In [] :: In [Int]))</pre>Note that at as of
--   PostgreSQL 9.4, the query planner cannot see inside the
--   <tt>COALESCE</tt> operator, so if you have an index on <tt>id</tt>
--   then you probably don't want to write the last example with
--   <tt>COALESCE</tt>, which would result in a table scan. There are
--   further caveats if <tt>id</tt> can be null or you want null treated
--   sensibly as a component of <tt>IN</tt> or <tt>NOT IN</tt>.</li>
--   </ol>
newtype In a :: * -> *
In :: a -> In a
newtype Oid :: *
Oid :: CUInt -> Oid

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

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

-- | Wrap a list for use as a PostgreSQL array.
newtype PGArray a :: * -> *
PGArray :: [a] -> PGArray a
[fromPGArray] :: PGArray a -> [a]
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 :: *
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 :: *