1ORLite::Migrate::TimeliUnsee(r3)Contributed Perl DocumenOtRaLtiitoen::Migrate::Timeline(3)
2
6 ORLite::Migrate::Timeline - ORLite::Migrate timelines contained in a
7 single class
8
10 package My::Timeline;
11 use strict;
13 use base 'ORLite::Migrate::Timeline';
14 sub upgrade1 { $_[0]->do(<<'END_SQL') }
16 CREATE TABLE foo (
17 bar INTEGER NOT NULL PRIMARY KEY,
18 )
19 END_SQL
20 sub upgrade2 {
22 my $self = shift;
23 $self->do('TRUNCATE TABLE foo');
24 foreach ( 1 .. 10 ) {
25 $self->do( 'INSERT INTO foo VALUES ( ? )', {}, $_ );
26 }
27 }
28 1;
30
32 The default ORLite::Migrate timeline implementation makes use of
33 separate Perl "patch" scripts to move the database schema timeline
34 forwards.
35 This solution is preferred because the separate scripts provide process
37 isolation between your migration and run-time code. That is, the code
38 that migrates the schema a single step forwards is guarenteed to never
39 use the same variables or load the same modules or interact strangely
40 with any other patch scripts, or with the main program.
41 However, to execute a sub-script your program needs to reliably know
43 where the Perl executable that launched it is and in some situations
44 this is difficult or infeasible.
45 ORLite::Migrate::Timeline provides an alternative mechanism for
47 specifying the migration timeline which adds the ability to run
48 migration timelines in strange Perl environments at the cost of losing
49 process isolation for your patch code.
50 When using this method, extra caution should be taken to avoid all use
52 of global variables, and to strictly avoid loading large amounts of
53 data into memory or using magic Perl modules such as Aspect or
54 UNIVERSAL::isa which might have a global impact on your program.
55 To use this method, create a new class which inherits from
57 ORLite::Migrate::Timeline and create a "upgrade1" method. When
58 encountering a new unversioned SQLite database, the migration planner
59 will execute this "upgrade1" method and set the schema version to 1
60 once completed.
61 To make further changes to the schema, you add additional "upgrade2",
63 "upgrade3" and so on.
64
66 A series of convenience methods are provided for you by the base class
67 to assist in making your schema patch code simpler and easier.
68 new
70 my $timeline = My::Class->new(
71 dbh => $DBI_db_object,
72 );
73 The "new" method is called internally by ORLite::Migrate on the
75 timeline class you specify to construct the timeline object.
76 The constructor takes a single parameter which should be a DBI::db
78 database connection to your SQLite database.
79 Returns an instance of your timeline class, or throws an exception
81 (dies) if not passed a DBI connection object, or the database handle is
82 not "AutoCommit".
83 upgrade
85 $timeline->upgrade(10);
86 The "update" method is called on the timeline object by ORLite::Migrate
88 to trigger the sequential execution of the individual "upgradeN"
89 methods.
90 The first method to be called will be the method one greater than the
92 current value of the "user_revision" pragma, and the last method to be
93 called will be the target revision, the first parameter to the method.
94 As all upgrade methods are contained in a single class, a high level of
96 control is assumed and so the execution plan will not be calculated in
97 advance. The "upgrade" method will simply start rolling forwards and
98 keep going until it reaches the target version (or die's trying).
99 Returns true if all (zero or more) upgrade methods executed without
101 throwing an exception.
102 Throws an exception (dies) if any "upgradeN" method throws an
104 exception, or if the migration process expects to find a particular
105 numeric "upgradeN" method and cannot do so.
106 do
108 The "do" method is a convenience which provides a direct wrapper over
109 the DBI method "do". It takes the same parameters and returns the same
110 results.
111 selectall_arrayref
113 The "selectall_arrayref" method is a convenience which provides a
114 direct wrapper over the DBI method "selectall_arrayref". It takes the
115 same parameters and returns the same results.
116 selectall_hashref
118 The "selectall_hashref" method is a convenience which provides a direct
119 wrapper over the DBI method "selectall_hashref". It takes the same
120 parameters and returns the same results.
121 selectcol_arrayref
123 The "selectcol_arrayref" method is a convenience which provides a
124 direct wrapper over the DBI method "selectcol_arrayref". It takes the
125 same parameters and returns the same results.
126 selectrow_array
128 The "selectrow_array" method is a convenience which provides a direct
129 wrapper over the DBI method "selectrow_array". It takes the same
130 parameters and returns the same results.
131 selectrow_arrayref
133 The "selectrow_arrayref" method is a convenience which provides a
134 direct wrapper over the DBI method "selectrow_arrayref". It takes the
135 same parameters and returns the same results.
136 selectrow_hashref
138 The "selectrow_hashref" method is a convenience which provides a direct
139 wrapper over the DBI method "selectrow_hashref". It takes the same
140 parameters and returns the same results.
141 pragma
143 # Get a pragma value
144 my $locking = $self->pragma('locking_mode');
145 # Set a pragma value
147 $self->pragma( synchronous => 0 );
148 The "pragma" method provides a convenience over the top of the "PRAGMA"
150 SQL statement, and allows the convenience query and change of SQLite
151 pragmas.
152 For example, if your application wanted to switch SQLite auto vacuuming
154 off and instead control vacuuming of the database manually, you could
155 do something like the following.
156 # Disable auto-vacuuming because we'll only fill this once.
158 # Do a one-time vacuum so we start with a clean empty database.
159 $dbh->pragma( auto_vacuum => 0 );
160 $dbh->do('VACUUM');
161 table_exists
163 The "table_exists" method is a convenience to check for the existance
164 of a table already. Most of the time this isn't going to be needed
165 because the schema revisioning itself guarentees there is or is not an
166 existing table of a particular name.
167 However, occasionally you may encounter a situation where your ORLite
169 module is sharing a SQLite database with other code, or you are taking
170 over control of a table from a plugin, or similar.
171 In these situations it provides a small amount of added safety to be
173 able to say things like.
174 sub upgrade25 {
176 my $self = shift;
177 if ( $self->table_exists('foo') ) {
178 $self->do('DROP TABLE foo');
179 }
180 }
181 Returns true (1) if the table exists or false (0) if not.
183 column_exists
185 The "column_exists" method is a convenience to check for the existance
186 of a column already. It has somewhat less uses than the similar
187 "table_exists" and is mainly used when a column may exist on various
188 miscellaneous developer versions of databases, or where the table
189 structure may be variable across different groups of users.
190 Returns true (1) if the table exists or false (0) if not.
192 dbh
194 If you need to do something to the database outside the scope of the
195 methods described above, the "dbh" method can be used to get access to
196 the database connection directly.
197 This is discouraged as it can allow your migration code to create
199 changes that might cause unexpected problems. However, in the 1% of
200 cases where the methods above are not enough, using it with caution
201 will allow you to make changes that would not otherwise be possible.
202
204 Bugs should be reported via the CPAN bug tracker at
205 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=ORLite-Migrate>
207 For other issues, contact the author.
209
211 Adam Kennedy <adamk@cpan.org>
212
214 Copyright 2009 - 2012 Adam Kennedy.
215 This program is free software; you can redistribute it and/or modify it
217 under the same terms as Perl itself.
218 The full text of the license can be found in the LICENSE file included
220 with this module.
221perl v5.36.0 2023-01-20 ORLite::Migrate::Timeline(3)