timex_ecto v3.0.4 Timex.Ecto
Timex Plugin for Ecto
Getting Started
Learn how to add timex_ecto
to your Elixir project and start using it.
NOTE: You must use Timex 3.0.2 or greater with timex_ecto 3.x!
Adding timex_ecto To Your Project
To use timex_ecto with your projects, edit your mix.exs
file and add it as a dependency:
def application do
[ applications: [:timex_ecto, ...], ...]
end
defp deps do
[{:timex, "~> 3.0"},
{:timex_ecto, "~> 3.0"}]
end
Adding Timex types to your Ecto models
defmodule User do
use Ecto.Schema
schema "users" do
field :name, :string
# Stored as an ISO date (year-month-day), reified as Date
field :a_date, Timex.Ecto.Date # Timex version of :date
# Stored as an ISO time (hour:minute:second.fractional), reified as Timex.Duration
field :a_time, Timex.Ecto.Time # Timex version of :time
# Stored as an ISO 8601 datetime in UTC (year-month-day hour:minute:second.fractional),
# reified as DateTime in UTC
field :a_datetime, Timex.Ecto.DateTime # Timex version of :datetime
# DateTimeWithTimezone is a special case, please see the `Using DateTimeWithTimezone` section!
# Stored as a tuple of ISO 8601 datetime and timezone name ((year-month-day hour:minute:second.fractional, timezone)),
# reified as DateTime in stored timezone
field :a_datetimetz, Timex.Ecto.DateTimeWithTimezone # A custom datatype (:datetimetz) implemented by Timex
end
end
Using Timex with Ecto’s timestamps
macro
Super simple! Your timestamps will now be Timex.DateTime
structs instead of Ecto.DateTime
structs.
defmodule User do
use Ecto.Schema
use Timex.Ecto.Timestamps
schema "users" do
field :name, :string
timestamps
end
end
Using with Phoenix
Phoenix allows you to apply defaults globally to Ecto models via web/web.ex
by changing the model
function like so:
def model do
quote do
use Ecto.Schema
use Timex.Ecto.Timestamps
end
end
By doing this, you bring the Timex timestamps into scope in all your models.
Precision
By default Timex will generate a timestamp to the nearest second. If you would
like to generate a timestamp with more precision you can pass the option
usec: true
to the macro. This will configure Timex to generate timestamps
down to the microsecond level of precision.
use Timex.Ecto.Timestamps, usec: true
Example Usage
The following is a simple test app I built for vetting this plugin:
defmodule EctoTest.Repo do
use Ecto.Repo, otp_app: :timex_ecto_test
end
defmodule EctoTest.User do
use Ecto.Schema
use Timex.Ecto.Timestamps
schema "users" do
field :name, :string
field :date_test, Timex.Ecto.Date
field :time_test, Timex.Ecto.Time
field :datetime_test, Timex.Ecto.DateTime
field :datetimetz_test, Timex.Ecto.DateTimeWithTimezone
end
end
defmodule EctoTest do
import Ecto.Query
use Timex
alias EctoTest.User
alias EctoTest.Repo
def seed do
time = Duration.now
date = Timex.today
datetime = Timex.now
datetimetz = Timezone.convert(datetime, "Europe/Copenhagen")
u = %User{name: "Paul", date_test: date, time_test: time, datetime_test: datetime, datetimetz_test: datetimetz}
Repo.insert!(u)
end
def all do
query = from u in User,
select: u
Repo.all(query)
end
end
defmodule EctoTest.App do
use Application
def start(_type, _args) do
import Supervisor.Spec
tree = [worker(EctoTest.Repo, [])]
opts = [name: EctoTest.Sup, strategy: :one_for_one]
Supervisor.start_link(tree, opts)
end
end
And the results:
iex(1)> EctoTest.seed
14:45:43.461 [debug] INSERT INTO "users" ("date_test", "datetime_test", "datetimetz_test", "name", "time_test") VALUES ($1, $2, $3, $4, $5) RETURNING "id" [{2015, 6, 25}, {{2015, 6, 25}, {19, 45, 43, 457000}}, {{{2015, 6, 25}, {21, 45, 43, 457000}}, "Europe/Copenhagen"}, "Paul", {19, 45, 43, 457000}] OK query=3.9ms
%EctoTest.User{__meta__: %Ecto.Schema.Metadata{source: "users",
state: :loaded},
date_test: ~D[2015-06-25],
datetime_test: #<DateTime(2015-06-25T21:45:43.457Z Etc/UTC),
datetimetz_test: #<DateTime(2015-06-25T21:45:43.457+02:00 Europe/Copenhagen),
name: "Paul", time_test: #<Duration(P45Y6M6DT19H45M43.456856S)
iex(2)> EctoTest.all
14:45:46.721 [debug] SELECT u0."id", u0."name", u0."date_test", u0."time_test", u0."datetime_test", u0."datetimetz_test" FROM "users" AS u0 [] OK query=0.7ms
[%EctoTest.User{__meta__: %Ecto.Schema.Metadata{source: "users",
state: :loaded},
date_test: ~D[2015-06-25],
datetime_test: #<DateTime(2015-06-25T21:45:43.457Z Etc/UTC),
datetimetz_test: #<DateTime(2015-06-25T21:45:43.457+02:00 Europe/Copenhagen),
name: "Paul", time_test: #<Duration(PT19H45M43S)>]
iex(3)>
Additional Documentation
Documentation for Timex and timex_ecto are available here, and on hexdocs.
License
This project is MIT licended. See the LICENSE file in this repo.