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

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

# Link to this section Summary

## Types

raw_sql()

Indicates returned string is am SQL command.

## Full

create_all(opts \\ [])

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

## Pg Types

create_function_schemas()

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

create_type_framestamp_fastrange()

Adds `framestamp_fastrange` RANGE type that uses double-precision floats under the hood.

create_type_framestamp_range()

Adds `framestamp_range` RANGE type.

inject_canonical_function()

There is a limitation with PL/pgSQL where shell-types cannot be used as either arguments OR return types.

## Pg Functions

create_func_framestamp_fastrange_from_range()

Creates `framestamp_fastrange(:framestamp_range)` to construct fast ranges out of the slower `framestamp_range` type.

create_func_framestamp_fastrange_from_stamps()

Creates `framestamp_fastrange(:framestamp, framestamp)` to construct fast ranges out of framestamps.

## Pg Private Functions

create_func_canonical()

Creates `framestamp.__private__canonicalization(a, b, type)` used by the range constructor to normalize ranges.

create_func_subtype_diff()

Creates `framestamp.__private__subtype_diff(a, b)` used by the range type for more efficient GiST indexes.

# Link to this section Types

Link to this type

# raw_sql()

View Source

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

Indicates returned string is am SQL command.

# 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 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.

> #### Required Permissions

> To add the `framestamp_range` canonical, function, we must directly add it to the `framestamp_range` type in the `pg_catalog` table. In most databases, this will require elevated permissions. See the `inject_canonical_function/0` for more information on why this is required.

> You can choose to skip this step if you wish my setting the `inject_canonical?` op to false, but operations that require discreet nudging of in and out points will not return correct results, and ranges with different upper/lowwer bound types will not be comparable.

##

types-created

Types Created

Calling this macro creates the following type definitions:

    CREATE TYPE framestamp_range AS RANGE (
      subtype = framestamp,
      subtype_diff = framestamp_range_private.subtype_diff
      canonical = framestamp_range_private.canonicalization
    );

    CREATE TYPE framestamp_fastrange AS RANGE (
      subtype = double precision,
      subtype_diff = float8mi
    );

##

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_range: [
          functions_schema: :framestamp_range,
          functions_prefix: "framestamp_range"
        ]
      ]

Option definitions are as follows:

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

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

##

examples

Examples

    defmodule MyMigration do
      use Ecto.Migration

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

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

# 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_fastrange()

View Source

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

Adds `framestamp_fastrange` RANGE type that uses double-precision floats under the hood.

Link to this function

# create_type_framestamp_range()

View Source

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

Adds `framestamp_range` RANGE type.

Link to this function

# inject_canonical_function()

View Source

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

There is a limitation with PL/pgSQL where shell-types cannot be used as either arguments OR return types.

However, in the user-facing API flow, the canonical function must be created before the range type with a shell type, then passed to the range type upon construction. Further, ALTER TYPE does not work on range functions out-of-the gate, so we cannot add it later... through the public API.

Instead this function edits the pg_catalog directly and supply the function after-the-fact ourselves. Since this will all happen in a single transaction it should be functionally equivalent to creating it on the type as part of the initial call.

> #### Permissions

> In most databases, directly editing the pg_catalog will require elevated permissions.

# Link to this section Pg Functions

Link to this function

# create_func_framestamp_fastrange_from_range()

View Source

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

Creates `framestamp_fastrange(:framestamp_range)` to construct fast ranges out of the slower `framestamp_range` type.

Link to this function

# create_func_framestamp_fastrange_from_stamps()

View Source

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

Creates `framestamp_fastrange(:framestamp, framestamp)` to construct fast ranges out of framestamps.

# Link to this section Pg Private Functions

Link to this function

# create_func_canonical()

View Source

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

Creates `framestamp.__private__canonicalization(a, b, type)` used by the range constructor to normalize ranges.

Output ranges have an inclusive lower bound and an exclusive upper bound.

Link to this function

# create_func_subtype_diff()

View Source

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

Creates `framestamp.__private__subtype_diff(a, b)` used by the range type for more efficient GiST indexes.