Moto.Registry

This module exports tools for implementing a registry that moto can use in order to keep track of the migrations that have been run so far.

It's unlikely that you'll need to concern yourself with this module as an end user of moto.

Please import as:

import qualified Moto.Registry as Moto

Command-line support

data RegistryConf

Configuration for the Registry that we'll use to keep track of the migrations we've run so far.

Constructors

RegistryConf

Fields

• registryConf_help :: String

  Help message for the --registry command line option.

• registryConf_parse :: String -> Either String r

  Parse the string obtained from the --registry command line option, refining it into some r of our choosing acceptable as an input to registryConf_with.

  Ideally, this String should be an URI (e.g., file:///var/db/migrations, or postgres://user:password@host:port/database).

• registryConf_with :: forall a. r -> (Registry -> IO a) -> IO a

  Given the r obtained from registryConf_parse, get a Registry that can be used within the given scope.

Registry

data Registry

Migrations registry, keeping track of what migrations have been run so far, as well as those that are running.

Consider using newAppendOnlyRegistry as an easy way to create a Registry.

Constructors

Registry

Fields

• registry_state :: Df1 -> IO State

  Current registry state.

  The passed in Df1 can be used for logging if necessary (see Di and Di.Df1), but please don't log exceptions nor messages telling whether this function succeeds or fails, since this library already does that for you.

• registry_prepare :: Df1 -> MigId -> Direction -> IO (Either Err_Prepare Log)

  Register a new pending change in the registry.

  Returns the Log_Prepare that describes this change to the registry.

  • This is the first commit in the two-phase commit mechanism to registering migrations as executed (registry_commit is the second).
  • If Forwards, then the given MigId shall be recorded in the registry as fully exceuted after a subsequent registry_commit. If the given MigId is already present and committed in the registry, then registry_prepare shall return Err_Prepare_Duplicate.
  • If Backwards, then the given MigId, which must be already present and committed to the registry, will be removed from the list of currently committed migtrations after a subsequent registry_commit. If the MigId is not already present and committed in the registry, then registry_prepare shall return Err_Prepare_NotFound.
  • If there is already an uncommitted migration (that is, if the status is Dirty), then Err_Prepare_Dirty shall be returned. This constraint implies that it is impossible to have more than one pending change at a time.
  • After a successful call to registry_prepare, the registry will be left in a Dirty status until one of registry_commit or registry_abort is performed.

  The passed in Df1 can be used for logging if necessary (see Di and Di.Df1), but don't log exceptions nor messages telling whether this function succeeds or fails, since this library already does that for you.

• registry_abort :: Df1 -> MigId -> Direction -> IO (Either Err_Abort Log)

  Abort the pending change in the given Direction most recently introduced via registry_prepare, expected to be identified by the given MigId.

  Returns the Log_Abort that describes this change to the registry.

  If there is no pending change to be aborted (that is, if the status is Clean), then Err_Abort_Clean shall be returned.

  If the currently pending migration's identifier is different from the the given MigId, or if its execution was intended for a Direction different than the one specified here, then Err_Abort_Dirty shall be returned.

  After a successful call to registry_abort, the registry will be left in a Clean status.

  The passed in Df1 can be used for logging if necessary (see Di and Di.Df1), but don't log exceptions nor messages telling whether this function succeeds or fails, since this library already does that for you.

• registry_commit :: Df1 -> MigId -> Direction -> IO (Either Err_Commit Log)

  Commit the pending change in the given Direction most recently introduced via registry_prepare, expected to be identified by the given MigId.

  Returns the Log_Commit that describes this change to the registry.

  This is the first commit in the two-phase commit mechanism to registering migrations as executed (registry_prepare is the first).

  If there is no pending change to be committed (that is, if the status is Clean), then Err_Commit_Clean shall be returned.

  If the currently pending migration's identifier is different from the the given MigId, or if its execution was intended for a Direction different than the one specified here, then Err_Commit_Dirty shall be returned.

  After a successful call to registry_commit, the registry will be left in a Clean status.

  The passed in Df1 can be used for logging if necessary (see Di and Di.Df1), but don't log exceptions nor messages telling whether this function succeeds or fails, since this library already does that for you.

newAppendOnlyRegistry

Arguments

:: State

Initial registry state obtained by reading Logs from the backing append-only storage and running updateState on them.

-> (Log -> IO ())

How to store a newly generated Log in the backing append-only storage.

If this function throws an exception, then the execption will propagated as usual, but also, this registry will be marked as tained and each subsequent operation on it will throw Err_Tainted.

-> IO Registry

Create a Registry backed by an append-only Log storage.

This registry maintains its internal State in memory as long as it is possible to successfuly store all the changes in the underlying append-only storage. If at some point this fails unrecoverably, then Err_Tainted will be thrown by the functions acting on this Registry.

It's important to acquire some kind of exclusive lock on the underlying storage, so that other applications can't poke it while our Registry is running.

State

data State

Internal State of a Registry.

Create with emptyState and updateState.

Instances

Eq State

Defined in Moto.Internal

Methods

(==) :: State -> State -> Bool

(/=) :: State -> State -> Bool

Show State

Defined in Moto.Internal

Methods

showsPrec :: Int -> State -> ShowS

show :: State -> String

showList :: [State] -> ShowS

emptyState :: State

A clean State without any committed migrations.

updateState :: State -> Log -> Either Err_UpdateState State

Modify a State by applying a Log to it, if possible.

Use emptyState as the initial state.

foldlM updateState emptyState
  :: Foldable t
  => t Log
  -> Either Err_UpdateState State

data Log

A State can be described as a list of Logs ordered chronologically (see updateState).

Constructors

Log_Prepare UTCTime MigId Direction

A particular migration identified by MigId is going to be executed in the specified Direction.

This is the first commit in the two-phase commit approach to registering a migration as executed.

The time when this log entry was created is mentioned as well.

Log_Commit UTCTime

The migration most recently prepared for execution with Log_Prepare is being committed.

This is the second commit in the two-phase commit approach to registering a migration as executed.

The time when this log entry was created is mentioned as well.

Log_Abort UTCTime

The migration most recently prepared for execution with Log_Prepare is being aborted.

This undoes the first commit in the two-phase commit approach to registering a migration as executed.

The time when this log entry was created is mentioned as well.

Instances

Eq Log

Defined in Moto.Internal

Methods

(==) :: Log -> Log -> Bool

(/=) :: Log -> Log -> Bool

Read Log

Defined in Moto.Internal

Methods

readsPrec :: Int -> ReadS Log

readList :: ReadS [Log]

readPrec :: ReadPrec Log

readListPrec :: ReadPrec [Log]

Show Log

Defined in Moto.Internal

Methods

showsPrec :: Int -> Log -> ShowS

show :: Log -> String

showList :: [Log] -> ShowS

Errors

data Err_Tainted

The Registry is tainted, meaning our last attempt to interact with the registry's backing storage failed. We can't be certain about the current state of the Registry.

Constructors

Err_Tainted

Instances

Eq Err_Tainted

Defined in Moto.Registry

Methods

(==) :: Err_Tainted -> Err_Tainted -> Bool

(/=) :: Err_Tainted -> Err_Tainted -> Bool

Show Err_Tainted

Defined in Moto.Registry

Methods

showsPrec :: Int -> Err_Tainted -> ShowS

show :: Err_Tainted -> String

showList :: [Err_Tainted] -> ShowS

Exception Err_Tainted

Defined in Moto.Registry

Methods

toException :: Err_Tainted -> SomeException

fromException :: SomeException -> Maybe Err_Tainted

displayException :: Err_Tainted -> String

data Err_Prepare

Errors from registry_prepare.

Constructors

Err_Prepare_Duplicate MigId

Err_Prepare_NotFound MigId

Err_Prepare_Dirty MigId Direction

Instances

Eq Err_Prepare

Defined in Moto.Internal

Methods

(==) :: Err_Prepare -> Err_Prepare -> Bool

(/=) :: Err_Prepare -> Err_Prepare -> Bool

Show Err_Prepare

Defined in Moto.Internal

Methods

showsPrec :: Int -> Err_Prepare -> ShowS

show :: Err_Prepare -> String

showList :: [Err_Prepare] -> ShowS

Exception Err_Prepare

Defined in Moto.Internal

Methods

toException :: Err_Prepare -> SomeException

fromException :: SomeException -> Maybe Err_Prepare

displayException :: Err_Prepare -> String

data Err_Abort

Errors from registry_abort.

Constructors

Err_Abort_Clean

Err_Abort_Dirty MigId Direction

Instances

Eq Err_Abort

Defined in Moto.Internal

Methods

(==) :: Err_Abort -> Err_Abort -> Bool

(/=) :: Err_Abort -> Err_Abort -> Bool

Show Err_Abort

Defined in Moto.Internal

Methods

showsPrec :: Int -> Err_Abort -> ShowS

show :: Err_Abort -> String

showList :: [Err_Abort] -> ShowS

Exception Err_Abort

Defined in Moto.Internal

Methods

toException :: Err_Abort -> SomeException

fromException :: SomeException -> Maybe Err_Abort

displayException :: Err_Abort -> String

data Err_Commit

Errors from registry_commit.

Constructors

Err_Commit_Clean

Err_Commit_Dirty MigId Direction

Instances

Eq Err_Commit

Defined in Moto.Internal

Methods

(==) :: Err_Commit -> Err_Commit -> Bool

(/=) :: Err_Commit -> Err_Commit -> Bool

Show Err_Commit

Defined in Moto.Internal

Methods

showsPrec :: Int -> Err_Commit -> ShowS

show :: Err_Commit -> String

showList :: [Err_Commit] -> ShowS

Exception Err_Commit

Defined in Moto.Internal

Methods

toException :: Err_Commit -> SomeException

fromException :: SomeException -> Maybe Err_Commit

displayException :: Err_Commit -> String

data Err_UpdateState

Errors from updateState.

Constructors

Err_UpdateState_Duplicate MigId

Err_UpdateState_NotFound MigId

Err_UpdateState_Clean

Err_UpdateState_Dirty

Instances

Eq Err_UpdateState

Defined in Moto.Internal

Methods

(==) :: Err_UpdateState -> Err_UpdateState -> Bool

(/=) :: Err_UpdateState -> Err_UpdateState -> Bool

Show Err_UpdateState

Defined in Moto.Internal

Methods

showsPrec :: Int -> Err_UpdateState -> ShowS

show :: Err_UpdateState -> String

showList :: [Err_UpdateState] -> ShowS

Exception Err_UpdateState

Defined in Moto.Internal

Methods

toException :: Err_UpdateState -> SomeException

fromException :: SomeException -> Maybe Err_UpdateState

displayException :: Err_UpdateState -> String