You write SQL or haskell DSL database migrations, and they are
compiled into a migrate binary that knows how to run migrations,
roll them back, and inspect the state of the database. Since it is a
binary, it can be shipped around via whatever deployment mechanism you
use, and will be available in your production environment (where it
can talk to production databases), if you need that.
All migrations will be Haskell source files in a migrations
directory. They will be run in lexicographic order, which means you should
name them accordingly. The convention I've used in M2016..._description_of_change,
where the beginning is a full timestamp. You should create the migrations directory,
and then add a target to your cabal file.
Executable migrate
hs-source-dirs: src migrations
main-is: rivet.hs
Build-depends: base,
... -- same as your application
default-language: Haskell2010
An example migration might be:
{-# LANGUAGE OverloadedStrings #-}
module M20141211212630_add_type_to_gift_subscriptions where
import Control.Monad
import Database.Rivet.V0
migrate :: Migration IO ()
migrate = do addColumn "gift_subscriptions" (ColumnSpec "type" "text" Nothing (Just "not null"))
addColumn "gift_subscriptions" (ColumnSpec "country_code" "text" Nothing (Just "not null"))Or
{-# LANGUAGE OverloadedStrings #-}
module M20160521_add_to_addr_index where
import Control.Monad
import Database.Rivet.V0
migrate :: Migration IO ()
migrate = sql up down
up = "CREATE INDEX CONCURRENTLY email_archive_to_addr_idx ON email_archive (to_addr);"
down = "DROP INDEX email_archive_to_addr_idx;"See the full (at this point very limited) API in Database.Rivet.V0.
Then you should create migrations/rivet.hs. Currently, there is
still some copying / pasting, in particular, to figure out how to
connect to the database. The following will work, first loading
environment variables from a .env file if it exists, and then
looking for an env.cfg file in the configurator format where it
will find database connection info. You can change this to be however
your application manages database connections. The preprocessor line
(second in file) and the last two lines in the main function are
required; everything else could vary.
{-# LANGUAGE OverloadedStrings #-}
{-# OPTIONS_GHC -F -pgmF rivet-autoimporter #-}
module Main where
import qualified Configuration.Dotenv
import Control.Monad (when)
import qualified Data.Configurator as C
import Data.Monoid
import Database.Rivet.Adaptor.PostgreSQL
import qualified Database.Rivet.Main as Rivet
import System.Directory (doesFileExist)
import System.Environment
main :: IO ()
main = do e <- doesFileExist ".env"
when e $ Configuration.Dotenv.loadFile False ".env"
args <- getArgs
let (env, mode) =
case args of
[env', "up"] -> (env', Rivet.MigrateUp)
[env', "down"] -> (env', Rivet.MigrateDown)
[env', "status"] -> (env', Rivet.MigrateStatus)
_ -> error "Usage: [executable] [devel|prod|...] [up|down|status]"
conf <- C.load [C.Required (env <> ".cfg")]
host <- C.require conf "postgresql-simple.host"
port <- C.require conf "postgresql-simple.port"
user <- C.require conf "postgresql-simple.user"
pass <- C.require conf "postgresql-simple.pass"
db <- C.require conf "postgresql-simple.db"
adaptor <- setup id (ConnectInfo host port user pass db)
Rivet.main adaptor mode migrationsOnce you've done that, build your project as normal, and then run the
produced migrate binary. The main file provided has usage
instructions, though if you customize it, obviously these might vary.