1ORLite::Migrate::TimeliUnsee(r3)Contributed Perl DocumenOtRaLtiitoen::Migrate::Timeline(3)
2
3
4

NAME

6       ORLite::Migrate::Timeline - ORLite::Migrate timelines contained in a
7       single class
8

SYNOPSIS

10         package My::Timeline;
11
12         use strict;
13         use base 'ORLite::Migrate::Timeline';
14
15         sub upgrade1 { $_[0]->do(<<'END_SQL') }
16         CREATE TABLE foo (
17             bar INTEGER NOT NULL PRIMARY KEY,
18         )
19         END_SQL
20
21         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
29         1;
30

DESCRIPTION

32       The default ORLite::Migrate timeline implementation makes use of
33       separate Perl "patch" scripts to move the database schema timeline
34       forwards.
35
36       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
42       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
46       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
51       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
56       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
62       To make further changes to the schema, you add additional "upgrade2",
63       "upgrade3" and so on.
64

METHODS

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
69   new
70         my $timeline = My::Class->new(
71             dbh => $DBI_db_object,
72         );
73
74       The "new" method is called internally by ORLite::Migrate on the
75       timeline class you specify to construct the timeline object.
76
77       The constructor takes a single parameter which should be a DBI::db
78       database connection to your SQLite database.
79
80       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
84   upgrade
85         $timeline->upgrade(10);
86
87       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
91       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
95       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
100       Returns true if all (zero or more) upgrade methods executed without
101       throwing an exception.
102
103       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
107   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
112   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
117   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
122   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
127   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
132   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
137   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
142   pragma
143         # Get a pragma value
144         my $locking = $self->pragma('locking_mode');
145
146         # Set a pragma value
147         $self->pragma( synchronous => 0 );
148
149       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
153       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
157           # 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
162   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
168       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
172       In these situations it provides a small amount of added safety to be
173       able to say things like.
174
175         sub upgrade25 {
176             my $self = shift;
177             if ( $self->table_exists('foo') ) {
178                 $self->do('DROP TABLE foo');
179             }
180         }
181
182       Returns true (1) if the table exists or false (0) if not.
183
184   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
191       Returns true (1) if the table exists or false (0) if not.
192
193   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
198       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

SUPPORT

204       Bugs should be reported via the CPAN bug tracker at
205
206       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=ORLite-Migrate>
207
208       For other issues, contact the author.
209

AUTHOR

211       Adam Kennedy <adamk@cpan.org>
212
214       Copyright 2009 - 2012 Adam Kennedy.
215
216       This program is free software; you can redistribute it and/or modify it
217       under the same terms as Perl itself.
218
219       The full text of the license can be found in the LICENSE file included
220       with this module.
221
222
223
224perl v5.36.0                      2023-01-20      ORLite::Migrate::Timeline(3)
Impressum