Django cannot connect to PostgreSQL through a pg_service.conf service
definition of service "my_service" not foundShort answer
Django passes a service name to PostgreSQL only through the OPTIONS dictionary, and libpq must find the file. On Windows the per-user service file is %APPDATA%\postgresql\.pg_service.conf and the password file is pgpass.conf in the same folder. Set both in OPTIONS or with environment variables.
Fix it fast
1Find out which cause you have
Check from the same terminal that libpq itself finds the service, bypassing Django. If this fails, the problem is the file, not Django.
psql "service=my_service" -c "select 1"2Match what you see, then jump to its fix
- 1
psql "service=my_service" prints definition of service not found, or service file not foundThe service file is not where libpq looks for itFix - 2
psql works, Django still reports no host or no databaseThe service name is not in OPTIONS in settings.pyFix - 3
The service is found, then password authentication failsThe password file is missing or in the wrong placeFix - 4
manage.py runserver works but manage.py test fails to create the test databaseRunning tests against a service-only configurationFix
- 1
What does the error look like?
definition of service "my_service" not foundservice file "C:\Users\you\AppData\Roaming\postgresql\.pg_service.conf" not found
Cause 1 of 4
The service file is not where libpq looks for it
1Check
The per-user file on Windows is %APPDATA%\postgresql\.pg_service.conf. PGSERVICEFILE can point to another file. A file named pg_service.conf in your project is not read.
dir "%APPDATA%\postgresql"
echo %PGSERVICEFILE%2Fix
Put the file in that folder with a leading dot in its name, or set PGSERVICEFILE to the full path of your file.
[my_service]
host=localhost
port=5432
dbname=NAME
user=USER3Verify
psql finds the service.
psql "service=my_service" -c "select 1"Confirmed by postgresql.org
Cause 2 of 4
The service name is not in OPTIONS in settings.py
1Check
Django documents the service and passfile keys inside OPTIONS only. Putting the service name in NAME or HOST does not use the file.
findstr /n "service OPTIONS NAME" settings.py2Fix
Declare the engine and put service in OPTIONS. Add passfile when the password lives in a password file.
DATABASES = {
"default": {
"ENGINE": "django.db.backends.postgresql",
"OPTIONS": {
"service": "my_service",
"passfile": ".my_pgpass",
},
}
}3Verify
Django opens a connection.
python manage.py check --database defaultConfirmed by docs.djangoproject.com
Cause 3 of 4
The password file is missing or in the wrong place
1Check
On Windows the default password file is %APPDATA%\postgresql\pgpass.conf. A custom path goes in PGPASSFILE or the passfile option, and each line has the form host:port:database:user:password.
type "%APPDATA%\postgresql\pgpass.conf"2Fix
Create the file at that default path, or point passfile or PGPASSFILE at your own file.
localhost:5432:NAME:USER:PASSWORD3Verify
Connect with psql and no password prompt.
psql "service=my_service" -c "select 1"Confirmed by postgresql.org
Cause 4 of 4
Running tests against a service-only configuration
1Check
Django states that using a service name for testing is not supported.
python manage.py test2Fix
Give the test setup explicit settings, such as a separate settings module for tests with host, name and user in the DATABASES entry.
# settings_test.py
from .settings import *
DATABASES["default"] = {
"ENGINE": "django.db.backends.postgresql",
"NAME": "app", "USER": "app", "HOST": "localhost", "PORT": "5432",
}3Verify
Run the tests with that module.
python manage.py test --settings=myproject.settings_testConfirmed by docs.djangoproject.com
How do I stop it coming back?
- Test the service with psql first, then wire it into Django.
- Keep the service file and password file out of version control.
- Set PGSERVICEFILE and PGPASSFILE explicitly in the environment of scheduled tasks and services, which may run under another user profile.
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
Django cannot connect to PostgreSQL: connection refused on port 5432, locally or in Docker
Is the server running on that host and accepting TCP/IP connections?
Connection refused means nothing accepted the connection at the host and port Django used.
4 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