SQL UNLISTEN

What does SQL UNLISTEN do?

UNLISTEN stops the current session from receiving further NOTIFY messages on a specified channel or on all channels.

Welcome to the Galaxy, Guardian!
You'll be receiving a confirmation email

Follow us on twitter :)

Oops! Something went wrong while submitting the form.

Compatible dialects for SQL UNLISTEN: Supported in PostgreSQL and derivatives that implement LISTEN/NOTIFY (e.g., TimescaleDB, Azure Database for PostgreSQL). Not available in MySQL, SQL Server, Oracle, SQLite, or standard SQL.

SQL UNLISTEN Full Explanation

UNLISTEN is part of PostgreSQL's asynchronous messaging system. A session that previously executed LISTEN channel_name will receive NOTIFY payloads sent on that channel. Executing UNLISTEN channel_name removes that registration so no more notifications for that channel reach the session. Using UNLISTEN * clears every active registration in the session. UNLISTEN takes effect immediately; it is not rolled back if the surrounding transaction aborts, because the listen state is associated with the session rather than the transaction. Each UNLISTEN statement generates a single row command-tag but returns no result rows. If the session was not listening on the given channel, the command is still accepted and silently does nothing.

SQL UNLISTEN Syntax

UNLISTEN channel_name;
UNLISTEN *;

SQL UNLISTEN Parameters

channel_name (identifier) - The name of the notification channel to stop listening on.
* (keyword) - A wildcard that removes the session from every channel it is currently listening to.

Example Queries Using SQL UNLISTEN

-- Start listening on two channels
LISTEN orders_update;
LISTEN inventory_low;

-- Later in the session, stop listening only to one channel
UNLISTEN inventory_low;

-- Or stop listening to all channels at once
UNLISTEN *;

Expected Output Using SQL UNLISTEN

Each UNLISTEN statement returns the command tag UNLISTEN
No result set is produced
The session will no longer receive NOTIFY messages for the removed channels

Use Cases with SQL UNLISTEN

Clean up listen registrations when a session no longer needs certain events
Switch from one channel to another without closing the connection
Ensure long-running background workers relinquish unused channels to avoid unnecessary wake-ups

Common Mistakes with SQL UNLISTEN

Misspelling the channel name so the command appears to work but the session keeps receiving messages
Assuming UNLISTEN is transaction-scoped; it is session-scoped and cannot be rolled back
Forgetting to include the * when intending to clear all channels

First Introduced In

PostgreSQL 6.4

Frequently Asked Questions

How is UNLISTEN different from LISTEN?

LISTEN registers the session to receive asynchronous notifications on a channel, whereas UNLISTEN removes that registration. Without an active LISTEN, NOTIFY messages on that channel are ignored by the session.

Can UNLISTEN be rolled back?

No. LISTEN and UNLISTEN are bound to the session, not the current transaction. A rollback does not restore the previous listen state.

Does UNLISTEN close my database connection?

No. UNLISTEN only alters which channels deliver notifications to the session. The connection itself remains open and can execute further SQL.

How do I verify which channels I am listening on?

Query the pg_listening_channels() set-returning function in PostgreSQL 9.6 or later. It returns one row per active channel for the current session.