Django psycopg connection pool + fork()

[Anna]

Django's PostgreSQL backend stores psycopg_pool.ConnectionPool objects in a class-level dict (DatabaseWrapper._connection_pools). When gunicorn (or any pre-forking server) forks worker processes, all children inherit references to the same pool objects — and crucially, the same underlying TCP sockets to PostgreSQL. Multiple workers then read/write the same socket concurrently, corrupting the PostgreSQL wire protocol.

Root cause

# django/db/backends/postgresql/base.py
class DatabaseWrapper(BaseDatabaseWrapper):
    _connection_pools = {}   # class-level dict — survives fork()

    @property
    def pool(self):
        if self.alias not in self._connection_pools:
            pool = ConnectionPool(...)
            self._connection_pools.setdefault(self.alias, pool)
        return self._connection_pools[self.alias]

Workaround

# gunicorn.conf.py
def post_fork(server, worker):
    from django.db.backends.postgresql.base import DatabaseWrapper
    DatabaseWrapper._connection_pools.clear()

Suggested fix
Use os.register_at_fork(after_in_child=...) to clear _connection_pools in child processes, or check os.getpid() in the pool property and recreate when it differs from the creating process.

Tested with
Django 6.0.2
psycopg 3.2.x – 3.3.2
psycopg-pool 3.2.x – 3.3.0
gunicorn 25.x (--worker-class asgi)
Python 3.12 – 3.14

The minimal reproducible example project is in the attachments

[Dhruvan Gnanadhandayuthapani]

Opened a PR that implements the os.register_at_fork() check along with a flag. This solution was preferred over running os.getpid() in the pool property, because it is wasteful to do it each time the property is accessed.

​https://github.com/django/django/pull/20790

[JaeHyuckSa]

Hello Djruvan! The “Accept” status on a Django ticket should be set by a triager after reviewing the ticket. If you haven’t had a chance to read the contribution guidelines, I would appreciate it if you could take a look.

• ​https://docs.djangoproject.com/en/dev/internals/contributing/triaging-tickets
• ​https://docs.djangoproject.com/en/dev/internals/contributing

[Simon Charette]

I would say this is close if not a duplicate of #31637. The problem of forking after connection creation is not specific to psycopg connection pools.

[Mariusz Felisiak]

Agreed, duplicate of #31637.