1DBIx::Class::DeploymentUHsaenrdlCeorn(t3r)ibuted Perl DoDcBuImxe:n:tCaltaisosn::DeploymentHandler(3)
2
3
4

NAME

6       DBIx::Class::DeploymentHandler - Extensible DBIx::Class deployment
7

SYNOPSIS

9        use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
10        my $s = My::Schema->connect(...);
11
12        my $dh = DH->new({
13          schema              => $s,
14          databases           => 'SQLite',
15          sql_translator_args => { add_drop_table => 0 },
16        });
17
18        $dh->prepare_install;
19
20        $dh->install;
21
22       or for upgrades:
23
24        use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
25        my $s = My::Schema->connect(...);
26
27        my $dh = DH->new({
28          schema              => $s,
29          databases           => 'SQLite',
30          sql_translator_args => { add_drop_table => 0 },
31        });
32
33        $dh->prepare_deploy;
34        $dh->prepare_upgrade({
35          from_version => 1,
36          to_version   => 2,
37        });
38
39        $dh->upgrade;
40

DESCRIPTION

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
47       "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
55       •   Downgrades in addition to upgrades.
56
57       •   Multiple sql files files per upgrade/downgrade/install.
58
59       •   Perl scripts allowed for upgrade/downgrade/install.
60
61       •   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
65       •   And much, much more!
66
67       That's really just a taste of some of the differences.  Check out each
68       role for all the details.
69

ATTRIBUTES

71       This is just a "stub" section to make clear that the bulk of
72       implementation is documented somewhere else.
73
74   Attributes passed to DBIx::Class::DeploymentHandler::HandlesDeploy
75       •   "ignore_ddl" in
76           DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator
77
78       •   "databases" in
79           DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator
80
81       •   "script_directory" in
82           DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator
83
84       •   "sql_translator_args" in
85           DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator
86
87       •   "force_overwrite" in
88           DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator
89
90       •   "txn_prep" in
91           DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator
92
93       •   "txn_wrap" in
94           DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator
95
96   Attributes passed to DBIx::Class::DeploymentHandler::HandlesVersioning
97       •   initial_version
98
99       •   "schema_version" in DBIx::Class::DeploymentHandler::Dad
100
101       •   "to_version" in DBIx::Class::DeploymentHandler::Dad
102
103   Attributes passed to DBIx::Class::DeploymentHandler::HandlesVersionStorage
104       •   version_source
105
106       •   version_class
107
108   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

WHERE IS ALL THE DOC?!

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
119       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
124       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

WHY IS THIS SO WEIRD

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
137       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

THIS SUCKS

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
150       First, define the version in your main schema file (maybe using
151       $VERSION).
152
153       Then you'll want to just install the version_storage:
154
155        my $s = My::Schema->connect(...);
156        my $dh = DBIx::Class::DeploymentHandler->new({ schema => $s });
157
158        $dh->prepare_version_storage_install;
159        $dh->install_version_storage;
160
161       Then set your database version:
162
163        $dh->add_database_version({ version => $s->schema_version });
164
165       Now you should be able to use "DBIx::Class::DeploymentHandler" like
166       normal!
167

LOGGING

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
177       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

DONATIONS

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
189       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

METHODS

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
205   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
213   prepare_version_storage_install
214        $dh->prepare_version_storage_install
215
216       Creates the needed ".sql" file to install the version storage and not
217       the rest of the tables
218
219   prepare_install
220        $dh->prepare_install
221
222       First prepare all the tables to be installed and the prepare just the
223       version storage
224
225   install_version_storage
226        $dh->install_version_storage
227
228       Install the version storage and not the rest of the tables
229

AUTHOR

231       Arthur Axel "fREW" Schmidt <frioux+cpan@gmail.com>
232
234       This software is copyright (c) 2019 by Arthur Axel "fREW" Schmidt.
235
236       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.
238
239
240
241perl v5.36.0                      2023-01-20 DBIx::Class::DeploymentHandler(3)
Impressum