This is the first article of a 2-part series. The second article is about a case study in multiple time zones.
Ruby provides two classes to manage time:
Since Ruby 1.9.3 there are fewer differences between the two libraries,
Time covering concepts of leapseconds and daylight saving time. For
the rest of this article,
Time will be used in all the examples.
TZInfo is another time zone library, which provides
daylight-saving-aware transformations between times in different time zones.
It is available as a gem and includes data on 582 different time zones.
Time zones in Rails
ActiveSupport::TimeZone is a wrapper around
TZInfo that limits the
set of zones provided by
TZInfo to a meaningful subset of 146 zones.
It displays zones with a friendlier name
(e.g. “Eastern Time (US & Canada)” instead of “America/New_York”).
And together with
Rails provides the same API as Ruby
Time instances, so that
ActiveSupport::TimeWithZone instances are interchangeable,
and you should never need to create a
In Rails, to see all the available time zones, run:
$ rake time:zones:all * UTC -11:00 * American Samoa International Date Line West Midway Island Samoa * UTC -10:00 * Hawaii * UTC -09:00 * Alaska ...
To check for the current set time zone, in console:
> Time.zone => #<ActiveSupport::TimeZone:0x007fbf46947b38 @current_period=#<TZInfo::TimezonePeriod: nil,nil,#<TZInfo::TimezoneOffset: 0,0,UTC>>>, @name="UTC", @tzinfo=#<TZInfo::TimezoneProxy: Etc/UTC>, @utc_offset=nil>
Still in console, to temporarily set a different time zone:
# in console > Time.zone = "Perth"
We can also permanently change our application time zone by
setting a config option in
# config/application.rb config.time_zone = "Perth"
The default time zone in Rails is UTC. As tempting as it may seem, it is best to leave the application-wide time zone as UTC and instead allow each individual user to set their own time zone. Check a case study in multiple time zones to see an example why.
With user time zones
Let’s decide that each of our users have their time zone defined. This can be
done by adding
:time_zone attribute to the
User model. Our migration might
look like so:
create_table :users do |t| t.string :time_zone, default: "UTC" ... end
We want to store the time zone as a string because
most of Rails’ time-zone-related methods use strings.
Above all, avoid storing time zones as
We can allow a user to set their own desired time zone when editing their
:time_zone and provides a form helper
so the user can select a time zone option from a select menu.
<%= f.input :time_zone %>
We can then use an
ApplicationController to apply
our user’s preferred time zone.
# app/controllers/application_controller.rb around_action :set_time_zone, if: :current_user private def set_time_zone(&block) Time.use_zone(current_user.time_zone, &block) end
We pass the current user’s time zone to
use_zone method on the
(a method which was added by
ActiveSupport). This method expects a block to be
passed to it and sets the time zone for the duration of that block,
so that when the request completes, the original time zone is set back.
If you are using Rails 3.2.13 or lower, instead of using
will need to use
And lastly, to display times in a specific user’s time zone,
we can use
<%= time.in_time_zone(current_user.time_zone) %>
Working with APIs
When working with APIs, it is best to use the
which represents date/time information as a string.
ISO8601’s advantages are that the string is
unambiguous, human readable, widely supported, and sortable.
The string looks like:
> timestamp = Time.now.utc.iso8601 => "2015-07-04T21:53:23Z"
Z at the end of the string indicates that this time is in UTC, not a
local time zone. To convert the string back to a
Time instance, we can say:
> Time.iso8601(timestamp) => 2015-07-04 21:53:23 UTC
Three time zones
In a Rails app, we have three different time zones:
- system time,
- application time, and
- database time.
Say we set our time zone to be Fiji. Let’s see what happens:
# This is the time on my machine, also commonly described as "system time" > Time.now => 2015-07-04 17:53:23 -0400 # Let's set the time zone to be Fiji > Time.zone = "Fiji" => "Fiji" # But we still get my system time > Time.now => 2015-07-04 17:53:37 -0400 # However, if we use `zone` first, we finally get the current time in Fiji > Time.zone.now => Sun, 05 Jul 2015 09:53:42 FJT +12:00 # We can also use `current` to get the same > Time.current => Sun, 05 Jul 2015 09:54:17 FJT +12:00 # Or even translate the system time to application time with `in_time_zone` > Time.now.in_time_zone => Sun, 05 Jul 2015 09:56:57 FJT +12:00 # Let's do the same with Date (we are still in Fiji time, remember?) # This again is the date on my machine, system date > Date.today => Sat, 04 Jul 2015 # But going through `zone` again, and we are back to application time > Time.zone.today => Sun, 05 Jul 2015 # And gives us the correct tomorrow according to our application's time zone > Time.zone.tomorrow => Mon, 06 Jul 2015 # Going through Rails' helpers, we get the correct tomorrow as well > 1.day.from_now => Mon, 06 Jul 2015 10:00:56 FJT +12:00
Time zone related querying
Rails saves timestamps to the database in UTC time zone.
We should always use
Time.current for any database queries,
so that Rails will translate and compare the correct times.
Post.where("published_at > ?", Time.current) # SELECT "posts".* FROM "posts" WHERE (published_at > '2015-07-04 17:45:01.452465')
A summary of do’s and don'ts with time zones
* Time.now * Date.today * Date.today.to_time * Time.parse("2015-07-04 17:05:37") * Time.strptime(string, "%Y-%m-%dT%H:%M:%S%z")
* Time.current * 2.hours.ago * Time.zone.today * Date.current * 1.day.from_now * Time.zone.parse("2015-07-04 17:05:37") * Time.strptime(string, "%Y-%m-%dT%H:%M:%S%z").in_time_zone
Testing time zones
Rails 4.1 added a
with three useful methods:
We can use these methods to freeze time within blocks in our tests.
If using an older version of Rails, there are three gems
to help us set and freeze the time in our tests:
Timecop, Delorean, and Zonebie.
As much as I love the reference to go
I usually use Timecop.
new_time = Time.zone.parse("2014-10-19 1:00:00") # With Timecop, we can freeze the time, Timecop.freeze new_time # or Timecop.travel new_time # but will need to clean up after the spec, and return to current time Timecop.return # Alternatively we can use blocks, which only freeze the time inside our block Time.use_zone("Sydney") do end # With Delorean, the syntax is a touch different Delorean.time_travel_to("1 month ago") do end Delorean.back_to_the_present # And Zonebie sets the time zone to a random one each time we run our tests Zonebie.set_random_timezone
If you want to learn how to persist future datetimes: check out How to save datetimes for future events article by Lau Taarnskov.
- Always work with UTC.
- Use testing helper methods of your choice to freeze the time in your tests, preferably by using a block.
Also remember to check out the second part of this article at a case study in multiple time zones.