Database.Peregrin

Documentation

migrate :: ToRow p => Connection -> Schema -> [(Text, Query, p)] -> IO ()

Apply a list of migrations to a database. For example,

migrate conn schema [("a", "CREATE TABLE ...", QP $ Only $ Table schema "foo")]
                    [("b", "INSERT INTO TABLE ...", QP $ (Table schema "foo", "bar"))]

will apply the given SQL statements in order and track them by the identifiers "a" and "b". It is recommended to use fixed, randomly generated UUIDs to identify migrations, though you are free to use whatever identifiers you like as long as they are unique within the given schema. For example, on a Linux system you can run the command `uuidgen -r` on the command line and paste that into your migration list.

If the parameter sets are all of the same "shape" (type), then the `P $` prefix may be omitted — it serves only to make sure that the types match up.

The given Schema parameter indicates the schema used for the metadata stored to track which migrations have been applied. It does not affect the migrations themselves in any way. Therefore, ALL migrations should ALWAYS specify their schema explicitly in the SQL.

Any migrations that have already been applied will be skipped. If the SQL text for any given migration changes, a MigrationModifiedError exception will be thrown.

Migrations are tracked using two tables, namely "__peregrin_migration_meta__" and "__peregrin_migration__", which will automatically be created in the given Schema.

data MigrationError

Exception happened running migrations.

Constructors

MigrationModifiedError Text

The migration with the given ID has been modified in the program code since it was applied. Since this can have very unpredictable effects it is considered an error.

Instances

Eq MigrationError

Methods

(==) :: MigrationError -> MigrationError -> Bool

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

Show MigrationError

Methods

showsPrec :: Int -> MigrationError -> ShowS

show :: MigrationError -> String

showList :: [MigrationError] -> ShowS

Exception MigrationError

Methods

toException :: MigrationError -> SomeException

fromException :: SomeException -> Maybe MigrationError

displayException :: MigrationError -> String

data QP

Parameter wrapper for a query. Used in when there are several sets of parameters which must have the same type.

Constructors

ToRow p => QP p

Instances

ToRow QP

Methods

toRow :: QP -> [Action]