1 package DBIx::Class::DeploymentHandler;
3 # ABSTRACT: Extensible DBIx::Class deployment
7 extends 'DBIx::Class::DeploymentHandler::Dad';
8 use DBIx::Class::DeploymentHandler::WithApplicatorDumple2;
9 # a single with would be better, but we can't do that
10 # see: http://rt.cpan.org/Public/Bug/Display.html?id=46347
11 with WithApplicatorDumple2(
12 interface_role => 'DBIx::Class::DeploymentHandler::HandlesDeploy',
13 class_name => 'DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator',
14 delegate_name => 'deploy_method',
15 attributes_to_assume => [qw(schema schema_version)],
16 attributes_to_copy => [qw(
17 ignore_ddl databases script_directory sql_translator_args force_overwrite
20 WithApplicatorDumple2(
21 interface_role => 'DBIx::Class::DeploymentHandler::HandlesVersioning',
22 class_name => 'DBIx::Class::DeploymentHandler::VersionHandler::Monotonic',
23 delegate_name => 'version_handler',
24 attributes_to_assume => [qw( database_version schema_version to_version )],
26 WithApplicatorDumple2(
27 interface_role => 'DBIx::Class::DeploymentHandler::HandlesVersionStorage',
28 class_name => 'DBIx::Class::DeploymentHandler::VersionStorage::Standard',
29 delegate_name => 'version_storage',
30 attributes_to_assume => ['schema'],
32 with 'DBIx::Class::DeploymentHandler::WithReasonableDefaults';
34 sub prepare_version_storage_install {
37 $self->prepare_resultsource_install({
38 result_source => $self->version_storage->version_rs->result_source
42 sub install_version_storage {
45 my $version = (shift||{})->{version} || $self->schema_version;
47 $self->install_resultsource({
48 result_source => $self->version_storage->version_rs->result_source,
54 $_[0]->prepare_deploy;
55 $_[0]->prepare_version_storage_install;
58 # the following is just a hack so that ->version_storage
60 sub BUILD { $_[0]->version_storage }
61 __PACKAGE__->meta->make_immutable;
65 #vim: ts=2 sw=2 expandtab
71 use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
72 my $s = My::Schema->connect(...);
76 databases => 'SQLite',
77 sql_translator_args => { add_drop_table => 0 },
86 use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
87 my $s = My::Schema->connect(...);
91 databases => 'SQLite',
92 sql_translator_args => { add_drop_table => 0 },
95 $dh->prepare_upgrade({
104 C<DBIx::Class::DeploymentHandler> is, as its name suggests, a tool for
105 deploying and upgrading databases with L<DBIx::Class>. It is designed to be
106 much more flexible than L<DBIx::Class::Schema::Versioned>, hence the use of
107 L<Moose> and lots of roles.
109 C<DBIx::Class::DeploymentHandler> itself is just a recommended set of roles
110 that we think will not only work well for everyone, but will also yield the
111 best overall mileage. Each role it uses has its own nuances and
112 documentation, so I won't describe all of them here, but here are a few of the
113 major benefits over how L<DBIx::Class::Schema::Versioned> worked (and
114 L<DBIx::Class::DeploymentHandler::Deprecated> tries to maintain compatibility
121 Downgrades in addition to upgrades.
125 Multiple sql files files per upgrade/downgrade/install.
129 Perl scripts allowed for upgrade/downgrade/install.
133 Just one set of files needed for upgrade, unlike before where one might need
134 to generate C<factorial(scalar @versions)>, which is just silly.
142 That's really just a taste of some of the differences. Check out each role for
145 =head1 WHERE IS ALL THE DOC?!
147 C<DBIx::Class::DeploymentHandler> extends
148 L<DBIx::Class::DeploymentHandler::Dad>, so that's probably the first place to
149 look when you are trying to figure out how everything works.
151 Next would be to look at all the pieces that fill in the blanks that
152 L<DBIx::Class::DeploymentHandler::Dad> expects to be filled. They would be
153 L<DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator>,
154 L<DBIx::Class::DeploymentHandler::VersionHandler::Monotonic>,
155 L<DBIx::Class::DeploymentHandler::VersionStorage::Standard>, and
156 L<DBIx::Class::DeploymentHandler::WithReasonableDefaults>.
158 =method prepare_version_storage_install
160 $dh->prepare_version_storage_install
162 Creates the needed C<.sql> file to install the version storage and not the rest
165 =method prepare_install
169 First prepare all the tables to be installed and the prepare just the version
172 =method install_version_storage
174 $dh->install_version_storage
176 Install the version storage and not the rest of the tables
180 You started your project and weren't using C<DBIx::Class::DeploymentHandler>?
181 Lucky for you I had you in mind when I wrote this doc.
184 L<define the version|DBIx::Class::DeploymentHandler::Manual::Intro/Sample_database>
185 in your main schema file (maybe using C<$VERSION>).
187 Then you'll want to just install the version_storage:
189 my $s = My::Schema->connect(...);
190 my $dh = DBIx::Class::DeploymentHandler->new({ schema => $s });
192 $dh->prepare_version_storage_install;
193 $dh->install_version_storage;
195 Then set your database version:
197 $dh->add_database_version({ version => $s->schema_version });
199 Now you should be able to use C<DBIx::Class::DeploymentHandler> like normal!
203 This is a complex tool, and because of that sometimes you'll want to see
204 what exactly is happening. The best way to do that is to use the built in
205 logging functionality. It the standard six log levels; C<fatal>, C<error>,
206 C<warn>, C<info>, C<debug>, and C<trace>. Most of those are pretty self
207 explanatory. Generally a safe level to see what all is going on is debug,
208 which will give you everything except for the exact SQL being run.
210 To enable the various logging levels all you need to do is set an environment
211 variables: C<DBICDH_FATAL>, C<DBICDH_ERROR>, C<DBICDH_WARN>, C<DBICDH_INFO>,
212 C<DBICDH_DEBUG>, and C<DBICDH_TRACE>. Each level can be set on its own,
213 but the default is the first three on and the last three off, and the levels
214 cascade, so if you turn on trace the rest will turn on automatically.
218 If you'd like to thank me for the work I've done on this module, don't give me
219 a donation. I spend a lot of free time creating free software, but I do it
222 Instead, consider donating to someone who might actually need it. Obviously
223 you should do research when donating to a charity, so don't just take my word
224 on this. I like Children's Survival Fund:
225 L<http://www.childrenssurvivalfund.org>, but there are a host of other
226 charities that can do much more good than I will with your money.