pg-status is an efficient microservice designed to monitor and assess the status of PostgreSQL hosts. This lightweight application operates as a sidecar, allowing seamless integration alongside your main application without introducing noticeable overhead. It provides rapid insights into the state of your PostgreSQL database instances, determining which ones are active, identifying the master node, tracking replicas, and measuring the replication lag for each replica.

Key Features

• Instant Status Detection: Quickly ascertain the status of PostgreSQL hosts, including their availability and replication status.
• Background Polling: Conducts background checks on database hosts at configurable intervals, ensuring up-to-date status information.
• Memory-based Responses: Serves data directly from memory for fast responses, making it suitable for frequent queries.
• Flexible HTTP Interface: Access the application's functionality via a robust HTTP interface that supports both plain text and JSON responses.

API Overview

pg-status exposes multiple HTTP endpoints to retrieve detailed information about PostgreSQL hosts. Key endpoints include:

• GET /master: Retrieve the current master node.
• GET /replica: Get a replica using round-robin selection, with optional lag constraints and freshness checks.
• GET /hosts: List all monitored hosts along with their status information, including lag metrics.

Usage Example

To fetch the current master host:

GET /master

The response will indicate the master host if one is available, or return null if none are found.

For selecting a healthy replica:

GET /replica?lag_ms=5000&min_lsn=0/3000060

This command retrieves an active replica that meets specified lag and LSN parameters, ensuring efficient database interactions.

Configuration

pg-status can be easily configured using environment variables for database connection settings, polling intervals, and thresholds for monitoring performance, such as acceptable replication lag. This adaptability allows it to integrate smoothly into various deployment environments.

Performance Efficiency

With a memory footprint of 9 MiB, pg-status is optimized for performance, achieving impressive throughput depending on the specific API used. For instance:

• On a 1 CPU setup, it can handle approximately 8600-9000 requests per second.

Further Reading

To dive deeper into why pg-status was developed and its role in solving PostgreSQL Master/Replica discovery issues, refer to the detailed article on PostgreSQL Master/Replica Discovery Problems.

For installation details and performance reports, please consult the documentation and performance reports.

pg-status is an effective tool for those looking to enhance their PostgreSQL database monitoring through a simple and efficient sidecar service.