Tempo.SQL.Migration (Tempo SQL v0.1.0)

View Source

Ecto migration helpers for the Tempo PostgreSQL range types.

These helpers wrap the underlying Postgres types — tstzrange and tstzmultirange — under Tempo-flavoured names, so a migration reads in the same vocabulary as the schema:

import Tempo.SQL.Migration

create table(:meetings) do
  add_interval :window
  add_interval_set :busy, null: false
end

create_interval_index :meetings, :window

All helpers are thin delegates to Ecto.Migration.add/3 and Ecto.Migration.index/3 — callers can also write the raw add :window, :tstzrange form if they prefer.

Summary

Functions

add_interval(field, options \\ [])

Add a tstzrange column for a Tempo.Ecto.Interval field.

add_interval_set(field, options \\ [])

Add a tstzmultirange column for a Tempo.Ecto.IntervalSet field.

add_tempo_multirange(field, options \\ [])

Add a tempo_multirange column for a Tempo.Ecto.TempoMultirange field.

add_tempo_range(field, options \\ [])

Add a tempo_range column for a Tempo.Ecto.TempoRange field.

create_interval_index(table, column, options \\ [])

Create a GiST index on a tstzrange or tstzmultirange column.

create_tempo_types()

Create the composite types used by Tempo.Ecto.TempoRange and Tempo.Ecto.TempoMultirange.

drop_tempo_types()

Drop the composite types created by create_tempo_types/0.

Functions

add_interval(field, options \\ [])

(macro)

Add a tstzrange column for a Tempo.Ecto.Interval field.

Arguments

  • field is the column name as an atom.

  • options are passed through to Ecto.Migration.add/3 — for example null: false, default: ....

Examples

add_interval :window
add_interval :window, null: false

add_interval_set(field, options \\ [])

(macro)

Add a tstzmultirange column for a Tempo.Ecto.IntervalSet field.

Requires PostgreSQL 14 or later.

Arguments

Examples

add_interval_set :busy_times
add_interval_set :free_slots, null: false

add_tempo_multirange(field, options \\ [])

(macro)

Add a tempo_multirange column for a Tempo.Ecto.TempoMultirange field.

Requires create_tempo_types/0 to have been run in an earlier migration.

add_tempo_range(field, options \\ [])

(macro)

Add a tempo_range column for a Tempo.Ecto.TempoRange field.

Requires create_tempo_types/0 to have been run in an earlier migration.

Examples

add_tempo_range :reporting_period
add_tempo_range :reporting_period, null: false

create_interval_index(table, column, options \\ [])

(macro)

Create a GiST index on a tstzrange or tstzmultirange column.

Range-operator queries (@>, &&, -|-) are only fast under a GiST index — this helper wraps create index(..., using: :gist).

Arguments

  • table is the table name.

  • column is the range column to index.

  • options are passed through to Ecto.Migration.index/3.

Examples

create_interval_index :meetings, :window

create_tempo_types()

Create the composite types used by Tempo.Ecto.TempoRange and Tempo.Ecto.TempoMultirange.

This should be run once, in an early migration, before any schema declares a tempo_range or tempo_multirange column:

defmodule MyApp.Repo.Migrations.CreateTempoTypes do
  use Ecto.Migration
  import Tempo.SQL.Migration

  def up,   do: create_tempo_types()
  def down, do: drop_tempo_types()
end

Creates two PostgreSQL composite types:

CREATE TYPE tempo_range AS (
  range      tstzrange,
  resolution text,
  meta       jsonb
);

CREATE TYPE tempo_multirange AS (
  ranges     tstzmultirange,
  resolution text,
  meta       jsonb
);

These are the round-trip-preserving counterparts to the plain tstzrange / tstzmultirange columns used by Tempo.Ecto.Interval and Tempo.Ecto.IntervalSet.

drop_tempo_types()

Drop the composite types created by create_tempo_types/0.

Intended for use in down/0 callbacks. Fails if any column still uses either type — drop the columns first.