Health and readiness
Separate artifact preflight, process liveness, protocol health, and workload readiness.
A production probe answers one question. Do not use a static executable check as proof that a running database can serve traffic.
Probe layers
| Layer | Check | Meaning |
|---|---|---|
| Artifact | nyxdb --capabilities | Build and runtime capability inventory |
| Deployment preflight | nyxdb --readiness | Static compiled-role capability gate for this executable |
| Process | Supervisor/container state | Process exists and has not exited |
| Listener | TCP connection to configured host/port | Socket accepts a connection |
| Protocol | Wire OP_PING | Event loop and protocol handler respond |
| Query | SELECT 1 | Admission, bind, execute, and result path respond |
| Workload | Representative read and optional canary write/read | Required catalog, storage, and policy are usable |
--readiness exits after evaluating compiled service-capability metadata. It
does not parse or validate startup flags, files, storage, the environment, or a
recently started server.
Startup gate
Keep traffic closed while:
- the process creates/opens the data directory;
- catalog and WAL recovery run;
- checkpoints and parts are validated;
- the listener reaches ready state;
OP_PINGsucceeds; and- a representative query returns the expected schema/result.
Start the readiness grace period from process launch and size it from measured recovery time on production-scale data.
Liveness policy
Use protocol ping as the normal live check. It is intentionally lighter than a query and remains independent of query admission. Require several consecutive failures before restart so a transient scheduler or I/O stall does not create a restart loop.
An automatic restart is appropriate only when:
- the process has exited;
- protocol ping is persistently unavailable; or
- a documented fatal condition cannot recover in place.
High query latency, a full admission queue, or governor BLOCK is an incident to diagnose; a blind restart may discard evidence and add recovery load.
Readiness policy
Remove the process from service when the workload contract is not met even if it is live. Examples include:
- recovery has not completed;
- query admission is persistently saturated;
- the memory governor remains at BLOCK;
- required storage is unavailable;
- a required transform is terminal; or
- the live probe passes but representative queries fail.
Because the current deployment is single-node, marking the only process unready means planned unavailability. There is no automatic peer to receive traffic.
Shutdown gate
On SIGTERM:
- stop opening new application work;
- let in-flight operations reach their documented boundary;
- wait for the process to exit cleanly;
- verify the supervisor did not escalate to
SIGKILL; and - preserve shutdown logs with the deployment record.
After restart, run the full startup gate again. A successful TCP connect alone does not prove storage recovery or query readiness.