-- 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.0.3 module Database.PostgreSQL.Simple.SqlQQ -- | sql is a quasiquoter that eases the syntactic burden of writing -- big sql statements in Haskell source code. It attempts to minimize -- whitespace. Note that this implementation is incomplete and can mess -- up your syntax; it only really understands standard sql string -- literals (default in PostgreSQL 9) and not the extended escape syntax -- or other situations where white space should be preserved as is. sql :: QuasiQuoter -- | Basic types. module Database.PostgreSQL.Simple.Types -- | A placeholder for the SQL NULL value. data Null Null :: Null -- | A single-value "collection". -- -- This is useful if you need to supply a single parameter to a SQL -- query, or extract a single column from a SQL result. -- -- Parameter example: -- -- 
--   query c "select x from scores where x > ?" (Only (42::Int))
--
-- -- Result example: -- -- 
--   xs <- query_ c "select id from users"
--   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 ?" (In [3,4,5])
--
newtype In a In :: a -> In a -- | Wrap a mostly-binary string to be escaped in hexadecimal. newtype Binary a Binary :: a -> Binary a -- | A query string. This type is intended to make it difficult to -- construct a SQL query by concatenating string fragments, as that is an -- extremely common way to accidentally introduce SQL injection -- vulnerabilities into an application. -- -- This type is an instance of 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 instance Typeable Null instance Typeable Query instance Typeable1 Only instance Typeable1 In instance Typeable1 Binary instance Read Null instance Show Null instance Eq Query instance Ord Query instance Eq a => Eq (Only a) instance Ord a => Ord (Only a) instance Read a => Read (Only a) instance Show a => Show (Only a) instance Functor Only instance Eq a => Eq (In a) instance Ord a => Ord (In a) instance Read a => Read (In a) instance Show a => Show (In a) instance Functor In instance Eq a => Eq (Binary a) instance Ord a => Ord (Binary a) instance Read a => Read (Binary a) instance Show a => Show (Binary a) instance Functor Binary instance Monoid Query instance IsString Query instance Read Query instance Show Query instance Eq Null -- | The Param typeclass, for rendering a parameter to a SQL query. module Database.PostgreSQL.Simple.Param -- | 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 -- | Concatenate a series of rendering actions. Many :: [Action] -> Action -- | A type that may be used as a single parameter to a SQL query. class Param a render :: Param a => a -> Action -- | Surround a string with single-quote characters: "'" -- -- This function does not perform any other escaping. inQuotes :: Builder -> Builder instance Typeable Action instance Param TimeOfDay instance Param Day instance Param UTCTime instance Param Text instance Param [Char] instance Param Text instance Param ByteString instance Param ByteString instance Param Double instance Param Float instance Param Oid instance Param Word64 instance Param Word instance Param Word32 instance Param Word16 instance Param Word8 instance Param Integer instance Param Int64 instance Param Int instance Param Int32 instance Param Int16 instance Param Int8 instance Param Bool instance Param Null instance Param (Binary ByteString) instance Param (Binary ByteString) instance Param a => Param (In [a]) instance Param a => Param (Maybe a) instance Param Action instance Show Action -- | The QueryParams 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.QueryParams -- | A collection type that can be turned into a list of rendering -- Actions. -- -- Instances should use the render method of the Param -- class to perform conversion of each element of the collection. class QueryParams a renderParams :: QueryParams a => a -> [Action] instance Param a => QueryParams [a] instance (Param a, Param b, Param c, Param d, Param e, Param f, Param g, Param h, Param i, Param j) => QueryParams (a, b, c, d, e, f, g, h, i, j) instance (Param a, Param b, Param c, Param d, Param e, Param f, Param g, Param h, Param i) => QueryParams (a, b, c, d, e, f, g, h, i) instance (Param a, Param b, Param c, Param d, Param e, Param f, Param g, Param h) => QueryParams (a, b, c, d, e, f, g, h) instance (Param a, Param b, Param c, Param d, Param e, Param f, Param g) => QueryParams (a, b, c, d, e, f, g) instance (Param a, Param b, Param c, Param d, Param e, Param f) => QueryParams (a, b, c, d, e, f) instance (Param a, Param b, Param c, Param d, Param e) => QueryParams (a, b, c, d, e) instance (Param a, Param b, Param c, Param d) => QueryParams (a, b, c, d) instance (Param a, Param b, Param c) => QueryParams (a, b, c) instance (Param a, Param b) => QueryParams (a, b) instance Param a => QueryParams (Only a) instance QueryParams () module Database.PostgreSQL.Simple.BuiltinTypes data BuiltinType Bool :: BuiltinType Bytea :: BuiltinType Char :: BuiltinType Name :: BuiltinType Int8 :: BuiltinType Int2 :: BuiltinType Int4 :: BuiltinType Regproc :: BuiltinType Text :: BuiltinType Oid :: BuiltinType Tid :: BuiltinType Xid :: BuiltinType Cid :: BuiltinType Xml :: BuiltinType Point :: BuiltinType Lseg :: BuiltinType Path :: BuiltinType Box :: BuiltinType Polygon :: BuiltinType Line :: BuiltinType Cidr :: BuiltinType Float4 :: BuiltinType Float8 :: BuiltinType Abstime :: BuiltinType Reltime :: BuiltinType Tinterval :: BuiltinType Unknown :: BuiltinType Circle :: BuiltinType Money :: BuiltinType Macaddr :: BuiltinType Inet :: BuiltinType Bpchar :: BuiltinType Varchar :: BuiltinType Date :: BuiltinType Time :: BuiltinType Timestamp :: BuiltinType TimestampWithTimeZone :: BuiltinType Interval :: BuiltinType TimeWithTimeZone :: BuiltinType Bit :: BuiltinType Varbit :: BuiltinType Numeric :: BuiltinType Refcursor :: BuiltinType Record :: BuiltinType Void :: BuiltinType builtin2oid :: BuiltinType -> Oid oid2builtin :: Oid -> Maybe BuiltinType builtin2typname :: BuiltinType -> ByteString oid2typname :: Oid -> Maybe ByteString instance Typeable BuiltinType instance Eq BuiltinType instance Ord BuiltinType instance Enum BuiltinType instance Bounded BuiltinType instance Read BuiltinType instance Show BuiltinType -- | Internal bits. This interface is less stable and can change at any -- time. In particular this means that while the rest of the -- postgresql-simple package endeavors to follow the package versioning -- policy, this module does not. Also, at the moment there are things in -- here that aren't particularly internal and are exported elsewhere; -- these will eventually disappear from this module. module Database.PostgreSQL.Simple.Internal -- | A Field represents metadata about a particular field -- -- You don't particularly want to retain these structures for a long -- period of time, as they will retain the entire query result, not just -- the field metadata data Field Field :: Result -> Column -> ByteString -> Field result :: Field -> Result column :: Field -> Column typename :: Field -> ByteString name :: Field -> Maybe ByteString tableOid :: Field -> Oid tableColumn :: Field -> Int format :: Field -> Format typeOid :: Field -> Oid data Connection Connection :: {-# UNPACK #-} !MVar Connection -> {-# UNPACK #-} !MVar (IntMap ByteString) -> Connection connectionHandle :: Connection -> {-# UNPACK #-} !MVar Connection connectionObjects :: Connection -> {-# UNPACK #-} !MVar (IntMap ByteString) data SqlType Builtin :: BuiltinType -> SqlType Other :: Oid -> SqlType data SqlError SqlError :: ByteString -> Int -> ByteString -> SqlError sqlState :: SqlError -> ByteString sqlNativeError :: SqlError -> Int sqlErrorMsg :: SqlError -> ByteString 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: -- -- -- -- 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 -- | Attempt to make a connection based on a libpq connection string. See -- http://www.postgresql.org/docs/9.1/static/libpq-connect.html -- for more information. connectPostgreSQL :: ByteString -> IO Connection -- | Turns a ConnectInfo data structure into a libpq connection -- string. postgreSQLConnectionString :: ConnectInfo -> ByteString oid2int :: Oid -> Int exec :: Connection -> ByteString -> IO Result -- | 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 RawResult RawResult :: Field -> Maybe ByteString -> RawResult rawField :: RawResult -> Field rawData :: RawResult -> Maybe ByteString instance Typeable SqlError instance Typeable ConnectInfo instance Show SqlError instance Eq ConnectInfo instance Read ConnectInfo instance Show ConnectInfo instance Exception SqlError module Database.PostgreSQL.Simple.Field -- | A Field represents metadata about a particular field -- -- You don't particularly want to retain these structures for a long -- period of time, as they will retain the entire query result, not just -- the field metadata data Field typename :: Field -> ByteString name :: Field -> Maybe ByteString tableOid :: Field -> Oid tableColumn :: Field -> Int format :: Field -> Format typeOid :: Field -> Oid data Oid :: * data Format :: * Text :: Format Binary :: Format data RawResult RawResult :: Field -> Maybe ByteString -> RawResult rawField :: RawResult -> Field rawData :: RawResult -> Maybe ByteString -- | The Result typeclass, for converting a single value in a row -- returned by a SQL query into a more useful Haskell representation. -- -- A Haskell numeric type is considered to be compatible with all -- PostgreSQL numeric types that are less accurate than it. For instance, -- the Haskell 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 a 64-bit BigInt, the two are not -- considered compatible. module Database.PostgreSQL.Simple.Result -- | A type that may be converted from a SQL type. class Result a convert :: Result a => Field -> Maybe ByteString -> Either SomeException a -- | Exception thrown if conversion from a SQL value to a Haskell value -- fails. data ResultError -- | The SQL and Haskell types are not compatible. Incompatible :: String -> String -> String -> ResultError errSQLType :: ResultError -> String errHaskellType :: ResultError -> String errMessage :: ResultError -> String -- | A SQL NULL was encountered when the Haskell type did not -- permit it. UnexpectedNull :: String -> String -> String -> ResultError errSQLType :: ResultError -> String errHaskellType :: ResultError -> String errMessage :: ResultError -> String -- | The SQL value could not be parsed, or could not be represented as a -- valid Haskell value, or an unexpected low-level error occurred (e.g. -- mismatch between metadata and actual data in a row). ConversionFailed :: String -> String -> String -> ResultError errSQLType :: ResultError -> String errHaskellType :: ResultError -> String errMessage :: ResultError -> String instance Typeable ResultError instance Eq ResultError instance Show ResultError instance Result RawResult instance (Result a, Result b) => Result (Either a b) instance Result TimeOfDay instance Result Day instance Result UTCTime instance Result [Char] instance Result Text instance Result Text instance Result (Binary ByteString) instance Result (Binary ByteString) instance Result ByteString instance Result Oid instance Result ByteString instance Result (Ratio Integer) instance Result Double instance Result Float instance Result Integer instance Result Int64 instance Result Int instance Result Int32 instance Result Int16 instance Result Bool instance Result Null instance Result a => Result (Maybe a) instance Exception ResultError -- | The QueryResults typeclass, for converting a row of results -- returned by a SQL query into a more useful Haskell representation. -- -- Predefined instances are provided for tuples containing up to ten -- elements. module Database.PostgreSQL.Simple.QueryResults -- | A collection type that can be converted from a list of strings. -- -- Instances should use the convert method of the Result -- class to perform conversion of each element of the collection. -- -- This example instance demonstrates how to convert a two-column row -- into a Haskell pair. Each field in the metadata is paired up with each -- value from the row, and the two are passed to convert. -- -- 
--   instance (Result a, Result b) => QueryResults (a,b) where
--       convertResults [fa,fb] [va,vb] = (a,b)
--           where !a = convert fa va
--                 !b = convert fb vb
--       convertResults fs vs  = convertError fs vs 2
--
-- -- Notice that this instance evaluates each element to WHNF before -- constructing the pair. By doing this, we guarantee two important -- properties: -- -- -- -- You can also declare Haskell types of your own to be instances of -- QueryResults. -- -- 
--   data User { firstName :: String, lastName :: String }
--   
--   instance QueryResults User where
--       convertResults [fa,fb] [va,vb] = User a b
--           where !a = convert fa va
--                 !b = convert fb vb
--       convertResults fs vs  = convertError fs vs
--
class QueryResults a convertResults :: QueryResults a => [Field] -> [Maybe ByteString] -> Either SomeException a -- | Throw a ConversionFailed exception, indicating a mismatch -- between the number of columns in the Field and row, and the -- number in the collection to be converted to. convertError :: [Field] -> [Maybe ByteString] -> Int -> Either SomeException a instance (Result a, Result b, Result c, Result d, Result e, Result f, Result g, Result h, Result i, Result j) => QueryResults (a, b, c, d, e, f, g, h, i, j) instance (Result a, Result b, Result c, Result d, Result e, Result f, Result g, Result h, Result i) => QueryResults (a, b, c, d, e, f, g, h, i) instance (Result a, Result b, Result c, Result d, Result e, Result f, Result g, Result h) => QueryResults (a, b, c, d, e, f, g, h) instance (Result a, Result b, Result c, Result d, Result e, Result f, Result g) => QueryResults (a, b, c, d, e, f, g) instance (Result a, Result b, Result c, Result d, Result e, Result f) => QueryResults (a, b, c, d, e, f) instance (Result a, Result b, Result c, Result d, Result e) => QueryResults (a, b, c, d, e) instance (Result a, Result b, Result c, Result d) => QueryResults (a, b, c, d) instance (Result a, Result b, Result c) => QueryResults (a, b, c) instance (Result a, Result b) => QueryResults (a, b) instance Result a => QueryResults (Only a) 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 System.IO.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 Database.PostgreSQL.Simple.Notification data Notification Notification :: CPid -> ByteString -> ByteString -> Notification notificationPid :: Notification -> CPid notificationChannel :: Notification -> ByteString notificationData :: Notification -> ByteString getNotification :: Connection -> IO Notification -- | A mid-level client library for the PostgreSQL database, aimed at ease -- of use and high performance. module Database.PostgreSQL.Simple data ConnectInfo ConnectInfo :: String -> Word16 -> String -> String -> String -> ConnectInfo connectHost :: ConnectInfo -> String connectPort :: ConnectInfo -> Word16 connectUser :: ConnectInfo -> String connectPassword :: ConnectInfo -> String connectDatabase :: ConnectInfo -> String data Connection -- | A query string. This type is intended to make it difficult to -- construct a SQL query by concatenating string fragments, as that is an -- extremely common way to accidentally introduce SQL injection -- vulnerabilities into an application. -- -- This type is an instance of 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 -- | 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 ?" (In [3,4,5])
--
newtype In a In :: a -> In a -- | Wrap a mostly-binary string to be escaped in hexadecimal. newtype Binary a Binary :: a -> Binary a -- | A single-value "collection". -- -- This is useful if you need to supply a single parameter to a SQL -- query, or extract a single column from a SQL result. -- -- Parameter example: -- -- 
--   query c "select x from scores where x > ?" (Only (42::Int))
--
-- -- Result example: -- -- 
--   xs <- query_ c "select id from users"
--   forM_ xs $ \(Only id) -> {- ... -}
--
newtype Only a Only :: a -> Only a fromOnly :: Only a -> a data SqlError SqlError :: ByteString -> Int -> ByteString -> SqlError sqlState :: SqlError -> ByteString sqlNativeError :: SqlError -> Int sqlErrorMsg :: SqlError -> ByteString -- | 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 -- | Exception thrown if query is used to perform an -- INSERT-like operation, or execute is used to perform a -- SELECT-like operation. data QueryError -- | Exception thrown if conversion from a SQL value to a Haskell value -- fails. data ResultError -- | Connect with the given username to the given database. Will throw an -- exception if it cannot connect. connect :: ConnectInfo -> IO Connection -- | Attempt to make a connection based on a libpq connection string. See -- http://www.postgresql.org/docs/9.1/static/libpq-connect.html -- for more information. connectPostgreSQL :: ByteString -> IO Connection -- | Turns a ConnectInfo data structure into a libpq connection -- string. postgreSQLConnectionString :: ConnectInfo -> ByteString -- | Default information for setting up a connection. -- -- Defaults are as follows: -- -- -- -- Use as in the following example: -- -- 
--   connect defaultConnectInfo { connectHost = "db.example.com" }
--
defaultConnectInfo :: ConnectInfo close :: Connection -> IO () -- | 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: -- -- query :: (QueryParams q, QueryResults r) => Connection -> Query -> q -> IO [r] -- | A version of query that does not perform query substitution. query_ :: QueryResults r => Connection -> Query -> IO [r] -- | 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. -- -- The result consumer must be carefully written to execute quickly. If -- the consumer is slow, server resources will be tied up, and other -- clients may not be able to update the tables from which the results -- are being streamed. -- -- 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. -- -- Exceptions that may be thrown: -- -- fold :: (QueryParams q, QueryResults r) => Connection -> Query -> q -> a -> (a -> r -> IO a) -> IO a -- | A version of fold that does not perform query substitution. fold_ :: QueryResults r => Connection -> Query -> a -> (a -> r -> IO a) -> IO a -- | A version of fold that does not transform a state value. forEach :: (QueryParams q, QueryResults r) => Connection -> Query -> q -> (r -> IO ()) -> IO () -- | A version of forEach that does not perform query substitution. forEach_ :: QueryResults r => Connection -> Query -> (r -> IO ()) -> IO () -- | 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. execute :: QueryParams 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. -- -- Throws FormatError if the query could not be formatted -- correctly. executeMany :: QueryParams 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 -- Base.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. withTransaction :: Connection -> IO a -> IO a -- | Begin a transaction. begin :: (MonadCatchIO m,MonadIO m) => -- Connection -> m () begin :: Connection -> IO () -- | Commit a transaction. commit :: (MonadCatchIO m,MonadIO m) => -- Connection -> m () commit :: Connection -> IO () -- | Rollback a transaction. rollback :: (MonadCatchIO m,MonadIO m) => -- Connection -> m () 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 :: QueryParams 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 :: QueryParams q => Connection -> Query -> q -> IO ByteString instance Typeable FormatError instance Typeable QueryError instance Eq FormatError instance Show FormatError instance Eq QueryError instance Show QueryError instance Exception QueryError instance Exception FormatError