Clarify backend-specific mappings and portable safe ranges of PositiveIntegerField types

[Jeff Cho]

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

[Natalia Bidart]

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.

[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!