Annotation Interface PostgresChangeNotification


@Documented @Retention(RUNTIME) @Target(METHOD) public @interface PostgresChangeNotification
Declares the PostgreSQL notification channel for a method annotated with ChangeListener.

Use database migrations to install the notification function and triggers for the entity's table. Configure the triggers with the channel declared by this annotation and the entity's primary-key column names as stored in PostgreSQL's catalogs. For development and tests using schema creation, micronaut.data.jdbc.notifications.postgres.schema-generate=true installs the function and triggers alongside tables generated with CREATE or CREATE_DROP.

Notifications are matched by channel and mapped table name. If the entity mapping specifies a schema, that schema must also match. Without an explicit schema, tables with the same name in different schemas can trigger the same listener when they publish to its channel. Entity loading without an explicit schema follows the datasource's schema search path and can therefore load from a different schema than the notification's source. Specify a schema or use separate channels to avoid this ambiguity.

Notifications describe table changes and include the operation and the old or new primary keys, as appropriate for that operation. Inserted and updated entities are loaded by primary key before the listener is invoked. The loaded entity reflects the database state at the time of loading, which may include changes made after the notification was sent. If the row no longer exists, the event contains no entity.

Payloads are unauthenticated hints: any role that can connect to the database can publish on a channel without permission to modify the reported table. Matching the channel, table, and keys does not verify the sender or the reported change. Deletes are delivered without checking whether the row still exists. Re-read current database state before taking irreversible action on delete metadata, and restrict database CONNECT privileges to trusted roles. Queue limits bound waiting work but do not rate-limit notifications or refreshes.

PostgreSQL notifications use one dedicated, non-pooled connection per participating datasource, shared by all listener methods using that datasource. Each listener has a dedicated worker and bounded queue for sequential entity loading and callback execution. Different listeners can run concurrently. After each successful reconnection, an INVALIDATE event replaces waiting callbacks so listeners can reload data that may have changed while disconnected.

If the configured recovery retry limit is exhausted, each affected listener receives ChangeOperation.TERMINATED after any running callback finishes. Waiting notifications are discarded. Applications should stop using notification-backed caches and fall back to database reads or another consistency mechanism.

Since:
5.3.0
  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    The exact, case-sensitive channel passed to PostgreSQL's pg_notify function.
  • Element Details

    • channel

      String channel
      The exact, case-sensitive channel passed to PostgreSQL's pg_notify function. Supply the channel name without surrounding SQL identifier quotes. The name must not be blank or contain a NUL character, and its UTF-8 encoding must be at most 63 bytes long. Property placeholders such as ${app.channel} are supported. Literal names are validated during compilation; resolved names are validated during startup before subscribing or installing notification triggers. Missing properties and invalid resolved names fail startup. The resolved name is used unchanged and must match the channel used by migration-managed triggers.
      Returns:
      The notification channel.