sql-server: provide a machine-readable startup-complete / readiness signal (--wait-for-ready / readiness file / sd_notify / documented log token)
- Dominant language
- Go
- Stars
- 24.4k
- Forks
- 873
- Avg merge
- 1d 5h
- Merged PRs (30d)
- 108
Description
**Background — an orchestrator's need.** We run `dolt sql-server` as a supervised, long-lived data plane and need to gate dependent work on "the server is actually ready to serve queries." Today the only sanctioned readiness checks are client-side polling: either a TCP connect (which #8131 showed gives false-ready — the port is open before the server can serve, yielding "Lost connection during query") or a repeated `dolt sql -q "select 1"` against the bound port. Both are races: a probe loop can't distinguish *not started yet* from *loading a large database* from *serving*, and the timeout has to be guessed (startup time scales with DB size and host load, as the #8131 thread notes).
**What exists today.**
- go-mysql-server logs a stable line `Server ready. Accepting connections.` at the readiness point, but it's undocumented, lives in a dependency, and isn't promised as a contract.
- The metrics HTTP listener (when `metrics.port` is set) exposes only `/metrics`; there is no `/readyz`.
- #7428 ("health and readiness checks") and #8131 both resolved with "poll with a real query" — there is no server-emitted ready signal.
**Proposal.** Provide one reliable, documented "server is serving" signal that an external supervisor can wait on without a polling race.
**Design options (≥2):**
1. **Formalize the existing log token (cheapest).** Document `Server ready. Accepting connections.` as a stable, supported readiness marker (and guarantee it's emitted to stdout/log before the listener accepts), so supervisors can wait on the log line. Low effort; no new surface.
2. **`--ready-file ` / `--wait-for-ready`.** Have sql-server atomically create/touch a readiness file (or write a pipe/fd passed in) once the listener is accepting connections; orchestrators wait on the file. Foreground-friendly and language-agnostic.
3. **sd_notify (`Type=notify`).** Emit `READY=1` via `$NOTIFY_SOCKET` when serving, enabling first-class `systemd` readiness without a wrapper. Natural fit for the documented systemd/k8s deployments.
4. **`/readyz` on the metrics listener.** Add a readiness endpoint alongside `/metrics` returning 200 only once the engine is accepting connections — reuses the existing HTTP server and aligns with the k8s `readinessProbe` ask from #7428.
We'd be happy with any one of these; option 1 alone would remove most of the race for us. Filing as a feature request — thanks for considering it.
---
_Filed from a downstream orchestrator (Gas City) that manages the `dolt sql-server` lifecycle; verified against current `dolthub/dolt` source and the live `sql-server --help`._
Contributor guide
No contributing guide indexed for this repository
Research direction
Start at the dolt sql-server entry point and inspect the existing `Server ready. Accepting connections.` log path and metrics HTTP listener. Compare the proposed log, readiness-file, sd_notify, and `/readyz` signals, then define one supported behavior and its tests. Done means an external supervisor has a documented, reliable indication that the server is ready to serve queries.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go, sql
- Domain
- backend, databases, observability
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100