https://github.com/zerowidth/jetlag
AR timezone fixes for 2.3.x
https://github.com/zerowidth/jetlag
Last synced: 12 months ago
JSON representation
AR timezone fixes for 2.3.x
- Host: GitHub
- URL: https://github.com/zerowidth/jetlag
- Owner: zerowidth
- License: mit
- Created: 2011-04-12T19:57:47.000Z (about 15 years ago)
- Default Branch: master
- Last Pushed: 2012-06-06T15:33:40.000Z (about 14 years ago)
- Last Synced: 2025-04-03T09:32:39.007Z (about 1 year ago)
- Language: Ruby
- Homepage:
- Size: 117 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Jetlag
Patches for ActiveRecord 2.3.x timezone-handling code to allow for non-UTC
databases.
Rails 3 mostly works, see discussion below.
## Synopsis
This rails plugin patches ActiveRecord to fix the time quoting when timezones
are involved, especially when using a non-UTC database.
This started as a set of specs to explore the various combinations of
ActiveRecord and related time zone settings and their effect on timestamp values
as written and retrieved from a non-timezone-aware database.
The underlying motivation was to figure out the edge cases that exist when a
database is not running in UTC, and find where the ActiveRecord code fails to
handle this correctly. Eventually it ended up becoming a patch to correct the
invalid behavior.
## Rails 3
Rails 3 timezone handling is correct, especially with the default settings. If
your database is not in UTC, make sure `ENV["TZ"]` for your rails app is set
appropriately, and set `ActiveRecord::Base.default_timezone = :local`. For more
details, see the rails3 branch -- there are specs there showing that the
behavior is correct, even when changing Time.zone "per request".
## Discussion
The rails convention is to keep all data in UTC. If, however, due to legacy
reasons, your database is *not* UTC, Rails is unable to write (and thus read)
dates with the correct timezone. This can lead to subtle bugs and, essentially,
corrupted data.
ActiveRecord does the incorrect thing in the following cases (copied from spec
output):
with Time.zone_default set (i.e. config.time_zone=) and default_timezone = :local and time_zone_aware_attributes = true (default)
- writes local Time objects to the database in UTC (invalid storage)
- writes local UTC Time objects as UTC (invalid storage)
- writes TimeWithZone objects using UTC (invalid storage)
- reads the timestamp as local but with the UTC offset (invalid round-trip)
with Time.zone_default set (i.e. config.time_zone=) and default_timezone = :local and time_zone_aware_attributes = false
- writes bare UTC timestamps as UTC (invalid storage)
- writes TimeWithZone objects as UTC (invalid storage)
with Time.zone_default set (i.e. config.time_zone=) and AR::Base.default_timezone = :utc (default) and time_zone_aware_attributes = false
- does not write bare timestamps as UTC (invalid storage)
- reads the timestamp as UTC (invalid round trip)
with Time.zone_default not set (i.e. config.time_zone is nil) with default_timezone as :local (default)
- writes bare UTC timestamps as UTC (invalid storage)
with Time.zone_default not set (i.e. config.time_zone is nil) with default_timezone as :utc
- does not write local timestamps as UTC (invalid storage)
Jetlag patches AR's column quoting to handle timezones correctly.
## Installation
To use in your Rails 2.3.x application (as a plugin):
script/plugin install https://github.com/aniero/jetlag.git
If your database is not in UTC, set `ENV["TZ"]` explicitly in your
`config/environment.rb` to match the database's timezone, and also add the
following line after `config.time_zone = 'UTC'`:
config.active_record.default_timezone = :local
To run manually, e.g. non-rails use of ActiveRecord:
require "jetlag"
Jetlag.enable
To run the specs:
bundle
rake