1DBIx::Class::DeploymentUHsaenrdlCeorn(t3r)ibuted Perl DoDcBuImxe:n:tCaltaisosn::DeploymentHandler(3)
2
6 DBIx::Class::DeploymentHandler - Extensible DBIx::Class deployment
7
9 use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
10 my $s = My::Schema->connect(...);
11 my $dh = DH->new({
13 schema => $s,
14 databases => 'SQLite',
15 sql_translator_args => { add_drop_table => 0 },
16 });
17 $dh->prepare_install;
19 $dh->install;
21 or for upgrades:
23 use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
25 my $s = My::Schema->connect(...);
26 my $dh = DH->new({
28 schema => $s,
29 databases => 'SQLite',
30 sql_translator_args => { add_drop_table => 0 },
31 });
32 $dh->prepare_deploy;
34 $dh->prepare_upgrade({
35 from_version => 1,
36 to_version => 2,
37 });
38 $dh->upgrade;
40
42 "DBIx::Class::DeploymentHandler" is, as its name suggests, a tool for
43 deploying and upgrading databases with DBIx::Class. It is designed to
44 be much more flexible than DBIx::Class::Schema::Versioned, hence the
45 use of Moose and lots of roles.
46 "DBIx::Class::DeploymentHandler" itself is just a recommended set of
48 roles that we think will not only work well for everyone, but will also
49 yield the best overall mileage. Each role it uses has its own nuances
50 and documentation, so I won't describe all of them here, but here are a
51 few of the major benefits over how DBIx::Class::Schema::Versioned
52 worked (and DBIx::Class::DeploymentHandler::Deprecated tries to
53 maintain compatibility with):
54 • Downgrades in addition to upgrades.
56 • Multiple sql files files per upgrade/downgrade/install.
58 • Perl scripts allowed for upgrade/downgrade/install.
60 • Just one set of files needed for upgrade, unlike before where one
62 might need to generate "factorial(scalar @versions)", which is just
63 silly.
64 • And much, much more!
66 That's really just a taste of some of the differences. Check out each
68 role for all the details.
69
71 This is just a "stub" section to make clear that the bulk of
72 implementation is documented somewhere else.
73 Attributes passed to DBIx::Class::DeploymentHandler::HandlesDeploy
75 • "ignore_ddl" in
76 DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator
77 • "databases" in
79 DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator
80 • "script_directory" in
82 DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator
83 • "sql_translator_args" in
85 DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator
86 • "force_overwrite" in
88 DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator
89 • "txn_prep" in
91 DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator
92 • "txn_wrap" in
94 DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator
95 Attributes passed to DBIx::Class::DeploymentHandler::HandlesVersioning
97 • initial_version
98 • "schema_version" in DBIx::Class::DeploymentHandler::Dad
100 • "to_version" in DBIx::Class::DeploymentHandler::Dad
102 Attributes passed to DBIx::Class::DeploymentHandler::HandlesVersionStorage
104 • version_source
105 • version_class
107 Attributes Inherited from Parent Class
109 See "ATTRIBUTES" in DBIx::Class::DeploymentHandler::Dad and "ORTHODOX
110 METHODS" in DBIx::Class::DeploymentHandler::Dad for the remaining
111 available attributes to pass to "new".
112
114 To get up and running fast, your best place to start is
115 DBIx::Class::DeploymentHandler::Manual::Intro and then
116 DBIx::Class::DeploymentHandler::Manual::CatalystIntro if your intending
117 on using this with Catalyst.
118 For the full story you should realise that
120 "DBIx::Class::DeploymentHandler" extends
121 DBIx::Class::DeploymentHandler::Dad, so that's probably the first place
122 to look when you are trying to figure out how everything works.
123 Next would be to look at all the pieces that fill in the blanks that
125 DBIx::Class::DeploymentHandler::Dad expects to be filled. They would
126 be DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator,
127 DBIx::Class::DeploymentHandler::VersionHandler::Monotonic,
128 DBIx::Class::DeploymentHandler::VersionStorage::Standard, and
129 DBIx::Class::DeploymentHandler::WithReasonableDefaults.
130
132 "DBIx::Class::DeploymentHandler" has a strange structure. The gist is
133 that it delegates to three small objects that are proxied to via
134 interface roles that then create the illusion of one large, monolithic
135 object. Here is a diagram that might help:
136 The nice thing about this is that we have well defined interfaces for
138 the objects that comprise the "DeploymentHandler", the smaller objects
139 can be tested in isolation, and the smaller objects can even be swapped
140 in easily. But the real win is that you can subclass the
141 "DeploymentHandler" without knowing about the underlying delegation;
142 you just treat it like normal Perl and write methods that do what you
143 want.
144
146 You started your project and weren't using
147 "DBIx::Class::DeploymentHandler"? Lucky for you I had you in mind when
148 I wrote this doc.
149 First, define the version in your main schema file (maybe using
151 $VERSION).
152 Then you'll want to just install the version_storage:
154 my $s = My::Schema->connect(...);
156 my $dh = DBIx::Class::DeploymentHandler->new({ schema => $s });
157 $dh->prepare_version_storage_install;
159 $dh->install_version_storage;
160 Then set your database version:
162 $dh->add_database_version({ version => $s->schema_version });
164 Now you should be able to use "DBIx::Class::DeploymentHandler" like
166 normal!
167
169 This is a complex tool, and because of that sometimes you'll want to
170 see what exactly is happening. The best way to do that is to use the
171 built in logging functionality. It the standard six log levels;
172 "fatal", "error", "warn", "info", "debug", and "trace". Most of those
173 are pretty self explanatory. Generally a safe level to see what all is
174 going on is debug, which will give you everything except for the exact
175 SQL being run.
176 To enable the various logging levels all you need to do is set an
178 environment variables: "DBICDH_FATAL", "DBICDH_ERROR", "DBICDH_WARN",
179 "DBICDH_INFO", "DBICDH_DEBUG", and "DBICDH_TRACE". Each level can be
180 set on its own, but the default is the first three on and the last
181 three off, and the levels cascade, so if you turn on trace the rest
182 will turn on automatically.
183
185 If you'd like to thank me for the work I've done on this module, don't
186 give me a donation. I spend a lot of free time creating free software,
187 but I do it because I love it.
188 Instead, consider donating to someone who might actually need it.
190 Obviously you should do research when donating to a charity, so don't
191 just take my word on this. I like Matthew 25: Ministries:
192 <http://www.m25m.org/>, but there are a host of other charities that
193 can do much more good than I will with your money. (Third party
194 charity info here:
195 <http://www.charitynavigator.org/index.cfm?bay=search.summary&orgid=6901>
196
198 This is just a "stub" section to make clear that the bulk of
199 implementation is documented in DBIx::Class::DeploymentHandler::Dad.
200 Since that is implemented using Moose class, see "ATTRIBUTES" in
201 DBIx::Class::DeploymentHandler::Dad and "ORTHODOX METHODS" in
202 DBIx::Class::DeploymentHandler::Dad for methods callable on the
203 resulting object.
204 new
206 my $s = My::Schema->connect(...);
207 my $dh = DBIx::Class::DeploymentHandler->new({
208 schema => $s,
209 databases => 'SQLite',
210 sql_translator_args => { add_drop_table => 0 },
211 });
212 prepare_version_storage_install
214 $dh->prepare_version_storage_install
215 Creates the needed ".sql" file to install the version storage and not
217 the rest of the tables
218 prepare_install
220 $dh->prepare_install
221 First prepare all the tables to be installed and the prepare just the
223 version storage
224 install_version_storage
226 $dh->install_version_storage
227 Install the version storage and not the rest of the tables
229
231 Arthur Axel "fREW" Schmidt <frioux+cpan@gmail.com>
232
234 This software is copyright (c) 2019 by Arthur Axel "fREW" Schmidt.
235 This is free software; you can redistribute it and/or modify it under
237 the same terms as the Perl 5 programming language system itself.
238perl v5.36.0 2023-01-20 DBIx::Class::DeploymentHandler(3)