mallard: Database migration and testing as a library.

[ database, library, mit, program ] [ Propose Tags ]

Please see

[Skip to Readme]


Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


  • No Candidates
Versions [RSS],,,,,,,,
Dependencies base (>=4 && <5), byteable, bytestring, cryptohash, exceptions, fgl, file-embed, hashable, hasql, hasql-optparse-applicative, hasql-pool, hasql-transaction, Interpolation, lens, mallard, megaparsec (>=6 && <7), mtl, optparse-applicative, optparse-text, path, path-io, text, unordered-containers [details]
License MIT
Copyright 2017 Andrew Rademacher <>
Author Andrew Rademacher
Category Database
Home page
Uploaded by andrewrademacher at 2017-09-24T19:06:55Z
Distributions NixOS:
Executables mallard
Downloads 5306 total (2 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2017-09-24 [all 1 reports]

Readme for mallard-

[back to package description]


No frills migration for relational databases. Usable as either an application or library.

Mallard offers the following key features:

  • Dependency resolution with circular reference prevention.
  • Native migration scripts.
  • Accretive implementation. Purposeful omission of "down migrations."


There are currently no packaged distributions for Mallard, though they are coming soon. We were added to Stackage on Sep 21, 2017. So we just might make it into the LTS-9.6. Packaged distributions for Homebrew and Debian will be coming along soon. Currently, we don't know if there is any demand for Windows or RPM distribution, let us know if there is.

Supported Databases

  • PostgreSQL

Application Mini-Manual

migrator - applies PSQL database migrations.

Usage: mallard ROOT [--host ARG] [--port ARG] [--user ARG] [--password ARG]
               --database ARG [-t|--test]
  Apply migrations to a database server.

Available options:
  --host ARG               Server host (default: "")
  --port ARG               Server port (default: 5432)
  --user ARG               Username (default: "postgres")
  --password ARG           Password (default: "")
  --database ARG           Database name
  -t,--test                Run tests after migration.
  -h,--help                Show this help text

Migration Structure

Mallard is designed to use a single root folder for all the migrations that define a database. Within this folder any structure is permitted. However, we recommend something like the following.

- root
    - tables
        - person.sql
        - phone.sql
    - views
        - person_with_phone.sql
    - functions
        - add_phone.sql

Wherein the migrations related to a given entity are kept in a single file. One such file might look like the following.

-- #!migration
-- name: "tables/phone",
-- description: "Phone numbers attached to a person.",
-- requires: ["tables/person"];
SET search_path TO contact;

    id          BIGSERIAL       NOT NULL,
    owner_id    bigint          NOT NULL,
    digits      text            NOT NULL,

    PRIMARY KEY (id),
    FOREIGN KEY (owner_id) REFERENCES person(id)

-- #!migration
-- name: "tables/phone/name",
-- description: "Add name column to phone number.",
-- requires: ["tables/phone"];
SET search_path TO contact;

ALTER TABLE phone ADD COLUMN name text;

Mallard is perfectly happy to accept as many migrations in a single file as you are willing to put there. However, there are a few rules you will have to follow.

  • The SQL comments in which a migrations header are located must be contiguous.
  • Each migration or test must begin with #!migration or #!test.
  • Each header field must end with ,, or if it is the last field a ;.

These rules allow the header to be fully defined in the comments of an otherwise normal SQL file.