PG_LISTEN(n)

🎀 PG_LISTEN — or, how to make your app listen for drama from Postgres 💅

ok so real talk, this page lives in the PostgreSQL Tcl Interface Documentation and it's the whole guide to pg_listen, which is basically the group-chat-notifications feature of pgtcl. stay with me bestie, it's actually so good ✨

---

✨ SYNOPSIS ✨

pg_listen conn notifyName [callbackCommand]

three little words and a maybe-fourth, that's the whole vibe 🦋

---

💖 DESCRIPTION 💖

okay so pg_listen creates, changes, or cancels a request to listen for asynchronous notification messages from the PostgreSQL server. that's the entire job description and honestly? iconic.

here's the tea on the two modes:

• pass a callbackCommand → the request is established, or, if a request already existed, its command string gets replaced. glow-up, not a new entry 😌
• pass no callbackCommand → any prior request is canceled. it's giving "we're not doing this anymore" 💀

once a pg_listen request is established, that specified command string gets executed whenever a notification message bearing the given name arrives from the server. and when does that happen? when any PostgreSQL client application issues a NOTIFY command referencing that name. so someone else's app can be the one pressing send, and your app gets the ping. teamwork, fr fr 🫶

now the technical bit, and it matters: the command string is executed from the Tcl idle loop. that's the normal idle state of an application written with Tk. in non-Tk Tcl shells, you can execute update or vwait to cause the idle loop to be entered. ngl if your non-Tk shell seems like it's ignoring you, that's why — no idle loop action, no callback. no cap ✨

🚨 important bestie warning 🚨 you should NOT invoke the SQL statements LISTEN or UNLISTEN directly when using pg_listen. pgtcl takes care of issuing those statements for you. it's handled! don't do it manually, that's double-texting in SQL form 🙈

but — and this is the fun part — if you want to send a notification message yourself, invoke the SQL NOTIFY statement using pg_exec. that's the approved slay route 👑

---

🌸 ARGUMENTS 🌸

• conn — the handle of the connection on which to listen for notifications. this is your ✨main character✨ connection.
• notifyName — the name of the notification condition to start or stop listening to. the name is the whole personality here, ok 💅
• callbackCommand — if present, provides the command string to execute when a matching notification arrives. present = "do this when it lands." absent = "we're done here." 🎀

---

⭐ RETURN VALUE ⭐

None. that's it. that's the return value. it does the thing, it doesn't hand you a value back. lowkey refreshing tbh 😌

---

🦋 reminder: callbackCommand in = established/replaced, callbackCommand out = canceled. + vs - energy, iykyk.

---

made with 💜 from the PostgreSQL Tcl Interface Documentation, dated 17 September 2020 — that's the source, the version, and the date all wrapped up with a bow 🎀 go forth and let your notifications reach you, bestie. periodt. 🔥👑🌈