iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Reliable uptime monitoring needs more than one green health check. Separate four questions: Is the API process alive? Should it receive traffic? Is PostgreSQL accepting connections? Can the application complete a small database operation through its real request path? Each signal covers a different failure boundary, so one should not stand in for the others.
What the four signals tell you
| Signal | Question answered | Best fit |
|---|---|---|
| API liveness | Is the API process responding? | Detecting a process that is stopped or unresponsive |
| API readiness | Should this instance receive traffic now? | Traffic routing when required dependencies are unavailable |
| PostgreSQL connection status | Is the database server accepting connections? | Checking database reachability and connection acceptance |
| Application-level database operation | Can the application complete a bounded database operation with the permissions and schema it needs? | Testing a specific application dependency path |
These are complementary checks, not four names for the same condition. A process can be alive while unable to serve requests. A database can accept connections while the application’s role, schema, or query path is broken.
1. Check API liveness without making it a dependency test
Liveness should answer a narrow question: is the API process running and responding? Prometheus documents /-/healthy as a health endpoint, while PostgREST’s /live endpoint checks whether PostgREST is running on its configured port. See the Prometheus Management API documentation and PostgREST 12.2 Admin Server documentation.
Do not make liveness depend on PostgreSQL if the purpose is to establish whether the process itself is alive. Otherwise, a database outage can make a healthy API process appear dead, potentially prompting unnecessary restarts rather than identifying the dependency problem.
#1 Best Overall
2. Use readiness to decide whether traffic should reach the instance
Readiness answers a routing question: should this instance receive requests now? Unlike liveness, it can include dependencies required to serve traffic. PostgREST 12.2’s /ready check covers its connection pool and schema cache in addition to liveness; it returns HTTP 200 when those checks are good and 503 when they are not, according to its Admin Server documentation.
Choose readiness conditions based on what the service must have to handle real requests. Keep the response semantics stable: a healthy response should mean the instance is suitable for traffic, while an unhealthy response should mean it is not. A routing check and an alerting check may use the same endpoint, but they have different consequences and should be designed accordingly.
Rank #2
3. Check whether PostgreSQL accepts connections
PostgreSQL’s pg_isready checks connection status; it is not a full application request-path test. PostgreSQL 16 documents these exit statuses:
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →| Exit status | Meaning |
|---|---|
| 0 | The server is accepting connections |
| 1 | The server is rejecting connections |
| 2 | No response was received |
| 3 | No attempt was made, for example because parameters were invalid |
The pg_isready documentation says correct user, password, or database values are not required to obtain server status. Incorrect values can still cause the server to log a failed connection attempt. Configure the check with that behavior in mind, and do not interpret a successful status as proof that the application’s credentials or database operation work.
4. Test a bounded operation through the application’s database path
When you need to know whether the application can use PostgreSQL as its requests do, add a small, bounded operation through the relevant connection path. It should exercise the role, permissions, and schema the application actually depends on—not just establish that a database port answers.
The exact query or endpoint depends on the application; there is no universal operation prescribed by the cited documentation. Keep the work cheap and time-bounded, avoid writes or other side effects unless they are deliberately made safe, and return only a concise status. Do not expose credentials, SQL errors, schema names, or other sensitive implementation details in a public health response.
How to combine the checks in practice
- Define the decision for each signal. Decide whether it is meant to detect a dead process, keep an unready instance out of rotation, report database connection status, or verify a particular application operation.
- Keep liveness independent of dependencies. Make it a fast process-level check rather than a proxy for overall system health.
- Put required service dependencies in readiness. Choose checks that establish whether the instance can safely receive traffic, and define clearly what HTTP status means for your routing system.
- Use
pg_isreadyfor the database server’s connection state. Preserve its distinct results for accepting, rejecting, no response, and no attempt instead of reducing every outcome to the same unexplained status. - Add an application-path check only for the question it answers. Use the same relevant credentials, permissions, and schema path as real requests, with bounded work and a timeout.
- Compare implementations by coverage and consequences. Check which layer each one covers, which failure states it distinguishes, its cost and timeout, and whether its result is appropriate for traffic routing, alerting, or both. These are design criteria, not performance benchmarks.
What to investigate when a check fails
A health endpoint is a compact status signal, not a diagnosis. To answer the operator’s question, “What is the system doing right now?”, inspect database and host activity rather than inferring a root cause from one failure response. PostgreSQL’s Monitoring Database Activity chapter describes statistics views including pg_stat_activity, pg_stat_replication, and pg_stat_database, and also points to Unix tools such as ps, top, iostat, and vmstat.
Recommended Free Tools
Start with the signal that failed: a liveness failure points toward the API process or its endpoint; a readiness failure points to a condition the service requires for traffic; a pg_isready result distinguishes server connection states; and a failed application operation calls for checking the relevant connection, role permissions, schema, and operation path. Use monitoring data to narrow the cause rather than returning sensitive diagnostic details to callers.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
