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

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:

• Don't Do This - PostgreSQL wiki
• Time zones in PostgreSQL, Elixir and Phoenix | AmberBit Sp. z o. o.
• How to save datetimes for future events - (when UTC is not the right answer)

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]
    end
  end
end

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.

Why was the migration_timestamps change in your config.exs necessary?

Because IIRC having inserted_at and updated_at being at a microsecond precision is not the default.

Because Ecto.SQL.Migration needs that configuration. AFAIK it is a different module from Ecto.Schema