Skip to content

Fix .pgpass file to properly de-escape backslash escapes#1304

Open
veeceey wants to merge 1 commit intoMagicStack:masterfrom
veeceey:fix/issue-1249-pgpass-backslash-escapes
Open

Fix .pgpass file to properly de-escape backslash escapes#1304
veeceey wants to merge 1 commit intoMagicStack:masterfrom
veeceey:fix/issue-1249-pgpass-backslash-escapes

Conversation

@veeceey
Copy link

@veeceey veeceey commented Feb 8, 2026

Summary

  • Fixes incorrect handling of backslash escapes in .pgpass files
  • Properly de-escapes \: to : and \\ to \
  • Updates test to match PostgreSQL-compatible behavior

Issue

Fixes #1249

According to the PostgreSQL documentation, backslashes in .pgpass files serve only to escape backslashes and colons, and are not considered part of the value. However, asyncpg was leaving escaped values as-is, causing authentication failures.

For example, a .pgpass row of:

*:*:test\:db:test\\:password with 4\:K1

Should convey:

  • Database: test:db (not test\:db)
  • User: test\ (not test\\)
  • Password: password with 4:K1 (not password with 4\:K1)

Previously, asyncpg would keep the backslashes, causing authentication to fail with psql but not with asyncpg (or vice versa depending on which escaping was used).

Changes

  • Modified asyncpg/connect_utils.py to properly de-escape \:: and \\\
  • Updated test in tests/test_connect.py to expect de-escaped values

Test plan

  • Updated existing test case to verify de-escaping behavior
  • Test verifies that *:*:test\:db:test\\:password matches database test:db and user test\
  • The fix ensures compatibility with psql and standard PostgreSQL clients

This allows users to have special characters (colons and backslashes) in their database names, usernames, and passwords while maintaining compatibility with PostgreSQL's standard .pgpass file format.

According to PostgreSQL documentation, backslashes in .pgpass files
serve to escape backslashes and colons, and are not part of the value.
Previously, asyncpg left escaped values as-is (e.g., `4\:K1` stayed
`4\:K1` instead of becoming `4:K1`), which caused authentication
failures when passwords contained colons.

This fix properly de-escapes:
- `\:` becomes `:`
- `\\` becomes `\`

Fixes MagicStack#1249
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

.pgpass file support handles backslash escapes incorrectly; should de-escape values

1 participant