.pgpass File

The .pgpass authentication profile allows you to use PostgreSQL’s standard password file for authentication. This is the same file format used by psql and other PostgreSQL client tools, making it easy to share credentials across tools.

Key Benefits

• Standard Format: Uses the same .pgpass file as psql and other PostgreSQL tools
• Credential Sharing: Share passwords across multiple PostgreSQL client applications
• Pattern Matching: Wildcards allow flexible credential matching
• No Code Changes: Works with existing .pgpass files without modification

File Format

The .pgpass file contains one entry per line with colon-separated fields:

hostname:port:database:username:password

Fields

Field	Description
hostname	Database server hostname or IP address
port	Database port number
database	Database name
username	PostgreSQL username
password	Password for this connection

Wildcards

Use * as a wildcard to match any value (except in the password field):

# Match any database on localhost
localhost:5432:*:myuser:mypassword

# Match any host on port 5432
*:5432:mydb:myuser:mypassword

# Match everything for a user
*:*:*:admin:adminpassword

Escaping

To include a literal colon (:) or backslash (\) in a field value, escape it with a backslash:

hostname\:with\:colons:5432:mydb:user:password

File Locations

Default Locations

Platform	Default Path
macOS / Linux	~/.pgpass
Windows	%APPDATA%\postgresql\pgpass.conf

Environment Variable

Set the PGPASSFILE environment variable to use a custom location:

export PGPASSFILE=/path/to/custom/pgpass

Configuration Options

File Location

Choose between:

• Default Location: Uses the standard .pgpass file path for your operating system
• Custom Path: Specify a custom file path

Example .pgpass File

# Development servers
localhost:5432:*:postgres:devpassword
dev-server.example.com:5432:appdb:appuser:devpass123

# Production (read-only user)
prod-db.example.com:5432:*:readonly:prodreadonly

# Staging with wildcard
*.staging.example.com:5432:*:deploy:stagingpass

Matching Rules

When connecting, DBCode searches the .pgpass file from top to bottom and uses the first matching entry. An entry matches if:

1. Hostname matches (or entry has *)
2. Port matches (or entry has *)
3. Database matches (or entry has *)
4. Username matches (or entry has *)

Example Matching

Given this .pgpass file:

localhost:5432:testdb:testuser:testpass
localhost:5432:*:postgres:postgrespass
*:*:*:admin:adminpass

Connection	Matched Entry	Password Used
localhost:5432/testdb as testuser	Line 1	testpass
localhost:5432/proddb as postgres	Line 2	postgrespass
anyhost:5432/anydb as admin	Line 3	adminpass
localhost:5432/testdb as postgres	Line 2	postgrespass

Creating an Auth Profile

1. Open the DBCode activity bar
2. Navigate to the Authentication Profiles section
3. Click the + (Create) icon
4. Select .pgpass File as the type
5. Choose the file location:
   • Default Location for standard .pgpass path
   • Custom Path to specify a different file
6. Click Save

Using with PostgreSQL Connections

1. Create or edit a PostgreSQL connection
2. In the Authentication section, select your pgpass profile
3. Enter the username (password will be read from .pgpass)
4. Save and connect

Supported Databases

The .pgpass authentication profile is available for:

• PostgreSQL
• Amazon Redshift (uses PostgreSQL protocol)
• CockroachDB
• Other PostgreSQL-compatible databases

Troubleshooting

”No matching entry found in .pgpass”

Cause: No entry in the file matches the connection parameters.

Solutions:

• Verify the hostname, port, database, and username match an entry
• Check for typos in the .pgpass file
• Add a wildcard entry as a fallback: *:*:*:username:password
• Remember: first match wins, so order matters

”Password file not found”

Cause: The .pgpass file doesn’t exist at the expected location.

Solutions:

• Create the file at the default location (~/.pgpass on Unix)
• Or use “Custom Path” and specify the correct location
• Check that the file path is correct and accessible

”Failed to read password file”

Cause: File permission or access issues.

Solutions:

• Ensure the file is readable by your user
• On Unix, file permissions should allow read access
• Check that the path doesn’t contain invalid characters

Hidden files not visible in file picker (macOS)

Cause: macOS hides files starting with . by default.

Solution: Press Cmd+Shift+. in the file picker to show hidden files.

Security Considerations

• Store .pgpass files with appropriate permissions
• On Unix systems, PostgreSQL tools typically require chmod 600 ~/.pgpass
• Consider using a secret manager with Command authentication for production environments
• The .pgpass file stores passwords in plain text

Related Documentation

• Authentication Profiles Overview
• PostgreSQL Connection Guide
• Command Authentication (for secret manager integration)