Documentation: Outdated warning about DateTimeField on MySQL?

[Kevin Christopher Henry]

The ​MySQL Database notes say:

MySQL does not have a timezone-aware column type. If an attempt is made to store a timezone-aware time or datetime to a TimeField or DateTimeField respectively, a ValueError is raised rather than truncating data.

I don't use MySQL so I can't check this, but isn't this wrong? Wasn't this fixed in 1.4 by storing timezone-aware datetimes in UTC? This note goes back to (at least) 1.3, so I'm guessing it was just never updated.

[Tim Graham]

This behavior is still tested: ​https://github.com/django/django/blob/65c1a37490b1e504cb69fb09731cfda85fcd6002/tests/timezones/tests.py#L149-L153

[Kevin Christopher Henry]

But that test class has @override_settings(TIME_ZONE='Africa/Nairobi', USE_TZ=False). When USE_TZ = True the ​code itself shows that it should work as expected, no?

[Tim Graham]

Thanks, I think the attached patch should clarify the situation then?

[Kevin Christopher Henry]

I think that wording is a little confusing if you're not already familiar with the way timezone-handling works. I would say something like this:

MySQL does not have a timezone-aware column type. When USE_TZ = True and an attempt is made to store a timezone-aware datetime (or time) in a DateTimeField (or TimeField), the datetime is converted to UTC and stored without a timezone. When USE_TZ = False, though, Django chooses to raise a ValueError rather than simply discard the timezone information in the aware datetime.

Either way, though, you should include the same warning for Oracle and SQLite, since they display the same behavior (see ​here and ​here).

(Sorry, I'm not able to create an actual patch at the moment.)

[Tim Graham]

Thanks for the research. In that case, maybe we could just remove the note since the exception that is thrown has a helpful message?

[Kevin Christopher Henry]

I think that's fine. This note predates Django's timezone support, and the timezone documentation makes pretty clear that correct usage requires a match between USE_TZ and timezone-awareness.

Since this has been inaccurate since version 1.4, hopefully you can backport the deletion...

[Tim Graham <timograham@…>]

In 9db3653670d85fbd34cd196b6f4964503c88a5c2:

Fixed #23631 -- Removed outdated note on MySQL timezone support.

Thanks marfire for the report.

[Tim Graham <timograham@…>]

In 643374bcf544dbcd1091539a9f3c832b5440fee2:

[1.4.x] Fixed #23631 -- Removed outdated note on MySQL timezone support.

Thanks marfire for the report.

Backport of 9db3653670 from master

[Tim Graham <timograham@…>]

In 625480cf0862f5998ed7e1e324087e58f8a740a7:

[1.7.x] Fixed #23631 -- Removed outdated note on MySQL timezone support.

Thanks marfire for the report.

Backport of 9db3653670 from master

[Tim Graham <timograham@…>]

In 0a31b4ea8e844f6b2f02027ef4d94b09c34ebb91:

[1.6.x] Fixed #23631 -- Removed outdated note on MySQL timezone support.

Thanks marfire for the report.

Backport of 9db3653670 from master