Settings View Source Print cheatsheet Ecto Quickstart

ecto-types

Ecto types

The custom Ecto & Postgres types provided by Vtc are:

PgRational

• Migrations Schema
• Not re-exported, Ratio is not owned by Vtc.

PgFramerate

• Migrations Schema
• Re-exported by Framerate

PgFramestamp

• Migrations Schema
• Re-exported by Framestamp

PgFramestamp.Range

• Migrations Schema
• Re-exported by Framestamp.Range

configuration

Configuration

Additional configuration is done at the Repo level:

config :vtc, Vtc.Test.Support.Repo,
  adapter: Ecto.Adapters.Postgres,
  vtc: [
    rational: [
      functions_schema: :rational,
      functions_prefix: ""
    ],
    framerate: [
      functions_schema: :framerate,
      functions_prefix: ""
    ],
    framestamp: [
      functions_schema: :framestamp,
      functions_prefix: ""
    ],
    framestamp_range: [
      functions_schema: :framestamp_range,
      functions_prefix: ""
    ]
  ]

config :vtc,
  ecto_repos: [Vtc.Test.Support.Repo]

Each type can be configured to store it's support functions on a schema of your choice as well as have a custom, per-type function name prefix.

By default, all functions are added to the public schema, and are prefaced by their type name. For example, the PgFramestamp frames function is created in the public schema, and named framestamp_frames.

initial-migration

Initial Migration

To create all the Postgres types, functions, operators, casts, and operator classes that Vtc provides, run the following migration:

defmodule Vtc.Test.Support.Repo.Migrations.AddPostgresTypes do
  @moduledoc false
  use Ecto.Migration

  def change do
    Vtc.Ecto.Postgres.Migrations.run()
  end
end

This migration is safe to run multiple times, and can be run again when new functionality is added to Vtc. All migrations implement both up and down functionality, and support rollbacks out of the box.

All objects created by the migration come complete with in-database documentation with links to the relevant Vtc docs. Using DataGrip:

ecto-api

Ecto API

Vtc's custom Ecto types are each implemented in a dedicated module. For instance, the framestamp type is implemented by PgFramestamp.

However, each ecto type's functions are re-exported by the Vtc elixir type it is designed to work with, allowing you to mostly ignore the dedicated ecto module when creating migrations and schemas:

defmodule MyApp.MySchema do
  @moduledoc false
  use Ecto.Migration

  alias Vtc.Ecto.Postgres.PgFramestamp
  alias Vtc.Framestamp

  def change do
    create table("my_table", primary_key: false) do
      add(:id, :uuid, primary_key: true, null: false)
      add(:a, Framestamp.type())
      add(:b, Framestamp.type())
    end
  end
end

Each type ships with a set of custom constraints that can be used for data integrity validation in migrations:

Framestamp constraint docs

def change do
  create table("my_table", primary_key: false) do
    add(:b, Framestamp.type())
  end

  PgFramestamp.Migrations.create_constraints("my_table", :b)
end

Vtc modules can be used directly in schemas:

Framestamp changeset casting docs

defmodule Vtc.Test.Support.FramestampSchema01 do
  @moduledoc false
  use Ecto.Schema

  alias Ecto.Changeset
  alias Vtc.Framestamp

  @type t() :: %__MODULE__{
          id: Ecto.UUID.t(),
          a: Framestamp.t(),
          b: Framestamp.t()
        }

  @primary_key {:id, Ecto.UUID, autogenerate: true}

  schema "my_table" do
    field(:a, Framestamp)
    field(:b, Framestamp)
  end

  @spec changeset(%__MODULE__{}, %{atom() => any()}) :: Changeset.t(%__MODULE__{})
  def changeset(schema, attrs), do: Changeset.cast(schema, attrs, [:id, :a, :b])
end

Values can be used in Ecto queries using the type/2 function. Vtc registers native operators for each type, so you can write queries like you would expect to with any other numeric type:

query value

iex> one_hour = Framestamp.with_frames("01:00:00:00", Rates.f23_98())
iex> 
iex> EdlEvents
iex> |> where([event], event.start > type(^one_hour, Framestamp))
iex> |> select([event], {event, event.end - event.in_framestamp})

The above query finds all events with a start time greater than 01:00:00:00 and returns the record AND its calculated duration.

private-functions

Private functions

Many of Vtc's postgres functions are prefaced with __private__, for instance, the framestamp__private__add function is used to back the addition + operator.

These functions have no API stability guarantee, and callers should avoid calling them directly.

framestamp-postgres-operators

Framestamp Postgres operators

Available operators

.

iex> a = Framestamp.with_frames!("01:00:00:00", Rates.f23_98())
iex> b = Framestamp.with_frames!("01:00:00:00", Rates.f47_95())
iex> 
iex> query =
iex>   Query.from(
iex>     f in fragment(
iex>       "SELECT "? +@ ? as r",
iex>       type(^a, Framestamp),
iex>       type(^b, Framestamp)
iex>     ),
iex>     select: f.r
iex>   )
iex> 
iex> Repo.one!(query) |> Framestamp.load() |> inspect()
"{:ok, <02:00:00:00 <47.95 NTSC>>}"

SELECT
  (18018, 5, 24000, 1001, '{non_drop}')::framestamp
  +@ (18018, 5, 48000, 1001, '{non_drop}')::framestamp;

                   ?column?
-----------------------------------------------
 ("(36036,5)","(""(48000,1001)"",{non_drop})")
(1 row)

rational-postgres-operators

Rational Postgres operators

Available operators