PostgreSQL LISTEN/NOTIFY Events Example

1. Introduction

In modern applications, real-time responsiveness is no longer optional. For developers working with Java and PostgreSQL, one of the most efficient ways to build reactive systems is by using LISTEN/NOTIFY. This feature allows database sessions to communicate instantly, eliminating the need for inefficient polling. In this article, we’ll explore how to implement Listen/Notify events in PostgreSQL so your Java applications can react immediately when data changes—ideal for chat systems, live dashboards, collaborative tools, and more.

PostgreSQL LISTEN/NOTIFY mechanism lets database sessions send asynchronous notifications to other sessions without the overhead of repeated queries. By combining this with Java, you can build highly responsive, event-driven systems without complex infrastructure or heavy message brokers.

In this article, we will explore how to implement PostgreSQL Listen/Notify events using two approaches:

1. The official PostgreSQL JDBC driver.
2. The alternative PGJDBC-NG driver.

We’ll cover the fundamentals of LISTEN/NOTIFY, demonstrate how to send notifications, and show you how to subscribe and react to them in Java code.

2. What Are LISTEN and NOTIFY?

LISTEN and NOTIFY are PostgreSQL commands for sending and receiving lightweight, asynchronous event notifications between sessions connected to the same database.

• NOTIFY sends a message to all clients that are currently listening on a particular channel.
• LISTEN registers interest in a channel so that the session will receive any notifications sent on it.

Key characteristics:

• Asynchronous: Notifications are delivered without requiring a query loop.
• Lightweight: They are not intended to carry large payloads—just small messages (up to about 8KB).
• Session-based: A LISTEN registration lasts until the session ends or an explicit UNLISTEN is issued.
• Transaction-aware: Notifications are sent only when the transaction that issued NOTIFY commits.

Example in SQL:

-- Session 1
LISTEN my_channel;

-- Session 2
NOTIFY my_channel, 'Data updated!';

If Session 1 is listening, it immediately receives the "Data updated!" message once Session 2 commits the transaction.

When to use LISTEN/NOTIFY:

• Cache invalidation.
• Triggering background processing.
• Coordinating between multiple application instances.
• Notifying real-time UIs when underlying data changes.

This makes it a great fit for scenarios, where you want Java code to react to changes in PostgreSQL without wasteful polling.

3. Raising Notifications With JDBC

Sending a notification from Java is straightforward because NOTIFY is just an SQL command. You can execute it using standard JDBC.

Example: Sending a NOTIFY from Java

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;

public class NotifyExample {
    public static void main(String[] args) throws Exception {
        String url = "jdbc:postgresql://localhost:5432/mydb";
        String user = "myuser";
        String password = "mypassword";

        try (Connection conn = DriverManager.getConnection(url, user, password)) {
            try (PreparedStatement stmt = conn.prepareStatement(
                    "NOTIFY my_channel, ?")) {
                stmt.setString(1, "Hello from Java!");
                stmt.execute();
            }
        }
    }
}

How it works:

1. We connect to the database with standard JDBC.
2. We execute NOTIFY my_channel, 'payload'.
3. Any session listening to my_channel will get the message.

Best practices when sending notifications:

• Keep payloads small and just enough to describe the event.
• If you need to send complex data, consider passing an ID and having the listener fetch the details.
• Remember that notifications are delivered only after transaction commit. If you send a NOTIFY and then roll back, no notification is sent.

4. Listening With the Official JDBC Drivers

Listening for notifications in Java is trickier than sending them because PostgreSQL delivers notifications asynchronously. The official JDBC driver supports this through its PGConnection interface, which exposes methods for retrieving notifications.

However, the driver does not automatically “push” notifications to your code—you must poll for them periodically.

Example: Listening With JDBC

import org.postgresql.PGConnection;
import org.postgresql.PGNotification;

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.Statement;

public class ListenExample {
    public static void main(String[] args) throws Exception {
        String url = "jdbc:postgresql://localhost:5432/mydb";
        String user = "myuser";
        String password = "mypassword";

        try (Connection conn = DriverManager.getConnection(url, user, password)) {
            PGConnection pgConn = conn.unwrap(PGConnection.class);

            try (Statement stmt = conn.createStatement()) {
                stmt.execute("LISTEN my_channel");
            }

            System.out.println("Waiting for notifications...");

            while (true) {
                // Wait for notifications
                PGNotification[] notifications = pgConn.getNotifications(5000); // 5 seconds timeout
                if (notifications != null) {
                    for (PGNotification notification : notifications) {
                        System.out.printf(
                                "Received on channel %s: %s%n",
                                notification.getName(),
                                notification.getParameter()
                        );
                    }
                }
            }
        }
    }
}

