-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | A mid-level PostgreSQL client library. -- -- A mid-level client library for the PostgreSQL database, intended to be -- fast and easy to use. @package pgsql-simple @version 0.1.2 -- | 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.MySQL.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 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 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.Base.Types -- | Connection configuration. 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 database connection. data Connection Connection :: MVar (Maybe Handle) -> MVar (IntMap Type) -> Connection connectionHandle :: Connection -> MVar (Maybe Handle) connectionObjects :: Connection -> MVar (IntMap Type) -- | A field description. data Field Field :: Type -> FormatCode -> Field fieldType :: Field -> Type fieldFormatCode :: Field -> FormatCode -- | Result of a database query. data Result Result :: [[Maybe ByteString]] -> Maybe [Field] -> Maybe ByteString -> [String] -> MessageType -> Maybe Integer -> Result resultRows :: Result -> [[Maybe ByteString]] resultDesc :: Result -> Maybe [Field] resultError :: Result -> Maybe ByteString resultNotices :: Result -> [String] resultType :: Result -> MessageType resultTagRows :: Result -> Maybe Integer data Type -- | 2 bytes, small-range integer Short :: Type -- | 4 bytes, usual choice for integer Long :: Type -- | 8 bytes large-range integer LongLong :: Type -- | variable, user-specified precision, exact, no limit Decimal :: Type -- | variable, user-specified precision, exact, no limit Numeric :: Type -- | 4 bytes, variable-precision, inexact Real :: Type -- | 8 bytes, variable-precision, inexact DoublePrecision :: Type -- | character varying(n), varchar(n), variable-length CharVarying :: Type -- | character(n), char(n), fixed-length Characters :: Type -- | text, variable unlimited length -- -- Lazy. Decoded from UTF-8 into Haskell native encoding. Text :: Type -- | boolean, 1 byte, state of true or false Boolean :: Type -- | timestamp without time zone -- -- More information about PostgreSQL’s dates here: -- http://www.postgresql.org/docs/current/static/datatype-datetime.html Timestamp :: Type -- | timestamp with time zone TimestampWithZone :: Type -- | date, 4 bytes julian day Date :: Type -- | 8 bytes, time of day (no date) Time :: Type -- | An internal message type. data MessageType CommandComplete :: MessageType RowDescription :: MessageType DataRow :: MessageType EmptyQueryResponse :: MessageType ErrorResponse :: MessageType ReadyForQuery :: MessageType NoticeResponse :: MessageType AuthenticationOk :: MessageType Query :: MessageType PasswordMessage :: MessageType UnknownMessageType :: MessageType -- | A field size. data Size Varying :: Size Size :: Int16 -> Size -- | A text format code. Will always be TextCode for DESCRIBE queries. data FormatCode TextCode :: FormatCode BinaryCode :: FormatCode -- | A type-specific modifier. data Modifier Modifier :: Modifier -- | A PostgreSQL object ID. type ObjectId = Int newtype Pool Pool :: MVar PoolState -> Pool unPool :: Pool -> MVar PoolState -- | A connection pool. data PoolState PoolState :: [Connection] -> ConnectInfo -> PoolState poolConnections :: PoolState -> [Connection] poolConnectInfo :: PoolState -> ConnectInfo data ConnectionError -- | Query returned an error. QueryError :: (Maybe String) -> ConnectionError -- | The query was empty. QueryEmpty :: ConnectionError -- | Connecting failed due to authentication problem. AuthenticationFailed :: String -> ConnectionError -- | Initialization (e.g. getting data types) failed. InitializationError :: String -> ConnectionError -- | Connection was lost when using withConnection. ConnectionLost :: ConnectionError -- | Unsupported method of authentication (e.g. md5). UnsupportedAuthenticationMethod :: Int32 -> String -> ConnectionError GeneralError :: String -> ConnectionError instance Typeable ConnectionError instance Typeable ConnectInfo instance Show ConnectionError instance Eq ConnectInfo instance Read ConnectInfo instance Show ConnectInfo instance Show MessageType instance Eq MessageType instance Eq Type instance Enum Type instance Show Type instance Eq Size instance Ord Size instance Show Size instance Eq FormatCode instance Ord FormatCode instance Show FormatCode instance Show Field instance Show Result instance Exception ConnectionError -- | 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 MySQL -- numeric types that are less accurate than it. For instance, the -- Haskell Double type is compatible with the MySQL Long -- type because it can represent a Long exactly. On the other -- hand, since a Double might lose precision if representing a -- LongLong, 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 -> 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 TimeOfDay instance Result Day instance Result UTCTime instance Result ZonedTime instance Result LocalTime instance Result [Char] instance Result Text instance Result Text instance Result ByteString instance Result ByteString instance Result (Ratio Integer) instance Result Double instance Result Float instance Result Word64 instance Result Word instance Result Word32 instance Result Word16 instance Result Integer instance Result Int64 instance Result Int instance Result Int32 instance Result Int16 instance Result Bool 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 class QueryResults a convertResults :: QueryResults a => [Field] -> [Maybe ByteString] -> 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 -> 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) -- | A front-end implementation for the PostgreSQL database protocol -- version 3.0 (implemented in PostgreSQL 7.4 and later). module Database.PostgreSQL.Base -- | Begin a transaction. begin :: (MonadCatchIO m, MonadIO m) => Connection -> m () -- | Rollback a transaction. rollback :: (MonadCatchIO m, MonadIO m) => Connection -> m () -- | Commit a transaction. commit :: (MonadCatchIO m, MonadIO m) => Connection -> m () -- | Run a simple query on a connection. query :: MonadCatchIO m => Connection -> ByteString -> m ([Field], [[Maybe ByteString]]) -- | Exec a command. exec :: MonadCatchIO m => Connection -> ByteString -> m Integer -- | Escape a string for PostgreSQL. escapeBS :: ByteString -> ByteString -- | Connect with the given username to the given database. Will throw an -- exception if it cannot connect. connect :: MonadIO m => ConnectInfo -> m Connection -- | 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 a connection. Can safely be called any number of times. close :: MonadIO m => Connection -> m () -- | Run a an action with a connection and close the connection afterwards -- (protects against exceptions). withDB :: (MonadCatchIO m, MonadIO m) => ConnectInfo -> (Connection -> m a) -> m a -- | With a transaction, do some action (protects against exceptions). withTransaction :: (MonadCatchIO m, MonadIO m) => Connection -> m a -> m a -- | Create a new connection pool. newPool :: MonadIO m => ConnectInfo -> m Pool -- | Connect using the connection pool. pconnect :: MonadIO m => Pool -> m Connection -- | Use the connection pool. withPoolConnection :: (MonadCatchIO m, MonadIO m) => Pool -> (Connection -> m a) -> m () -- | A mid-level client library for the MySQL database, aimed at ease of -- use and high performance. module Database.PostgreSQL.Simple -- | Connection configuration. 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 database connection. 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.MySQL.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 -- | A processed, appendable. query data ProcessedQuery r data Pool -- | 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 :: MonadIO m => ConnectInfo -> m Connection -- | 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 a connection. Can safely be called any number of times. close :: MonadIO m => Connection -> m () -- | 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] -- | Process a query for later use. processQuery :: (QueryParams q, QueryResults r) => Query -> q -> IO (ProcessedQuery r) -- | A version of query that does not perform query substitution. queryProcessed :: QueryResults r => Connection -> ProcessedQuery r -> 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. execute :: QueryParams q => Connection -> Query -> q -> IO Integer -- | A version of execute that does not perform query substitution. execute_ :: Connection -> Query -> IO Integer -- | 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 Integer -- | 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 -- MySQL-related exception), the transaction will be rolled back using -- rollback, then the exception will be rethrown. withTransaction :: Connection -> IO a -> IO a -- | Commit a transaction. commit :: (MonadCatchIO m, MonadIO m) => Connection -> m () -- | Rollback a transaction. rollback :: (MonadCatchIO m, MonadIO m) => Connection -> m () -- | 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 => Query -> [q] -> IO ByteString -- | Format a query string. formatQuery :: QueryParams q => Query -> q -> IO ByteString -- | Use the connection pool. withPoolConnection :: (MonadCatchIO m, MonadIO m) => Pool -> (Connection -> m a) -> m () -- | Create a new connection pool. newPool :: MonadIO m => ConnectInfo -> m Pool instance Typeable FormatError instance Typeable QueryError instance Eq FormatError instance Show FormatError instance Eq QueryError instance Show QueryError instance Monoid (ProcessedQuery r) instance Show (ProcessedQuery r) instance Exception QueryError instance Exception FormatError