[Django] #36425: Clarify backend-specific mappings and portable safe ranges of PositiveIntegerField types

[Django]

#36425: Clarify backend-specific mappings and portable safe ranges of
PositiveIntegerField types
-------------------------------------+-------------------------------------
Reporter: Jeff Cho | Type:
| Cleanup/optimization
Status: new | Component:
| Documentation
Version: 5.1 | Severity: Normal
Keywords: docs, mysql, orm, | Triage Stage:
fields | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Currently, the documentation for PositiveSmallIntegerField,
PositiveIntegerField, and PositiveBigIntegerField mentions only a "safe
range" of values. However, it doesn't explain why these ranges were
chosen, nor what actual database column types these fields map to.

For example, in MySQL, these fields map to UNSIGNED types (UNSIGNED INT,
BIGINT, SMALLINT), and can accept much larger values than the "safe
range". This mapping is not mentioned anywhere in the documentation.

As a result, users must inspect the Django source code or rely on third-
party discussions to understand what these fields actually do in
production.

This patch proposes to:

- Clearly define "safe range" as the portable, cross-backend-compatible
range
- Explicitly mention that actual DB column types vary by backend
- Add MySQL-specific notes stating these fields map to UNSIGNED
INT/BIGINT/SMALLINT

See common user confusion:
- https://stackoverflow.com/questions/18925760/unsigned-integer-field-in-
django
- https://stackoverflow.com/questions/18513350/can-i-have-an-unsigned-
autofield
- https://stackoverflow.com/questions/73027108/django-
positivebigintegerfield
--
Ticket URL: <https://code.djangoproject.com/ticket/36425>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#36425: Clarify backend-specific mappings and portable safe ranges of
PositiveIntegerField types
-------------------------------------+-------------------------------------

Reporter: Jeff Cho | Owner: Jeff Cho
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: 5.1
Severity: Normal | Resolution:

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

Changes (by Jeff Cho):

* owner: (none) => Jeff Cho
* status: new => assigned

--
Ticket URL: <https://code.djangoproject.com/ticket/36425#comment:1>

[Django]

#36425: Clarify backend-specific mappings and portable safe ranges of
PositiveIntegerField types
-------------------------------------+-------------------------------------
Reporter: Jeff Cho | Owner: Jeff Cho
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: 5.1
Severity: Normal | Resolution:
Keywords: docs, mysql, orm, | Triage Stage:
fields | Unreviewed

Has patch: 1 | Needs documentation: 0

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

* has_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/36425#comment:2>

[Django]

#36425: Clarify backend-specific mappings and portable safe ranges of
PositiveIntegerField types
-------------------------------------+-------------------------------------
Reporter: Jeff Cho | Owner: Jeff Cho
Type: | Status: assigned
Cleanup/optimization |

Component: Database layer | Version: dev
(models, ORM) |
Severity: Normal | Resolution:
Keywords: docs, mysql, orm, | Triage Stage: Accepted
fields |

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

Changes (by Natalia Bidart):

* cc: Simon Charette (added)
* component: Documentation => Database layer (models, ORM)
* stage: Unreviewed => Accepted
* version: 5.1 => dev

Comment:

Hello Jeff Cho, tanks for this report! I think this is a valid
documentation improvement.

We can accept this ticket on the basis that the documentation could
clarify that the actual database column types and supported value ranges
may vary between backends. However, we prefer to avoid including backend-
specific details (such as MySQL’s use of UNSIGNED) in the main
documentation, in order to maintain backend neutrality.

A patch that adds a brief note explaining that the documented "safe range"
corresponds to the cross-database-compatible range, and that backends may
internally support larger ranges, would be welcome.
--
Ticket URL: <https://code.djangoproject.com/ticket/36425#comment:3>

[Django]

#36425: Clarify backend-specific mappings and portable safe ranges of
PositiveIntegerField types
-------------------------------------+-------------------------------------
Reporter: Jeff Cho | Owner: Jeff Cho
Type: | Status: assigned
Cleanup/optimization |
Component: Database layer | Version: dev
(models, ORM) |
Severity: Normal | Resolution:
Keywords: docs, mysql, orm, | Triage Stage: Accepted
fields |
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Jeff Cho):

