[Proposal] Exploring Native Database Connection Pooling Support in Django ORM

Django Internals ORM
1

Hi Django community :waving_hand:,

I’m currently working on some high-load projects and wanted to bring up a topic that feels increasingly important — native support for database connection pooling in Django.

I realize this probably belongs in the Internals category, but I don’t yet have posting permissions there. I’m sharing it here to get feedback and start a discussion — happy to repost it in Internals when possible!

:brain: Why this matters

In Django, CONN_MAX_AGE helps with persistent connections, but it doesn’t provide true connection pooling like you’d get with SQLAlchemy in FastAPI or similar frameworks.

In contrast, SQLAlchemy gives you:

  • Configurable pool sizes
  • Queueing and timeout behavior
  • Recycle/reconnect logic
  • Pool health insights

This makes a huge performance difference for apps with high concurrency, short-lived processes (e.g. in serverless), or async workflows.

:magnifying_glass_tilted_left: Current Django Workarounds

Some common strategies we use today:

  • External tools like pgbouncer
  • Third-party libraries like django-db-geventpool
  • DIY solutions or monkey-patching backends

But none of these feel native to Django or widely documented, and they’re not always obvious to developers starting out.

:light_bulb: What I’m proposing

Would it make sense to explore:

  • Pluggable pool support via the DATABASES setting
  • Native connection pooling logic (opt-in, maybe backend-specific)
  • Exposing pool stats or metrics

Even a minimal version — something closer to SQLAlchemy’s QueuePool — could go a long way.

:thinking: Open Questions

  • Has this been considered before?
  • Is there a specific architectural reason Django ORM doesn’t offer this natively?
  • Would the community be open to a discussion or draft proposal?

Thanks for reading! :folded_hands:
Looking forward to hearing thoughts — and if I get access to Internals, I’ll gladly move the discussion there.

2

5.1 introduced pools for Postgres Django 5.1 release notes | Django documentation | Django

and briefly searching through tickets it would seem other backends have been considered and worked on before. (#7732 (Oracle Backend with SessionPool) – Django, #35702 (Clarify mysqlclient does not provide connection pooling) – Django)

I would suggest you do some more research via code.djangoproject.com to see what has been done and if there are any gaps left which you could fulfill.

2 Likes
3

First of all please make my apology for such late respond.
Thank you for taking time to write here , I really appreciate it.
you’re absolutely right.

I looked into the Django 5.1 release notes and saw that PostgreSQL now supports pooling via pooling_class, which is great to see. I also checked out those tickets you mentioned (#7732 and #35702), and it’s clear there has been backend-specific consideration in the past.

my concern isn’t about absence of pooling, but more about:

  • Inconsistency in support across different DB backends (Postgres vs MySQL vs Oracle)
  • Lack of a unified abstraction or interface to configure and manage pools
  • Scattered documentation, making it hard for devs to know what’s supported and how to use it properly

So maybe a more valuable contribution could be:

  • Consolidating DB pooling capabilities into a single place in the docs
  • Proposing a backend-agnostic POOL_OPTIONS interface (like CACHES)
  • Adding dev tools/metrics for pool debugging

but I appreciate your direction and make sense. I will dig more and find out what’s already done and what the remaining gap are. if there any room, I will contribute towards improving clarity.
Thank you so much

4

This sounds a reasonable approach, and you may find that the consolidating the docs might be a sufficient solution.

If you do decide to proceed with other features, then proposing them in the new features repo would be the place to do so, but you could probably also bundle any solution into a third-party package.

1 Like
5

I did a review of Django’s documentation and repo:
and as you mentioned eariler in thread.

  • Django 5.1 officially introduced PostgreSQL connection pooling via OPTIONS: { pool: ... }, using psycopg[pool].
  • For Oracle, ticket #7732 added a SessionPool, and it’s documented under the Oracle backend notes.
  • MySQL / MariaDB / SQLite currently have no native pooling support only CONN_MAX_AGE for persistent connections.

Also, while going through various threads and Django’s async roadmap, it seems that connection management including pooling is one of the practical blockers for making the Django ORM fully async.

Better and more consistent connection handling across backends could potentially play a role in unlocking more robust async support down the line.

Would you recommend I put together a draft PR for the docs at this point?
Thanks again for feedback and guidance.

6

What would the draft PR contain? The Django docs follows diataxis for it’s structure so any new documentation would need to follow this.

Perhaps a new-feature issue for this before a PR?

1 Like
7

Actually that makes a lot of sense . I’ll go through the Diátaxis model (it’s new to me) and see where this could best fit in the docs. may be I will be having some questions after going through it.

I agree creating a new-feature issue first would be the right way to frame this.

I’ll draft something and share it soon. Thanks