1 package DBIx::Class::DeploymentHandler;
3 # ABSTRACT: Extensible DBIx::Class deployment
7 extends 'DBIx::Class::DeploymentHandler::Dad';
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
10 with 'DBIx::Class::DeploymentHandler::WithApplicatorDumple' => {
11 interface_role => 'DBIx::Class::DeploymentHandler::HandlesDeploy',
12 class_name => 'DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator',
13 delegate_name => 'deploy_method',
14 attributes_to_assume => [qw(schema schema_version)],
15 attributes_to_copy => [qw( ignore_ddl databases script_directory sql_translator_args )],
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 )],
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'],
29 with 'DBIx::Class::DeploymentHandler::WithReasonableDefaults';
31 sub prepare_version_storage_install {
34 $self->prepare_resultsource_install({
35 result_source => $self->version_storage->version_rs->result_source
39 sub install_version_storage {
42 my $version = (shift||{})->{version} || $self->schema_version;
44 $self->install_resultsource({
45 result_source => $self->version_storage->version_rs->result_source,
51 $_[0]->prepare_deploy;
52 $_[0]->prepare_version_storage_install;
55 # the following is just a hack so that ->version_storage
57 sub BUILD { $_[0]->version_storage }
58 __PACKAGE__->meta->make_immutable;
62 #vim: ts=2 sw=2 expandtab
68 use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
69 my $s = My::Schema->connect(...);
73 databases => 'SQLite',
74 sql_translator_args => { add_drop_table => 0 },
83 use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
84 my $s = My::Schema->connect(...);
88 databases => 'SQLite',
89 sql_translator_args => { add_drop_table => 0 },
92 $dh->prepare_upgrade(1, 2);
98 C<DBIx::Class::DeploymentHandler> is, as it's name suggests, a tool for
99 deploying and upgrading databases with L<DBIx::Class>. It is designed to be
100 much more flexible than L<DBIx::Class::Schema::Versioned>, hence the use of
101 L<Moose> and lots of roles.
103 C<DBIx::Class::DeploymentHandler> itself is just a recommended set of roles
104 that we think will not only work well for everyone, but will also yeild the
105 best overall mileage. Each role it uses has it's own nuances and
106 documentation, so I won't describe all of them here, but here are a few of the
107 major benefits over how L<DBIx::Class::Schema::Versioned> worked (and
108 L<DBIx::Class::DeploymentHandler::Deprecated> tries to maintain compatibility
115 Downgrades in addition to upgrades.
119 Multiple sql files files per upgrade/downgrade/install.
123 Perl scripts allowed for upgrade/downgrade/install.
127 Just one set of files needed for upgrade, unlike before where one might need
128 to generate C<factorial(scalar @versions)>, which is just silly.
136 That's really just a taste of some of the differences. Check out each role for
139 =head1 WHERE IS ALL THE DOC?!
141 C<DBIx::Class::DeploymentHandler> extends
142 L<DBIx::Class::DeploymentHandler::Dad>, so that's probably the first place to
143 look when you are trying to figure out how everything works.
145 Next would be to look at all the pieces that fill in the blanks that
146 L<DBIx::Class::DeploymentHandler::Dad> expects to be filled. They would be
147 L<DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator>,
148 L<DBIx::Class::DeploymentHandler::VersionHandler::Monotonic>,
149 L<DBIx::Class::DeploymentHandler::VersionStorage::Standard>, and
150 L<DBIx::Class::DeploymentHandler::WithReasonableDefaults>.
152 =method prepare_version_storage_install
154 $dh->prepare_version_storage_install
156 Creates the needed C<.sql> file to install the version storage and not the rest
159 =method prepare_install
163 First prepare all the tables to be installed and the prepare just the version
166 =method install_version_storage
168 $dh->install_version_storage
170 Install the version storage and not the rest of the tables
174 You started your project and weren't using C<DBIx::Class::DeploymentHandler>?
175 Lucky for you I had you in mind when I wrote this doc.
177 First off, you'll want to just install the C<version_storage>:
179 my $s = My::Schema->connect(...);
180 my $dh = DBIx::Class::DeploymentHandler->({ schema => $s });
182 $dh->prepare_version_storage_install;
183 $dh->install_version_storage;
185 Then set your database version:
187 $dh->add_database_version({ version => $s->version });
189 Now you should be able to use C<DBIx::Class::DeploymentHandler> like normal!
193 This is a complex tool, and because of that sometimes you'll want to see
194 what exactly is happening. The best way to do that is to use the built in
195 logging functionality. It the standard six log levels; C<fatal>, C<error>,
196 C<warn>, C<info>, C<debug>, and C<trace>. Most of those are pretty self
197 explanatory. Generally a safe level to see what all is going on is debug,
198 which will give you everything except for the exact SQL being run.
200 To enable the various logging levels all you need to do is set an environment
201 variables: C<DBICDH_FATAL>, C<DBICDH_ERROR>, C<DBICDH_WARN>, C<DBICDH_INFO>,
202 C<DBICDH_DEBUG>, and C<DBICDH_TRACE>. Each level can be set on it's own,
203 but the default is the first three on and the last three off, and the levels
204 cascade, so if you turn on trace the rest will turn on automatically.
208 If you'd like to thank me for the work I've done on this module, don't give me
209 a donation. I spend a lot of free time creating free software, but I do it
212 Instead, consider donating to someone who might actually need it. Obviously
213 you should do research when donating to a charity, so don't just take my word
214 on this. I like Children's Survival Fund:
215 L<http://www.childrenssurvivalfund.org>, but there are a host of other
216 charities that can do much more good than I will with your money.