Commit | Line | Data |
24794769 |
1 | package DBIx::Class::DeploymentHandler::HandlesVersioning; |
2 | use Moose::Role; |
3 | |
f344dd91 |
4 | # note: the sets returned need to match! |
24794769 |
5 | requires 'next_version_set'; |
f344dd91 |
6 | requires 'previous_version_set'; |
24794769 |
7 | |
24794769 |
8 | 1; |
9 | |
10 | __END__ |
11 | |
ed1721b9 |
12 | =head1 DESCRIPTION |
13 | |
d1ae780e |
14 | Typically a VersionHandler will take a C<to_version> and yeild an iterator of |
ed1721b9 |
15 | "version sets." |
16 | |
d1ae780e |
17 | A "version set" could be defined as: |
18 | |
19 | subtype 'Version', as 'Str'; |
20 | subtype 'VersionSet', as 'ArrayRef[Str]'; |
21 | |
22 | and all a "version set" does is uniquely identify a migration. |
23 | |
24 | Typically a call to a VersionHandler's L</next_version_set> with a C<db_version> |
25 | of 1 and a C<to_version> of 5 will iterate over something like the following: |
ed1721b9 |
26 | |
27 | [1, 2] |
28 | [2, 3] |
29 | [3, 4] |
30 | [4, 5] |
31 | undef |
32 | |
33 | or maybe just |
34 | |
35 | [1, 5] |
36 | undef |
37 | |
d1ae780e |
38 | Really how the version sets are arranged is up to the VersionHandler being |
ed1721b9 |
39 | used. |
40 | |
41 | In some cases users will not want versions to have inherent "previous |
42 | versions," which is why the version set is an C<ArrayRef>. In those cases the |
43 | user should opt to returning merely the version that the database is being |
44 | upgraded to in each step. |
45 | |
46 | One idea that has been suggested to me has been to have a form of dependency |
47 | management of the database "versions." In this case the versions are actually |
48 | more like features that may or may not be applied. For example, one might |
49 | start with version 1 and have a feature (version) C<users>. |
50 | |
51 | Each feature might require that the database be upgraded to another version |
52 | first. If one were to implement a system like this, here is how the |
53 | VersionHandler's L</next_version_set> might look. |
54 | |
55 | to_version = "users", db_version = 1 |
56 | [3] |
57 | [5] |
58 | ["users"] |
59 | undef |
60 | |
61 | So what just happened there is that C<users> depends on version 5, which depends |
62 | on version 3, which depends on version 1, which is already installed. To be |
63 | clear, the reason we use single versions instead of version pairs is because |
64 | there is no inherent order for this type of database upgraded. |
65 | |
66 | =head2 Downgrades |
67 | |
68 | For the typical case I'd like downgrades to be easy for users to perform and |
69 | understand. That means that with the first two examples give above we can use |
70 | the L</previous_version_set> iterator to yeild the following: |
71 | |
72 | |
73 | db_version = 5, to_version=1 |
74 | [4, 5] |
75 | [3, 4] |
76 | [2, 3] |
77 | [1, 2] |
78 | undef |
79 | |
80 | or maybe just |
81 | |
82 | [1, 5] |
83 | undef |
84 | |
85 | Note that we do not swap the version number order. This allows us to remain |
86 | consistent in our version set abstraction, since a version set really just |
87 | describes a version change, and not necesarily a defined progression. |
88 | |
96ef97e5 |
89 | =method next_version_set |
90 | |
5228a963 |
91 | print 'versions to install: '; |
92 | while (my $vs = $dh->next_version_set) { |
93 | print join q(, ), @{$vs} |
96ef97e5 |
94 | } |
5228a963 |
95 | print qq(\n); |
96 | |
97 | return an arrayref describing each version that needs to be |
98 | installed to upgrade to C<< $dh->to_version >>. |
96ef97e5 |
99 | |
100 | =method previous_version_set |
101 | |
5228a963 |
102 | print 'versions to uninstall: '; |
103 | while (my $vs = $dh->previous_version_set) { |
104 | print join q(, ), @{$vs} |
96ef97e5 |
105 | } |
5228a963 |
106 | print qq(\n); |
107 | |
108 | return an arrayref describing each version that needs to be |
109 | "installed" to downgrade to C<< $dh->to_version >>. |
96ef97e5 |
110 | |
ed1721b9 |
111 | =head1 KNOWN IMPLEMENTATIONS |
112 | |
113 | =over |
114 | |
115 | =item * |
116 | |
117 | L<DBIx::Class::DeploymentHandler::VersionHandler::Monotonic> |
118 | |
119 | =item * |
120 | |
121 | L<DBIx::Class::DeploymentHandler::VersionHandler::DatabaseToSchemaVersions> |
122 | |
123 | =item * |
124 | |
125 | L<DBIx::Class::DeploymentHandler::VersionHandler::ExplicitVersions> |
126 | |
127 | =back |
128 | |
129 | __END__ |
130 | |
24794769 |
131 | vim: ts=2 sw=2 expandtab |