#
View Source Vtc.Ecto.Postgres.PgFramestamp.Migrations (vtc v0.13.15)

Migrations for adding framestamp types, functions and constraints to a Postgres database.

# Link to this section Summary

## Types

constraint_opt()

Option types for `create_constraints/2`.

raw_sql()

Indicates returned string is am SQL command.

sql_value()

SQL value that can be passed as an atom or a string.

## Full

create_all(opts \\ [])

Adds raw SQL queries to a migration for creating the database types, associated functions, casts, operators, and operator families.

## Pg Constraints

create_constraints(table, field, opts \\ [])

Creates basic constraints for a PgFramestamp / Framestamp database field.

## Pg Types

create_function_schemas()

Creates function schema as described by the Configuring Database Objects section above.

create_type_framestamp()

Adds `framestamp` composite type.

## Pg Operators

create_op_add()

Creates a custom :framestamp, :framestamp `+` operator.

create_op_div_rational()

Creates a custom :framestamp, :rational `/` operator.

create_op_eq()

Creates a custom :framestamp, :framestamp `=` operator that returns true if the real-world seconds values for both framestamps are equal.

create_op_gt()

Creates a custom :framestamp, :framestamp `>` operator.

create_op_gte()

Creates a custom :framestamp, :framestamp `>=` operator.

create_op_lt()

Creates a custom :framestamp, :framestamp `<` operator.

create_op_lte()

Creates a custom :framestamp, :framestamp `<=` operator.

create_op_modulo_rational()

Creates a custom :framestamp, :rational `%` operator.

create_op_mult_rational()

Creates a custom :framestamp, :rational `*` operator.

create_op_neq()

Creates a custom :framestamp, :framestamp `<>` operator that returns true if the real-world seconds values for both framestamps are not equal.

create_op_strict_eq()

Creates a custom :framestamp, :framestamp `===` operator that returns true if both the real-world seconds values and the framerates for both framestamps are equal.

create_op_strict_neq()

Creates a custom :framestamp, :framestamp `!===` operator that returns true if `a` and `b` do not have the same real-world-seconds, framerate playback, or framerate tags.

create_op_sub()

Creates a custom :framestamp, :framestamp `-` operator.

## Pg Operator Classes

create_op_class_btree()

Creates a B-tree operator class to support indexing on comparison operations.

## Pg Functions

create_func_floor_div_rational()

Creates `DIV(:framestamp, :rational)` that returns a floored :framestamp to match Postgres' DIV(real, real) behavior.

create_func_frames()

Converts `framestamp` to a frame number by the frame's index in the timecode stream, with `0` as SMPTE midnight.

create_func_with_frames()

Creates `framestamp.with_frames(frames, rate)` that creates a framestamp for the given frame count.

create_func_with_seconds()

`framestamp.with_seconds(seconds, rate)`

## Pg Private Functions

create_func_add()

Creates `framestamp.__private__add(a, b)` that backs the `+` operator.

create_func_cmp()

Creates `framestamp.__private__cmp(a, b)` used in the PgTimecode b-tree operator class.

create_func_div_rational()

Creates `framestamp.__private__div(:framestamp, :rational)` that backs the `/` operator.

create_func_eq()

`framestamp.__private__eq(framestamp, framestamp)`

create_func_gt()

Creates `framestamp.__private__gt(a, b)` that backs the `>` operator.

create_func_gte()

Creates `framestamp.__private__gte(a, b)` that backs the `>=` operator.

create_func_lt()

Creates `framestamp.__private__lt(a, b)` that backs the `<` operator.

create_func_lte()

Creates `framestamp.__private__lte(a, b)` that backs the `<=` operator.

create_func_modulo_rational()

Creates `framestamp.__private__modulo(:framestamp, :rational)` that backs the `%` operator.

create_func_mult_rational()

Creates `framestamp.__private__mult(:framestamp, :rational)` that backs the `*` operator.

create_func_neq()

Creates `framestamp.__private__neq(a, b)` that backs the `<>` operator.

create_func_strict_eq()

Creates `framestamp.__private__strict_eq(a, b)` that backs the `===` operator.

create_func_strict_neq()

Creates `framestamp.__private__strict_neq(a, b)` that backs the `!===` operator.

create_func_sub()

`framestamp.__private__sub(a, b)`.

## Functions

function(name, repo)

Returns the config-qualified name of the function for this type.

# Link to this section Types

Link to this type

# constraint_opt()

