DBIx::C...rsioning(3)

✨ NAME ✨

DBIx::Class::DeploymentHandler::HandlesVersioning — bestie, it's the interface for version methods. That's it, that's the whole job. It's giving "I define the vibe, you do the work." 💅

This page is from the User Contributed Perl Documentation collection, and we're about to make it make sense. 🫶

---

🌸 DESCRIPTION 🌸

Okay so picture this: a VersionHandler is gonna take a to_version and hand you back an iterator of version sets. Iconic behavior honestly. ✨

Like, typically when you call a VersionHandler's next_version_set with a db_version of 1 and a to_version of 5, it's gonna iterate over something like this:

[1, 2]
[2, 3]
[3, 4]
[4, 5]
undef

or maybe just

[1, 5]
undef

ngl, how the version sets actually get arranged is entirely up to the VersionHandler you're using. Not our problem, not our business. 💀

In some cases users won't want versions to have inherent "previous versions," which is lowkey exactly why the version set is an ArrayRef. In those cases, bestie, you should just return the version that the database is being upgraded to in each step. Simple. Clean. Slay. 💖

One idea that got suggested to me — and honestly it's kinda galaxy brain — is having a form of dependency management for the database "versions." In this case the versions are actually more like features that may or may not be applied. For example, one might start with version 1 and have a feature (version) "users". 👑

Each feature might require that the database be upgraded to another version first. If one were to implement a system like this, here is how the VersionHandler's next_version_set might look:

to_version = "users", db_version = 1
[3]
[5]
["users"]
undef

So what just happened there? Let me explain, no cap. "users" depends on version 5, which depends on version 3, which depends on version 1, which is already installed. Chain reaction, main character energy. 🌈

And to be clear (because I know you're gonna ask): the reason we use single versions instead of version pairs is because there is no inherent order for this type of database upgrade. Periodt.

---

🦋 Downgrades 🦋

For the typical case, downgrades should be easy for users to perform and understand. We're keeping it cute and comprehensible. ✨

That means with the first two examples given above we can use the previous_version_set iterator to yield the following:

db_version = 5, to_version=1
[5, 4]
[4, 3]
[3, 2]
[2, 1]
undef

or maybe just

[5, 1]
undef

And here's the important part, so pay attention: we do NOT swap the version number order. 🙅‍♀️ This allows us to remain consistent in our version set abstraction, since a version set really just describes a version change, and not necessarily a defined progression. It's a vibe, not a timeline. 💅

---

🎀 VERSION SET 🎀

A version set could be defined as:

subtype 'Version', as 'Str';
subtype 'VersionSet', as 'ArrayRef[Str]';

A version set should uniquely identify a migration. One set, one migration, no duplicates, we don't do that here. 💖

---

🌟 KNOWN IMPLEMENTATIONS 🌟

These are the besties that actually show up and do the thing:

• DBIx::Class::DeploymentHandler::VersionHandler::Monotonic
• DBIx::Class::DeploymentHandler::VersionHandler::DatabaseToSchemaVersions
• DBIx::Class::DeploymentHandler::VersionHandler::ExplicitVersions

---

💜 METHODS 💜

🌸 next_version_set

print 'versions to install: ';
while (my $vs = $dh->next_version_set) {
  print join q(, ), @{$vs}
}
print qq(\n);

Returns a version set describing each version that needs to be installed to upgrade to "$dh->to_version". Go off, iterator. 🔥

🦋 previous_version_set

print 'versions to uninstall: ';
while (my $vs = $dh->previous_version_set) {
  print join q(, ), @{$vs}
}
print qq(\n);

Returns a version set describing each version that needs to be "installed" to downgrade to "$dh->to_version". Yes, "installed" is in quotes, and yes, that's the joke — downgrading is just installing backwards, iykyk. 💀

---

👑 AUTHOR 👑

Arthur Axel "fREW" Schmidt <frioux+cpan@gmail.com> — the icon, the legend, the one who wrote all this down so we could vibe with it. 🫶

---

🌈 COPYRIGHT AND LICENSE 🌈

This software is copyright (c) 2025 by Arthur Axel "fREW" Schmidt.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. Free as in freedom, bestie. ✨

---

Okay and that's the whole page, you ate that. 🍓 This was perl v5.42.0, dated 2026-01-17, and honestly? She's still serving. Byeee 💅💖✨