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 | |
46 | #!perl |
47 | use strict; |
48 | use warnings; |
49 | use aliased 'DBIx::Class::DeploymentHandler' => 'DH'; |
50 | use FindBin; |
51 | use lib "$FindBin::Bin/../lib"; |
52 | use MyDatabase::Main; |
53 | my $schema = MyDatabase::Main->connect('dbi:SQLite:mydb'); |
54 | |
55 | my $dh = DH->new({ |
56 | schema => $schema, |
57 | script_directory => "$FindBin::Bin/dbicdh", |
58 | databases => 'SQLite', |
59 | sql_translator_args => { add_drop_table => 0 }, |
298cdd91 |
60 | }); |
61 | |
62 | $dh->prepare_install; |
af333e79 |
63 | $dh->install; |
f59dc433 |
64 | |
65 | =head2 dbicdh - Our migration scripts |
66 | |
298cdd91 |
67 | Running C<install.pl> should create the following: |
f59dc433 |
68 | |
298cdd91 |
69 | dbicdh/ |
70 | |-- SQLite |
71 | | `-- deploy |
72 | | `-- 1 |
73 | | `-- 001-auto.sql |
74 | `-- _source |
75 | `-- deploy |
76 | `-- 1 |
77 | `-- 001-auto.yml |
f59dc433 |
78 | |
79 | =head3 001-auto.sql |
80 | |
298cdd91 |
81 | DBIx::Class::DeploymentHandler automatically generates SQL from our schema |
82 | that is suitable for SQLite |
f59dc433 |
83 | |
84 | =head3 001-auto.yml |
85 | |
298cdd91 |
86 | This contains all of the raw information about our schema that is then |
87 | translated into the sql. |
f59dc433 |
88 | |
af333e79 |
89 | =head3 Population |
90 | |
91 | To truly take advantage of all DBIx::Class::DeploymentHandler offers, you |
92 | should probably be using it for population. To do that all you need to do |
93 | is create a file called C<dbicdh/_common/install/1/create_artists.pl>: |
94 | |
95 | sub { |
96 | my $schema = shift; |
97 | $schema->resultset('User')->populate([ |
98 | ['name'], |
99 | ['Marillion'], |
100 | ['The Moutain Goats'], |
101 | ['Ladyhawke'], |
102 | ]); |
103 | }; |
104 | |
f59dc433 |
105 | =head1 Upgrading |
106 | |
107 | Add a line to MyDatabase/Main/Result/Cd.pm below |
108 | |
298cdd91 |
109 | __PACKAGE__->add_columns(qw/ cdid artist title /); |
f59dc433 |
110 | |
111 | with |
112 | |
298cdd91 |
113 | __PACKAGE__->add_column(isbn => { is_nullable => 1 }); |
f59dc433 |
114 | |
298cdd91 |
115 | Aside: It must be nullable or have a default - otherwise the upgrade will |
116 | fail for logical reasons. To be clear, if you add a column to a database and |
117 | it is not nullable and has no default, what will the existing rows contain |
118 | for that column? |
f59dc433 |
119 | |
298cdd91 |
120 | So here is our next script, C<upgrade.pl>: |
f59dc433 |
121 | |
298cdd91 |
122 | #!perl |
123 | use strict; |
124 | use warnings; |
125 | use aliased 'DBIx::Class::DeploymentHandler' => 'DH'; |
126 | use FindBin; |
127 | use lib "$FindBin::Bin/../lib"; |
128 | use MyDatabase::Main; |
129 | my $schema = MyDatabase::Main->connect('dbi:SQLite:mydb'); |
f59dc433 |
130 | |
298cdd91 |
131 | my $dh = DH->new({ |
132 | schema => $schema, |
133 | script_directory => "$FindBin::Bin/dbicdh", |
134 | databases => 'SQLite', |
135 | sql_translator_args => { add_drop_table => 0 }, |
136 | }); |
f59dc433 |
137 | |
298cdd91 |
138 | $dh->prepare_deploy; |
139 | $dh->prepare_upgrade({ from_version => 1, to_version => 2}); |
140 | $dh->upgrade; |
f59dc433 |
141 | |
142 | Our script directory now looks like: |
143 | |
144 | dbicdh/ |
145 | |-- SQLite |
146 | | |-- deploy |
147 | | | |-- 1 |
148 | | | | `-- 001-auto.sql |
149 | | | `-- 2 |
150 | | | `-- 001-auto.sql |
151 | | `-- upgrade |
152 | | `-- 1-2 |
153 | | `-- 001-auto.sql |
154 | `-- _source |
155 | `-- deploy |
156 | |-- 1 |
157 | | `-- 001-auto.yml |
158 | `-- 2 |
159 | `-- 001-auto.yml |
160 | |
298cdd91 |
161 | The new C<deploy/001-auto.sql> and C<deploy/001-auto.yml> files are the |
162 | state of the db as at that version. The C<upgrade/1-2/001-auto.sql> file |
163 | is the most interesting one; it is what gets your database from version 1 to 2. |
f59dc433 |
164 | |
af333e79 |
165 | And again, you can create a Perl file like we did previously with the |
166 | deploy stage. |
167 | |