View Source

    @type constraint_opt() ::
      {:create_seconds_divisible_by_rate?, boolean()}
      | {:framerate_opts, Vtc.Ecto.Postgres.PgFramerate.Migrations.constraint_opt()}

Option types for `create_constraints/2`.

Link to this type

# raw_sql()

View Source

    @type raw_sql() :: String.t()

Indicates returned string is am SQL command.

Link to this type

# sql_value()

View Source

    @type sql_value() :: String.t() | atom()

SQL value that can be passed as an atom or a string.

# Link to this section Full

Link to this function

# create_all(opts \\ [])

View Source

    @spec create_all(include: Keyword.t(), exclude: Keyword.t()) :: :ok

Adds raw SQL queries to a migration for creating the database types, associated functions, casts, operators, and operator families.

This migration included all migraitons under the Pg Types, Pg Operators, Pg Operator Classes, Pg Functions, and Pg Private Functions, headings.

Safe to run multiple times when new functionality is added in updates to this library. Existing values will be skipped.

Individual migration functions return raw sql commands in an {up_command, down_command} tuple.

##

options

Options

- `include`: A list of migration functions to inclide. If not set, all sub-migrations will be included.

- `exclude`: A list of migration functions to exclude. If not set, no sub-migrations will be excluded.

##

types-created

Types Created

Calling this macro creates the following type definitions:

    CREATE TYPE framestamp AS (
      seconds rational,
      rate framerate
    );

##

schemas-created

Schemas Created

Up to two schemas are created as detailed by the Configuring Database Objects section below.

##

configuring-database-objects

Configuring Database Objects

To change where supporting functions are created, add the following to your Repo confiugration:

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

Option definitions are as follows:

- `functions_schema`: The postgres schema to store framestamp-related custom functions.

- `functions_prefix`: A prefix to add before all functions. Defaults to "framestamp" for any function created in the `:public` schema, and "" otherwise.

##

private-functions

Private Functions

Some custom function names are prefaced with `__private__`. These functions should not be called by end-users, as they are not subject to any API staility guarantees.

##

examples

Examples

    defmodule MyMigration do
      use Ecto.Migration

      alias Vtc.Ecto.Postgres.PgFramestamp
      require PgFramestamp.Migrations

      def change do
        PgFramestamp.Migrations.create_all()
      end
    end

# Link to this section Pg Constraints

Link to this function

# create_constraints(table, field, opts \\ [])

View Source

    @spec create_constraints(atom(), atom(), [constraint_opt()]) :: :ok

Creates basic constraints for a PgFramestamp / Framestamp database field.

##

options

Options

- `create_seconds_divisible_by_rate?`: If true, creates `{field_name}_seconds_divisible_by_rate` constraint (see below). Default: `true`.

- `framerate_opts`: Opts for framerate constraints. See PgFramerate.Migrations.create_constraints/3

##

constraints-created

Constraints created:

- `{field}_rate_positive`: Checks that the playback speed is positive.

- `{field}_rate_ntsc_tags`: Checks that both `drop` and `non_drop` are not set at the same time.

- `{field}_rate_ntsc_valid`: Checks that NTSC framerates are mathematically sound, i.e., that the rate is equal to `(round(rate.playback) * 1000) / 1001`.

- `{field}_rate_ntsc_drop_valid`: Checks that NTSC, drop-frame framerates are valid, i.e, are cleanly divisible by `30_000/1001`.

- `{field_name}_seconds_divisible_by_rate`: Checks that the `seconds` value of the framestamp is cleanly divisible by the `rate.playback` value.

##

examples

Examples

    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

    PgRational.migration_add_field_constraints(:my_table, :a)
    PgRational.migration_add_field_constraints(:my_table, :b)

# Link to this section Pg Types

Link to this function

# create_function_schemas()

View Source

    @spec create_function_schemas() :: {raw_sql(), raw_sql()}

Creates function schema as described by the Configuring Database Objects section above.

Link to this function

# create_type_framestamp()

View Source

    @spec create_type_framestamp() :: {raw_sql(), raw_sql()}

Adds `framestamp` composite type.

# Link to this section Pg Operators

Link to this function

# create_op_add()

View Source

    @spec create_op_add() :: {raw_sql(), raw_sql()}

Creates a custom :framestamp, :framestamp `+` operator.

Just like Framestamp.add/3, if the `rate` of `a` and `b` are not equal, the result will inheret `a`'s framerate, and the internal `seconds` field will be rounded to the nearest whole-frame to ensure data integrity.

