Documentation
¶
Overview ¶
Package pgxlisten provides higher level PostgreSQL LISTEN / NOTIFY tooling built on pgx.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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)
// ReconnectDelay configures the amount of time to wait before reconnecting in case the connection to the database
// is lost. If set to 0, the default of 1 minute is used. A negative value disables the timeout entirely.
ReconnectDelay time.Duration
// contains filtered or unexported fields
}
Listener connects to a PostgreSQL server, listens for notifications, and dispatches them to handlers based on channel.
func (*Listener) Listen ¶
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.
Source Files