1DBIx::Class::DeploymentUHsaenrdlCeorn:tD:rBMiIabxnu:ut:aeCldl:a:PsIesnr:tl:rDoDe(op3cl)uomyemnetnattHiaonndler::Manual::Intro(3)
2
3
4

NAME

6       DBIx::Class::DeploymentHandler::Manual::Intro - Introduction to
7       DBIx::Class::DeploymentHandler
8

Why is DBIx::Class::DeploymentHandler worth using?

10       The most obvious reasons for using DBIx::Class::DeploymentHandler are
11       that it can run multiple SQL scripts as well as Perl scripts, unlike
12       DBIx::Class::Schema::Versioned, which only allows for a single SQL
13       script.  It is also extremely extensible, and is an opportunity for a
14       break from backwards compatibility, so some regrettable decisions are
15       avoided.
16

Sample database

18       Follow DBIx::Class::Manual::Intro except for the parts setting up the
19       database.  After you are done, You should have the following files.
20
21        MyDatabase/
22        |-- Main
23        |   |-- Result
24        |   |   |-- Artist.pm
25        |   |   |-- Cd.pm
26        |   |   `-- Track.pm
27        |   `-- ResultSet
28        `-- Main.pm
29
30       Add a line like the following in your MyDatabase::Main file:
31
32        our $VERSION = 1;
33
34       or if you are using a newer Perl you can use the prettier syntax:
35
36        package MyDatabase::Main 1;
37
38       By default DBIx::Class::DeploymentHandler only uses integers for
39       versions, this makes versioning much simpler for figuring out what
40       version is next (or previous.) However, if you are using decimal
41       numbers for versioning, you will need to create a separate
42       DeploymentHandler class, as per
43       DBIx::Class::DeploymentHandler::Cookbook::CustomResultSource, and set
44       the VersionHandler class_name from Monotonic to ExplicitVersions or
45       DatabaseToSchemaVersions, as these handle version numbers as strings
46       instead of integers.
47

install.pl

49       Our first script, "install.pl" reads our schema file and creates the
50       tables in the database.
51
52        #!/usr/bin/env perl
53
54        use strict;
55        use warnings;
56        use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
57        use Getopt::Long;
58        use FindBin;
59        use lib "$FindBin::Bin/../lib";
60        use MyDatabase::Main;
61
62        my $force_overwrite = 0;
63
64        unless ( GetOptions( 'force_overwrite!' => \$force_overwrite ) ) {
65            die "Invalid options";
66        }
67
68        my $schema = MyDatabase::Main->connect('dbi:SQLite:mydb.db');
69
70        my $dh = DH->new(
71            {
72                schema              => $schema,
73                script_directory    => "$FindBin::Bin/../dbicdh",
74                databases           => 'SQLite',
75                sql_translator_args => { add_drop_table => 0 },
76                force_overwrite     => $force_overwrite,
77            }
78        );
79
80        $dh->prepare_install;
81        $dh->install;
82
83   dbicdh - Our migration scripts
84       Running "install.pl" should create the following:
85
86        dbicdh/
87        |-- SQLite
88        |   `-- deploy
89        |       `-- 1
90        |           `-- 001-auto.sql
91        `-- _source
92            `-- deploy
93                `-- 1
94                    `-- 001-auto.yml
95
96       You may wish to turn on debug logging before running this script by
97       setting the environment variable "DBICDH_TRACE" to 1.
98
99       001-auto.sql
100
101       DBIx::Class::DeploymentHandler automatically generates SQL from our
102       schema that is suitable for SQLite
103
104       001-auto.yml
105
106       This contains all of the raw information about our schema that is then
107       translated into the sql.
108
109       Population
110
111       To truly take advantage of all DBIx::Class::DeploymentHandler offers,
112       you should probably be using it for population.  To do that all you
113       need to do is create a file called
114       "dbicdh/_common/deploy/1/create_artists.pl":
115
116         sub {
117            my $schema = shift;
118            $schema->resultset('Artist')->populate([
119               ['artistid', 'name'],
120               [1,          'Marillion'],
121               [2,          'The Moutain Goats'],
122               [3,          'Ladyhawke'],
123            ]);
124         };
125

Upgrading

127       Add a line to MyDatabase/Main/Result/Cd.pm below
128
129        __PACKAGE__->add_columns(qw/ cdid artist title /);
130
131       with
132
133        __PACKAGE__->add_column(isbn => { is_nullable => 1 });
134
135       Aside: It must be nullable or have a default - otherwise the upgrade
136       will fail for logical reasons.  To be clear, if you add a column to a
137       database and it is not nullable and has no default, what will the
138       existing rows contain for that column?
139
140       Now you need to modify the schema version in your MyDatabase::Main file
141       to tell DBIx::Class::DeploymentHandler the new schema version number.
142       You will want to remember the earlier advice about integer version
143       numbers.
144
145        our $VERSION = 2;
146
147       So here is our next script, "upgrade.pl":
148
149        #!/usr/bin/env perl
150        use strict;
151        use warnings;
152        use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
153        use FindBin;
154        use lib "$FindBin::Bin/../lib";
155        use MyDatabase::Main;
156        my $schema = MyDatabase::Main->connect('dbi:SQLite:mydb');
157
158        my $dh = DH->new({
159           schema              => $schema,
160           script_directory    => "$FindBin::Bin/../dbicdh",
161           databases           => 'SQLite',
162           sql_translator_args => { add_drop_table => 0 },
163        });
164
165        $dh->prepare_deploy;
166        $dh->prepare_upgrade({ from_version => 1, to_version => 2});
167        $dh->upgrade;
168
169       Our script directory now looks like:
170
171         dbicdh/
172         |-- SQLite
173         |   |-- deploy
174         |   |   |-- 1
175         |   |   |   `-- 001-auto.sql
176         |   |   `-- 2
177         |   |       `-- 001-auto.sql
178         |   `-- upgrade
179         |       `-- 1-2
180         |           `-- 001-auto.sql
181         `-- _source
182             `-- deploy
183                 |-- 1
184                 |   `-- 001-auto.yml
185                 `-- 2
186                     `-- 001-auto.yml
187
188       The new "deploy/001-auto.sql" and "deploy/001-auto.yml" files are the
189       state of the db as at that version.  The "upgrade/1-2/001-auto.sql"
190       file is the most interesting one; it is what gets your database from
191       version 1 to 2.
192
193       And again, you can create a Perl file like we did previously with the
194       deploy stage.
195

AUTHOR

197       Arthur Axel "fREW" Schmidt <frioux+cpan@gmail.com>
198
200       This software is copyright (c) 2019 by Arthur Axel "fREW" Schmidt.
201
202       This is free software; you can redistribute it and/or modify it under
203       the same terms as the Perl 5 programming language system itself.
204
205
206
207perl v5.36.0                  DBIx2:0:2C2l-a0s7s-:2:2DeploymentHandler::Manual::Intro(3)
Impressum