Safe Haskell	Safe-Inferred
Language	Haskell2010

Hasql.Notifications

Description

This module has functions to send commands LISTEN and NOTIFY to the database server. It also has a function to wait for and handle notifications on a database connection.

For more information check the PostgreSQL documentation.

Synopsis

notifyPool :: Pool -> Text -> Text -> IO (Either UsageError ())
notify :: Connection -> PgIdentifier -> Text -> IO (Either QueryError ())
listen :: Connection -> PgIdentifier -> IO ()
unlisten :: Connection -> PgIdentifier -> IO ()
waitForNotifications :: (ByteString -> ByteString -> IO ()) -> Connection -> IO ()
data PgIdentifier
toPgIdentifier :: Text -> PgIdentifier
fromPgIdentifier :: PgIdentifier -> Text
newtype FatalError = FatalError {
- fatalErrorMessage :: String
}

Documentation

notifyPool Source #

Arguments

:: Pool	Pool from which the connection will be used to issue a NOTIFY command.
-> Text	Channel where to send the notification
-> Text	Payload to be sent with the notification
-> IO (Either UsageError ())

Given a Hasql Pool, a channel and a message sends a notify command to the database

notify Source #

Arguments

:: Connection	Connection to be used to send the NOTIFY command
-> PgIdentifier	Channel where to send the notification
-> Text	Payload to be sent with the notification
-> IO (Either QueryError ())

Given a Hasql Connection, a channel and a message sends a notify command to the database

listen Source #

Arguments

:: Connection	Connection to be used to send the LISTEN command
-> PgIdentifier	Channel this connection will be registered to listen to
-> IO ()

Given a Hasql Connection and a channel sends a listen command to the database. Once the connection sends the LISTEN command the server register its interest in the channel. Hence it's important to keep track of which connection was used to open the listen command.

Example of listening and waiting for a notification:

 import System.Exit (die)

 import Hasql.Connection
 import Hasql.Notifications

 main :: IO ()
 main = do
   dbOrError <- acquire "postgres:/localhostdb_name"
   case dbOrError of
       Right db -> do
           let channelToListen = toPgIdentifier "sample-channel"
           listen db channelToListen
           waitForNotifications (channel _ -> print $ "Just got notification on channel " <> channel) db
       _ -> die "Could not open database connection"

unlisten Source #

Arguments

:: Connection	Connection currently registerd by a previous `listen` call
-> PgIdentifier	Channel this connection will be deregistered from
-> IO ()

Given a Hasql Connection and a channel sends a unlisten command to the database

waitForNotifications Source #

Arguments

:: (ByteString -> ByteString -> IO ())	Callback function to handle incoming notifications
-> Connection	Connection where we will listen to
-> IO ()

Given a function that handles notifications and a Hasql connection it will listen on the database connection and call the handler everytime a message arrives.

The message handler passed as first argument needs two parameters channel and payload. See an example of handling notification on a separate thread:

 import Control.Concurrent.Async (async)
 import Control.Monad (void)
 import System.Exit (die)

 import Hasql.Connection
 import Hasql.Notifications

 notificationHandler :: ByteString -> ByteString -> IO()
 notificationHandler channel payload =
   void $ async do
     print $ "Handle payload " <> payload <> " in its own thread"

 main :: IO ()
 main = do
   dbOrError <- acquire "postgres:/localhostdb_name"
   case dbOrError of
       Right db -> do
           let channelToListen = toPgIdentifier "sample-channel"
           listen db channelToListen
           waitForNotifications notificationHandler db
       _ -> die "Could not open database connection"

data PgIdentifier Source #

A wrapped text that represents a properly escaped and quoted PostgreSQL identifier

Instances

Instances details

Show PgIdentifier Source #
Instance details Defined in Hasql.Notifications Methods showsPrec :: Int -> PgIdentifier -> ShowS # show :: PgIdentifier -> String # showList :: [PgIdentifier] -> ShowS #

toPgIdentifier :: Text -> PgIdentifier Source #

Given a text returns a properly quoted and escaped PgIdentifier

fromPgIdentifier :: PgIdentifier -> Text Source #

Given a PgIdentifier returns the wrapped text

newtype FatalError Source #

Uncatchable exceptions thrown and never caught.

Constructors

FatalError
Fields fatalErrorMessage :: String

Instances

Instances details

Exception FatalError Source #
Instance details Defined in Hasql.Notifications Methods toException :: FatalError -> SomeException # fromException :: SomeException -> Maybe FatalError # displayException :: FatalError -> String #
Show FatalError Source #
Instance details Defined in Hasql.Notifications Methods showsPrec :: Int -> FatalError -> ShowS # show :: FatalError -> String # showList :: [FatalError] -> ShowS #