SQL LISTEN

What is the SQL LISTEN command?

Subscribes the current PostgreSQL session to asynchronous notifications on a specified channel.

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 LISTEN: Supported: PostgreSQL, CockroachDB, YugabyteDB, EDB Advanced Server. Not Supported: MySQL, SQL Server, Oracle, SQLite, Snowflake, Redshift.

SQL LISTEN Full Explanation

LISTEN is a PostgreSQL session-level command that registers the current connection as a subscriber to one or more notification channels. Once registered, the backend delivers any NOTIFY messages sent on those channels to the client as asynchronous events. A LISTEN takes effect immediately and lasts until the session ends or an UNLISTEN command cancels it. LISTEN is transaction-scoped during execution (it is rolled back if the surrounding transaction aborts) but the subscription itself persists across subsequent transactions in that session. LISTEN has no performance cost when idle, because the server only wakes the client when a relevant NOTIFY is committed. Each notification carries an optional payload string and the process ID of the backend that sent it. LISTEN is useful for building pub-sub systems, cache invalidation hooks, real-time user interfaces, and any workflow that benefits from triggerless eventing. Caveats: LISTEN works only inside a single PostgreSQL cluster, is not forwarded by logical replication, and requires the client driver to poll or wait on the socket for notifications.

SQL LISTEN Syntax

LISTEN channel_name;
LISTEN *;  -- listen on all channels (PostgreSQL 16+)

SQL LISTEN Parameters

channel_name (identifier) - The name of the channel to subscribe to.
* (asterisk) - Special wildcard that subscribes to every channel (PostgreSQL 16+).

Example Queries Using SQL LISTEN

-- Basic usage
LISTEN orders_updated;

-- In another session
NOTIFY orders_updated, 'order_id=42';

-- Wildcard listen (PostgreSQL 16+)
LISTEN *;

-- Stop listening
UNLISTEN orders_updated;

Expected Output Using SQL LISTEN

When LISTEN runs, PostgreSQL replies with the command tag LISTEN
No rows are returned
Afterward, whenever a committed NOTIFY on the chosen channel occurs, the backend sends an asynchronous notification message that the client library can fetch (often via a callback or polling)

Use Cases with SQL LISTEN

Real-time cache invalidation after table changes
Chat or collaborative applications that broadcast events
Background workers waiting for jobs queued via NOTIFY
Microservices coordination without an external message broker
Alerting systems that react to database state changes

Common Mistakes with SQL LISTEN

Expecting notifications before the NOTIFY transaction commits
Forgetting to UNLISTEN, causing a buildup of idle listeners
Assuming the subscription survives reconnects or connection pool recycling
Quoting channel names unnecessarily (they are identifiers, not strings)
Using LISTEN in databases other than PostgreSQL

First Introduced In

PostgreSQL 6.4

Frequently Asked Questions

What is the difference between LISTEN and NOTIFY?

LISTEN subscribes a session to a channel, while NOTIFY publishes a message to that channel. Both together form PostgreSQL's built-in pub-sub mechanism.

Does LISTEN block the session?

No. The command itself returns immediately. After that, the backend delivers notifications asynchronously while the session is idle or between statements.

How do I receive the notification in my application code?

Most PostgreSQL client libraries expose an event loop, callback, or polling function (e.g., `pg_connection.notifies` in libpq) that returns pending notifications along with the channel name, payload, and sender PID.

Can LISTEN be used inside PL/pgSQL functions?

Yes, but only in AUTONOMOUS transactions or when the function is called directly. A long-running function cannot process incoming notifications while executing.