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


-- | postgresql-simple snaplet for the Snap Framework
--   
@package snaplet-postgresql-simple
@version 0.6


-- | This snaplet makes it simple to use a PostgreSQL database from your
--   Snap application and is based on the excellent postgresql-simple
--   library (<a>http://hackage.haskell.org/package/postgresql-simple</a>)
--   by Leon Smith (adapted from Bryan O'Sullivan's mysql-simple). Now,
--   adding a database to your web app takes just two simple steps.
--   
--   First, include this snaplet in your application's state.
--   
--   <pre>
--   data App = App
--       { ... -- Other state needed in your app
--       , _db :: Snaplet Postgres
--       }
--   </pre>
--   
--   Next, call the pgsInit from your application's initializer.
--   
--   <pre>
--   appInit = makeSnaplet ... $ do
--       ...
--       d &lt;- nestSnaplet "db" db pgsInit
--       return $ App ... d
--   </pre>
--   
--   Now you can use any of the postgresql-simple wrapper functions defined
--   in this module anywhere in your application handlers. For instance:
--   
--   <pre>
--   postHandler :: Handler App App ()
--   postHandler = do
--       posts &lt;- with db $ query_ "select * from blog_post"
--       ...
--   </pre>
--   
--   Optionally, if you find yourself doing many database queries, you can
--   eliminate some of the boilerplate by defining a HasPostgres instance
--   for your application.
--   
--   <pre>
--   instance HasPostgres (Handler b App) where
--     getPostgresState = with db get
--   </pre>
--   
--   With this code, our postHandler example no longer requires the
--   <a>with</a> function:
--   
--   <pre>
--   postHandler :: Handler App App ()
--   postHandler = do
--       posts &lt;- query_ "select * from blog_post"
--       ...
--   </pre>
--   
--   The first time you run an application with the postgresql-simple
--   snaplet, a configuration file <tt>devel.cfg</tt> is created in the
--   <tt>snaplets/postgresql-simple</tt> directory underneath your project
--   root. It specifies how to connect to your PostgreSQL server and what
--   user, password, and database to use. Edit this file and modify the
--   values appropriately and you'll be off and running.
--   
--   If you want to have out-of-the-box authentication, look at the
--   documentation for the
--   <a>Snap.Snaplet.Auth.Backends.PostgresqlSimple</a> module.
module Snap.Snaplet.PostgresqlSimple

-- | The state for the postgresql-simple snaplet. To use it in your app
--   include this in your application state and use pgsInit to initialize
--   it.
data Postgres
PostgresPool :: (Pool Connection) -> Postgres
PostgresConn :: Connection -> Postgres

-- | Instantiate this typeclass on 'Handler b YourAppState' so this snaplet
--   can find the connection source. If you need to have multiple instances
--   of the postgres snaplet in your application, then don't provide this
--   instance and leverage the default instance by using "<tt>with
--   dbLens</tt>" in front of calls to snaplet-postgresql-simple functions.
class MonadCatchIO m => HasPostgres m
getPostgresState :: HasPostgres m => m Postgres
setLocalPostgresState :: HasPostgres m => Postgres -> m a -> m a

-- | Data type holding all the snaplet's config information.
data PGSConfig
PGSConfig :: ByteString -> Int -> Double -> Int -> PGSConfig

-- | A libpq connection string.
pgsConnStr :: PGSConfig -> ByteString

-- | The number of distinct sub-pools to maintain. The smallest acceptable
--   value is 1.
pgsNumStripes :: PGSConfig -> Int

-- | Amount of time for which an unused resource is kept open. The smallest
--   acceptable value is 0.5 seconds.
pgsIdleTime :: PGSConfig -> Double

-- | Maximum number of resources to keep open per stripe. The smallest
--   acceptable value is 1.
pgsResources :: PGSConfig -> Int

-- | Returns a config object with default values and the specified
--   connection string.
pgsDefaultConfig :: ByteString -> PGSConfig

-- | Builds a PGSConfig object from a configurator Config object. This
--   function uses getConnectionString to construct the connection string.
--   The rest of the PGSConfig fields are obtained from "numStripes",
--   "idleTime", and "maxResourcesPerStripe".
mkPGSConfig :: MonadIO m => Config -> m PGSConfig

-- | Initialize the snaplet
pgsInit :: SnapletInit b Postgres

-- | Initialize the snaplet using a specific configuration.
pgsInit' :: PGSConfig -> SnapletInit b Postgres

-- | Produce a connection string from a config
getConnectionString :: Config -> IO ByteString

-- | Function that reserves a single connection for the duration of the
--   given action.
withPG :: HasPostgres m => m b -> m b

-- | Convenience function for executing a function that needs a database
--   connection.
liftPG :: HasPostgres m => (Connection -> IO b) -> m b

-- | See <a>query</a>
query :: (HasPostgres m, ToRow q, FromRow r) => Query -> q -> m [r]

-- | See <a>query_</a>
query_ :: (HasPostgres m, FromRow r) => Query -> m [r]
fold :: (HasPostgres m, FromRow row, ToRow params) => Query -> params -> b -> (b -> row -> IO b) -> m b
foldWithOptions :: (HasPostgres m, FromRow row, ToRow params, MonadCatchIO m) => FoldOptions -> Query -> params -> b -> (b -> row -> IO b) -> m b
fold_ :: (HasPostgres m, FromRow row, MonadCatchIO m) => Query -> b -> (b -> row -> IO b) -> m b
foldWithOptions_ :: (HasPostgres m, FromRow row) => FoldOptions -> Query -> b -> (b -> row -> IO b) -> m b
forEach :: (HasPostgres m, FromRow r, ToRow q) => Query -> q -> (r -> IO ()) -> m ()
forEach_ :: (HasPostgres m, FromRow r) => Query -> (r -> IO ()) -> m ()
execute :: (HasPostgres m, ToRow q) => Query -> q -> m Int64
execute_ :: HasPostgres m => Query -> m Int64
executeMany :: (HasPostgres m, ToRow q) => Query -> [q] -> m Int64

-- | See <a>returning</a>
returning :: (HasPostgres m, ToRow q, FromRow r) => Query -> [q] -> m [r]
withTransaction :: HasPostgres m => m a -> m a
withTransactionLevel :: HasPostgres m => IsolationLevel -> m a -> m a
withTransactionMode :: HasPostgres m => TransactionMode -> m a -> m a
formatMany :: (ToRow q, HasPostgres m) => Query -> [q] -> m ByteString
formatQuery :: (ToRow q, HasPostgres m) => Query -> q -> m ByteString

-- | 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.
data Query :: *

-- | 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>
newtype In a :: * -> *
In :: a -> In a

-- | Wrap binary data for use as a <tt>bytea</tt> value.
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:
--   
--   <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
data SqlError :: *
SqlError :: ByteString -> ExecStatus -> ByteString -> ByteString -> ByteString -> SqlError
sqlState :: SqlError -> ByteString
sqlExecStatus :: SqlError -> ExecStatus
sqlErrorMsg :: SqlError -> ByteString
sqlErrorDetail :: SqlError -> ByteString
sqlErrorHint :: SqlError -> ByteString

-- | Exception thrown if a <a>Query</a> could not be formatted correctly.
--   This may occur if the number of '<tt>?</tt>' characters in the query
--   string does not match the number of parameters provided.
data FormatError :: *

-- | Exception thrown if <tt>query</tt> is used to perform an
--   <tt>INSERT</tt>-like operation, or <tt>execute</tt> is used to perform
--   a <tt>SELECT</tt>-like operation.
data QueryError :: *

-- | Exception thrown if conversion from a SQL value to a Haskell value
--   fails.
data ResultError :: *
data TransactionMode :: *
TransactionMode :: SrictNotUnpackedIsolationLevel -> SrictNotUnpackedReadWriteMode -> TransactionMode
isolationLevel :: TransactionMode -> SrictNotUnpackedIsolationLevel
readWriteMode :: TransactionMode -> SrictNotUnpackedReadWriteMode

-- | Of the four isolation levels defined by the SQL standard, these are
--   the three levels distinguished by PostgreSQL as of version 9.0. See
--   <a>http://www.postgresql.org/docs/9.1/static/transaction-iso.html</a>
--   for more information. Note that prior to PostgreSQL 9.0,
--   <a>RepeatableRead</a> was equivalent to <a>Serializable</a>.
data IsolationLevel :: *

-- | the isolation level will be taken from PostgreSQL's per-connection
--   <tt>default_transaction_isolation</tt> variable, which is initialized
--   according to the server's config. The default configuration is
--   <a>ReadCommitted</a>.
DefaultIsolationLevel :: IsolationLevel
ReadCommitted :: IsolationLevel
RepeatableRead :: IsolationLevel
Serializable :: IsolationLevel
data ReadWriteMode :: *

-- | the read-write mode will be taken from PostgreSQL's per-connection
--   <tt>default_transaction_read_only</tt> variable, which is initialized
--   according to the server's config. The default configuration is
--   <a>ReadWrite</a>.
DefaultReadWriteMode :: ReadWriteMode
ReadWrite :: ReadWriteMode
ReadOnly :: ReadWriteMode

-- | Begin a transaction.
begin :: Connection -> IO ()

-- | Begin a transaction with a given isolation level
beginLevel :: IsolationLevel -> Connection -> IO ()

-- | Begin a transaction with a given transaction mode
beginMode :: TransactionMode -> Connection -> IO ()

-- | Rollback a transaction.
rollback :: Connection -> IO ()

-- | Commit a transaction.
commit :: Connection -> IO ()

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

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

-- | A collection type that can be converted from a sequence of fields.
--   Instances are provided for tuples up to 10 elements and lists of any
--   length.
--   
--   Note that instances can be defined outside of postgresql-simple, which
--   is often useful. For example, here's an instance for a user-defined
--   pair:
--   
--   @data User = User { name :: String, fileQuota :: Int }
--   
--   instance <a>FromRow</a> User where fromRow = User &lt;$&gt;
--   <a>field</a> &lt;*&gt; <a>field</a> @
--   
--   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 it's 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

-- | 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
defaultTransactionMode :: TransactionMode
defaultIsolationLevel :: IsolationLevel
defaultReadWriteMode :: ReadWriteMode
field :: FromField a => RowParser a
instance MonadCatchIO m => HasPostgres (ReaderT Postgres m)
instance MonadCatchIO m => HasPostgres (ReaderT (Snaplet Postgres) m)
instance HasPostgres (Handler b Postgres)


-- | This module allows you to use the auth snaplet with your user database
--   stored in a PostgreSQL database. When you run your application with
--   this snaplet, a config file will be copied into the the
--   <tt>snaplets/postgresql-auth</tt> directory. This file contains all of
--   the configurable options for the snaplet and allows you to change them
--   without recompiling your application.
--   
--   To use this snaplet in your application enable the session, postgres,
--   and auth snaplets as follows:
--   
--   <pre>
--   data App = App
--       { ... -- your own application state here
--       , _sess :: Snaplet SessionManager
--       , _db   :: Snaplet Postgres
--       , _auth :: Snaplet (AuthManager App)
--       }
--   </pre>
--   
--   Then in your initializer you'll have something like this:
--   
--   <pre>
--   d &lt;- nestSnaplet "db" db pgsInit
--   a &lt;- nestSnaplet "auth" auth $ initPostgresAuth sess d
--   </pre>
--   
--   If you have not already created the database table for users, it will
--   automatically be created for you the first time you run your
--   application.
module Snap.Snaplet.Auth.Backends.PostgresqlSimple

-- | Initializer for the postgres backend to the auth snaplet.
initPostgresAuth :: SnapletLens b SessionManager -> Snaplet Postgres -> SnapletInit b (AuthManager b)
instance IAuthBackend PostgresAuthManager
instance ToField Password
instance FromRow AuthUser
instance FromField Password
instance FromField UserId