A Go program is refused by Postgres with password authentication failed
pq: password authentication failed for user "user-name"Short answer
The server rejected the credentials your Go code sent. Test the same user and password in psql first. If psql fails too, the role has a different password, or none. If psql works, the Go connection string is mangling the password, usually because special characters are not percent-encoded in a postgres:// URL.
Fix it fast
1Find out which cause you have
Run psql with the exact user, host and password your Go program uses. The result splits the two causes.
PGPASSWORD='the-password' psql -h localhost -U user-name -d mydb -c 'select 1'2Match what you see, then jump to its fix
What does the error look like?
pq: password authentication failed for user "user-name"
Cause 1 of 2
The role has a different password, or no password at all
1Check
PostgreSQL documents that a role with no password has a null stored password, and password authentication always fails for it.
PGPASSWORD='the-password' psql -h localhost -U user-name -d mydb -c 'select 1'2Fix
Set the password again as a superuser, then update the Go configuration to match.
ALTER ROLE "user-name" WITH PASSWORD 'new-secret';3Verify
The psql command from the first step prints 1.
PGPASSWORD='new-secret' psql -h localhost -U user-name -d mydb -c 'select 1'Confirmed by postgresql.org
Cause 2 of 2
Special characters in the password break the connection URL
1Check
Characters such as @, :, / or # have a meaning in a URL. The libpq documentation says a connection URI must be percent-encoded where a character has special meaning, following RFC 3986.
grep -rn "postgres://" --include=*.go --include=*.env .2Fix
Percent-encode the password inside the URL (for example @ becomes %40, : becomes %3A, / becomes %2F).
// password p@ss:w/rd
dsn := "postgres://user-name:p%40ss%3Aw%2Frd@localhost:5432/mydb"
db, err := sql.Open("postgres", dsn)3Verify
Ping the database right after opening it.
if err := db.Ping(); err != nil {
log.Fatal(err)
}Confirmed by postgresql.org
How do I stop it coming back?
- Read the password from an environment variable and build the URL in code, so encoding happens in one place.
- Keep the user and password the same in the Go config and in the tool you use to test.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Related fixes
Databases
The Postgres container rejects the password you set in POSTGRES_PASSWORD
psql: error: connection to server at "localhost" (127.0.0.1), port 5432 failed: FATAL: password authentication failed for user "postgres"
The official Postgres image reads POSTGRES_PASSWORD only when it creates a new database cluster in an empty data directory.
2 causes, each with a fixDatabases
DBeaver cannot run pg_restore: the utility is not found in the client home
Utility 'pg_restore' not found in client home '/usr/lib' (/usr/lib)
DBeaver runs pg_restore from a local PostgreSQL client folder; it does not bundle one.
3 causes, each with a fixDatabases
DBeaver cannot download the PostgreSQL driver from Maven
The PostgreSQL driver files are missing and the download does not complete
DBeaver downloads the PostgreSQL JDBC driver from a Maven repository the first time you connect.
3 causes, each with a fixDatabases
python manage.py migrate finishes but the tables for my app are missing
relation "myapp_book" does not exist
migrate only applies migration files that exist.
3 causes, each with a fixDatabases
Django save fails on PostgreSQL: null value in a column violates a not-null constraint
django.db.utils.IntegrityError: null value in column "price" of relation "shop_product" violates not-null constraint
A model field is NOT NULL in the database unless it has null=True.
3 causes, each with a fixDatabases
Django migration on PostgreSQL stops with 'pending trigger events'
django.db.utils.OperationalError: cannot ALTER TABLE "mytable" because it has pending trigger events
PostgreSQL runs a Django migration in one transaction.
2 causes, each with a fix