pgxlisten

Documentation

Overview

Package pgxlisten provides higher level PostgreSQL LISTEN / NOTIFY tooling built on pgx.

Index

• type BacklogHandler
• type Handler
• type HandlerFunc
  • func (f HandlerFunc) HandleNotification(ctx context.Context, notification *pgconn.Notification, conn *pgx.Conn) error
• type Listener
  • func (l *Listener) Handle(channel string, handler Handler)
  • func (l *Listener) Listen(ctx context.Context) error

Types

type BacklogHandler

type BacklogHandler interface {
	// HandleBacklog is synchronously called by Listener at the beginning of Listen at process any previously queued
	// messages or jobs. If processing can take any significant amount of time this method should process it
	// asynchronously (e.g. via goroutine with a different database connection). If an error is returned it will be logged
	// with the Listener.LogError function.
	HandleBacklog(ctx context.Context, channel string, conn *pgx.Conn) error
}

BacklogHandler is an optional interface that can be implemented by a Handler to process unhandled events that occurred before the Listener started. For example, a simple pattern is to insert jobs into a table and to send a notification of the new work. When jobs are enqueued but the Listener is not running then HandleBacklog can read from that table and handle all jobs.

To ensure that no notifications are lost the Listener starts listening before handling any backlog. This means it is possible for HandleBacklog to handle a notification and for HandleNotification still to be called. A Handler must be prepared for this situation when it is also a BacklogHandler.

type Handler

type Handler interface {
	// HandleNotification is synchronously called by Listener to handle a notification. If processing the notification can
	// take any significant amount of time this method should process it asynchronously (e.g. via goroutine with a
	// different database connection). If an error is returned it will be logged with the Listener.LogError function.
	HandleNotification(ctx context.Context, notification *pgconn.Notification, conn *pgx.Conn) error
}

Handler is the interface by which notifications are handled.

type HandlerFunc

type HandlerFunc func(ctx context.Context, notification *pgconn.Notification, conn *pgx.Conn) error

HandlerFunc is an adapter to allow use of a function as a Handler.

func (HandlerFunc) HandleNotification

func (f HandlerFunc) HandleNotification(ctx context.Context, notification *pgconn.Notification, conn *pgx.Conn) error

HandleNotification calls f(ctx, notificaton, conn).

type Listener

type Listener struct {
	// Connect establishes or otherwise gets a connection for the exclusive use of the Listener. Listener takes
	// responsibility for closing any connection it receives. Connect is required.
	Connect func(ctx context.Context) (*pgx.Conn, error)

	// LogError is called by Listen when a non-fatal error occurs. Most errors are non-fatal. For example, a database
	// connection failure is considered non-fatal as it may be due to a temporary outage and the connection should be
	// attempted again later. LogError is optional.
	LogError func(context.Context, error)
	// contains filtered or unexported fields
}

Listener connects to a PostgreSQL server, listens for notifications, and dispatches them to handlers based on channel.

func (*Listener) Handle

func (l *Listener) Handle(channel string, handler Handler)

Handle sets the handler for notifications sent to channel.

func (*Listener) Listen

func (l *Listener) Listen(ctx context.Context) error

Listen listens for and handles notifications. It will only return when ctx is cancelled or a fatal error occurs. Because Listen is intended to continue running even when there is a network or database outage most errors are not considered fatal. For example, if connecting to the database fails it will wait a while and try to reconnect.