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

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