Correct local Postgres diagnostics and help

[sdairs]

Summary

• use Postgres-specific validation and runtime errors instead of ClickHouse execution errors
• provide sanitized, platform-aware Docker constructor and ping guidance for Desktop/Engine, permissions, contexts, rootless Docker, and DOCKER_HOST
• correct Postgres start help for managed labels and omitted versus explicit ports
• restore actionable psql launch context and remove redundant Postgres error prefixes
• add exact help, fake-socket, Docker classification, and missing-psql subprocess coverage

Tests

• cargo fmt --all --check
• cargo build -p clickhousectl
• cargo check -p clickhousectl --all-targets
• cargo test -p clickhousectl
• cargo clippy -p clickhousectl --all-targets -- -D warnings
• bash -n scripts/test-postgres-integration.sh
• direct CLI verification of the integration-script port-zero and unsupported-version diagnostics

The full Docker-backed scripts/test-postgres-integration.sh was not run because the configured OrbStack socket at ~/.orbstack/run/docker.sock is unavailable.

Closes #465

[sdairs]

Carry-over review from PR #509 (old PR for #465). This PR has genuinely better engineering than #509 (sanitized Docker failure causes with no-leak tests vs #509 echoing raw bollard text/paths; structured io::ErrorKind/source-chain classification; single Error::Postgres variant). But it carries over one directly violated sdairs review comment and several defects. Required:

1. Remove the data-path help sentence sdairs explicitly rejected on Correct local Postgres diagnostics and help #509. Correct local Postgres diagnostics and help #509 had a pending inline review comment from sdairs on crates/clickhousectl/src/local/cli.rs (start help hunk, on the data-path line): "unnecessary - does not assist in usage of the cli", followed by his issue comment: "Addressed the pending feedback in 86dde3f: removed the non-actionable data-path/bind-mount sentence from local postgres start --help and updated its exact snapshot." In this PR that exact sentence is restored at crates/clickhousectl/src/local/cli.rs:~463 ("Data persists at .clickhouse/servers/-pg/data/ and is bind-mounted into the container.") — and worse, pinned in a test (tests/local_postgres_start_validation_test.rs:~228, postgres_start_help_matches_managed_runtime_behavior), so removing it later breaks the suite. Tension: issue Correct local Postgres diagnostics and help #465's acceptance criteria literally say "Help documents the versioned data path", so if the sentence is kept, state explicitly in the PR description that the earlier review position is being withdrawn; otherwise delete it from help and from the pinned snapshot.

2. Restore psql diagnostic context. exec_host_psql (postgres.rs:~731) now returns Error::Postgres(err.to_string()), so a user with no psql installed sees Postgres error: No such file or directory (os error 2) with no mention of psql. Correct local Postgres diagnostics and help #509 wrapped it ("could not execute psql: ...") and had a subprocess test for the missing-psql case. Add the wrapper and the test.

3. Fix the Windows socket/named-pipe contradiction (open Cursor Bugbot finding here). docker_failure_cause (docker.rs:~157-177) describes MissingSocket/PermissionDenied as socket failures on every platform while the Windows docker_guidance (docker.rs:~188) says named-pipe permissions — contradictory on Windows; and assert_platform_guidance in tests/local_docker_diagnostics_test.rs:~24-44 asserts "socket" on all platforms, so the test cannot catch it.

4. Update scripts/test-postgres-integration.sh expectations. This PR changes the diagnostics this script greps (--port 0 wording via the stack base's clap range, not supported version wording) and leaves the edge-cases suite red. (Inherited from Validate local Postgres start options #547, but this is the diagnostics PR and should carry the script update.)

5. Minor: message composition produces redundant "Postgres error: Postgres port 5432 is already in use" and "Postgres error: Postgres '' ... is gone" — pinned verbatim in tests; decide acceptable wording. HttpStatus/TimedOut classification branches have no test coverage. --port 0 handling in resolve_port is dead at the CLI layer (clap catches it first) — remove or keep for the API boundary.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 621ab59. Configure here.}

[cursor]

Docker errors misclassified as missing socket

Low Severity

The Docker connect fallback treats any error-chain text containing not found as MissingSocket. A TCP DOCKER_HOST with a bad hostname typically surfaces glibc's Name or service not found, so ping failures are reported as a missing Docker socket and the platform guidance then talks about sockets instead of the host lookup.

 

^{Reviewed by Cursor Bugbot for commit 621ab59. Configure here.}