-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Implementation of named parameters for `postgresql-simple` library
--
-- Implementation of named parameters for postgresql-simple
-- library.
--
-- Here is an exaple of how it could be used in your code:
--
--
-- queryNamed dbConnection [sql|
-- SELECT *
-- FROM table
-- WHERE foo = ?foo
-- AND bar = ?bar
-- AND baz = ?foo
-- |] [ "foo" =? "fooBar"
-- , "bar" =? "barVar"
-- ]
--
@package postgresql-simple-named
@version 0.0.2.0
-- | Introduces named parameters for postgresql-simple library. It
-- uses ? question mark symbol as the indicator of the named
-- parameter which is replaced with the standard syntax with question
-- marks.
--
-- Check out the example of usage:
--
--
-- queryNamed dbConnection [sql|
-- SELECT *
-- FROM users
-- WHERE foo = ?foo
-- AND bar = ?bar
-- AND baz = ?foo
-- |] [ "foo" =? "fooBar"
-- , "bar" =? "barVar"
-- ]
--
module PgNamed
-- | Data type to represent each named parameter.
data NamedParam
NamedParam :: !Name -> !Action -> NamedParam
[namedParamName] :: NamedParam -> !Name
[namedParamParam] :: NamedParam -> !Action
-- | Wrapper over name of the argument.
newtype Name
Name :: Text -> Name
[unName] :: Name -> Text
-- | Operator to create NamedParams.
--
--
-- >>> "foo" =? (1 :: Int)
-- NamedParam {namedParamName = "foo", namedParamParam = Plain "1"}
--
--
-- So it can be used in creating the list of the named arguments:
--
--
-- queryNamed dbConnection [sql|
-- SELECT *
-- FROM users
-- WHERE foo = ?foo
-- AND bar = ?bar
-- AND baz = ?foo
-- |] [ "foo" =? "fooBar"
-- , "bar" =? "barVar"
-- ]
--
(=?) :: ToField a => Name -> a -> NamedParam
infix 1 =?
-- | PostgreSQL error type for named parameters.
data PgNamedError
-- | Named parameter is not specified.
PgNamedParam :: Name -> PgNamedError
-- | Query has no names inside but was called with named functions.
PgNoNames :: Query -> PgNamedError
-- | Query contains an empty name.
PgEmptyName :: Query -> PgNamedError
-- | Type alias for monads that can throw errors of the PgNamedError
-- type.
type WithNamedError = MonadError PgNamedError
-- | This function takes query with named parameters specified like this:
--
--
-- SELECT name, user FROM users WHERE id = ?id
--
--
-- and returns either the error or the query with all names replaced by
-- question marks ? with the list of the names in the order of
-- their appearance.
--
-- For example:
--
--
-- >>> extractNames "SELECT * FROM users WHERE foo = ?foo AND bar = ?bar AND baz = ?foo"
-- Right ("SELECT * FROM users WHERE foo = ? AND bar = ? AND baz = ?","foo" :| ["bar","foo"])
--
extractNames :: Query -> Either PgNamedError (Query, NonEmpty Name)
-- | Returns the list of values to use in query by given list of
-- Names. Throws PgNamedError if any named parameter is not
-- specified.
namesToRow :: forall m. WithNamedError m => NonEmpty Name -> [NamedParam] -> m (NonEmpty Action)
-- | Queries the database with a given query and named parameters and
-- expects a list of rows in return.
--
--
-- queryNamed dbConnection [sql|
-- SELECT id
-- FROM table
-- WHERE foo = ?foo
-- |] [ "foo" =? "bar" ]
--
queryNamed :: (MonadIO m, WithNamedError m, FromRow res) => Connection -> Query -> [NamedParam] -> m [res]
-- | Queries the database with a given row parser, Query, and named
-- parameters and expects a list of rows in return.
--
-- Sometimes there are multiple ways to parse tuples returned by
-- PostgreSQL into the same data type. However, it's not possible to
-- implement multiple intances of the FromRow typeclass (or any
-- other typeclass).
--
-- Consider the following data type:
--
--
-- data Person = Person
-- { personName :: !Text
-- , personAge :: !(Maybe Int)
-- }
--
--
-- We might want to parse values of the Person data type in two
-- ways:
--
--
-- - Default by parsing all fields.
-- - Parse only name and age to Nothing.
--
--
-- If you want to have multiple instances, you need to create
-- newtype for each case. However, in some cases it might not be
-- convenient to deal with newtypes around large data types. So you can
-- implement custom RowParser and use it with
-- queryWithNamed.
--
--
-- queryWithNamed rowParser dbConnection [sql|
-- SELECT id
-- FROM table
-- WHERE foo = ?foo
-- |] [ "foo" =? "bar" ]
--
queryWithNamed :: (MonadIO m, WithNamedError m) => RowParser res -> Connection -> Query -> [NamedParam] -> m [res]
-- | Modifies the database with a given query and named parameters and
-- expects a number of the rows affected.
--
--
-- executeNamed dbConnection [sql|
-- UPDATE table
-- SET foo = 'bar'
-- WHERE id = ?id
-- |] [ "id" =? someId ]
--
executeNamed :: (MonadIO m, WithNamedError m) => Connection -> Query -> [NamedParam] -> m Int64
-- | Same as executeNamed but discard the nubmer of rows affected by
-- the given query. This function is useful when you're not interested in
-- this number.
executeNamed_ :: (MonadIO m, WithNamedError m) => Connection -> Query -> [NamedParam] -> m ()
-- | Helper to use named parameters. Use it to implement named wrappers
-- around functions from postgresql-simple library. If you think
-- that the function is useful, consider opening feature request to the
-- postgresql-simple-named library:
--
--
withNamedArgs :: WithNamedError m => Query -> [NamedParam] -> m (Query, NonEmpty Action)
instance GHC.Classes.Eq PgNamed.PgNamedError
instance GHC.Show.Show PgNamed.NamedParam
instance Data.String.IsString PgNamed.Name
instance GHC.Classes.Ord PgNamed.Name
instance GHC.Classes.Eq PgNamed.Name
instance GHC.Show.Show PgNamed.Name
instance GHC.Show.Show PgNamed.PgNamedError