MojoX::Pg::Migrations::Env

Mojo::Pg migrations that replace environment placeholders in their sql.

A drop-in replacement for Mojo::Pg::Migrations. It is a subclass that loads, selects and applies migrations exactly like its parent, with one difference: placeholders in the migration sql are replaced with values from the environment when the sql is produced. That lets migrations refer to things that differ between environments, for example the name of a role to grant to.

The module is sponsored by Fibia.

-- 3 up
grant select on invoices to ${APP_READONLY_ROLE:-readonly};
-- 3 down
revoke select on invoices from ${APP_READONLY_ROLE:-readonly};

Nothing else is touched, so $1 and dollar quoted function bodies are safe, and migrations without placeholders produce the same sql as they do with Mojo::Pg::Migrations.

use Mojo::Pg;
use MojoX::Pg::Migrations::Env;

my $pg = Mojo::Pg->new('postgresql://app@/app');
$pg->migrations(MojoX::Pg::Migrations::Env->new(pg => $pg, name => 'app'));
$pg->migrations->from_file('db/migrations.sql')->migrate;

All sql between two versions is produced before any of it runs, so a missing variable aborts migrate with nothing applied. See the module documentation for env, placeholders and resolve, which tell what a migration needs and where each value comes from without running it.

Development procedure

Perl toolchain

We use ExtUtils::MakeMaker::CPANfile to handle the installation of MojoX::Pg::Migrations::Env.

ExtUtils::MakeMaker creates a Makefile that can build and install MojoX::Pg::Migrations::Env just like any other perl module on CPAN.

[!TIP] Run mise run prepare to build the code, create the Makefile and update the MANIFEST.

Tests

mise run test runs the tests. The ones that migrate a database are skipped unless TEST_ONLINE holds a database url with a search_path, which mise.toml sets for a local PostgreSQL. The tests create and drop the schema named in search_path.

External dependencies

If you have any external dependencies, add them to the cpanfile and install them using mise run install:dependencies

Release procedure

[!NOTE] If you want to override the next version, you can pass --next major to mise run release:create like so:

mise run release:create --next major

Any version identifier accepted by changie next can be used. (major, minor, patch and auto which is default)