Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

Django cannot connect to PostgreSQL through a pg_service.conf service

Errordefinition of service "my_service" not found

Short 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.

  • Applies to Django 5.2, psycopg 3, PostgreSQL 17, Windows 11
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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"
  2. 2Match what you see, then jump to its fix

    1. 1psql "service=my_service" prints definition of service not found, or service file not foundThe service file is not where libpq looks for itFix
    2. 2psql works, Django still reports no host or no databaseThe service name is not in OPTIONS in settings.pyFix
    3. 3The service is found, then password authentication failsThe password file is missing or in the wrong placeFix
    4. 4manage.py runserver works but manage.py test fails to create the test databaseRunning tests against a service-only configurationFix

What does the error look like?

  • definition of service "my_service" not found
  • service 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=USER

3Verify

psql finds the service.

psql "service=my_service" -c "select 1"

Confirmed by postgresql.org

Did this fix it?

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.py

2Fix

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 default

Confirmed by docs.djangoproject.com

Did this fix it?

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:PASSWORD

3Verify

Connect with psql and no password prompt.

psql "service=my_service" -c "select 1"

Confirmed by postgresql.org

Did this fix it?

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 test

2Fix

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_test

Confirmed by docs.djangoproject.com

Did this fix it?

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.