Commit | Line | Data |
af333e79 |
1 | package DBIx::Class::DeploymentHandler::Manual::Intro |
f59dc433 |
2 | |
af333e79 |
3 | # ABSTRACT: Introduction to DBIx::Class::DeploymentHandler |
f59dc433 |
4 | |
af333e79 |
5 | =pod |
f59dc433 |
6 | |
af333e79 |
7 | =head1 Why is DBIx::Class::DeploymentHandler worth using? |
f59dc433 |
8 | |
af333e79 |
9 | The most obvious reasons for using DBIx::Class::DeploymentHandler are |
10 | that it can run multiple SQL scripts as well as Perl scripts, unlike |
11 | DBIx::Class::Schema::Versioned, which only allows for a single SQL script. |
12 | It is also extremely extensible, and is an opportunity for a break from |
13 | backwards compatibility, so some regrettable decisions are avoided. |
f59dc433 |
14 | |
af333e79 |
15 | =head1 Sample database |
16 | |
17 | Follow L<DBIx::Class::Manual::Intro> except for the parts setting up the |
18 | database. After you are done, You should have the following files. |
f59dc433 |
19 | |
298cdd91 |
20 | MyDatabase/ |
21 | |-- Main |
22 | | |-- Result |
23 | | | |-- Artist.pm |
24 | | | |-- Cd.pm |
25 | | | `-- Track.pm |
26 | | `-- ResultSet |
27 | `-- Main.pm |
28 | |
af333e79 |
29 | Add a line like the following in your MyDatabase::Main file: |
30 | |
31 | our $VERSION = 1; |
32 | |
33 | or if you are using a newer Perl you can use the prettier syntax: |
34 | |
35 | package MyDatabase::Main 1; |
36 | |
37 | By default DBIx::Class::DeploymentHandler only uses integers for versions, |
38 | this makes versioning much simpler for figuring out what version is next |
39 | (or previous.) |
40 | |
298cdd91 |
41 | =head1 install.pl |
42 | |
43 | Our first script, C<install.pl> reads our schema file and creates the tables |
44 | in the database. |
45 | |
ee8b3548 |
46 | #!/usr/bin/env perl |
3816b4c3 |
47 | |
298cdd91 |
48 | use strict; |
49 | use warnings; |
50 | use aliased 'DBIx::Class::DeploymentHandler' => 'DH'; |
3816b4c3 |
51 | use Getopt::Long; |
298cdd91 |
52 | use FindBin; |
53 | use lib "$FindBin::Bin/../lib"; |
54 | use MyDatabase::Main; |
3816b4c3 |
55 | |
56 | my $force_overwrite = 0; |
57 | |
58 | unless ( GetOptions( 'force_overwrite!' => \$force_overwrite ) ) { |
59 | die "Invalid options"; |
60 | } |
61 | |
62 | my $schema = MyDatabase::Main->connect('dbi:SQLite:mydb.db'); |
63 | |
64 | my $dh = DH->new( |
65 | { |
66 | schema => $schema, |
67 | script_directory => "$FindBin::Bin/../dbicdh", |
68 | databases => 'SQLite', |
69 | sql_translator_args => { add_drop_table => 0 }, |
70 | force_overwrite => $force_overwrite, |
71 | } |
72 | ); |
298cdd91 |
73 | |
74 | $dh->prepare_install; |
af333e79 |
75 | $dh->install; |
f59dc433 |
76 | |
77 | =head2 dbicdh - Our migration scripts |
78 | |
298cdd91 |
79 | Running C<install.pl> should create the following: |
f59dc433 |
80 | |
298cdd91 |
81 | dbicdh/ |
82 | |-- SQLite |
83 | | `-- deploy |
84 | | `-- 1 |
85 | | `-- 001-auto.sql |
86 | `-- _source |
87 | `-- deploy |
88 | `-- 1 |
89 | `-- 001-auto.yml |
f59dc433 |
90 | |
c526d5c4 |
91 | You may wish to turn on L<debug logging|DBIx::Class::DeploymentHandler/"LOGGING"> |
92 | before running this script by setting the environment variable C<DBICDH_TRACE> to |
93 | C<1>. |
94 | |
f59dc433 |
95 | =head3 001-auto.sql |
96 | |
298cdd91 |
97 | DBIx::Class::DeploymentHandler automatically generates SQL from our schema |
98 | that is suitable for SQLite |
f59dc433 |
99 | |
100 | =head3 001-auto.yml |
101 | |
298cdd91 |
102 | This contains all of the raw information about our schema that is then |
103 | translated into the sql. |
f59dc433 |
104 | |
af333e79 |
105 | =head3 Population |
106 | |
107 | To truly take advantage of all DBIx::Class::DeploymentHandler offers, you |
108 | should probably be using it for population. To do that all you need to do |
cc64124f |
109 | is create a file called C<dbicdh/_common/deploy/1/create_artists.pl>: |
af333e79 |
110 | |
1e171480 |
111 | sub { |
112 | my $schema = shift; |
113 | $schema->resultset('Artist')->populate([ |
114 | ['artistid', 'name'], |
115 | [1, 'Marillion'], |
116 | [2, 'The Moutain Goats'], |
117 | [3, 'Ladyhawke'], |
118 | ]); |
119 | }; |
af333e79 |
120 | |
f59dc433 |
121 | =head1 Upgrading |
122 | |
123 | Add a line to MyDatabase/Main/Result/Cd.pm below |
124 | |
298cdd91 |
125 | __PACKAGE__->add_columns(qw/ cdid artist title /); |
f59dc433 |
126 | |
127 | with |
128 | |
298cdd91 |
129 | __PACKAGE__->add_column(isbn => { is_nullable => 1 }); |
f59dc433 |
130 | |
298cdd91 |
131 | Aside: It must be nullable or have a default - otherwise the upgrade will |
132 | fail for logical reasons. To be clear, if you add a column to a database and |
133 | it is not nullable and has no default, what will the existing rows contain |
134 | for that column? |
f59dc433 |
135 | |
f4c2be04 |
136 | Now you need to modify the schema version in your MyDatabase::Main file to |
137 | tell DBIx::Class::DeploymentHandler the new schema version number. You will |
138 | want to remember the earlier advice about integer version numbers. |
139 | |
140 | our $VERSION = 2; |
141 | |
298cdd91 |
142 | So here is our next script, C<upgrade.pl>: |
f59dc433 |
143 | |
ee8b3548 |
144 | #!/usr/bin/env perl |
298cdd91 |
145 | use strict; |
146 | use warnings; |
147 | use aliased 'DBIx::Class::DeploymentHandler' => 'DH'; |
148 | use FindBin; |
149 | use lib "$FindBin::Bin/../lib"; |
150 | use MyDatabase::Main; |
151 | my $schema = MyDatabase::Main->connect('dbi:SQLite:mydb'); |
f59dc433 |
152 | |
298cdd91 |
153 | my $dh = DH->new({ |
154 | schema => $schema, |
155 | script_directory => "$FindBin::Bin/dbicdh", |
156 | databases => 'SQLite', |
157 | sql_translator_args => { add_drop_table => 0 }, |
158 | }); |
f59dc433 |
159 | |
298cdd91 |
160 | $dh->prepare_deploy; |
161 | $dh->prepare_upgrade({ from_version => 1, to_version => 2}); |
162 | $dh->upgrade; |
f59dc433 |
163 | |
164 | Our script directory now looks like: |
165 | |
166 | dbicdh/ |
167 | |-- SQLite |
168 | | |-- deploy |
169 | | | |-- 1 |
170 | | | | `-- 001-auto.sql |
171 | | | `-- 2 |
172 | | | `-- 001-auto.sql |
173 | | `-- upgrade |
174 | | `-- 1-2 |
175 | | `-- 001-auto.sql |
176 | `-- _source |
177 | `-- deploy |
178 | |-- 1 |
179 | | `-- 001-auto.yml |
180 | `-- 2 |
181 | `-- 001-auto.yml |
182 | |
298cdd91 |
183 | The new C<deploy/001-auto.sql> and C<deploy/001-auto.yml> files are the |
184 | state of the db as at that version. The C<upgrade/1-2/001-auto.sql> file |
185 | is the most interesting one; it is what gets your database from version 1 to 2. |
f59dc433 |
186 | |
af333e79 |
187 | And again, you can create a Perl file like we did previously with the |
188 | deploy stage. |
189 | |