Add address hint to connect errors when PostgreSQL is unreachable

[aryansk]

What

Fixes #1342 — when a connection attempt fails, the raised error now names the address that was tried, so a PostgreSQL server listening on a different port is distinguishable from a server that is not running.

Why

ConnectionRefusedError is byte-for-byte identical whether the server is down or simply listening elsewhere. The classic failure mode is connect(port=5433) against a server on 5432, or a wrong hostname — the error message gives no clue which address was actually attempted, and users assume PostgreSQL is broken instead of checking the port.

How

_connect() keeps the last attempted addr alongside the last error and, when re-raising, appends a hint:

[Errno 61] Connect call failed ('127.0.0.1', 5433) - verify that PostgreSQL is running and listening on 127.0.0.1:5433

The original exception is preserved as __cause__ and the same exception type is re-raised, so existing except OSError / except ConnectionRefusedError handling is unaffected. The TargetServerAttributeNotMatched branch (no OSError at all) is unchanged. Unix socket paths are formatted as path/.s.PGSQL.port, matching asyncpg's convention.

Tests

Added TestConnectErrorHint in tests/test_connect.py:

• test_connect_error_includes_address_hint — a refused TCP connection reports 127.0.0.1:5432 in the message, and __cause__ is the original error (fails before the fix: message lacks the address).
• test_connect_error_hint_for_unix_socket — a missing socket reports /var/run/postgresql/.s.PGSQL.5432 (fails before: message lacks the socket).

Both use unittest.mock.patch.object(connect_utils, '_connect_addr', ...) so they run without a live server. Full tests/test_connect.py suite passes.

🤖 Generated with Codebuff