Hi Natalia,

Thank you for the feedback and acceptance! I've updated the patch
according to your guidance.

**Changes made:**

1. **Added a brief note** to `PositiveIntegerField` explaining that the
documented "safe range" represents the cross-database-compatible range,
and that individual backends may internally support larger ranges.

2. **Maintained backend neutrality** by avoiding specific backend details
(like MySQL's UNSIGNED types) as requested.

3. **Reduced documentation redundancy** by adding the detailed note only
to `PositiveIntegerField` and using cross-references in
`PositiveBigIntegerField` and `PositiveSmallIntegerField` to avoid
duplication.

The implementation follows Django's documentation patterns where related
fields reference each other (similar to how `DateTimeField` references
`DateField`). This approach improves maintainability while ensuring all
three fields convey the same portability information.

The patch addresses the user confusion mentioned in the ticket by clearly
explaining why these specific ranges were chosen and what they guarantee
across different database backends.

Ready for review!
--
Ticket URL: <https://code.djangoproject.com/ticket/36425#comment:4>

[Django]

#36425: Clarify backend-specific mappings and portable safe ranges of
PositiveIntegerField types
-------------------------------------+-------------------------------------
Reporter: Jeff Cho | Owner: Jeff Cho
Type: | Status: assigned
Cleanup/optimization |
Component: Database layer | Version: dev
(models, ORM) |
Severity: Normal | Resolution:
Keywords: docs, mysql, orm, | Triage Stage: Accepted
fields |
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Sarah Boyce):

* needs_better_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/36425#comment:5>

[Django]

#36425: Clarify backend-specific mappings and portable safe ranges of
PositiveIntegerField types
-------------------------------------+-------------------------------------
Reporter: Jeff Cho | Owner: Jeff Cho
Type: | Status: assigned
Cleanup/optimization |
Component: Database layer | Version: dev
(models, ORM) |
Severity: Normal | Resolution:

Keywords: docs, mysql, orm, | Triage Stage: Ready for
fields | checkin

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Sarah Boyce):

* needs_better_patch: 1 => 0
* stage: Accepted => Ready for checkin

--
Ticket URL: <https://code.djangoproject.com/ticket/36425#comment:6>

[Django]

#36425: Clarify backend-specific mappings and portable safe ranges of
PositiveIntegerField types
-------------------------------------+-------------------------------------
Reporter: Jeff Cho | Owner: Jeff Cho

Type: | Status: closed

Cleanup/optimization |
Component: Database layer | Version: dev
(models, ORM) |

Severity: Normal | Resolution: fixed

Keywords: docs, mysql, orm, | Triage Stage: Ready for
fields | checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Sarah Boyce <42296566+sarahboyce@…>):

* resolution: => fixed
* status: assigned => closed

Comment:

In [changeset:"091f66e51aa900f7d7650529621bdc8e4b0dee68" 091f66e5]:
{{{#!CommitTicketReference repository=""
revision="091f66e51aa900f7d7650529621bdc8e4b0dee68"
Fixed #36425 -- Standardized integer fields descriptions.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36425#comment:7>

[Django]

#36425: Clarify backend-specific mappings and portable safe ranges of
PositiveIntegerField types
-------------------------------------+-------------------------------------
Reporter: Jeff Cho | Owner: Jeff Cho
Type: | Status: closed
Cleanup/optimization |
Component: Database layer | Version: dev
(models, ORM) |
Severity: Normal | Resolution: fixed
Keywords: docs, mysql, orm, | Triage Stage: Ready for
fields | checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Sarah Boyce <42296566+sarahboyce@…>):

In [changeset:"91569cffeccf03756bb9217c46e1b18591213d6a" 91569cf]:
{{{#!CommitTicketReference repository=""
revision="91569cffeccf03756bb9217c46e1b18591213d6a"
[5.2.x] Fixed #36425 -- Standardized integer fields descriptions.

Backport of 091f66e51aa900f7d7650529621bdc8e4b0dee68 from main.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36425#comment:8>