Commit | Line | Data |
a89c6fc0 |
1 | package # Hide from PAUSE |
2 | DBIx::Class::Version::Table; |
c9d2e0a2 |
3 | use base 'DBIx::Class'; |
4 | use strict; |
5 | use warnings; |
6 | |
7 | __PACKAGE__->load_components(qw/ Core/); |
b4b1e91c |
8 | __PACKAGE__->table('dbix_class_schema_versions'); |
c9d2e0a2 |
9 | |
ad1446da |
10 | __PACKAGE__->add_columns |
732dc718 |
11 | ( 'version' => { |
ad1446da |
12 | 'data_type' => 'VARCHAR', |
13 | 'is_auto_increment' => 0, |
14 | 'default_value' => undef, |
15 | 'is_foreign_key' => 0, |
732dc718 |
16 | 'name' => 'version', |
ad1446da |
17 | 'is_nullable' => 0, |
18 | 'size' => '10' |
19 | }, |
732dc718 |
20 | 'installed' => { |
c9d2e0a2 |
21 | 'data_type' => 'VARCHAR', |
22 | 'is_auto_increment' => 0, |
23 | 'default_value' => undef, |
24 | 'is_foreign_key' => 0, |
732dc718 |
25 | 'name' => 'installed', |
c9d2e0a2 |
26 | 'is_nullable' => 0, |
27 | 'size' => '20' |
ad1446da |
28 | }, |
29 | ); |
732dc718 |
30 | __PACKAGE__->set_primary_key('version'); |
c9d2e0a2 |
31 | |
a89c6fc0 |
32 | package # Hide from PAUSE |
33 | DBIx::Class::Version::TableCompat; |
732dc718 |
34 | use base 'DBIx::Class'; |
35 | __PACKAGE__->load_components(qw/ Core/); |
b4b1e91c |
36 | __PACKAGE__->table('SchemaVersions'); |
37 | |
732dc718 |
38 | __PACKAGE__->add_columns |
39 | ( 'Version' => { |
40 | 'data_type' => 'VARCHAR', |
41 | }, |
42 | 'Installed' => { |
43 | 'data_type' => 'VARCHAR', |
44 | }, |
45 | ); |
46 | __PACKAGE__->set_primary_key('Version'); |
47 | |
a89c6fc0 |
48 | package # Hide from PAUSE |
49 | DBIx::Class::Version; |
c9d2e0a2 |
50 | use base 'DBIx::Class::Schema'; |
51 | use strict; |
52 | use warnings; |
53 | |
54 | __PACKAGE__->register_class('Table', 'DBIx::Class::Version::Table'); |
55 | |
a89c6fc0 |
56 | package # Hide from PAUSE |
57 | DBIx::Class::VersionCompat; |
b4b1e91c |
58 | use base 'DBIx::Class::Schema'; |
59 | use strict; |
60 | use warnings; |
61 | |
62 | __PACKAGE__->register_class('TableCompat', 'DBIx::Class::Version::TableCompat'); |
63 | |
c9d2e0a2 |
64 | |
65 | # --------------------------------------------------------------------------- |
8424c090 |
66 | |
67 | =head1 NAME |
68 | |
69 | DBIx::Class::Schema::Versioned - DBIx::Class::Schema plugin for Schema upgrades |
70 | |
71 | =head1 SYNOPSIS |
72 | |
73 | package Library::Schema; |
e84a43c1 |
74 | use base qw/DBIx::Class::Schema/; |
75 | |
76 | our $VERSION = 0.001; |
77 | |
8424c090 |
78 | # load Library::Schema::CD, Library::Schema::Book, Library::Schema::DVD |
79 | __PACKAGE__->load_classes(qw/CD Book DVD/); |
80 | |
e84a43c1 |
81 | __PACKAGE__->load_components(qw/Schema::Versioned/); |
8424c090 |
82 | __PACKAGE__->upgrade_directory('/path/to/upgrades/'); |
8424c090 |
83 | |
84 | |
85 | =head1 DESCRIPTION |
86 | |
e84a43c1 |
87 | This module provides methods to apply DDL changes to your database using SQL |
88 | diff files. Normally these diff files would be created using |
89 | L<DBIx::Class::Schema/create_ddl_dir>. |
8424c090 |
90 | |
b4b1e91c |
91 | A table called I<dbix_class_schema_versions> is created and maintained by the |
e84a43c1 |
92 | module. This is used to determine which version your database is currently at. |
93 | Similarly the $VERSION in your DBIC schema class is used to determine the |
94 | current DBIC schema version. |
8424c090 |
95 | |
e84a43c1 |
96 | The upgrade is initiated manually by calling C<upgrade> on your schema object, |
97 | this will attempt to upgrade the database from its current version to the current |
98 | schema version using a diff from your I<upgrade_directory>. If a suitable diff is |
99 | not found then no upgrade is possible. |
8424c090 |
100 | |
101 | NB: At the moment, only SQLite and MySQL are supported. This is due to |
102 | spotty behaviour in the SQL::Translator producers, please help us by |
e63a82f7 |
103 | enhancing them. Ask on the mailing list or IRC channel for details (community details |
e84a43c1 |
104 | in L<DBIx::Class>). |
93e4d41a |
105 | |
106 | =head1 GETTING STARTED |
107 | |
e84a43c1 |
108 | Firstly you need to setup your schema class as per the L</SYNOPSIS>, make sure |
109 | you have specified an upgrade_directory and an initial $VERSION. |
93e4d41a |
110 | |
e84a43c1 |
111 | Then you'll need two scripts, one to create DDL files and diffs and another to perform |
112 | upgrades. Your creation script might look like a bit like this: |
93e4d41a |
113 | |
e84a43c1 |
114 | use strict; |
115 | use Pod::Usage; |
116 | use Getopt::Long; |
117 | use MyApp::Schema; |
8424c090 |
118 | |
e84a43c1 |
119 | my ( $preversion, $help ); |
120 | GetOptions( |
121 | 'p|preversion:s' => \$preversion, |
122 | ) or die pod2usage; |
8424c090 |
123 | |
e84a43c1 |
124 | my $schema = MyApp::Schema->connect( |
125 | $dsn, |
126 | $user, |
127 | $password, |
128 | ); |
129 | my $sql_dir = './sql'; |
130 | my $version = $schema->schema_version(); |
131 | $schema->create_ddl_dir( 'MySQL', $version, $sql_dir, $preversion ); |
8424c090 |
132 | |
e84a43c1 |
133 | Then your upgrade script might look like so: |
134 | |
135 | use strict; |
136 | use MyApp::Schema; |
137 | |
138 | my $schema = MyApp::Schema->connect( |
139 | $dsn, |
140 | $user, |
141 | $password, |
142 | ); |
8424c090 |
143 | |
e84a43c1 |
144 | if (!$schema->get_db_version()) { |
145 | # schema is unversioned |
146 | $schema->deploy(); |
147 | } else { |
148 | $schema->upgrade(); |
149 | } |
150 | |
151 | The script above assumes that if the database is unversioned then it is empty |
152 | and we can safely deploy the DDL to it. However things are not always so simple. |
153 | |
154 | if you want to initialise a pre-existing database where the DDL is not the same |
155 | as the DDL for your current schema version then you will need a diff which |
156 | converts the database's DDL to the current DDL. The best way to do this is |
157 | to get a dump of the database schema (without data) and save that in your |
158 | SQL directory as version 0.000 (the filename must be as with |
159 | L<DBIx::Class::Schema/ddl_filename>) then create a diff using your create DDL |
160 | script given above from version 0.000 to the current version. Then hand check |
161 | and if necessary edit the resulting diff to ensure that it will apply. Once you have |
162 | done all that you can do this: |
163 | |
164 | if (!$schema->get_db_version()) { |
165 | # schema is unversioned |
166 | $schema->install("0.000"); |
167 | } |
168 | |
169 | # this will now apply the 0.000 to current version diff |
170 | $schema->upgrade(); |
171 | |
172 | In the case of an unversioned database the above code will create the |
173 | dbix_class_schema_versions table and write version 0.000 to it, then |
174 | upgrade will then apply the diff we talked about creating in the previous paragraph |
175 | and then you're good to go. |
8424c090 |
176 | |
177 | =cut |
178 | |
c9d2e0a2 |
179 | package DBIx::Class::Schema::Versioned; |
180 | |
181 | use strict; |
182 | use warnings; |
183 | use base 'DBIx::Class'; |
184 | use POSIX 'strftime'; |
185 | use Data::Dumper; |
186 | |
187 | __PACKAGE__->mk_classdata('_filedata'); |
188 | __PACKAGE__->mk_classdata('upgrade_directory'); |
8795fefb |
189 | __PACKAGE__->mk_classdata('backup_directory'); |
f925f7cb |
190 | __PACKAGE__->mk_classdata('do_backup'); |
8424c090 |
191 | __PACKAGE__->mk_classdata('do_diff_on_init'); |
192 | |
e84a43c1 |
193 | |
194 | =head1 METHODS |
195 | |
196 | =head2 upgrade_directory |
197 | |
198 | Use this to set the directory your upgrade files are stored in. |
199 | |
200 | =head2 backup_directory |
201 | |
202 | Use this to set the directory you want your backups stored in (note that backups |
203 | are disabled by default). |
204 | |
205 | =cut |
206 | |
93e4d41a |
207 | =head2 install |
c9d2e0a2 |
208 | |
93e4d41a |
209 | =over 4 |
c9d2e0a2 |
210 | |
93e4d41a |
211 | =item Arguments: $db_version |
e6129e56 |
212 | |
93e4d41a |
213 | =back |
8424c090 |
214 | |
93e4d41a |
215 | Call this to initialise a previously unversioned database. The table 'dbix_class_schema_versions' will be created which will be used to store the database version. |
8424c090 |
216 | |
93e4d41a |
217 | Takes one argument which should be the version that the database is currently at. Defaults to the return value of L</schema_version>. |
8424c090 |
218 | |
93e4d41a |
219 | See L</getting_started> for more details. |
f81b9157 |
220 | |
8424c090 |
221 | =cut |
222 | |
93e4d41a |
223 | sub install |
c9d2e0a2 |
224 | { |
93e4d41a |
225 | my ($self, $new_version) = @_; |
c9d2e0a2 |
226 | |
93e4d41a |
227 | # must be called on a fresh database |
228 | if ($self->get_db_version()) { |
229 | warn 'Install not possible as versions table already exists in database'; |
8424c090 |
230 | } |
c9d2e0a2 |
231 | |
93e4d41a |
232 | # default to current version if none passed |
233 | $new_version ||= $self->schema_version(); |
8424c090 |
234 | |
e84a43c1 |
235 | if ($new_version) { |
93e4d41a |
236 | # create versions table and version row |
237 | $self->{vschema}->deploy; |
238 | $self->_set_db_version; |
8424c090 |
239 | } |
c9d2e0a2 |
240 | } |
241 | |
e84a43c1 |
242 | =head2 deploy |
243 | |
244 | Same as L<DBIx::Class::Schema/deploy> but also calls C<install>. |
245 | |
246 | =cut |
247 | |
248 | sub deploy { |
249 | my $self = shift; |
250 | $self->next::method(@_); |
251 | $self->install(); |
252 | } |
253 | |
8424c090 |
254 | =head2 upgrade |
e2c0df8e |
255 | |
8424c090 |
256 | Call this to attempt to upgrade your database from the version it is at to the version |
e84a43c1 |
257 | this DBIC schema is at. If they are the same it does nothing. |
258 | |
259 | It requires an SQL diff file to exist in you I<upgrade_directory>, normally you will |
260 | have created this using L<DBIx::Class::Schema/create_ddl_dir>. |
c9d2e0a2 |
261 | |
e84a43c1 |
262 | If successful the dbix_class_schema_versions table is updated with the current |
263 | DBIC schema version. |
c9d2e0a2 |
264 | |
8424c090 |
265 | =cut |
c9d2e0a2 |
266 | |
8424c090 |
267 | sub upgrade |
268 | { |
269 | my ($self) = @_; |
270 | my $db_version = $self->get_db_version(); |
c9d2e0a2 |
271 | |
8424c090 |
272 | # db unversioned |
273 | unless ($db_version) { |
93e4d41a |
274 | warn 'Upgrade not possible as database is unversioned. Please call install first.'; |
8424c090 |
275 | return; |
c9d2e0a2 |
276 | } |
277 | |
8424c090 |
278 | # db and schema at same version. do nothing |
279 | if ($db_version eq $self->schema_version) { |
280 | print "Upgrade not necessary\n"; |
281 | return; |
c9d2e0a2 |
282 | } |
283 | |
37fcb5b5 |
284 | # strangely the first time this is called can |
285 | # differ to subsequent times. so we call it |
286 | # here to be sure. |
287 | # XXX - just fix it |
288 | $self->storage->sqlt_type; |
289 | |
8424c090 |
290 | my $upgrade_file = $self->ddl_filename( |
291 | $self->storage->sqlt_type, |
8424c090 |
292 | $self->schema_version, |
99a74c4a |
293 | $self->upgrade_directory, |
8424c090 |
294 | $db_version, |
295 | ); |
c9d2e0a2 |
296 | |
8424c090 |
297 | unless (-f $upgrade_file) { |
298 | warn "Upgrade not possible, no upgrade file found ($upgrade_file), please create one\n"; |
299 | return; |
300 | } |
c9d2e0a2 |
301 | |
8424c090 |
302 | # backup if necessary then apply upgrade |
303 | $self->_filedata($self->_read_sql_file($upgrade_file)); |
304 | $self->backup() if($self->do_backup); |
305 | $self->txn_do(sub { $self->do_upgrade() }); |
c9d2e0a2 |
306 | |
b4b1e91c |
307 | # set row in dbix_class_schema_versions table |
8424c090 |
308 | $self->_set_db_version; |
309 | } |
c9d2e0a2 |
310 | |
e6129e56 |
311 | =head2 do_upgrade |
312 | |
c9d2e0a2 |
313 | This is an overwritable method used to run your upgrade. The freeform method |
314 | allows you to run your upgrade any way you please, you can call C<run_upgrade> |
315 | any number of times to run the actual SQL commands, and in between you can |
316 | sandwich your data upgrading. For example, first run all the B<CREATE> |
317 | commands, then migrate your data from old to new tables/formats, then |
e7b14c5b |
318 | issue the DROP commands when you are finished. Will run the whole file as it is by default. |
8424c090 |
319 | |
320 | =cut |
321 | |
322 | sub do_upgrade |
323 | { |
e7b14c5b |
324 | my ($self) = @_; |
8424c090 |
325 | |
e7b14c5b |
326 | # just run all the commands (including inserts) in order |
327 | $self->run_upgrade(qr/.*?/); |
8424c090 |
328 | } |
329 | |
c9d2e0a2 |
330 | =head2 run_upgrade |
331 | |
332 | $self->run_upgrade(qr/create/i); |
333 | |
334 | Runs a set of SQL statements matching a passed in regular expression. The |
335 | idea is that this method can be called any number of times from your |
e84a43c1 |
336 | C<do_upgrade> method, running whichever commands you specify via the |
8424c090 |
337 | regex in the parameter. Probably won't work unless called from the overridable |
338 | do_upgrade method. |
c9d2e0a2 |
339 | |
8424c090 |
340 | =cut |
8795fefb |
341 | |
8424c090 |
342 | sub run_upgrade |
343 | { |
344 | my ($self, $stm) = @_; |
8795fefb |
345 | |
8424c090 |
346 | return unless ($self->_filedata); |
347 | my @statements = grep { $_ =~ $stm } @{$self->_filedata}; |
348 | $self->_filedata([ grep { $_ !~ /$stm/i } @{$self->_filedata} ]); |
8795fefb |
349 | |
8424c090 |
350 | for (@statements) |
351 | { |
352 | $self->storage->debugobj->query_start($_) if $self->storage->debug; |
353 | $self->storage->dbh->do($_) or warn "SQL was:\n $_"; |
354 | $self->storage->debugobj->query_end($_) if $self->storage->debug; |
355 | } |
8795fefb |
356 | |
8424c090 |
357 | return 1; |
358 | } |
42416a0b |
359 | |
93e4d41a |
360 | =head2 get_db_version |
361 | |
362 | Returns the version that your database is currently at. This is determined by the values in the |
e84a43c1 |
363 | dbix_class_schema_versions table that C<upgrade> and C<install> write to. |
93e4d41a |
364 | |
365 | =cut |
366 | |
367 | sub get_db_version |
368 | { |
369 | my ($self, $rs) = @_; |
370 | |
371 | my $vtable = $self->{vschema}->resultset('Table'); |
372 | my $version = 0; |
373 | eval { |
374 | my $stamp = $vtable->get_column('installed')->max; |
375 | $version = $vtable->search({ installed => $stamp })->first->version; |
376 | }; |
377 | return $version; |
378 | } |
379 | |
380 | =head2 schema_version |
381 | |
382 | Returns the current schema class' $VERSION |
383 | |
384 | =cut |
385 | |
386 | =head2 backup |
387 | |
388 | This is an overwritable method which is called just before the upgrade, to |
389 | allow you to make a backup of the database. Per default this method attempts |
390 | to call C<< $self->storage->backup >>, to run the standard backup on each |
391 | database type. |
392 | |
393 | This method should return the name of the backup file, if appropriate.. |
394 | |
395 | This method is disabled by default. Set $schema->do_backup(1) to enable it. |
396 | |
397 | =cut |
398 | |
399 | sub backup |
400 | { |
401 | my ($self) = @_; |
402 | ## Make each ::DBI::Foo do this |
403 | $self->storage->backup($self->backup_directory()); |
404 | } |
405 | |
ecea7937 |
406 | =head2 connection |
407 | |
408 | Overloaded method. This checks the DBIC schema version against the DB version and |
409 | warns if they are not the same or if the DB is unversioned. It also provides |
410 | compatibility between the old versions table (SchemaVersions) and the new one |
411 | (dbix_class_schema_versions). |
412 | |
e84a43c1 |
413 | To avoid the checks on connect, set the env var DBIC_NO_VERSION_CHECK or alternatively you can set the ignore_version attr in the forth argument like so: |
f81b9157 |
414 | |
415 | my $schema = MyApp::Schema->connect( |
416 | $dsn, |
417 | $user, |
418 | $password, |
419 | { ignore_version => 1 }, |
420 | ); |
ecea7937 |
421 | |
422 | =cut |
423 | |
8424c090 |
424 | sub connection { |
425 | my $self = shift; |
426 | $self->next::method(@_); |
f81b9157 |
427 | $self->_on_connect($_[3]); |
8424c090 |
428 | return $self; |
429 | } |
430 | |
431 | sub _on_connect |
432 | { |
f81b9157 |
433 | my ($self, $args) = @_; |
434 | |
435 | $args = {} unless $args; |
8424c090 |
436 | $self->{vschema} = DBIx::Class::Version->connect(@{$self->storage->connect_info()}); |
b4b1e91c |
437 | my $vtable = $self->{vschema}->resultset('Table'); |
438 | |
439 | # check for legacy versions table and move to new if exists |
440 | my $vschema_compat = DBIx::Class::VersionCompat->connect(@{$self->storage->connect_info()}); |
441 | unless ($self->_source_exists($vtable)) { |
442 | my $vtable_compat = $vschema_compat->resultset('TableCompat'); |
443 | if ($self->_source_exists($vtable_compat)) { |
444 | $self->{vschema}->deploy; |
732dc718 |
445 | map { $vtable->create({ installed => $_->Installed, version => $_->Version }) } $vtable_compat->all; |
b4b1e91c |
446 | $self->storage->dbh->do("DROP TABLE " . $vtable_compat->result_source->from); |
447 | } |
448 | } |
f81b9157 |
449 | |
ecea7937 |
450 | # useful when connecting from scripts etc |
f81b9157 |
451 | return if ($args->{ignore_version} || ($ENV{DBIC_NO_VERSION_CHECK} && !exists $args->{ignore_version})); |
8424c090 |
452 | my $pversion = $self->get_db_version(); |
453 | |
454 | if($pversion eq $self->schema_version) |
455 | { |
ffdf4f11 |
456 | # warn "This version is already installed\n"; |
8424c090 |
457 | return 1; |
458 | } |
42416a0b |
459 | |
8424c090 |
460 | if(!$pversion) |
461 | { |
462 | warn "Your DB is currently unversioned. Please call upgrade on your schema to sync the DB.\n"; |
463 | return 1; |
464 | } |
465 | |
466 | warn "Versions out of sync. This is " . $self->schema_version . |
467 | ", your database contains version $pversion, please call upgrade on your Schema.\n"; |
468 | } |
469 | |
93e4d41a |
470 | # is this just a waste of time? if not then merge with DBI.pm |
471 | sub _create_db_to_schema_diff { |
472 | my $self = shift; |
473 | |
474 | my %driver_to_db_map = ( |
475 | 'mysql' => 'MySQL' |
476 | ); |
477 | |
478 | my $db = $driver_to_db_map{$self->storage->dbh->{Driver}->{Name}}; |
479 | unless ($db) { |
480 | print "Sorry, this is an unsupported DB\n"; |
481 | return; |
482 | } |
483 | |
484 | eval 'require SQL::Translator "0.09"'; |
485 | if ($@) { |
486 | $self->throw_exception("SQL::Translator 0.09 required"); |
487 | } |
488 | |
489 | my $db_tr = SQL::Translator->new({ |
490 | add_drop_table => 1, |
491 | parser => 'DBI', |
492 | parser_args => { dbh => $self->storage->dbh } |
493 | }); |
494 | |
495 | $db_tr->producer($db); |
496 | my $dbic_tr = SQL::Translator->new; |
497 | $dbic_tr->parser('SQL::Translator::Parser::DBIx::Class'); |
498 | $dbic_tr = $self->storage->configure_sqlt($dbic_tr, $db); |
499 | $dbic_tr->data($self); |
500 | $dbic_tr->producer($db); |
501 | |
502 | $db_tr->schema->name('db_schema'); |
503 | $dbic_tr->schema->name('dbic_schema'); |
504 | |
505 | # is this really necessary? |
506 | foreach my $tr ($db_tr, $dbic_tr) { |
507 | my $data = $tr->data; |
508 | $tr->parser->($tr, $$data); |
509 | } |
510 | |
511 | my $diff = SQL::Translator::Diff::schema_diff($db_tr->schema, $db, |
512 | $dbic_tr->schema, $db, |
513 | { ignore_constraint_names => 1, ignore_index_names => 1, caseopt => 1 }); |
514 | |
515 | my $filename = $self->ddl_filename( |
516 | $db, |
517 | $self->schema_version, |
518 | $self->upgrade_directory, |
519 | 'PRE', |
520 | ); |
521 | my $file; |
522 | if(!open($file, ">$filename")) |
523 | { |
524 | $self->throw_exception("Can't open $filename for writing ($!)"); |
525 | next; |
526 | } |
527 | print $file $diff; |
528 | close($file); |
529 | |
530 | print "WARNING: There may be differences between your DB and your DBIC schema. Please review and if necessary run the SQL in $filename to sync your DB.\n"; |
531 | } |
532 | |
533 | |
534 | sub _set_db_version { |
535 | my $self = shift; |
536 | |
537 | my $vtable = $self->{vschema}->resultset('Table'); |
538 | $vtable->create({ version => $self->schema_version, |
539 | installed => strftime("%Y-%m-%d %H:%M:%S", gmtime()) |
540 | }); |
541 | |
542 | } |
543 | |
544 | sub _read_sql_file { |
545 | my $self = shift; |
546 | my $file = shift || return; |
547 | |
548 | my $fh; |
549 | open $fh, "<$file" or warn("Can't open upgrade file, $file ($!)"); |
550 | my @data = split(/\n/, join('', <$fh>)); |
551 | @data = grep(!/^--/, @data); |
552 | @data = split(/;/, join('', @data)); |
553 | close($fh); |
554 | @data = grep { $_ && $_ !~ /^-- / } @data; |
555 | @data = grep { $_ !~ /^(BEGIN|BEGIN TRANSACTION|COMMIT)/m } @data; |
556 | return \@data; |
557 | } |
558 | |
559 | sub _source_exists |
560 | { |
561 | my ($self, $rs) = @_; |
562 | |
563 | my $c = eval { |
564 | $rs->search({ 1, 0 })->count; |
565 | }; |
566 | return 0 if $@ || !defined $c; |
567 | |
568 | return 1; |
569 | } |
570 | |
8424c090 |
571 | 1; |
572 | |
573 | |
574 | =head1 AUTHORS |
c9d2e0a2 |
575 | |
576 | Jess Robinson <castaway@desert-island.demon.co.uk> |
8424c090 |
577 | Luke Saunders <luke@shadowcatsystems.co.uk> |
578 | |
579 | =head1 LICENSE |
580 | |
581 | You may distribute this code under the same terms as Perl itself. |