Skip to content
A friendly PostgreSQL script runner in the spirit of DbUp.
C C# C++ Rich Text Format Other
Branch: dev
Clone or download
Latest commit 3bee99c Jul 9, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
build Resolves #2 - publish binaries for macOS and Linux Jul 23, 2017
src/Datalust.Piggy Tidy up connection handling Jul 9, 2019
test/Datalust.Piggy.Tests Add ILLink/netcoreapp2.0 Aug 30, 2017
.gitignore Initial commit Jul 19, 2017
Build.ps1 Tweak artifact output path Jul 9, 2019
LICENSE Initial commit Jul 19, 2017 C# API Jul 9, 2019
nuget.config Add ILLink/netcoreapp2.0 Aug 30, 2017
piggy.sln Bye, nuget.config Jul 9, 2019
piggy.sln.DotSettings C# API Jul 9, 2019


A friendly PostgreSQL script runner in the spirit of DbUp.

Build status Join the chat at

What is Piggy?

Piggy is a simple command-line tool for managing schema and data changes to PostgreSQL databases. Piggy looks for .sql files in a directory and applies them to the database in order, using transactions and a change log table to ensure each script runs only once per database.


Piggy is available for Windows, macOS and Linux from the releases page. Download the MSI or archive file for your platform. If your platform of choice isn't listed, please raise an issue here so that we can add it.


To manage database updates with Piggy, write SQL scripts to make changes, rather than applying changes directly.

Organize change scripts on the file system under a script root directory. Name files so that they sort lexicographically in the order in which they need to be executed:


If the scripts are arranged in subdirectories, these must be ordered by name as well:


Piggy enumerates .sql files and generates names like /v1/001-create-schema.sql using each script's filename relative to the script root. These relative names are checked against the change log table to determine which of them need to be run.

To bring a database up to date, run piggy up, providing the script root, host, database name, username and password:

piggy up -s <scripts> -h <host> -d <database> -u <username> -p <password>

If the database does not exist, Piggy will create it using sensible defaults. To opt out of this behavior, add the --no-create flag.

Over time, as your application grows, create new scripts to move the database forwards - don't edit the existing ones, since they've already been applied and will be ignored by Piggy.

Piggy can be used to update from any previous schema version to the current one: scripts that have already been run on a database are ignored, so only necessary scripts are applied.

For more detailed usage information, run piggy help up; to see all available commands run piggy help.


Piggy wraps each script in a transaction that also covers the change log table update. A few DDL statements can't run within a transaction in PostgreSQL - in these cases, add:


as the first line of the script.

Variable substitution

Piggy uses $var$ syntax for replaced variables:

create table $schema$.users (name varchar(140) not null);
insert into $schema$.users (name) values ('$admin$');

Values are inserted using pure text substitution: no escaping or other processing is applied. If no value is supplied for a variable that appears in a script, Piggy will leave the script unchanged (undefined variables will not be replaced with the empty string).

Variables are supplied on the command-line with the -v flag:

piggy up ... -v schema=myapp -v admin=myuser

Change log

The change log is stored in the target database in piggy.changes. The piggy log command is used to view applied change scripts.


Run piggy help to see all available commands, and piggy help <command> for detailed command help.

> piggy help
Usage: piggy <command> [<args>]

Available commands are:
  baseline   Add scripts to the change log without running them
  help       Show information about available commands
  log        List change scripts that have been applied to a database
  pending    Determine which scripts will be run in an update
  up         Bring a database up to date
  --version  Print the current executable version

Type `piggy help <command>` for detailed help


For development and test automation purposes, the core script runner is also packaged as a C♯ API and published to NuGet as Datalust.Piggy.

// dotnet add package Datalust.Piggy
var connectionString = // Npgsql connection string
using (var connection = DatabaseConnector.Connect(connectionString, createIfMissing: true)
    UpdateSession.ApplyChangeScripts(connection, "./db", new Dictionary<string, string>());
You can’t perform that action at this time.