1DBIx::Class::Schema::VeUrsseironCeodn(t3r)ibuted Perl DoDcBuImxe:n:tCaltaisosn::Schema::Versioned(3)
2
6 DBIx::Class::Schema::Versioned - DBIx::Class::Schema plugin for Schema
7 upgrades
8
10 package MyApp::Schema;
11 use base qw/DBIx::Class::Schema/;
12 our $VERSION = 0.001;
14 # load MyApp::Schema::CD, MyApp::Schema::Book, MyApp::Schema::DVD
16 __PACKAGE__->load_classes(qw/CD Book DVD/);
17 __PACKAGE__->load_components(qw/Schema::Versioned/);
19 __PACKAGE__->upgrade_directory('/path/to/upgrades/');
20
22 This module provides methods to apply DDL changes to your database
23 using SQL diff files. Normally these diff files would be created using
24 "create_ddl_dir" in DBIx::Class::Schema.
25 A table called dbix_class_schema_versions is created and maintained by
27 the module. This is used to determine which version your database is
28 currently at. Similarly the $VERSION in your DBIC schema class is used
29 to determine the current DBIC schema version.
30 The upgrade is initiated manually by calling "upgrade" on your schema
32 object, this will attempt to upgrade the database from its current
33 version to the current schema version using a diff from your
34 upgrade_directory. If a suitable diff is not found then no upgrade is
35 possible.
36 NB: At the moment, only SQLite and MySQL are supported. This is due to
38 spotty behaviour in the SQL::Translator producers, please help us by
39 enhancing them. Ask on the mailing list or IRC channel for details
40 (community details in DBIx::Class).
41
43 Firstly you need to setup your schema class as per the "SYNOPSIS", make
44 sure you have specified an upgrade_directory and an initial $VERSION.
45 Then you'll need two scripts, one to create DDL files and diffs and
47 another to perform upgrades. Your creation script might look like a bit
48 like this:
49 use strict;
51 use Pod::Usage;
52 use Getopt::Long;
53 use MyApp::Schema;
54 my ( $preversion, $help );
56 GetOptions(
57 'p|preversion:s' => \$preversion,
58 ) or die pod2usage;
59 my $schema = MyApp::Schema->connect(
61 $dsn,
62 $user,
63 $password,
64 );
65 my $sql_dir = './sql';
66 my $version = $schema->schema_version();
67 $schema->create_ddl_dir( 'MySQL', $version, $sql_dir, $preversion );
68 Then your upgrade script might look like so:
70 use strict;
72 use MyApp::Schema;
73 my $schema = MyApp::Schema->connect(
75 $dsn,
76 $user,
77 $password,
78 );
79 if (!$schema->get_db_version()) {
81 # schema is unversioned
82 $schema->deploy();
83 } else {
84 $schema->upgrade();
85 }
86 The script above assumes that if the database is unversioned then it is
88 empty and we can safely deploy the DDL to it. However things are not
89 always so simple.
90 if you want to initialise a pre-existing database where the DDL is not
92 the same as the DDL for your current schema version then you will need
93 a diff which converts the database's DDL to the current DDL. The best
94 way to do this is to get a dump of the database schema (without data)
95 and save that in your SQL directory as version 0.000 (the filename must
96 be as with "ddl_filename" in DBIx::Class::Schema) then create a diff
97 using your create DDL script given above from version 0.000 to the
98 current version. Then hand check and if necessary edit the resulting
99 diff to ensure that it will apply. Once you have done all that you can
100 do this:
101 if (!$schema->get_db_version()) {
103 # schema is unversioned
104 $schema->install("0.000");
105 }
106 # this will now apply the 0.000 to current version diff
108 $schema->upgrade();
109 In the case of an unversioned database the above code will create the
111 dbix_class_schema_versions table and write version 0.000 to it, then
112 upgrade will then apply the diff we talked about creating in the
113 previous paragraph and then you're good to go.
114
116 upgrade_directory
117 Use this to set the directory your upgrade files are stored in.
118 backup_directory
120 Use this to set the directory you want your backups stored in (note
121 that backups are disabled by default).
122 install
124 Arguments: $db_version
125 Call this to initialise a previously unversioned database. The table
127 'dbix_class_schema_versions' will be created which will be used to
128 store the database version.
129 Takes one argument which should be the version that the database is
131 currently at. Defaults to the return value of "schema_version".
132 See "getting_started" for more details.
134 deploy
136 Same as "deploy" in DBIx::Class::Schema but also calls "install".
137 create_upgrade_path
139 Arguments: { upgrade_file => $file }
140 Virtual method that should be overridden to create an upgrade file.
142 This is useful in the case of upgrading across multiple versions to
143 concatenate several files to create one upgrade file.
144 You'll probably want the db_version retrieved via $self->get_db_version
146 and the schema_version which is retrieved via $self->schema_version
147 ordered_schema_versions
149 Returns: a list of version numbers, ordered from lowest to highest
150 Virtual method that should be overridden to return an ordered list of
152 schema versions. This is then used to produce a set of steps to upgrade
153 through to achieve the required schema version.
154 You may want the db_version retrieved via $self->get_db_version and the
156 schema_version which is retrieved via $self->schema_version
157 upgrade
159 Call this to attempt to upgrade your database from the version it is at
160 to the version this DBIC schema is at. If they are the same it does
161 nothing.
162 It will call "ordered_schema_versions" to retrieve an ordered list of
164 schema versions (if ordered_schema_versions returns nothing then it is
165 assumed you can do the upgrade as a single step). It then iterates
166 through the list of versions between the current db version and the
167 schema version applying one update at a time until all relevant updates
168 are applied.
169 The individual update steps are performed by using
171 "upgrade_single_step", which will apply the update and also update the
172 dbix_class_schema_versions table.
173 upgrade_single_step
175 Arguments: db_version - the version currently within the db
176 Arguments: target_version - the version to upgrade to
177 Call this to attempt to upgrade your database from the db_version to
179 the target_version. If they are the same it does nothing.
180 It requires an SQL diff file to exist in your upgrade_directory,
182 normally you will have created this using "create_ddl_dir" in
183 DBIx::Class::Schema.
184 If successful the dbix_class_schema_versions table is updated with the
186 target_version.
187 This method may be called repeatedly by the upgrade method to upgrade
189 through a series of updates.
190 do_upgrade
192 This is an overwritable method used to run your upgrade. The freeform
193 method allows you to run your upgrade any way you please, you can call
194 "run_upgrade" any number of times to run the actual SQL commands, and
195 in between you can sandwich your data upgrading. For example, first run
196 all the CREATE commands, then migrate your data from old to new
197 tables/formats, then issue the DROP commands when you are finished.
198 Will run the whole file as it is by default.
199 run_upgrade
201 $self->run_upgrade(qr/create/i);
202 Runs a set of SQL statements matching a passed in regular expression.
204 The idea is that this method can be called any number of times from
205 your "do_upgrade" method, running whichever commands you specify via
206 the regex in the parameter. Probably won't work unless called from the
207 overridable do_upgrade method.
208 apply_statement
210 Takes an SQL statement and runs it. Override this if you want to handle
211 errors differently.
212 get_db_version
214 Returns the version that your database is currently at. This is
215 determined by the values in the dbix_class_schema_versions table that
216 "upgrade" and "install" write to.
217 schema_version
219 Returns the current schema class' $VERSION
220 backup
222 This is an overwritable method which is called just before the upgrade,
223 to allow you to make a backup of the database. Per default this method
224 attempts to call "$self->storage->backup", to run the standard backup
225 on each database type.
226 This method should return the name of the backup file, if appropriate..
228 This method is disabled by default. Set $schema->do_backup(1) to enable
230 it.
231 connection
233 Overloaded method. This checks the DBIC schema version against the DB
234 version and warns if they are not the same or if the DB is unversioned.
235 It also provides compatibility between the old versions table
236 (SchemaVersions) and the new one (dbix_class_schema_versions).
237 To avoid the checks on connect, set the environment var
239 DBIC_NO_VERSION_CHECK or alternatively you can set the ignore_version
240 attr in the forth argument like so:
241 my $schema = MyApp::Schema->connect(
243 $dsn,
244 $user,
245 $password,
246 { ignore_version => 1 },
247 );
248
250 Jess Robinson <castaway@desert-island.me.uk> Luke Saunders
251 <luke@shadowcatsystems.co.uk>
252
254 You may distribute this code under the same terms as Perl itself.
255perl v5.12.0 2010-05-12 DBIx::Class::Schema::Versioned(3)