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
38 DBIx::Class::DeploymentHandler is a much more powerful alternative to
39 this module. Examples of things it can do that this module cannot do
40 include
41 • Downgrades in addition to upgrades
43 • Multiple sql files per upgrade/downgrade/install
45 • Perl scripts allowed for upgrade/downgrade/install
47 • Just one set of files needed for upgrade, unlike this module where
49 one might need to generate "factorial(scalar @versions)"
50
52 Firstly you need to setup your schema class as per the "SYNOPSIS", make
53 sure you have specified an upgrade_directory and an initial $VERSION.
54 Then you'll need two scripts, one to create DDL files and diffs and
56 another to perform upgrades. Your creation script might look like a bit
57 like this:
58 use strict;
60 use Pod::Usage;
61 use Getopt::Long;
62 use MyApp::Schema;
63 my ( $preversion, $help );
65 GetOptions(
66 'p|preversion:s' => \$preversion,
67 ) or die pod2usage;
68 my $schema = MyApp::Schema->connect(
70 $dsn,
71 $user,
72 $password,
73 );
74 my $sql_dir = './sql';
75 my $version = $schema->schema_version();
76 $schema->create_ddl_dir( 'MySQL', $version, $sql_dir, $preversion );
77 Then your upgrade script might look like so:
79 use strict;
81 use MyApp::Schema;
82 my $schema = MyApp::Schema->connect(
84 $dsn,
85 $user,
86 $password,
87 );
88 if (!$schema->get_db_version()) {
90 # schema is unversioned
91 $schema->deploy();
92 } else {
93 $schema->upgrade();
94 }
95 The script above assumes that if the database is unversioned then it is
97 empty and we can safely deploy the DDL to it. However things are not
98 always so simple.
99 if you want to initialise a pre-existing database where the DDL is not
101 the same as the DDL for your current schema version then you will need
102 a diff which converts the database's DDL to the current DDL. The best
103 way to do this is to get a dump of the database schema (without data)
104 and save that in your SQL directory as version 0.000 (the filename must
105 be as with "ddl_filename" in DBIx::Class::Schema) then create a diff
106 using your create DDL script given above from version 0.000 to the
107 current version. Then hand check and if necessary edit the resulting
108 diff to ensure that it will apply. Once you have done all that you can
109 do this:
110 if (!$schema->get_db_version()) {
112 # schema is unversioned
113 $schema->install("0.000");
114 }
115 # this will now apply the 0.000 to current version diff
117 $schema->upgrade();
118 In the case of an unversioned database the above code will create the
120 dbix_class_schema_versions table and write version 0.000 to it, then
121 upgrade will then apply the diff we talked about creating in the
122 previous paragraph and then you're good to go.
123
125 upgrade_directory
126 Use this to set the directory your upgrade files are stored in.
127 backup_directory
129 Use this to set the directory you want your backups stored in (note
130 that backups are disabled by default).
131 install
133 Arguments: $db_version
134 Call this to initialise a previously unversioned database. The table
136 'dbix_class_schema_versions' will be created which will be used to
137 store the database version.
138 Takes one argument which should be the version that the database is
140 currently at. Defaults to the return value of "schema_version".
141 See "GETTING STARTED" for more details.
143 deploy
145 Same as "deploy" in DBIx::Class::Schema but also calls "install".
146 create_upgrade_path
148 Arguments: { upgrade_file => $file }
149 Virtual method that should be overridden to create an upgrade file.
151 This is useful in the case of upgrading across multiple versions to
152 concatenate several files to create one upgrade file.
153 You'll probably want the db_version retrieved via $self->get_db_version
155 and the schema_version which is retrieved via $self->schema_version
156 ordered_schema_versions
158 Return Value: a list of version numbers, ordered from lowest to highest
159 Virtual method that should be overridden to return an ordered list of
161 schema versions. This is then used to produce a set of steps to upgrade
162 through to achieve the required schema version.
163 You may want the db_version retrieved via $self->get_db_version and the
165 schema_version which is retrieved via $self->schema_version
166 upgrade
168 Call this to attempt to upgrade your database from the version it is at
169 to the version this DBIC schema is at. If they are the same it does
170 nothing.
171 It will call "ordered_schema_versions" to retrieve an ordered list of
173 schema versions (if ordered_schema_versions returns nothing then it is
174 assumed you can do the upgrade as a single step). It then iterates
175 through the list of versions between the current db version and the
176 schema version applying one update at a time until all relevant updates
177 are applied.
178 The individual update steps are performed by using
180 "upgrade_single_step", which will apply the update and also update the
181 dbix_class_schema_versions table.
182 upgrade_single_step
184 Arguments: db_version - the version currently within the db
185 Arguments: target_version - the version to upgrade to
186 Call this to attempt to upgrade your database from the db_version to
188 the target_version. If they are the same it does nothing.
189 It requires an SQL diff file to exist in your upgrade_directory,
191 normally you will have created this using "create_ddl_dir" in
192 DBIx::Class::Schema.
193 If successful the dbix_class_schema_versions table is updated with the
195 target_version.
196 This method may be called repeatedly by the upgrade method to upgrade
198 through a series of updates.
199 do_upgrade
201 This is an overwritable method used to run your upgrade. The freeform
202 method allows you to run your upgrade any way you please, you can call
203 "run_upgrade" any number of times to run the actual SQL commands, and
204 in between you can sandwich your data upgrading. For example, first run
205 all the CREATE commands, then migrate your data from old to new
206 tables/formats, then issue the DROP commands when you are finished.
207 Will run the whole file as it is by default.
208 run_upgrade
210 $self->run_upgrade(qr/create/i);
211 Runs a set of SQL statements matching a passed in regular expression.
213 The idea is that this method can be called any number of times from
214 your "do_upgrade" method, running whichever commands you specify via
215 the regex in the parameter. Probably won't work unless called from the
216 overridable do_upgrade method.
217 apply_statement
219 Takes an SQL statement and runs it. Override this if you want to handle
220 errors differently.
221 get_db_version
223 Returns the version that your database is currently at. This is
224 determined by the values in the dbix_class_schema_versions table that
225 "upgrade" and "install" write to.
226 schema_version
228 Returns the current schema class' $VERSION
229 backup
231 This is an overwritable method which is called just before the upgrade,
232 to allow you to make a backup of the database. Per default this method
233 attempts to call "$self->storage->backup", to run the standard backup
234 on each database type.
235 This method should return the name of the backup file, if appropriate..
237 This method is disabled by default. Set $schema->do_backup(1) to enable
239 it.
240 connection
242 Overloaded method. This checks the DBIC schema version against the DB
243 version and warns if they are not the same or if the DB is unversioned.
244 It also provides compatibility between the old versions table
245 (SchemaVersions) and the new one (dbix_class_schema_versions).
246 To avoid the checks on connect, set the environment var
248 DBIC_NO_VERSION_CHECK or alternatively you can set the ignore_version
249 attr in the forth argument like so:
250 my $schema = MyApp::Schema->connect(
252 $dsn,
253 $user,
254 $password,
255 { ignore_version => 1 },
256 );
257
259 Check the list of additional DBIC resources.
260
262 This module is free software copyright by the DBIx::Class (DBIC)
263 authors. You can redistribute it and/or modify it under the same terms
264 as the DBIx::Class library.
265perl v5.36.0 2022-07-22 DBIx::Class::Schema::Versioned(3)