Why use `utc_datetime` over `naive_datetime` for Ecto?

Hi all,

Trying to get some more clarity over utc_datetime and naive_datetime for Ecto:


The documentation above suggests that while NaiveDateTime doesn’t store any
TimeZone data associated with it, DateTime seems to, however the former, when used,
Ecto seems to store timestamps (inserted_at, updated_at) in according to UTC timezone anyway.
I read that using utc_datetime “ensures” that dates are always converted to utc before getting stored/retrieved from and to the database, however I am not sure what the significance of the “ensures” aspect here is, since naive_datetime seems to do it anyway.

And I also think storing timestamptz values in the database may not be really required, since I can just store utc timestamps everywhere and user timezone preferences in another table and use these two pieces of info to convert accordingly before presenting to the users.

Can someone throw some light on what the real world significance in using utc_datetime type for timestamps is? What am I missing here?

1 Like

You’re correct. timestamp columns are actually better for ecto (alone) as with timestamptz postgres will try to convert the timestamp to the clients timezone on its own. While for timestamp you can be sure postgres just leaves timestamps as is, with ecto handling all the timezone stuff at runtime using the settings/timezone db of elixir.

naive_datetime does store timestamps as UTC datetimes – that’s true. But that’s only “accidental” because it’s using NaiveDateTime.utc_now() to generate timestamps. If you manually set such fields to a different naive datetime you build from another timezone there’s no way for ecto to detect that. NaiveDateTime structs just don’t have a timezone component, which is the reason why they’re called naive.

For utc_datetime ecto will enforce that any saved datetime uses the Etc/UTC timezone. It’ll error otherwise. If you query the record you’ll also get back only datetimes with tthe timezone set to UTC. So the fact that datetimes use UTC changed from being implicit and prone to error with naive_datetime to explicit and enforced at runtime with utc_datetime.


This only works for automatically generated fields like inserted_at and updated_at and if you manually set other datetime fields to DateTime.utc_now(). But if you have any other Elixir code that is not timezone-aware and it fetches time in the local timezone (or have a legacy DB with non-UTC datetimes in it) then you’re in for trouble.

Better to do all of these together:

  • Use utc_datetime type for datetime fields in your Ecto schema modules.
  • When setting times manually, always start with DateTime.utc_now() and/or do calculations with Elixir’s stdlib or timex, always making sure you use UTC.
  • If you have to work with an inherited legacy database, just make a one-off script to convert any non-UTC datetimes to UTC. It will save you a world of trouble in the future.

Definitely use :utc_datetime_*. In hindsight, we wish we made that the default in Ecto but now we can’t due to backwards compatibility (and there are no plans for Ecto 4)

Here are some resources:


Thank you all so much! this sums it up, once and for all !
So basically it’s just great that Ecto is enforcing saving DateTime values in utc with the utc_datetime, which I feel really positive about since it’s a standard development practice. I’ve seen no other library/framework enforcing it.

I made the following global changes to my Phoenix 1.5 app to use utc_datetime instead of naive_datetime by Ecto, both in schemas and migrations for anyone who may find it useful:

In config.exs, I added this:

config :myapp, MyApp.Repo, migration_timestamps: [type: :utc_datetime]

created a new schema.ex with the following code:

defmodule MyApp.Schema do
  defmacro __using__(_) do
    quote do
      use Ecto.Schema
      @timestamps_opts [type: :utc_datetime]

And in my models everywhere, I replaced use Ecto.Schema with use MyApp.Schema

And, done!


I do almost the same:

@timestamps_opts [type: :utc_datetime_usec]

You likely will have cases when you would need sub-second precision. Even if you never do I’d think this extra precision won’t cost you almost anything in terms of disk space.

I started with :utc_datetime but switched to :utc_datetime_usec just because it got annoying having to do DateTime.utc_now() |> DateTime.truncate(:second) every time. I don’t really need the precision but it seemed to be less friction for the stuff I’ve done so far.


Sounds great! then I’ll make this change in my app to get rid of this friction, nothin’ much to lose here anyway.