A Web Developer's Diary

Good to know: how to properly store date and time values in MySQL

6/30/2012

6 Comments

 
MySQL has two native field types that can store information about both date and time: timestamp and datetime. The major differences between timestamp and datetime field types are:
  1. timestamp can hold values only in the range '1970-01-01 00:00:01' UTC to '2038-01-19 03:14:07' UTC while datetime can hold any value in the range '1000-01-01 00:00:00' to '9999-12-31 23:59:59'.
  2. timestamp is the only mysql field type that stores values relative to a timezone (namely UTC), datetime does not store according to a time zone!

This has some serious implications. First, timestamp can only be used where the supported value range is sufficient. Second, for scenarios where you would want to log, compare or perform other tasks with date and time, datetime is not reliable if you adhere to your server time zone settings because datetime does not store the time zone information. An example to illustrate this unreliability:

Suppose you are logging transactions of some sort to your MySQL database, neatly adding the date and time at which the transaction took place, relying on the server time zone settings. Another process is monitoring the transactions (e.g. is client X not exceeding Y transactions per hour, whether transactions result in insufficient account balance, etc.). Now suppose the time zone of the server changes, this could be because of any reason:
  1. Some countries have daylight savings time, if your server is configured to that country's particular timezone, your server automatically changes time zone upon entering and leaving daylight savings time.
  2. The server administrator manually changes the time zone, e.g. because the server moved physically, perhaps the change is by accident or he/she decided it was better to change to a time zone that doesn't have daylight savings time ;-)
  3. A bug in the system software changes the time zone by accident.

To stick with the daylight savings example, let's say the clock gets rewound one hour. Transactions are still happily being inserted into the database using datetime. Now, according to the transaction log, customers are making twice the amount of transactions during this hour. But wait?! Weren't we keeping an eye on the maximum amount of transactions per hour of clients? It looks like some clients that are operating at only half of their capacity suddenly exceed the maximum transaction limit during that hour, uh oh!

How will MySQL know whether it was 2:30 AM before or after daylight saving time when you use timestamp? The answer is: MySQL doesn't know! E.g. 28 October 2012 2:30 AM in either CEST (UTC+2:00) or CET (UTC+1:00) are both stored as unix timestamp value 1351387800 (= "2012-10-28 02:30 CET" = "2012-10-28 01:30 UTC"). As we will see soon, this is documented behaviour. It's not possible to insert unix timestamps directly into a timestamp field, so you are required to use a text representation of the date and time you are trying to store (e.g. "2012-10-28 2:30", NOW(), CURRENT_TIMESTAMP). MySQL takes this string and converts it into an unix timestamp using UNIX_TIMESTAMP(), this is where the point where 28 October 2012 2:30 AM CEST and CET both get mapped to 1351387800. One suggested work-around I came accross doesn't work in my boundary case, confirming what the manual says:

 mysql> SELECT FROM_UNIXTIME(@ts := 1351387800) = FROM_UNIXTIME(@ts - 3600);
+--------------------------------------------------------------+
| FROM_UNIXTIME(@ts := 1351387800) = FROM_UNIXTIME(@ts - 3600) |
+--------------------------------------------------------------+
| 1 |
+--------------------------------------------------------------+
1 row in set (0.00 sec)

So how can we store our dates and times without being affected by this? The answer lies in designing your database (and application). Trusting your server's time zone settings and MySQL's time zone conversion abilities is a bad idea. Instead, use datetime fields and store UTC formatted values only.  You can always get the current date and time in UTC via UTC_TIMESTAMP(), e.g.:

 mysql> SELECT UNIX_TIMESTAMP(), UTC_TIMESTAMP(), NOW();
+------------------+---------------------+---------------------+
| UNIX_TIMESTAMP() | UTC_TIMESTAMP() | NOW() |
+------------------+---------------------+---------------------+
| 1351384200 | 2012-10-28 00:30:00 | 2012-10-28 02:30:00 |
+------------------+---------------------+---------------------+
1 row in set (0.00 sec)

Alternatively, you could store unix timestamps in unsigned int columns. But then you can not reliably use all those useful documented MySQL date and time functions, and, you would have to write your own date and time calculations using math in queries which can get messy.

A disadvantage of storing all values in a datetime field is that you cannot make use anymore of the CURRENT_TIMESTAMP default value. But then again, if you need to store values outside the timestamp range or need 100% reliability, that might be one of your lesser concerns.

Conclusion
Use UTC formatted date and time values within MySQL and your application for reliability    . Store all your date and time values in UTC format in a datetime column.
6 Comments
Tomas
7/1/2012 06:30:47 pm

Eh, no discussion about using unix timestamps, which imho is superior to both options discussed here ... quite pointless

Reply
Rasmus Schultz link
6/10/2013 03:05:13 am

UTC timestamps stored in a DATETIME column is effectively the same thing as unix timestamps - the key difference is that timestamps in DATETIME columns, as opposed to INT columns, are exposed in a format that makes sense to humans; underneath the hood, they are effectively stored and indexed the same way.

Reply
shayne oneill
6/27/2013 06:56:27 pm

Thats because its a discussion about mysql time, not unix time. You should ONLY store time in mysql using mysql time, NOT unix time, and for very good reasons, as mysql is going to give you pretty undefined behavior as soon as you factor in timezones and so on. unix time is local to your machine, mysql however correctly accounts for time zones and so on, and thus you won't have truly accurate time if you use unix timestamps.

Reply
Brian Mowrey
1/7/2014 01:04:49 am

Unix time, or POSIX time, is a system for describing instants in time, defined as the number of seconds that have elapsed since 00:00:00 Coordinated Universal Time (UTC), Thursday, 1 January 1970

It is not local to your machine, so it would be the same as storing UTC_TIMESTAMP, although like Rasmus said above, UTC_TIMESTAMP is more readable

Ryan
7/24/2012 12:23:24 am

Excellent article.

It recently helped me decide between using datetime vs int.

Reply
Paul
11/20/2017 02:52:47 am

Thank you for the helpful article!

Reply

Your comment will be posted after it is approved.


Leave a Reply.

    Author

    Blog about random challenges of a web developer.

    Archives

    April 2015
    May 2013
    January 2013
    July 2012
    June 2012

    Categories

    All
    Aws
    Cdn
    Code Igniter
    Css
    H2database
    Jamp
    Java
    Javascript
    Magento
    Maven
    Mysql
    Opencl
    Php
    Play-framework
    Quercus
    Scala
    Ubuntu

    RSS Feed

Powered by Create your own unique website with customizable templates.