[Django] #36964: Documentation incorrectly states that persistent connections don't work with runserver

[Django]

#36964: Documentation incorrectly states that persistent connections don't work
with runserver
-------------------------------------+-------------------------------------
Reporter: Adam Sołtysik | Type:
| Cleanup/optimization
Status: new | Component:
| Documentation
Version: 5.2 | Severity: Normal
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
From https://docs.djangoproject.com/en/5.2/ref/databases/#caveats:

> The development server creates a new thread for each request it handles,
negating the effect of persistent connections. Don’t enable them during
development.

Something here seems to be incorrect. I'm using `'CONN_MAX_AGE': None`
with the development server, and it works as expected. My requests are
significantly faster than with the default setting. When analyzing with
`SELECT * FROM pg_stat_activity WHERE datname = '<dbname>'`, I can see a
single connection created and persisting after the first request, and it
disappears after autoreload.
--
Ticket URL: <https://code.djangoproject.com/ticket/36964>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#36964: Documentation incorrectly states that persistent connections don't work
with runserver
-------------------------------------+-------------------------------------

Reporter: Adam Sołtysik | Owner: (none)
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 5.2
Severity: Normal | Resolution:

Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Mankameshwar Mishra):

I’d like to work on a documentation patch for this issue.
--
Ticket URL: <https://code.djangoproject.com/ticket/36964#comment:1>

[Django]

#36964: Documentation incorrectly states that persistent connections don't work
with runserver
-------------------------------------+-------------------------------------
Reporter: Adam Sołtysik | Owner: (none)
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Shubh Rai):

Sequential requests reuse the same thread, which results in single DB
connection visible . The connection is dropped only on autoreload.

It seems the documentation warning is for concurrent requests, where
multiple threads may create separate connections, rather than sequential
development testing. I believe that the documentation is not wrong but
little bit clarification can be given.
--
Ticket URL: <https://code.djangoproject.com/ticket/36964#comment:2>

[Django]

#36964: Documentation incorrectly states that persistent connections don't work
with runserver
-------------------------------------+-------------------------------------

Reporter: Adam Sołtysik | Owner: Youssef
Type: | Tarek Ali
Cleanup/optimization | Status: assigned

Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Youssef Tarek Ali):

* has_patch: 0 => 1
* owner: (none) => Youssef Tarek Ali
* status: new => assigned

Comment:

I have assigned this to myself and drafted a documentation update. The new
wording clarifies that persistent connections do work for sequential
requests in the development server, while noting that they are reset upon
auto reload and that concurrent requests still trigger new threads.
Verified the build locally with make html.

PR: https://github.com/django/django/pull/20825
--
Ticket URL: <https://code.djangoproject.com/ticket/36964#comment:3>

[Django]

#36964: Documentation incorrectly states that persistent connections don't work
with runserver
-------------------------------------+-------------------------------------

Reporter: Adam Sołtysik | Owner: Shubh Rai
Type: | Status: assigned
Cleanup/optimization |

Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Shubh Rai):

* owner: Youssef Tarek Ali => Shubh Rai

--
Ticket URL: <https://code.djangoproject.com/ticket/36964#comment:4>

[Django]

#36964: Documentation incorrectly states that persistent connections don't work
with runserver
-------------------------------------+-------------------------------------
Reporter: Adam Sołtysik | Owner: Shubh Rai
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed

Has patch: 1 | Needs documentation: 1

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Shubh Rai):

* needs_docs: 0 => 1

Comment:

I have opened a pull request addressing this documentation clarification.

PR: https://github.com/django/django/pull/20827
Ticket: #36964

The change clarifies the wording about persistent database connections
when using the development server. In practice, persistent connections can
still be observed when CONN_MAX_AGE is enabled, but due to the development
server’s thread-per-request model and autoreload behavior, connection
reuse may be inconsistent and not representative of production
environments.

Feedback and suggestions are welcome.
--
Ticket URL: <https://code.djangoproject.com/ticket/36964#comment:5>

[Django]

#36964: Documentation incorrectly states that persistent connections don't work
with runserver
-------------------------------------+-------------------------------------
Reporter: Adam Sołtysik | Owner: Shubh Rai
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: 5.2
Severity: Normal | Resolution:

Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 1
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Shubh Rai):

* stage: Unreviewed => Accepted

Comment:

A pull request has been opened for this documentation clarification:

https://github.com/django/django/pull/20827

The PR updates the wording about persistent connections when using the
development server to clarify that they may still be observed when
`CONN_MAX_AGE` is enabled, but their behavior may not reflect production
environments due to autoreload and the thread-per-request model.
--
Ticket URL: <https://code.djangoproject.com/ticket/36964#comment:6>

[Django]

#36964: Documentation incorrectly states that persistent connections don't work
with runserver
-------------------------------------+-------------------------------------
Reporter: Adam Sołtysik | Owner: Shubh Rai
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: | Triage Stage:

| Unreviewed

Has patch: 1 | Needs documentation: 1
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by VIZZARD-X):

* stage: Accepted => Unreviewed

Comment:

Reverting the triage stage back to 'Unreviewed' for now so it can be
officially assessed and accepted by a core reviewer/triager, as per the
standard workflow.
--
Ticket URL: <https://code.djangoproject.com/ticket/36964#comment:7>

[Django]

#36964: Documentation incorrectly states that persistent connections don't work
with runserver
-------------------------------------+-------------------------------------

Reporter: Adam Sołtysik | Owner: Youssef
Type: | Tarek Ali
Cleanup/optimization | Status: assigned

Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Natalia Bidart):

* needs_docs: 1 => 0
* owner: Shubh Rai => Youssef Tarek Ali

--
Ticket URL: <https://code.djangoproject.com/ticket/36964#comment:8>

[Django]

#36964: Documentation incorrectly states that persistent connections don't work
with runserver
-------------------------------------+-------------------------------------
Reporter: Adam Sołtysik | Owner: Youssef
Type: | Tarek Ali
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Shubh Rai):

,Sorry for taking ownership of this ticket. I'm still new to the Django
ticket workflow and didn't realize it was already being worked on. My
apologies for the confusion.
--
Ticket URL: <https://code.djangoproject.com/ticket/36964#comment:9>