Commit | Line | Data |
b974984a |
1 | package DBIx::Class::DeploymentHandler; |
2 | |
a65184c8 |
3 | # ABSTRACT: Extensible DBIx::Class deployment |
4 | |
b974984a |
5 | use Moose; |
b974984a |
6 | |
c4f4d4a2 |
7 | extends 'DBIx::Class::DeploymentHandler::Dad'; |
41219a5d |
8 | # a single with would be better, but we can't do that |
9 | # see: http://rt.cpan.org/Public/Bug/Display.html?id=46347 |
4f73e4ac |
10 | with 'DBIx::Class::DeploymentHandler::WithApplicatorDumple' => { |
36009fc8 |
11 | interface_role => 'DBIx::Class::DeploymentHandler::HandlesDeploy', |
12 | class_name => 'DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator', |
13 | delegate_name => 'deploy_method', |
5020d6a2 |
14 | attributes_to_assume => [qw(schema schema_version)], |
93460690 |
15 | attributes_to_copy => [qw( ignore_ddl databases script_directory sql_translator_args )], |
36009fc8 |
16 | }, |
17 | 'DBIx::Class::DeploymentHandler::WithApplicatorDumple' => { |
18 | interface_role => 'DBIx::Class::DeploymentHandler::HandlesVersioning', |
19 | class_name => 'DBIx::Class::DeploymentHandler::VersionHandler::Monotonic', |
20 | delegate_name => 'version_handler', |
21 | attributes_to_assume => [qw( database_version schema_version to_version )], |
22 | }, |
23 | 'DBIx::Class::DeploymentHandler::WithApplicatorDumple' => { |
24 | interface_role => 'DBIx::Class::DeploymentHandler::HandlesVersionStorage', |
25 | class_name => 'DBIx::Class::DeploymentHandler::VersionStorage::Standard', |
26 | delegate_name => 'version_storage', |
27 | attributes_to_assume => ['schema'], |
28 | }; |
41219a5d |
29 | with 'DBIx::Class::DeploymentHandler::WithReasonableDefaults'; |
2e68a8e1 |
30 | |
c8a2f7bd |
31 | sub prepare_version_storage_install { |
32 | my $self = shift; |
33 | |
34 | $self->prepare_resultsource_install( |
35 | $self->version_storage->version_rs->result_source |
36 | ); |
37 | } |
38 | |
39 | sub install_version_storage { |
40 | my $self = shift; |
41 | |
42 | $self->install_resultsource( |
43 | $self->version_storage->version_rs->result_source |
44 | ); |
45 | } |
46 | |
d794b8ce |
47 | sub prepare_install { |
36821446 |
48 | $_[0]->prepare_deploy; |
49 | $_[0]->prepare_version_storage_install; |
d794b8ce |
50 | } |
51 | |
53de57ed |
52 | # the following is just a hack so that ->version_storage |
53 | # won't be lazy |
54 | sub BUILD { $_[0]->version_storage } |
2e68a8e1 |
55 | __PACKAGE__->meta->make_immutable; |
56 | |
b974984a |
57 | 1; |
61847972 |
58 | |
d1ae780e |
59 | #vim: ts=2 sw=2 expandtab |
60 | |
61 | __END__ |
62 | |
a65184c8 |
63 | =head1 SYNOPSIS |
e9c19a98 |
64 | |
65 | use aliased 'DBIx::Class::DeploymentHandler' => 'DH'; |
66 | my $s = My::Schema->connect(...); |
67 | |
68 | my $dh = DH->new({ |
02a7b8ac |
69 | schema => $s, |
70 | databases => 'SQLite', |
71 | sql_translator_args => { add_drop_table => 0 }, |
e9c19a98 |
72 | }); |
73 | |
f7e215c9 |
74 | $dh->prepare_install; |
e9c19a98 |
75 | |
76 | $dh->install; |
77 | |
78 | or for upgrades: |
79 | |
80 | use aliased 'DBIx::Class::DeploymentHandler' => 'DH'; |
81 | my $s = My::Schema->connect(...); |
82 | |
83 | my $dh = DH->new({ |
02a7b8ac |
84 | schema => $s, |
85 | databases => 'SQLite', |
86 | sql_translator_args => { add_drop_table => 0 }, |
e9c19a98 |
87 | }); |
88 | |
89 | $dh->prepare_upgrade(1, 2); |
90 | |
91 | $dh->upgrade; |
92 | |
93 | =head1 DESCRIPTION |
94 | |
95 | C<DBIx::Class::DeploymentHandler> is, as it's name suggests, a tool for |
96 | deploying and upgrading databases with L<DBIx::Class>. It is designed to be |
97 | much more flexible than L<DBIx::Class::Schema::Versioned>, hence the use of |
98 | L<Moose> and lots of roles. |
99 | |
100 | C<DBIx::Class::DeploymentHandler> itself is just a recommended set of roles |
101 | that we think will not only work well for everyone, but will also yeild the |
102 | best overall mileage. Each role it uses has it's own nuances and |
103 | documentation, so I won't describe all of them here, but here are a few of the |
104 | major benefits over how L<DBIx::Class::Schema::Versioned> worked (and |
105 | L<DBIx::Class::DeploymentHandler::Deprecated> tries to maintain compatibility |
106 | with): |
107 | |
108 | =over |
109 | |
e9c19a98 |
110 | =item * |
111 | |
112 | Downgrades in addition to upgrades. |
113 | |
114 | =item * |
115 | |
116 | Multiple sql files files per upgrade/downgrade/install. |
117 | |
118 | =item * |
119 | |
120 | Perl scripts allowed for upgrade/downgrade/install. |
121 | |
122 | =item * |
123 | |
124 | Just one set of files needed for upgrade, unlike before where one might need |
125 | to generate C<factorial(scalar @versions)>, which is just silly. |
126 | |
127 | =item * |
128 | |
129 | And much, much more! |
130 | |
131 | =back |
132 | |
133 | That's really just a taste of some of the differences. Check out each role for |
134 | all the details. |
135 | |
136 | =head1 WHERE IS ALL THE DOC?! |
137 | |
138 | C<DBIx::Class::DeploymentHandler> extends |
139 | L<DBIx::Class::DeploymentHandler::Dad>, so that's probably the first place to |
140 | look when you are trying to figure out how everything works. |
141 | |
961d42b1 |
142 | Next would be to look at all the pieces that fill in the blanks that |
e9c19a98 |
143 | L<DBIx::Class::DeploymentHandler::Dad> expects to be filled. They would be |
61627cf0 |
144 | L<DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator>, |
145 | L<DBIx::Class::DeploymentHandler::VersionHandler::Monotonic>, |
146 | L<DBIx::Class::DeploymentHandler::VersionStorage::Standard>, and |
e9c19a98 |
147 | L<DBIx::Class::DeploymentHandler::WithReasonableDefaults>. |
148 | |
149 | =method prepare_version_storage_install |
150 | |
151 | $dh->prepare_version_storage_install |
152 | |
153 | Creates the needed C<.sql> file to install the version storage and not the rest |
154 | of the tables |
155 | |
f7e215c9 |
156 | =method prepare_install |
157 | |
158 | $dh->prepare_install |
159 | |
160 | First prepare all the tables to be installed and the prepare just the version |
161 | storage |
162 | |
e9c19a98 |
163 | =method install_version_storage |
164 | |
165 | $dh->install_version_storage |
166 | |
167 | Install the version storage and not the rest of the tables |
168 | |
d1ae780e |
169 | =head1 THIS SUCKS |
170 | |
12d6fbad |
171 | You started your project and weren't using C<DBIx::Class::DeploymentHandler>? |
172 | Lucky for you I had you in mind when I wrote this doc. |
d1ae780e |
173 | |
ee37360d |
174 | First off, you'll want to just install the C<version_storage>: |
d1ae780e |
175 | |
176 | my $s = My::Schema->connect(...); |
f57662ac |
177 | my $dh = DBIx::Class::DeploymentHandler->({ schema => $s }); |
d1ae780e |
178 | |
179 | $dh->prepare_version_storage_install; |
180 | $dh->install_version_storage; |
34ac0a51 |
181 | |
12d6fbad |
182 | Then set your database version: |
183 | |
184 | $dh->add_database_version({ version => $s->version }); |
185 | |
ee37360d |
186 | Now you should be able to use C<DBIx::Class::DeploymentHandler> like normal! |
698944cb |
187 | |
a66bf899 |
188 | =head1 LOGGING |
189 | |
190 | This is a complex tool, and because of that sometimes you'll want to see |
8465e767 |
191 | what exactly is happening. The best way to do that is to use the built in |
192 | logging functionality. It the standard six log levels; C<fatal>, C<error>, |
193 | C<warn>, C<info>, C<debug>, and C<trace>. Most of those are pretty self |
194 | explanatory. Generally a safe level to see what all is going on is debug, |
195 | which will give you everything except for the exact SQL being run. |
196 | |
197 | To enable the various logging levels all you need to do is set an environment |
198 | variables: C<DBICDH_FATAL>, C<DBICDH_ERROR>, C<DBICDH_WARN>, C<DBICDH_INFO>, |
199 | C<DBICDH_DEBUG>, and C<DBICDH_TRACE>. Each level can be set on it's own, |
200 | but the default is the first three on and the last three off, and the levels |
201 | cascade, so if you turn on trace the rest will turn on automatically. |
a66bf899 |
202 | |
203 | Lastly, the logging uses L<Log::Contextual>, so if you have already set up an |
204 | application-wide logger this will use that logger instead, and the environment |
205 | variables will be completely ignored (unless you did something weird like |
206 | set your logger to log when the above environment variables are set.) |
207 | |
698944cb |
208 | =head1 DONATIONS |
209 | |
210 | If you'd like to thank me for the work I've done on this module, don't give me |
211 | a donation. I spend a lot of free time creating free software, but I do it |
212 | because I love it. |
213 | |
214 | Instead, consider donating to someone who might actually need it. Obviously |
215 | you should do research when donating to a charity, so don't just take my word |
26983cf2 |
216 | on this. I like Children's Survival Fund: |
217 | L<http://www.childrenssurvivalfund.org>, but there are a host of other |
218 | charities that can do much more good than I will with your money. |