Hasql.Notifications

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.

Documentation

notifyPool

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

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

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

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

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

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

Instances

Show PgIdentifier

Defined in Hasql.Notifications

Methods

showsPrec :: Int -> PgIdentifier -> ShowS

show :: PgIdentifier -> String

showList :: [PgIdentifier] -> ShowS

toPgIdentifier :: Text -> PgIdentifier

Given a text returns a properly quoted and escaped PgIdentifier

fromPgIdentifier :: PgIdentifier -> Text

Given a PgIdentifier returns the wrapped text