dolthub / dolthub/dolt

sql-server: provide a machine-readable startup-complete / readiness signal (--wait-for-ready / readiness file / sd_notify / documented log token)

Open
#11,261 1 comment 0 reactions 0 assignees View on GitHub
customer issue enhancement sql server
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.