Key points:

• We call LISTEN my_channel once to start listening.
• We repeatedly call getNotifications() to retrieve new events.
• The call can be blocking or have a timeout.

Advantages:

• Uses the official, widely supported driver.
• No external dependencies.

Limitations:

• Still requires polling (though at the socket level, not the database query level).
• Requires dedicated threads if you want continuous listening without blocking other work.

If you want a more reactive approach without writing your own polling loop, the PGJDBC-NG driver offers native listener callbacks.

5. Listening with PGJDBC-NG

PGJDBC-NG is an alternative JDBC driver for PostgreSQL with additional features, including a built-in, event-driven mechanism for LISTEN/NOTIFY. Instead of polling, you can register listeners and receive notifications asynchronously through callbacks.

Why choose PGJDBC-NG for java postgresql listen notify events?

• Non-blocking I/O with Netty under the hood.
• Direct notification callbacks (no manual polling loop).
• Suitable for highly concurrent, reactive applications.

Example: Listening with PGJDBC-NG

import com.impossibl.postgres.api.jdbc.PGConnection;
import com.impossibl.postgres.api.jdbc.PGNotificationListener;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.Statement;

public class PGJDBCNGListenExample {
    public static void main(String[] args) throws Exception {
        String url = "jdbc:pgsql://localhost:5432/mydb";
        String user = "myuser";
        String password = "mypassword";

        try (Connection conn = DriverManager.getConnection(url, user, password)) {
            PGConnection pgConn = conn.unwrap(PGConnection.class);

            // Register a listener for notifications
            pgConn.addNotificationListener(new PGNotificationListener() {
                @Override
                public void notification(int processId, String channelName, String payload) {
                    System.out.printf("Process %d sent %s: %s%n", processId, channelName, payload);
                }
            });

            try (Statement stmt = conn.createStatement()) {
                stmt.execute("LISTEN my_channel");
            }

            System.out.println("Listening for notifications...");

            // Keep the application alive
            Thread.sleep(Long.MAX_VALUE);
        }
    }
}

How it works:

1. Connect to PostgreSQL using jdbc:pgsql:// instead of the standard JDBC URL.
2. Unwrap the connection to PGConnection from the PGJDBC-NG API.
3. Add a PGNotificationListener to handle events.
4. Call LISTEN on your channel.
5. The driver automatically invokes your listener when notifications arrive.

Advantages:

• True event-driven handling (no polling loop).
• Cleaner code for long-running services.
• Better fit for reactive architectures.

Limitations:

• Requires switching to a non-standard JDBC driver.
• PGJDBC-NG is less widely adopted than the official driver, so community support may be smaller.

6. Conclusion

The PostgreSQL LISTEN/NOTIFY mechanism is a powerful way to implement real-time event-driven architectures without external message brokers. By leveraging it in Java, you can efficiently respond to database changes with minimal overhead.

We covered two ways to integrate java postgresql listen notify events:

1. Official JDBC driver: Standard, widely supported, but requires manual polling for notifications.
2. PGJDBC-NG driver: Offers built-in asynchronous callbacks, making it more suitable for reactive systems.

When to use the official JDBC driver:

• You already use it elsewhere in your application.
• Polling fits your architecture and performance requirements.

When to use PGJDBC-NG:

• You need fully event-driven, non-blocking notification handling.
• You’re building a reactive or highly concurrent system.

By adopting either approach, you can replace inefficient polling with lightweight, real-time database event handling, keeping your applications fast, responsive, and ready for modern user expectations.

Do you want to know how to develop your skillset to become a Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

To get you started we give you our best selling eBooks for FREE!

1. JPA Mini Book

2. JVM Troubleshooting Guide

3. JUnit Tutorial for Unit Testing

4. Java Annotations Tutorial

5. Java Interview Questions

6. Spring Interview Questions

7. Android UI Design

and many more ....

I agree to the Terms and Privacy Policy

Sign up

Thank you!

We will contact you soon.