LISTEN(7)

💌 LISTEN(7) — the LISTEN page, bestie edition 💌

okay so this is the LISTEN(7) page from the PostgreSQL 14.24 Documentation, and honestly? it's giving "database group chat" and i'm obsessed. let's get into it 🫶

---

✨ NAME ✨

LISTEN — literally just. listen for a notification. that's the whole vibe. 👂💖

---

✨ SYNOPSIS ✨

LISTEN channel

that's it. one line. iconic. 🎀

---

✨ DESCRIPTION ✨

so LISTEN registers the current session as a listener on the notification channel named channel. lowkey a "subscribe" button for your database session, no cap. and if the current session is already registered as a listener for this notification channel? nothing is done. it's a no-op. she already knew. 💅

whenever the command NOTIFY channel gets invoked — either by this session or another one connected to the same database — all the sessions currently listening on that notification channel are notified, and each will in turn notify its connected client application. it's a whole relay race and everyone ate. 🔥

a session can be unregistered for a given notification channel with the UNLISTEN command. and a session's listen registrations are automatically cleared when the session ends — so like, no ghost subscriptions haunting the place. 🦋

now, the method a client application must use to detect notification events depends on which PostgreSQL application programming interface it uses. keep up bestie:

• with the libpq library, the application issues LISTEN as an ordinary SQL command, and then must periodically call the function PQnotifies to find out whether any notification events have been received. yes it's giving "checking your phone every 30 seconds" energy. 😭
• other interfaces such as libpgtcl provide higher-level methods for handling notify events; indeed, with libpgtcl the application programmer should not even issue LISTEN or UNLISTEN directly. main character energy, it handles it for you.

see the documentation for the interface you are using for more details. ✨

---

✨ PARAMETERS ✨

• channel — name of a notification channel (any identifier). any identifier, girl. go wild. 🌸

---

✨ NOTES ✨

okay this is the part you actually need to read, don't skip it 🙈

• LISTEN takes effect at transaction commit. if LISTEN or UNLISTEN is executed within a transaction that later rolls back, the set of notification channels being listened to is unchanged. so like, the vibe is: committed or it didn't happen. 💀
• a transaction that has executed LISTEN cannot be prepared for two-phase commit. not up for debate, it's just not allowed.
• ⚠️ there is a race condition when first setting up a listening session: if concurrently-committing transactions are sending notify events, exactly which of those will the newly listening session receive? and the answer is that the session will receive all events committed after an instant during the transaction's commit step. but that is slightly later than any database state that the transaction could have observed in queries. sneaky little timing thing. 🕐

so here's the rule for using LISTEN, straight up: first execute (and commit!) that command, then in a new transaction inspect the database state as needed by the application logic, then rely on notifications to find out about subsequent changes to the database state. order matters bestie, it's a whole choreography. 🧚

the first few received notifications might refer to updates already observed in the initial database inspection, but this is usually harmless. so don't panic. 💜

also NOTIFY(7) contains a more extensive discussion of the use of LISTEN and NOTIFY — go read it, it's the extended cut. 👑

---

✨ EXAMPLES ✨

configure and execute a listen/notify sequence from psql:

LISTEN virtual;
NOTIFY virtual;
Asynchronous notification "virtual" received from server process with PID 8448.

look at that. she listened, she got notified, PID 8448 said hi. slay. 🎀✨

---

✨ COMPATIBILITY ✨

there is no LISTEN statement in the SQL standard. so this is a PostgreSQL exclusive, iykyk. 🌈

---

✨ SEE ALSO ✨

• NOTIFY(7)
• UNLISTEN(7)

the whole friend group fr fr 🫶

---

and that's the page!! this little beauty is from PostgreSQL 14.24, dated 2026 — so go forth, listen responsibly, commit your transactions, and never forget to check PQnotifies. mwah 💋💖🎀