Enable .pgpass support for SSH tunnel connections

[DiegoDAF]

Summary

This PR enables PostgreSQL's .pgpass file to work seamlessly with SSH tunnel connections. Previously, when using --ssh-tunnel, the .pgpass file was not consulted because pgcli was connecting to 127.0.0.1 instead of the original database hostname.

Problem

When using SSH tunnels, the connection flow was:

1. User specifies: --ssh-tunnel user@bastion --host production.db.com
2. SSH tunnel created: 127.0.0.1:random_port → production.db.com:5432
3. pgcli connects to: 127.0.0.1:random_port
4. .pgpass lookup fails (looking for 127.0.0.1 instead of production.db.com)

Solution

Use PostgreSQL's host/hostaddr parameter separation:

• host: Original database hostname (for .pgpass lookup and SSL verification)
• hostaddr: Actual connection endpoint 127.0.0.1 (SSH tunnel local port)

Changes

Core Functionality

• Modified connect() to preserve original host and use hostaddr for tunnel
• Updated connect_uri() to pass DSN parameter for proper .pgpass handling
• Modified pgexecute.py to preserve hostaddr when using DSN connections

SSH Tunnel Enhancements

• Added ssh_config_file: Use ~/.ssh/config for host settings
• Added allow_agent: Enable SSH agent for authentication
• Set compression: False: Better performance for database connections

Benefits

✅ .pgpass file now works with SSH tunnels
✅ No manual password entry needed
✅ Standard PostgreSQL authentication flow
✅ SSL certificate verification uses correct hostname
✅ Maintains all existing functionality

Example Usage

# Setup .pgpass file
echo "production.db.example.com:5432:mydb:dbuser:secret_password" >> ~/.pgpass
chmod 600 ~/.pgpass

# Connect via SSH tunnel - password read from .pgpass automatically!
pgcli --ssh-tunnel user@bastion.example.com -h production.db.example.com -d mydb -U dbuser

Technical Details

PostgreSQL supports both host and hostaddr parameters:

• When both are specified, host is used for authentication (.pgpass, Kerberos, SSL CN)
• hostaddr is used for the actual TCP connection
• This is perfect for SSH tunnels where we need different values for each

Compatibility

• Fully backward compatible
• No changes to non-SSH tunnel connections
• Existing SSH tunnel connections continue to work
• New functionality is transparent to users

Made with ❤️ and 🤖 Claude Code

[j-bennet]

This needs test coverage before it can go in.

[DiegoDAF]

Addressed the feedback:

• Simplified preserved_params: Replaced with a direct dict comprehension filtering for dsn, password, and hostaddr — no intermediary variable needed.
• Added test coverage: 4 new tests covering host preservation with SSH tunnels, DSN+hostaddr behavior, no-tunnel baseline, and connect_uri dsn passing.
• Rebased on latest main (a0c2ee4).

[j-bennet]

Looks like there are test failures, take a look @DiegoDAF.

[DiegoDAF]

Fixed! The test failures were caused by connect_uri passing dsn=uri which changed the call signature. Removed that change — it's not needed since the hostaddr approach already preserves the original host without modifying connect_uri.

All URI tests pass now (test_quoted_db_uri, test_ssl_db_uri, test_port_db_uri, test_multihost_db_uri, test_application_name_db_uri).

[j-bennet]

Now the ruff check is failing.

[DiegoDAF]

The ruff check failure is fixed and conflicts with main are resolved. Test coverage was added in the earlier round of feedback. Ready for another review, thanks!

[DiegoDAF]

Hi @j-bennet 👋 Gentle nudge here too. I addressed the failing ruff check a while back and this has been waiting since. With the CI fix from #1596 in place it should pass cleanly now. Happy to rebase again if needed, just let me know. Thanks for all the review work! 🙏

[DiegoDAF]

And just, for the record, I've moved away from sshtunnel to paramiko 4, now 5 in my last local update.

[DiegoDAF]

Hi @j-bennet! 🎉 Huge thanks for the 4.5.0 release and for merging #1559! Riding that wave, this .pgpass + SSH tunnel one is also ready and passing. Happy to rebase or tweak anything if it helps, just say the word. No rush whatsoever, and thank you for all the awesome maintenance work! 🙏

[DiegoDAF]

@codex review

[chatgpt-codex-connector]

To use Codex here, create a Codex account and connect to github.

[DiegoDAF]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ef9a6e20a6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Do not replace the .pgpass port with the tunnel port

When --ssh-tunnel binds a random local port, this overwrites the original database port before libpq performs password-file lookup. PostgreSQL matches .pgpass entries against hostname:port:database:username:password (docs), so a normal entry such as production.db.example.com:5432:mydb:dbuser:... will not match the connection parameters host=production.db.example.com port=<random local port>, and pgcli will still prompt unless the user wildcards the port or somehow knows the local bind port.

Useful? React with 👍 / 👎.

[DiegoDAF]

Good catch, thanks @codex. We're intentionally keeping this behavior. It matches how pgAdmin 4 handles the same case: keep the real host for matching and SSL, set hostaddr to 127.0.0.1, use the local bind port, and let libpq resolve .pgpass. With that, .pgpass works through the tunnel when the entry wildcards the port (host:*:db:user:pass), which is the common setup. Fully decoupling the port would require parsing .pgpass ourselves, and we'd rather not diverge from libpq/pgAdmin for that. Accepting as-is.

[chatgpt-codex-connector]

To use Codex here, create an environment for this repo.