Link to this function

# create_op_div_rational()

View Source

    @spec create_op_div_rational() :: {raw_sql(), raw_sql()}

Creates a custom :framestamp, :rational `/` operator.

Just like Framestamp.div/3, `a`'s the internal `seconds` field will be rounded to the nearest whole-frame to ensure data integrity.

Unlike Framestamp.div/3, the result is rounded to the closest frame, rather than truncating ala integer division.

Link to this function

# create_op_eq()

View Source

    @spec create_op_eq() :: {raw_sql(), raw_sql()}

Creates a custom :framestamp, :framestamp `=` operator that returns true if the real-world seconds values for both framestamps are equal.

Link to this function

# create_op_gt()

View Source

    @spec create_op_gt() :: {raw_sql(), raw_sql()}

Creates a custom :framestamp, :framestamp `>` operator.

Link to this function

# create_op_gte()

View Source

    @spec create_op_gte() :: {raw_sql(), raw_sql()}

Creates a custom :framestamp, :framestamp `>=` operator.

Link to this function

# create_op_lt()

View Source

    @spec create_op_lt() :: {raw_sql(), raw_sql()}

Creates a custom :framestamp, :framestamp `<` operator.

Link to this function

# create_op_lte()

View Source

    @spec create_op_lte() :: {raw_sql(), raw_sql()}

Creates a custom :framestamp, :framestamp `<=` operator.

Link to this function

# create_op_modulo_rational()

View Source

    @spec create_op_modulo_rational() :: {raw_sql(), raw_sql()}

Creates a custom :framestamp, :rational `%` operator.

Just like Framestamp.rem/3, this operation is done on the frame count representation of the Framestamp, which is then used as the basis of a new framestamp.

Link to this function

# create_op_mult_rational()

View Source

    @spec create_op_mult_rational() :: {raw_sql(), raw_sql()}

Creates a custom :framestamp, :rational `*` operator.

Just like Framestamp.add/3, `a`'s the internal `seconds` field will be rounded to the nearest whole-frame to ensure data integrity.

Link to this function

# create_op_neq()

View Source

    @spec create_op_neq() :: {raw_sql(), raw_sql()}

Creates a custom :framestamp, :framestamp `<>` operator that returns true if the real-world seconds values for both framestamps are not equal.

Link to this function

# create_op_strict_eq()

View Source

    @spec create_op_strict_eq() :: {raw_sql(), raw_sql()}

Creates a custom :framestamp, :framestamp `===` operator that returns true if both the real-world seconds values and the framerates for both framestamps are equal.

Link to this function

# create_op_strict_neq()

View Source

    @spec create_op_strict_neq() :: {raw_sql(), raw_sql()}

Creates a custom :framestamp, :framestamp `!===` operator that returns true if `a` and `b` do not have the same real-world-seconds, framerate playback, or framerate tags.

Link to this function

# create_op_sub()

View Source

    @spec create_op_sub() :: {raw_sql(), raw_sql()}

Creates a custom :framestamp, :framestamp `-` operator.

Just like Framestamp.add/3, if the `rate` of `a` and `b` are not equal, the result will inheret `a`'s framerate, and the internal `seconds` field will be rounded to the nearest whole-frame to ensure data integrity.

# Link to this section Pg Operator Classes

Link to this function

# create_op_class_btree()

View Source

    @spec create_op_class_btree() :: {raw_sql(), raw_sql()}

Creates a B-tree operator class to support indexing on comparison operations.

# Link to this section Pg Functions

Link to this function

# create_func_floor_div_rational()

View Source

    @spec create_func_floor_div_rational() :: {raw_sql(), raw_sql()}

Creates `DIV(:framestamp, :rational)` that returns a floored :framestamp to match Postgres' DIV(real, real) behavior.

Just like Framestamp.div/3, this operation is done on the frame count representation of the Framestamp, which is then used as the basis of a new framestamp.

Link to this function

# create_func_frames()

View Source

    @spec create_func_frames() :: {raw_sql(), raw_sql()}

Converts `framestamp` to a frame number by the frame's index in the timecode stream, with `0` as SMPTE midnight.

Equivalent to Framestamp.frames/2 with `:round` set to `trunc`.

Link to this function

# create_func_with_frames()

View Source

    @spec create_func_with_frames() :: {raw_sql(), raw_sql()}

