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