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