Orville.PostgreSQL.AutoMigration

Facilities for performing some database migrations automatically. See autoMigrateSchema as a primary, high-level entry point.

Since: 1.0.0.0

Documentation

data MigrationOptions

Options to control how autoMigrateSchema and similar functions behave. You should use defaultOptions to construct a MigrationOptions value and then use the record accessors to change any values you want to customize.

Since: 1.0.0.0

defaultOptions :: MigrationOptions

The default MigrationOptions, which is to run both the schema changes and concurrent index creations together using the default Orville migration lock.

Since: 1.0.0.0

autoMigrateSchema :: MonadOrville m => MigrationOptions -> [SchemaItem] -> m ()

This function compares the list of SchemaItems provided against the current schema found in the database to determine whether any migrations are necessary. If any changes need to be made, this function executes. You can call generateMigrationPlan and executeMigrationPlan yourself if you want to have more control over the process, but must then take care to ensure that the schema has not changed between the two calls. This function uses a PostgreSQL advisory lock to ensure that no other calls to autoMigrateSchema (potentially on other processes) attempt to modify the schema at the same time.

Since: 1.0.0.0

data SchemaItem where

A SchemaItem represents a single item in a database schema such as a table, index or constraint. The constructor functions below can be used to create items from other types (such as TableDefinition) to put them into a list to be used with autoMigrateSchema.

Since: 1.0.0.0

Constructors

SchemaTable :: TableDefinition key writeEntity readEntity -> SchemaItem

Constructs a SchemaItem from a TableDefinition. @since 1.0.0.0

SchemaDropTable :: TableIdentifier -> SchemaItem

Constructs a SchemaItem that will drop the specified table if it is found in the database. @since 1.0.0.0

SchemaSequence :: SequenceDefinition -> SchemaItem

Constructs a SchemaItem from a SequenceDefinition. @since 1.0.0.0

SchemaDropSequence :: SequenceIdentifier -> SchemaItem

Constructs a SchemaItem that will drop the specified table if it is found in the database. @since 1.0.0.0

schemaItemSummary :: SchemaItem -> String

Returns a one-line string describing the SchemaItem, suitable for a human to identify it in a list of output.

For example, a SchemaItem constructed via SchemaTable gives Table <table name>.

Since: 1.0.0.0

data MigrationPlan

A MigrationPlan contains an ordered list of migration steps. Each one is a single DDL statement to make a specific database change. The steps are ordered such that dependencies from earlier steps will be in place before a later step is executed (e.g. new columns are added before foreign keys referring to them).

While most steps are executed together in a single transaction this is not possible for indexes being created concurrently. Any such steps are executed last after the transaction for the rest of the schema changes has been successfully committed.

Since: 1.0.0.0

generateMigrationPlan :: MonadOrville m => MigrationOptions -> [SchemaItem] -> m MigrationPlan

Compares the list of SchemaItems provided against the current schema found in the database and returns a MigrationPlan that could be executed to make the database schema match the items given.

You can execute the MigrationPlan yourself using the executeMigrationPlan convenience function, though autoMigrateSchema is usually a better option because it uses a database lock to ensure that no other processes are also using autoMigrateSchema to apply migrations at the same time. If you use generateMigrationPlan and executeMigrationPlan separately, you are responsible for ensuring that the schema has not changed between the time the plan is generated and executed yourself.

Since: 1.0.0.0

migrationPlanSteps :: MigrationPlan -> [MigrationStep]

Returns all the MigrationSteps found in a MigrationPlan together in a single list. This is useful if you merely want to examine the steps of a plan rather than execute them. You should always use executeMigrationPlan to execute a migration plan to ensure that the transactional steps are done within a transaction while the concurrent index steps are done afterward outside of it.

Since: 1.0.0.0

executeMigrationPlan :: MonadOrville m => MigrationOptions -> MigrationPlan -> m ()

Executes a MigrationPlan that has been previously devised via generateMigrationPlan. Normally all the steps in a migration plan are executed in a transaction so that they will all be applied together successfully or all rolled-back if one of them fails. Any indexes using the Concurrent creation strategy cannot be created this way, however, because PostgreSQL does not allow CREATE INDEX CONCURRENTLY to be used from inside a transaction. If a MigrationPlan includes any indexes whose creation strategy is set to Concurrent, Orville will create indexes after the rest of the migration steps have been committed successfully. This function will wait until all of the migration steps that it runs to finish before returning. If one of the concurrent indexes fails during creation, it will be left in an invalid state (as is the default PostgreSQL behavior). You should check on the status of indexes created this way manually to ensure they were created successfully. If they could not be, you can drop them and Orville will re-attempt creating them the next time migration is performed.

Since: 1.0.0.0

data MigrationStep

A single SQL statement that will be executed in order to migrate the database to the desired result. You can use generateMigrationPlan to get a list of these yourself for inspection and debugging.

Since: 1.0.0.0

Instances

SqlExpression MigrationStep

Since: 1.0.0.0

Defined in Orville.PostgreSQL.AutoMigration

Methods

toRawSql :: MigrationStep -> RawSql

unsafeFromRawSql :: RawSql -> MigrationStep

data MigrationDataError

A MigrationDataError will be thrown from the migration functions if data necessary for migration cannot be found.

Since: 1.0.0.0

Instances

Exception MigrationDataError

Since: 1.0.0.0

Defined in Orville.PostgreSQL.AutoMigration

Methods

toException :: MigrationDataError -> SomeException

fromException :: SomeException -> Maybe MigrationDataError

displayException :: MigrationDataError -> String

Show MigrationDataError

Since: 1.0.0.0

Defined in Orville.PostgreSQL.AutoMigration

Methods

showsPrec :: Int -> MigrationDataError -> ShowS

show :: MigrationDataError -> String

showList :: [MigrationDataError] -> ShowS

data MigrationLockId

Identifies a PostgreSQL advisory lock to to be aquired by the application. Use defaultLockId to obtain the default value and nextLockId to create custom values if you need them.

Since: 1.0.0.0

defaultLockId :: MigrationLockId

The lock id that Orville uses by default to ensure that just one copy of the application is attempting to run migrations at a time.

Since: 1.0.0.0

nextLockId :: MigrationLockId -> MigrationLockId

Increments the id of the given MigrationLockId, creating a new distinct lock id. You can use this to create your own custom MigrationLockId values as necessary if you need to control migration runs in a custom manner.

Since: 1.0.0.0

withMigrationLock :: MonadOrville m => MigrationLockId -> m a -> m a

Executes an Orville action with a PostgreSQL advisory lock held that indicates to other Orville processes that a database migration is being done and no others should be performed concurrently.

Since: 1.0.0.0

data MigrationLockError

Raised if withMigrationLock cannot acquire the migration lock in a timely manner.

Since: 1.0.0.0

Instances

Exception MigrationLockError

Defined in Orville.PostgreSQL.Internal.MigrationLock

Methods

toException :: MigrationLockError -> SomeException

fromException :: SomeException -> Maybe MigrationLockError

displayException :: MigrationLockError -> String

Show MigrationLockError

Defined in Orville.PostgreSQL.Internal.MigrationLock

Methods

showsPrec :: Int -> MigrationLockError -> ShowS

show :: MigrationLockError -> String

showList :: [MigrationLockError] -> ShowS