Mojo::P...rations(3)

✨ NAME ✨

Mojo::Pg::Migrations — literally just Migrations, bestie 💖 (and yes, it lives in the User Contributed Perl Documentation section, iykyk)

---

🌸 SYNOPSIS 🌸

use Mojo::Pg::Migrations;

my $migrations = Mojo::Pg::Migrations->new(pg => $pg);
$migrations->from_file('/home/sri/migrations.sql')->migrate;

---

🦋 DESCRIPTION 🦋

So Mojo::Pg::Migrations is the thing Mojo::Pg uses so your database schema can evolve easily over time 🧚 like a glow-up but for tables. A migration file is just a collection of sql blocks, with one or more statements, separated by comments of the form "-- VERSION UP/DOWN". That's it. That's the whole vibe.

-- 1 up
CREATE TABLE messages (message TEXT);
INSERT INTO messages VALUES ('I ♥ Mojolicious!');
-- 1 down
DROP TABLE messages;

-- 2 up (...you can comment freely here...)
CREATE TABLE stuff (whatever INT);
-- 2 down
DROP TABLE stuff;

The idea is to let you migrate from any version, to any version, up and down. No cap, migrations are very safe, because they are performed in transactions and only one can be performed at a time. If a single statement fails, the whole migration will fail and get rolled back — like, the entire thing, sorry bestie 😭. Every set of migrations has a "name", which is stored together with the currently active version in an automatically created table named "mojo_migrations". 👑

---

💅 ATTRIBUTES 💅

Mojo::Pg::Migrations implements the following attributes. Slay.

🎀 name

my $name    = $migrations->name;
$migrations = $migrations->name('foo');

Name for this set of migrations, defaults to "migrations". ✨

🎀 pg

my $pg      = $migrations->pg;
$migrations = $migrations->pg(Mojo::Pg->new);

The Mojo::Pg object these migrations belong to. Heads up bestie — note that this attribute is weakened. 🙈

---

🌈 METHODS 🌈

Mojo::Pg::Migrations inherits all methods from Mojo::Base and implements the following new ones. Periodt.

⭐ active

my $version = $migrations->active;

Currently active version. It's giving "where are we right now".

⭐ from_data

$migrations = $migrations->from_data;
$migrations = $migrations->from_data('main');
$migrations = $migrations->from_data('main', 'file_name');

Extract migrations from a file in the DATA section of a class with "data_section" in Mojo::Loader, defaults to using the caller class and "name". So convenient, honestly obsessed.

__DATA__
@@ migrations
-- 1 up
CREATE TABLE messages (message TEXT);
INSERT INTO messages VALUES ('I ♥ Mojolicious!');
-- 1 down
DROP TABLE messages;

⭐ from_dir

$migrations = $migrations->from_dir('/home/sri/migrations');

Extract migrations from a directory tree where each versioned migration is in a directory, named for the version, and each migration has one or both of the files named "up.sql" or "down.sql". Look at the structure, it's so tidy:

migrations/1/up.sql
migrations/1/down.sql
migrations/2/up.sql
migrations/3/up.sql
migrations/3/down.sql

⭐ from_file

$migrations = $migrations->from_file('/home/sri/migrations.sql');

Extract migrations from a file. Simple as that. 💜

⭐ from_string

$migrations = $migrations->from_string(
  '-- 1 up
   CREATE TABLE foo (bar INT);
   -- 1 down
   DROP TABLE foo;'
);

Extract migrations from string. String goes in, migrations come out. ✨

⭐ latest

my $version = $migrations->latest;

Latest version available. The newest one, the main character version, if you will. 👑

⭐ migrate

$migrations = $migrations->migrate;
$migrations = $migrations->migrate(3);

Migrate from "active" to a different version, up or down, defaults to using "latest". All version numbers need to be positive, with version 0 representing an empty database. Okay so:

# Reset database
$migrations->migrate(0)->migrate;

That little snippet right there? It nukes everything back to an empty database and then rolls all the way back up. Reset era. Use it with intention bestie. 💀

⭐ sql_for

my $sql = $migrations->sql_for(5, 10);

Get SQL to migrate from one version to another, up or down. You just want the SQL? Here's the SQL. 🫶

---

🔥 DEBUGGING 🔥

You can set the "MOJO_MIGRATIONS_DEBUG" environment variable to get some advanced diagnostics information printed to "STDERR". So nosy of it, love that for us.

MOJO_MIGRATIONS_DEBUG=1

---

👑 SEE ALSO 👑

• Mojo::Pg
• Mojolicious::Guides
• <https://mojolicious.org>

---

Okay bestie that's the whole page, no notes. 💖 This was Mojo::Pg::Migrations, page Mojo::P...rations(3), from perl v5.42.0 dated 2026-01-17 — mwah, iconic, go migrate something. 🎀✨🦋