Standalone PostgreSQL Migration Runner using Migratus runnable as a native-image binary.

There are BREAKING changes since release 0.4.0 changing most environment variables and some command line options to match psql.

See Changelog for upgrade path hints.

There are prebuild binaries that you can download from Github Releases.

The latest PGMig build can be pulled from the dockerhub.

Follow the build instructions below and place the resulting binary in your path, e.g. to /usr/local/bin.

lein with-profile native do clean, test, uberjar

If you have already GraalVM CE installed and properly set GRAAL_HOME, JAVA_HOME and PATH you can try to build and run the native image locally. You need Graal 21.2 release with native-image to build and deploy pgmig successfully.

From the project directory create the uberjar and run the create-image.sh helper script.

lein with-profile native do clean, test, uberjar
./create-image.sh target/uberjar/pgmig.jar

You can use both pgmig command line options or environment variables when running it (command line options have the priority).

./pgmig -h localhost -p 5432 -d pgmig -U pgmig -P pgmig -r samples/db/migrations pending

Status code 0 is returned on success, non-zero return code signals an error.

Note that you need the same .so libraries that the native binary is linked to on the target machine. Also keep in mind that you might need to add -Djava.library.path=<path-to-shared-libs> as a pgmig option if it needs to load some libraries dynamically (including shared libraries from the JDK itself). When building the docker image the .so library addition is done automatically.

The docker image is based on the GraalVM Community Edition Official Image. Once you have successfully built the uberjar you can create the migration runner image itself

lein with-profile native do clean, test, uberjar
docker build -t leafclick/pgmig .

PGMig supports following commands:

The following options skip all other actions:

For example to apply all pending migrations run the migrate command

pgmig -h localhost -p 5432 -d pgmig -U pgmig -P pgmig -r samples/db/migrations --classpath samples/db/clj migrate

Note that if you use clj programmatic migrations (using sci) you need to list all directories that contain migration support code files (if there are any). You can usually create a classpath list by running lein classpath or clj -Spath in the project.

To try out the basic functionality you can run the uberjar itself. To get help and available commands run

java -jar target/uberjar/pgmig.jar 

To list pending migrations (uberjar)

java -jar target/uberjar/pgmig.jar -h localhost -p 5432 -d pgmig -U pgmig -P pgmig -r samples/db/migrations pending

To run the native image within the docker container set the environment, bind the migrations directory and specify the action

docker run -ti \
           --rm \
           --mount "type=bind,src=$PWD/samples/db/migrations,dst=/migrations" \
           --mount "type=bind,src=$PWD/samples/db/clj,dst=/clj" \
           -e PGHOST=172.17.0.2 \
           -e PGDATABASE=pgmig \
           -e PGUSER=pgmig \
           -e PGPASSWORD=pgmig \
           -e RESOURCE_DIR=migrations \
           -e CLASSPATH=clj \
           leafclick/pgmig migrate

For now the expected output is something like this

20180830154000 first
20190216143455 second
20201106155531 programmatic-third

You can safely ignore warnings about unsupported features as they are not used by PGMig.

There is a number of Graal's SubstrateVM LIMITATTIONS and they all apply to PGMig.

Because of this the only supported(*) JDBC driver is PostgreSQL JDBC DataSource which is bundled with PGMig binary.

(*) not all features are supported but the basics work well

Copyright © 2019-2021 leafclick s.r.o.

Licensed under the Apache License, Version 2.0.