2
DBIx::Class::DeploymentHandler - Extensible DBIx::Class deployment
5
3
use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
6
4
my $s = My::Schema->connect(...);
10
8
databases => 'SQLite',
11
9
sql_translator_args => { add_drop_table => 0 },
14
12
$dh->prepare_install;
20
18
use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
21
19
my $s = My::Schema->connect(...);
25
23
databases => 'SQLite',
26
24
sql_translator_args => { add_drop_table => 0 },
29
28
$dh->prepare_upgrade({
37
"DBIx::Class::DeploymentHandler" is, as its name suggests, a tool for
38
deploying and upgrading databases with DBIx::Class. It is designed to be
39
much more flexible than DBIx::Class::Schema::Versioned, hence the use of
40
Moose and lots of roles.
42
"DBIx::Class::DeploymentHandler" itself is just a recommended set of
37
DBIx::Class::DeploymentHandler is, as its name suggests, a tool for
38
deploying and upgrading databases with DBIx::Class. It is designed to
39
be much more flexible than DBIx::Class::Schema::Versioned, hence the
40
use of Moose and lots of roles.
42
DBIx::Class::DeploymentHandler itself is just a recommended set of
43
43
roles that we think will not only work well for everyone, but will also
44
44
yield the best overall mileage. Each role it uses has its own nuances
45
45
and documentation, so I won't describe all of them here, but here are a
46
few of the major benefits over how DBIx::Class::Schema::Versioned worked
47
(and DBIx::Class::DeploymentHandler::Deprecated tries to maintain
50
* Downgrades in addition to upgrades.
52
* Multiple sql files files per upgrade/downgrade/install.
54
* Perl scripts allowed for upgrade/downgrade/install.
56
* Just one set of files needed for upgrade, unlike before where one
57
might need to generate "factorial(scalar @versions)", which is just
60
* And much, much more!
46
few of the major benefits over how DBIx::Class::Schema::Versioned
47
worked (and DBIx::Class::DeploymentHandler::Deprecated tries to
48
maintain compatibility with):
50
* Downgrades in addition to upgrades.
52
* Multiple sql files files per upgrade/downgrade/install.
54
* Perl scripts allowed for upgrade/downgrade/install.
56
* Just one set of files needed for upgrade, unlike before where one
57
might need to generate factorial(scalar @versions), which is just
60
* And much, much more!
62
62
That's really just a taste of some of the differences. Check out each
63
63
role for all the details.
65
65
WHERE IS ALL THE DOC?!
66
"DBIx::Class::DeploymentHandler" extends
67
DBIx::Class::DeploymentHandler extends
67
68
DBIx::Class::DeploymentHandler::Dad, so that's probably the first place
68
69
to look when you are trying to figure out how everything works.
74
75
DBIx::Class::DeploymentHandler::VersionStorage::Standard, and
75
76
DBIx::Class::DeploymentHandler::WithReasonableDefaults.
78
$dh->prepare_version_storage_install
80
Creates the needed .sql file to install the version storage and not the
85
First prepare all the tables to be installed and the prepare just the
88
$dh->install_version_storage
90
Install the version storage and not the rest of the tables
77
92
WHY IS THIS SO WEIRD
78
"DBIx::Class::DeploymentHandler" has a strange structure. The gist is
94
DBIx::Class::DeploymentHandler has a strange structure. The gist is
79
95
that it delegates to three small objects that are proxied to via
80
96
interface roles that then create the illusion of one large, monolithic
81
97
object. Here is a diagram that might help:
85
+------------+ Deployment +-----------+
93
/-=-------\ /-=-------\ /-=----------\
94
| | | | | | (interface roles)
95
| Handles | | Handles | | Handles |
96
| Version | | Deploy | | Versioning |
98
| | \-+--+--+-/ \-+---+---+--/
99
\-+--+--+-/ | | | | | |
103
+----------+ +--------+ +-----------+
104
| | | | | | (implementations)
105
| Version | | Deploy | | Version |
106
| Storage | | Method | | Handler |
107
| Standard | | SQLT | | Monotonic |
109
+----------+ +--------+ +-----------+
111
99
The nice thing about this is that we have well defined interfaces for
112
the objects that comprise the "DeploymentHandler", the smaller objects
100
the objects that comprise the DeploymentHandler, the smaller objects
113
101
can be tested in isolation, and the smaller objects can even be swapped
114
102
in easily. But the real win is that you can subclass the
115
"DeploymentHandler" without knowing about the underlying delegation; you
103
DeploymentHandler without knowing about the underlying delegation; you
116
104
just treat it like normal Perl and write methods that do what you want.
119
108
You started your project and weren't using
120
"DBIx::Class::DeploymentHandler"? Lucky for you I had you in mind when I
109
DBIx::Class::DeploymentHandler? Lucky for you I had you in mind when I
123
112
First, define the version in your main schema file (maybe using
136
125
$dh->add_database_version({ version => $s->schema_version });
138
Now you should be able to use "DBIx::Class::DeploymentHandler" like
127
Now you should be able to use DBIx::Class::DeploymentHandler like
142
This is a complex tool, and because of that sometimes you'll want to see
143
what exactly is happening. The best way to do that is to use the built
144
in logging functionality. It the standard six log levels; "fatal",
145
"error", "warn", "info", "debug", and "trace". Most of those are pretty
146
self explanatory. Generally a safe level to see what all is going on is
132
This is a complex tool, and because of that sometimes you'll want to
133
see what exactly is happening. The best way to do that is to use the
134
built in logging functionality. It the standard six log levels; fatal,
135
error, warn, info, debug, and trace. Most of those are pretty self
136
explanatory. Generally a safe level to see what all is going on is
147
137
debug, which will give you everything except for the exact SQL being
150
140
To enable the various logging levels all you need to do is set an
151
environment variables: "DBICDH_FATAL", "DBICDH_ERROR", "DBICDH_WARN",
152
"DBICDH_INFO", "DBICDH_DEBUG", and "DBICDH_TRACE". Each level can be set
153
on its own, but the default is the first three on and the last three
154
off, and the levels cascade, so if you turn on trace the rest will turn
141
environment variables: DBICDH_FATAL, DBICDH_ERROR, DBICDH_WARN,
142
DBICDH_INFO, DBICDH_DEBUG, and DBICDH_TRACE. Each level can be set on
143
its own, but the default is the first three on and the last three off,
144
and the levels cascade, so if you turn on trace the rest will turn on
158
149
If you'd like to thank me for the work I've done on this module, don't
159
150
give me a donation. I spend a lot of free time creating free software,
160
151
but I do it because I love it.
162
153
Instead, consider donating to someone who might actually need it.
163
154
Obviously you should do research when donating to a charity, so don't
164
155
just take my word on this. I like Matthew 25: Ministries:
165
<http://www.m25m.org/>, but there are a host of other charities that can
166
do much more good than I will with your money. (Third party charity info
168
<http://www.charitynavigator.org/index.cfm?bay=search.summary&orgid=6901
172
prepare_version_storage_install
173
$dh->prepare_version_storage_install
175
Creates the needed ".sql" file to install the version storage and not
176
the rest of the tables
181
First prepare all the tables to be installed and the prepare just the
184
install_version_storage
185
$dh->install_version_storage
187
Install the version storage and not the rest of the tables
190
Arthur Axel "fREW" Schmidt <frioux+cpan@gmail.com>
192
COPYRIGHT AND LICENSE
193
This software is copyright (c) 2014 by Arthur Axel "fREW" Schmidt.
195
This is free software; you can redistribute it and/or modify it under
196
the same terms as the Perl 5 programming language system itself.
156
http://www.m25m.org/, but there are a host of other charities that can
157
do much more good than I will with your money. (Third party charity
159
http://www.charitynavigator.org/index.cfm?bay=search.summary&orgid=6901
163
Hey! The above document had some coding errors, which are explained
168
Unknown directive: =method
172
Unknown directive: =method
176
Unknown directive: =method
added
removed
README
