Safe Haskell	None
Language	Haskell2010

Moto.Registry

Contents

Command-line support
Registry
State
Errors

Description

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

Synopsis

data RegistryConf = RegistryConf {
- registryConf_help :: String
- registryConf_parse :: String -> Either String r
- registryConf_with :: forall a. Df1 -> r -> (Registry -> IO a) -> IO a
}
data Registry = Registry {
- registry_state :: Df1 -> IO State
- registry_prepare :: Df1 -> MigId -> Direction -> IO (Either Err_Prepare Log)
- registry_abort :: Df1 -> MigId -> Direction -> IO (Either Err_Abort Log)
- registry_commit :: Df1 -> MigId -> Direction -> IO (Either Err_Commit Log)
}
newAppendOnlyRegistry :: State -> (Log -> IO ()) -> IO Registry
data State
emptyState :: State
updateState :: State -> Log -> Either Err_UpdateState State
data Log
- = Log_Prepare UTCTime MigId Direction
- | Log_Commit UTCTime
- | Log_Abort UTCTime
data Err_Tainted = Err_Tainted
data Err_Prepare
data Err_Abort
- = Err_Abort_Clean
- | Err_Abort_Dirty MigId Direction
data Err_Commit
- = Err_Commit_Clean
- | Err_Commit_Dirty MigId Direction
data Err_UpdateState

Command-line support

data RegistryConf Source #

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.
This could be something like /var/db/migrations or postgres://user:password@host:port/database.
registryConf_with :: forall a. Df1 -> 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 Source #

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

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

Internal State of a Registry.

Create with emptyState and updateState.

Instances

Eq State Source #
Instance details Defined in Moto.Internal Methods (==) :: State -> State -> Bool # (/=) :: State -> State -> Bool #
Show State Source #
Instance details Defined in Moto.Internal Methods showsPrec :: Int -> State -> ShowS # show :: State -> String # showList :: [State] -> ShowS #

emptyState :: State Source #

A clean State without any committed migrations.

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

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

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 Source #
Instance details Defined in Moto.Internal Methods (==) :: Log -> Log -> Bool # (/=) :: Log -> Log -> Bool #
Read Log Source #
Instance details Defined in Moto.Internal Methods readsPrec :: Int -> ReadS Log # readList :: ReadS [Log] # readPrec :: ReadPrec Log # readListPrec :: ReadPrec [Log] #
Show Log Source #
Instance details Defined in Moto.Internal Methods showsPrec :: Int -> Log -> ShowS # show :: Log -> String # showList :: [Log] -> ShowS #

Errors

data Err_Tainted Source #

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 Source #
Instance details Defined in Moto.Registry Methods (==) :: Err_Tainted -> Err_Tainted -> Bool # (/=) :: Err_Tainted -> Err_Tainted -> Bool #
Show Err_Tainted Source #
Instance details Defined in Moto.Registry Methods showsPrec :: Int -> Err_Tainted -> ShowS # show :: Err_Tainted -> String # showList :: [Err_Tainted] -> ShowS #
Exception Err_Tainted Source #
Instance details Defined in Moto.Registry Methods toException :: Err_Tainted -> SomeException # fromException :: SomeException -> Maybe Err_Tainted # displayException :: Err_Tainted -> String #

data Err_Prepare Source #

Errors from registry_prepare.

Constructors

Err_Prepare_Duplicate MigId
Err_Prepare_NotFound MigId
Err_Prepare_Dirty MigId Direction

Instances

Eq Err_Prepare Source #
Instance details Defined in Moto.Internal Methods (==) :: Err_Prepare -> Err_Prepare -> Bool # (/=) :: Err_Prepare -> Err_Prepare -> Bool #
Show Err_Prepare Source #
Instance details Defined in Moto.Internal Methods showsPrec :: Int -> Err_Prepare -> ShowS # show :: Err_Prepare -> String # showList :: [Err_Prepare] -> ShowS #
Exception Err_Prepare Source #
Instance details Defined in Moto.Internal Methods toException :: Err_Prepare -> SomeException # fromException :: SomeException -> Maybe Err_Prepare # displayException :: Err_Prepare -> String #

data Err_Abort Source #

Errors from registry_abort.

Constructors

Err_Abort_Clean
Err_Abort_Dirty MigId Direction

Instances

Eq Err_Abort Source #
Instance details Defined in Moto.Internal Methods (==) :: Err_Abort -> Err_Abort -> Bool # (/=) :: Err_Abort -> Err_Abort -> Bool #
Show Err_Abort Source #
Instance details Defined in Moto.Internal Methods showsPrec :: Int -> Err_Abort -> ShowS # show :: Err_Abort -> String # showList :: [Err_Abort] -> ShowS #
Exception Err_Abort Source #
Instance details Defined in Moto.Internal Methods toException :: Err_Abort -> SomeException # fromException :: SomeException -> Maybe Err_Abort # displayException :: Err_Abort -> String #

data Err_Commit Source #

Errors from registry_commit.

Constructors

Err_Commit_Clean
Err_Commit_Dirty MigId Direction

Instances

Eq Err_Commit Source #
Instance details Defined in Moto.Internal Methods (==) :: Err_Commit -> Err_Commit -> Bool # (/=) :: Err_Commit -> Err_Commit -> Bool #
Show Err_Commit Source #
Instance details Defined in Moto.Internal Methods showsPrec :: Int -> Err_Commit -> ShowS # show :: Err_Commit -> String # showList :: [Err_Commit] -> ShowS #
Exception Err_Commit Source #
Instance details Defined in Moto.Internal Methods toException :: Err_Commit -> SomeException # fromException :: SomeException -> Maybe Err_Commit # displayException :: Err_Commit -> String #

data Err_UpdateState Source #

Errors from updateState.

Constructors

Err_UpdateState_Duplicate MigId
Err_UpdateState_NotFound MigId
Err_UpdateState_Clean
Err_UpdateState_Dirty

Instances

Eq Err_UpdateState Source #
Instance details Defined in Moto.Internal Methods (==) :: Err_UpdateState -> Err_UpdateState -> Bool # (/=) :: Err_UpdateState -> Err_UpdateState -> Bool #
Show Err_UpdateState Source #
Instance details Defined in Moto.Internal Methods showsPrec :: Int -> Err_UpdateState -> ShowS # show :: Err_UpdateState -> String # showList :: [Err_UpdateState] -> ShowS #
Exception Err_UpdateState Source #
Instance details Defined in Moto.Internal Methods toException :: Err_UpdateState -> SomeException # fromException :: SomeException -> Maybe Err_UpdateState # displayException :: Err_UpdateState -> String #