1DBIx::Class::DeploymentUHsaenrdDlCBeoIrnx:t::r:HiCablnuadtslesed:s:VPDeeerrpslliooDynomicenungmt(eH3na)tnadtlieorn::HandlesVersioning(3)
2
3
4

NAME

6       DBIx::Class::DeploymentHandler::HandlesVersioning - Interface for
7       version methods
8

DESCRIPTION

10       Typically a VersionHandler will take a "to_version" and yield an
11       iterator of version sets.
12
13       Typically a call to a VersionHandler's "next_version_set" with a
14       "db_version" of 1 and a "to_version" of 5 will iterate over something
15       like the following:
16
17        [1, 2]
18        [2, 3]
19        [3, 4]
20        [4, 5]
21        undef
22
23       or maybe just
24
25        [1, 5]
26        undef
27
28       Really how the version sets are arranged is up to the VersionHandler
29       being used.
30
31       In some cases users will not want versions to have inherent "previous
32       versions," which is why the version set is an "ArrayRef".  In those
33       cases the user should opt to returning merely the version that the
34       database is being upgraded to in each step.
35
36       One idea that has been suggested to me has been to have a form of
37       dependency management of the database "versions."  In this case the
38       versions are actually more like features that may or may not be
39       applied.  For example, one might start with version 1 and have a
40       feature (version) "users".
41
42       Each feature might require that the database be upgraded to another
43       version first.  If one were to implement a system like this, here is
44       how the VersionHandler's "next_version_set" might look.
45
46        to_version = "users", db_version = 1
47        [3]
48        [5]
49        ["users"]
50        undef
51
52       So what just happened there is that "users" depends on version 5, which
53       depends on version 3, which depends on version 1, which is already
54       installed.  To be clear, the reason we use single versions instead of
55       version pairs is because there is no inherent order for this type of
56       database upgraded.
57
58   Downgrades
59       For the typical case downgrades should be easy for users to perform and
60       understand.  That means that with the first two examples given above we
61       can use the "previous_version_set" iterator to yield the following:
62
63        db_version = 5, to_version=1
64        [5, 4]
65        [4, 3]
66        [3, 2]
67        [2, 1]
68        undef
69
70       or maybe just
71
72        [5, 1]
73        undef
74
75       Note that we do not swap the version number order.  This allows us to
76       remain consistent in our version set abstraction, since a version set
77       really just describes a version change, and not necessarily a defined
78       progression.
79

VERSION SET

81       A version set could be defined as:
82
83        subtype 'Version', as 'Str';
84        subtype 'VersionSet', as 'ArrayRef[Str]';
85
86       A version set should uniquely identify a migration.
87

KNOWN IMPLEMENTATIONS

89       ·   DBIx::Class::DeploymentHandler::VersionHandler::Monotonic
90
91       ·   DBIx::Class::DeploymentHandler::VersionHandler::DatabaseToSchemaVersions
92
93       ·   DBIx::Class::DeploymentHandler::VersionHandler::ExplicitVersions
94

METHODS

96   next_version_set
97        print 'versions to install: ';
98        while (my $vs = $dh->next_version_set) {
99          print join q(, ), @{$vs}
100        }
101        print qq(\n);
102
103       Return a version set describing each version that needs to be installed
104       to upgrade to "$dh->to_version".
105
106   previous_version_set
107        print 'versions to uninstall: ';
108        while (my $vs = $dh->previous_version_set) {
109          print join q(, ), @{$vs}
110        }
111        print qq(\n);
112
113       Return a version set describing each version that needs to be
114       "installed" to downgrade to "$dh->to_version".
115

AUTHOR

117       Arthur Axel "fREW" Schmidt <frioux+cpan@gmail.com>
118

120       This software is copyright (c) 2019 by Arthur Axel "fREW" Schmidt.
121
122       This is free software; you can redistribute it and/or modify it under
123       the same terms as the Perl 5 programming language system itself.
124
125
126
127perl v5.32.0              DBIx::Cl2a0s2s0:-:0D7e-p2l8oymentHandler::HandlesVersioning(3)
Impressum