Opened 22 months ago

Closed 22 months ago

Last modified 22 months ago

#21427 closed Cleanup/optimization (fixed)

Clearly state the value range of all integer type fields in the model field documentation

Reported by: giuliettamasina Owned by: nobody
Component: Documentation Version: master
Severity: Normal Keywords:
Cc: Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

The documentation for BigIntegerField, PositiveSmallIntegerField and SmallIntegerField clearly state what integer values fit into that field's size:

https://docs.djangoproject.com/en/dev/ref/models/fields/#bigintegerfield
https://docs.djangoproject.com/en/dev/ref/models/fields/#positivesmallintegerfield
https://docs.djangoproject.com/en/dev/ref/models/fields/#smallintegerfield

But these do not state the same info:

https://docs.djangoproject.com/en/dev/ref/models/fields/#integerfield
https://docs.djangoproject.com/en/dev/ref/models/fields/#positiveintegerfield

For clarity, I think all of the above fields should be documented with a standardized sentence like this:

"Values from X to Y are safe in all databases supported by Django."

Change History (8)

comment:1 Changed 22 months ago by timo

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted
  • Version set to master

comment:2 Changed 22 months ago by giuliettamasina

Opened a pull request here: https://github.com/django/django/pull/1949

comment:3 Changed 22 months ago by timo

  • Has patch set
  • Triage Stage changed from Accepted to Ready for checkin

Assuming the ranges are correct, this looks good. Could you amend your PR to follow the commit message guidelines? Also, don't forget to check "Has patch" so the ticket appears in the review queue. Thanks!

comment:4 Changed 22 months ago by claudep

  • Triage Stage changed from Ready for checkin to Accepted

Sorry, but I'd like to know where do the new figures come from. Could you please document here your findings (with appropriate links to backends documentation)?

comment:5 Changed 22 months ago by giuliettamasina

Sorry, I did not do my homework properly, and the values were not correct.

I've now corrected them and opened a new pull request (following commit message guidelines): https://github.com/django/django/pull/1955

The values and their sources are as follows:

MySQL
IntegerField (integer): -2147483648 to 2147483647
PositiveIntegerField (integer UNSIGNED): 0 to 2147483647
PositiveSmallIntegerField (smallint UNSIGNED): 0 to 32767
Source: http://dev.mysql.com/doc/refman/5.0/en/integer-types.html

Postgres
IntegerField (integer): -2147483648 to 2147483647
PositiveIntegerField (integer): 0 to 2147483647
PositiveSmallIntegerField (smallint): 0 to 32767
Source: http://www.postgresql.org/docs/devel/static/datatype-numeric.html

Oracle
IntegerField (NUMBER(11)): -99999999999 to 99999999999
PositiveIntegerField (NUMBER(11)): 0 to 99999999999
PositiveSmallIntegerField (NUMBER(11)): 0 to 99999999999
Source: http://docs.oracle.com/cd/E11882_01/server.112/e25513/limits001.htm

SQLite
("1, 2, 3, 4, 6, or 8 bytes depending on the magnitude of the value.")
IntegerField (integer): -9223372036854775808 to 9223372036854775807
PositiveIntegerField (integer unsigned): 0 to 9223372036854775807
PositiveSmallIntegerField (smallint unsigned): 0 to 9223372036854775807
Source: http://www.sqlite.org/datatype3.html

comment:6 Changed 22 months ago by bmispelon

  • Triage Stage changed from Accepted to Ready for checkin

Everything looks good.

Thanks for finding all the references too, this is very valuable.

I'll mark the ticket as ready for checkin and commit it later today if no one does it before.

comment:7 Changed 22 months ago by Baptiste Mispelon <bmispelon@…>

  • Resolution set to fixed
  • Status changed from new to closed

In b6a6cf4ab791b092e18ab16537aa88dd7ae9bc36:

Fixed #21427 -- Clearly state integer field value ranges in docs

Added an explicit mention of the exact value ranges for integer type
fields that are safe in all databases supported by Django. Also, put
all value numbers inside double ticks.

comment:8 Changed 22 months ago by Baptiste Mispelon <bmispelon@…>

In 47abfa237e21ca71d8ee901cf8ba1f1c89ae1f2e:

[1.6.x] Fixed #21427 -- Clearly state integer field value ranges in docs

Added an explicit mention of the exact value ranges for integer type
fields that are safe in all databases supported by Django. Also, put
all value numbers inside double ticks.

Backport of b6a6cf4ab791b092e18ab16537aa88dd7ae9bc36 from master.

Note: See TracTickets for help on using tickets.
Back to Top