Creates `framestamp.with_frames(frames, rate)` that creates a framestamp for the given frame count.

Link to this function

# create_func_with_seconds()

View Source

    @spec create_func_with_seconds() :: {raw_sql(), raw_sql()}

`framestamp.with_seconds(seconds, rate)`

Rounds `seconds` to the nearest whole frame based on `rate` and returns a constructed `framestamp`.

# Link to this section Pg Private Functions

Link to this function

# create_func_add()

View Source

    @spec create_func_add() :: {raw_sql(), raw_sql()}

Creates `framestamp.__private__add(a, b)` that backs the `+` operator.

Just like Framestamp.add/3, if the `rate` of `a` and `b` are not equal, the result will inheret `a`'s framerate, and the internal `seconds` field will be rounded to the nearest whole-frame to ensure data integrity.

Link to this function

# create_func_cmp()

View Source

    @spec create_func_cmp() :: {raw_sql(), raw_sql()}

Creates `framestamp.__private__cmp(a, b)` used in the PgTimecode b-tree operator class.

Link to this function

# create_func_div_rational()

View Source

    @spec create_func_div_rational() :: {raw_sql(), raw_sql()}

Creates `framestamp.__private__div(:framestamp, :rational)` that backs the `/` operator.

Just like Framestamp.div/3, `a`'s the internal `seconds` field will be rounded to the nearest whole-frame to ensure data integrity.

Unlike Framestamp.div/3, the result is rounded to the closest frame, rather than truncating ala integer division.

Link to this function

# create_func_eq()

View Source

    @spec create_func_eq() :: {raw_sql(), raw_sql()}

`framestamp.__private__eq(framestamp, framestamp)`

Backs the `=` operator.

Link to this function

# create_func_gt()

View Source

    @spec create_func_gt() :: {raw_sql(), raw_sql()}

Creates `framestamp.__private__gt(a, b)` that backs the `>` operator.

Link to this function

# create_func_gte()

View Source

    @spec create_func_gte() :: {raw_sql(), raw_sql()}

Creates `framestamp.__private__gte(a, b)` that backs the `>=` operator.

Link to this function

# create_func_lt()

View Source

    @spec create_func_lt() :: {raw_sql(), raw_sql()}

Creates `framestamp.__private__lt(a, b)` that backs the `<` operator.

Link to this function

# create_func_lte()

View Source

    @spec create_func_lte() :: {raw_sql(), raw_sql()}

Creates `framestamp.__private__lte(a, b)` that backs the `<=` operator.

Link to this function

# create_func_modulo_rational()

View Source

    @spec create_func_modulo_rational() :: {raw_sql(), raw_sql()}

Creates `framestamp.__private__modulo(:framestamp, :rational)` that backs the `%` operator.

Just like Framestamp.rem/3, this operation is done on the frame count representation of the Framestamp, which is then used as the basis of a new framestamp.

Link to this function

# create_func_mult_rational()

View Source

    @spec create_func_mult_rational() :: {raw_sql(), raw_sql()}

Creates `framestamp.__private__mult(:framestamp, :rational)` that backs the `*` operator.

Just like Framestamp.add/3, `a`'s the internal `seconds` field will be rounded to the nearest whole-frame to ensure data integrity.

Link to this function

# create_func_neq()

View Source

    @spec create_func_neq() :: {raw_sql(), raw_sql()}

Creates `framestamp.__private__neq(a, b)` that backs the `<>` operator.

Link to this function

# create_func_strict_eq()

View Source

    @spec create_func_strict_eq() :: {raw_sql(), raw_sql()}

Creates `framestamp.__private__strict_eq(a, b)` that backs the `===` operator.

Link to this function

# create_func_strict_neq()

View Source

    @spec create_func_strict_neq() :: {raw_sql(), raw_sql()}

Creates `framestamp.__private__strict_neq(a, b)` that backs the `!===` operator.

Link to this function

# create_func_sub()

View Source

    @spec create_func_sub() :: {raw_sql(), raw_sql()}

`framestamp.__private__sub(a, b)`.

Backs the `-` operator.

Just like Framestamp.sub/3, if the `rate` of `a` and `b` are not equal, the result will inheret `a`'s framerate, and the internal `seconds` field will be rounded to the nearest whole-frame to ensure data integrity.

# Link to this section Functions

Link to this function

# function(name, repo)

View Source

    @spec function(atom(), Ecto.Repo.t()) :: String.t()

Returns the config-qualified name of the function for this type.