Fixes #1340.

Root cause

WriteBuffer.write_str(), which builds the startup packet, lives in the vendored pgproto submodule and is declared as:

cdef write_str(self, str string, str encoding):

That str-typed parameter rejects str subclasses at the C level — enum.StrEnum members, or third-party string-like values like tomlkit.items.String — even though isinstance(x, str) is True for them (confirmed in the issue). When one of these reaches the startup packet via user, database, or a server_settings key/value, building it raises a TypeError deep inside the compiled protocol layer. That in turn triggers a second failure — AttributeError: 'Protocol' object has no attribute '_on_error' — while trying to report the original error, which is why the issue's traceback shows the confusing AttributeError rather than the real TypeError.

The actual type check lives in the separate MagicStack/py-pgproto repo (asyncpg's git submodule), so I fixed this at the asyncpg call site instead — coercing user, database, and server_settings keys/values to plain str right after they're resolved/validated in _parse_connect_dsn_and_args(), before they ever reach the protocol layer. This keeps the fix in one repo and doesn't require asyncpg to bump its pinned pgproto submodule version.

host doesn't need the same treatment — it's consumed for the socket connection itself, not written via write_str() in the startup packet, and the issue's own repro confirms host=-only StrEnum values work fine (the crash only happens once user is also a StrEnum).

Verification

I built the Cython extension locally (pip install --no-build-isolation -e ., submodule initialized) and reproduced the exact reported failure end-to-end against a real PostgreSQL server (Docker, postgres:16-alpine):

• Before the fix: asyncpg.connect(user=SomeStrEnum.USER, ...) → AttributeError: 'Protocol' object has no attribute '_on_error', matching the issue's traceback exactly.
• After the fix: the same call succeeds, SELECT current_user round-trips correctly.

I also verified with a minimal in-process fake TCP server (accepts the connection, replies N to the SSL negotiation probe, doesn't require a real PostgreSQL) that the client-side startup-packet construction itself succeeds post-fix (67-byte packet sent, then a clean timeout waiting on the fake server — no more TypeError/AttributeError).

Changes

• asyncpg/connect_utils.py: coerce user/database to str right after their None-checks in _parse_connect_dsn_and_args(); coerce server_settings dict keys/values to str right after its existing isinstance validation.
• tests/test_connect.py: added test_connect_params_coerces_str_subclasses, which passes str-subclass user/database/server_settings values (custom subclasses, not relying on enum.StrEnum) and asserts type(...) is str on the resulting _ConnectionParameters — confirmed this fails without the fix (AssertionError: <class '...SUser'> != <class 'str'>) and passes with it.

Testing

• python -m unittest tests.test_connect.TestConnectParams — all 12 tests pass (this class unit-tests _parse_connect_dsn_and_args() directly, no live cluster needed).
• flake8 on both changed files — clean (the one pre-existing E731 in connect_utils.py is on an unrelated, untouched line).
• The full tests.test_connect module also spins up a local Postgres cluster via pg_config/initdb for other test classes, which isn't available in my environment — those failures are unrelated to this change (I confirmed the affected functionality directly against a real Dockerized PostgreSQL instead, as described above).

🤖 Generated with Claude Code