Postgrex v0.15.0 Postgrex.Notifications View Source
API for notifications (pub/sub) in PostgreSQL.
In order to use it, first you need to start the notification process. In your supervision tree:
{Postgrex.Notifications, name: MyApp.Notifications}
Then you can listen to certain channels:
{:ok, listen_ref} = Postgrex.Notifications.listen(MyApp.Notifications, "channel")
Now every time a message is broadcast on said channel, for example via PostgreSQL command line:
NOTIFY "channel", "Oh hai!";
You will receive a message in the formmat:
{:notification, notification_pid, listen_ref, channel, message}
A note on casing
While PostgreSQL seems to behave as case-insensitive, it actually has a very perculiar behaviour on casing. When you write:
SELECT * FROM POSTS
PostgreSQL actually converts POSTS
into the lowercase posts
. That's why
both SELECT * FROM POSTS
and SELECT * FROM posts
feel equivalent.
However, if you wrap the table name in quotes, then the casing in quotes
will be preserved.
These same rules apply to PostgreSQL notification channels. More importantly,
whenever Postgrex.Notifications
listens to a channel, it wraps the channel
name in quotes. Therefore, if you listen to a channel named "fooBar" and
you send a notification without quotes in the channel name, such as:
NOTIFY fooBar, "Oh hai!";
The notification will not be received by Postgrex.Notifications because the
notification will be effectively sent to "foobar"
and not "fooBar"
. Therefore,
you must guarantee one of the two following properties:
If you can wrap the channel name in quotes when sending a notification, then make sure the channel name has the exact same casing when listening and sennding notifications
If you cannot wrap the channel name in quotes when sending a notification, then make sure to give the lowercased channel name when listening
Link to this section Summary
Functions
Listens to an asynchronous notification channel using the LISTEN
command.
A message {:notification, connection_pid, ref, channel, payload}
will be
sent to the calling process when a notification is received.
Listens to an asynchronous notification channel channel
. See listen/2
.
Start the notification connection process and connect to postgres.
Stops listening on the given channel by passing the reference returned from
listen/2
.
Stops listening on the given channel by passing the reference returned from
listen/2
.
Link to this section Types
Link to this section Functions
Listens to an asynchronous notification channel using the LISTEN
command.
A message {:notification, connection_pid, ref, channel, payload}
will be
sent to the calling process when a notification is received.
Options
:timeout
- Call timeout (default:5000
)
Listens to an asynchronous notification channel channel
. See listen/2
.
start_link(opts)
View Sourcestart_link(Keyword.t()) :: {:ok, pid()} | {:error, Postgrex.Error.t() | term()}
Start the notification connection process and connect to postgres.
The option that this function accepts are exactly the same accepted by
Postgrex.start_link/1
. Note :sync_connect
defaults to true
.
Stops listening on the given channel by passing the reference returned from
listen/2
.
Options
:timeout
- Call timeout (default:5000
)
Stops listening on the given channel by passing the reference returned from
listen/2
.