View Source migraterl (migraterl v0.5.0)

migraterl public API.

A forward-only SQL migration engine for PostgreSQL 18+. Scripts are grouped into a namespace and classified as once, on_change or always; the engine diffs the directories against the temporal journal and applies only what is needed, one namespace-locked run at a time.

Example 

Conn = migraterl:default_connection(),
{ok, Summary} = migraterl:migrate(Conn, #{
    namespace => <<"app">>,
    sources => [
        {once,      "priv/migrations/schema"},
        {on_change, "priv/migrations/views"},
        {always,    "priv/migrations/grants"}
    ],
    txn => per_script,
    variables => #{<<"env">> => <<"prod">>}
}).

Summary

Types

namespace()
summary()
warning()

Functions

default_connection()

A default local/CI connection driven by PG* environment variables.

migrate(Conn, OptsMap)

Apply all pending migrations for the given configuration.

plan(Conn, OptsMap)

Dry run: compute and return what would be applied without touching any target schema (the journal is still created and read).

status(Conn, Namespace)

The currently-applied journal state for a namespace.

Types

namespace()

-type namespace() :: binary().

summary()

-type summary() ::
          #{planned := [binary()],
            applied := [binary()],
            skipped := [binary()],
            warnings := [warning()]}.

warning()

-type warning() :: {out_of_order, binary()} | {drift, binary()} | {missing, binary()}.

Functions

default_connection()

-spec default_connection() -> epgsql:connection() | {error, term()}.

A default local/CI connection driven by PG* environment variables.

migrate(Conn, OptsMap)

-spec migrate(epgsql:connection(), map()) -> {ok, summary()} | {error, term()}.

Apply all pending migrations for the given configuration.

plan(Conn, OptsMap)

-spec plan(epgsql:connection(), map()) -> {ok, summary()} | {error, term()}.

Dry run: compute and return what would be applied without touching any target schema (the journal is still created and read).

status(Conn, Namespace)

-spec status(epgsql:connection(), namespace()) -> {ok, [map()]} | {error, term()}.

The currently-applied journal state for a namespace.