In a .pgpass file in your home directory, if you want psql and other libpq tools to connect without a prompt. PostgreSQL ignores the file on Unix unless its permissions block all group and world access, so run chmod 0600 on it. Never put the password in a connection URL you commit.
What the file does
The PostgreSQL documentation describes .pgpass in a user's home directory as holding passwords to use when a connection requires one and no password was given another way. On Windows the file is named pgpass.conf under %APPDATA%\postgresql. You can point to another file with the passfile connection parameter or the PGPASSFILE environment variable.
The format
Each line has five fields separated by colons:
hostname:port:database:username:password
The first four fields can be a literal value or an asterisk that matches anything. The first line that matches the connection parameters supplies the password, so put more specific entries above wildcard ones. If a field needs a colon or a backslash, escape it with a backslash. You can add a comment by starting a line with #.
For example, localhost:5432:appdb:appuser:example-only-password would serve one local database and no others.
The permission rule
On Unix systems, the documentation says the permissions on a password file must disallow any access to world or group. It gives the command:
chmod 0600 ~/.pgpass
If the permissions are less strict, the file is ignored. That is a useful failure, since it nudges you to lock it down, but it can confuse people who see a password prompt and do not know why. On Windows, no permission check is made, because the file is assumed to sit in a secure directory.
Why this is better than the alternatives
| Where the password goes | Problem |
|---|---|
| Typed in a command or URL | Lands in shell history and logs |
| A committed config file | Lands in version control history |
| Environment variable in a shared profile | Visible to child processes and easy to leak |
| .pgpass with 0600 | Local, scoped by host and database, not in the repo |
The file still holds plain text, so it protects against casual exposure, not against malware running as your user. Keep dev databases free of real customer data, and use a different account for each environment so a leaked development password opens nothing important.
Habits that keep it clean
Use one line per database and avoid the all wildcard entry that matches everything. Delete lines for databases you no longer use. If you need to share access with a teammate, have them create their own database role instead of passing yours around, which also keeps audit trails meaningful. For production, prefer short-lived credentials from your platform over any file on a laptop.
Where Safeguard fits
Safeguard works on the dependency and code side of your software: SBOM and dependency scanning, reachability analysis and policy gates. It does not store or manage credentials, so keep using your password manager, secrets manager or cloud identity for that. You can run a free scan of a project at gold.safeguard.sh/scan.
Quick check
Why is my pgpass file being ignored?
On Unix the documentation says it is ignored when group or world have any access. Run chmod 0600.
Can I keep several passwords in one file?
Yes, one line per host, port, database and user combination. The first matching line is used.
Is the password encrypted in the file?
No. The format shown in the docs holds the password as plain text.
Sources
Last reviewed: 19 October 2026.
