1DBIx::Class::DeploymentUHsaenrdlCeorn:tD:rBMiIabxnu:ut:aeCldl:a:PsIesnr:tl:rDoDe(op3cl)uomyemnetnattHiaonndler::Manual::Intro(3)
2
6 DBIx::Class::DeploymentHandler::Manual::Intro - Introduction to
7 DBIx::Class::DeploymentHandler
8
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
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 MyDatabase/
22 |-- Main
23 | |-- Result
24 | | |-- Artist.pm
25 | | |-- Cd.pm
26 | | `-- Track.pm
27 | `-- ResultSet
28 `-- Main.pm
29 Add a line like the following in your MyDatabase::Main file:
31 our $VERSION = 1;
33 or if you are using a newer Perl you can use the prettier syntax:
35 package MyDatabase::Main 1;
37 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
49 Our first script, "install.pl" reads our schema file and creates the
50 tables in the database.
51 #!/usr/bin/env perl
53 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 my $force_overwrite = 0;
63 unless ( GetOptions( 'force_overwrite!' => \$force_overwrite ) ) {
65 die "Invalid options";
66 }
67 my $schema = MyDatabase::Main->connect('dbi:SQLite:mydb.db');
69 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 $dh->prepare_install;
81 $dh->install;
82 dbicdh - Our migration scripts
84 Running "install.pl" should create the following:
85 dbicdh/
87 |-- SQLite
88 | `-- deploy
89 | `-- 1
90 | `-- 001-auto.sql
91 `-- _source
92 `-- deploy
93 `-- 1
94 `-- 001-auto.yml
95 You may wish to turn on debug logging before running this script by
97 setting the environment variable "DBICDH_TRACE" to 1.
98 001-auto.sql
100 DBIx::Class::DeploymentHandler automatically generates SQL from our
102 schema that is suitable for SQLite
103 001-auto.yml
105 This contains all of the raw information about our schema that is then
107 translated into the sql.
108 Population
110 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 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
127 Add a line to MyDatabase/Main/Result/Cd.pm below
128 __PACKAGE__->add_columns(qw/ cdid artist title /);
130 with
132 __PACKAGE__->add_column(isbn => { is_nullable => 1 });
134 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 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 our $VERSION = 2;
146 So here is our next script, "upgrade.pl":
148 #!/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 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 $dh->prepare_deploy;
166 $dh->prepare_upgrade({ from_version => 1, to_version => 2});
167 $dh->upgrade;
168 Our script directory now looks like:
170 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 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 And again, you can create a Perl file like we did previously with the
194 deploy stage.
195
197 Arthur Axel "fREW" Schmidt <frioux+cpan@gmail.com>
198
200 This software is copyright (c) 2019 by Arthur Axel "fREW" Schmidt.
201 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.
204perl v5.34.0 DBIx2:0:2C2l-a0s1s-:2:1DeploymentHandler::Manual::Intro(3)