1ORLite::Migrate(3)    User Contributed Perl Documentation   ORLite::Migrate(3)
2
3
4

NAME

6       ORLite::Migrate - Extremely light weight SQLite-specific schema
7       migration
8

SYNOPSIS

10         # Build your ORM class using a patch timeline
11         # stored in the shared files directory.
12         use ORLite::Migrate {
13             create       => 1,
14             file         => 'sqlite.db',
15             timeline     => File::Spec->catdir(
16                 File::ShareDir::module_dir('My::Module'), 'patches',
17             ),
18             user_version => 8,
19         };
20
21         # migrate-1.pl - A trivial schema patch
22         #!/usr/bin/perl
23
24         use strict;
25         use DBI ();
26
27         # Locate the SQLite database
28         my $file = <STDIN>;
29         chomp($file);
30         unless ( -f $file and -w $file ) {
31             die "SQLite file $file does not exist";
32         }
33
34         # Connect to the SQLite database
35         my $dbh = DBI->connect("dbi:SQLite(RaiseError=>1):$file");
36         unless ( $dbh ) {
37           die "Failed to connect to $file";
38         }
39
40         $dbh->do( <<'END_SQL' );
41         create table foo (
42             id integer not null primary key,
43             name varchar(32) not null
44         )
45         END_SQL
46

DESCRIPTION

48       SQLite is a light weight single file SQL database that provides an
49       excellent platform for embedded storage of structured data.
50
51       ORLite is a light weight single class Object-Relational Mapper (ORM)
52       system specifically designed for (and limited to only) work with
53       SQLite.
54
55       ORLite::Migrate is a light weight single class Database Schema
56       Migration enhancement for ORLite.
57
58       It provides a simple implementation of schema versioning within the
59       SQLite database using the built-in "user_version" pragma (which is set
60       to zero by default).
61
62       When setting up the ORM class, an additional "timeline" parameter is
63       provided, which should be either a monolithic timeline class, or a
64       directory containing standalone migration scripts.
65
66       A "timeline" is a set of revisioned schema changed, to be applied in
67       order and representing the evolution of the database schema over time.
68       The end of the timeline, representing by the highest revision number,
69       represents the "current" anticipated schema for the application.
70
71       Because the patch sequence can be calculated from any arbitrary
72       starting version, by keeping the historical set of changes in your
73       application as schema patches it is possible for the user of any older
74       application version to install the most current version of an
75       application and have their database upgraded smoothly and safely.
76
77       The recommended location to store the migration timeline is a shared
78       files directory, locatable using one of the functions from
79       File::ShareDir.
80
81       The timeline for your application can be specified in two different
82       forms, with different advantages and disadvantages.
83
84   Timeline Directories
85       A Timeline Directory is a directory on the filesystem containing a set
86       of Perl scripts named in a consistent pattern.
87
88       These patch scripts are named in the form migrate-$version.pl, where
89       $version is the schema version to migrate to. A typical timeline
90       directory will look something like the following.
91
92         migrate-01.pl
93         migrate-02.pl
94         migrate-03.pl
95         migrate-04.pl
96         migrate-05.pl
97         migrate-06.pl
98         migrate-07.pl
99         migrate-08.pl
100         migrate-09.pl
101         migrate-10.pl
102
103       ORLite::Migrate formulates a migration plan that starts at the current
104       database "user_version" pragma value, executing the migration script
105       that has the version "user_version + 1", then executing "user_version +
106       2" and so on.
107
108       It will continue stepping forwards until it runs out of patches to
109       execute.
110
111       The main advantage of a timeline directory is that each patch is run in
112       its own process and interpreter. Hundreds of patches can be produced by
113       many different authors, with certainty that the changes described in
114       each will be executed as intended.
115
116       The main disadvantage of using a timeline directory is that your
117       application must be able to identify the Perl interpreter it is run in
118       so that it can execute a sub-process. This may be difficult or
119       impossible for cases such as PAR-packaged applications and Perl
120       interpreters embedded inside .exe wrappers or larger non-Perl
121       applications.
122
123       In general, it is recommended that you use the timeline directory
124       approach unless you encounter a situation in which sub-process
125       execution (or locating the patch files) is difficult.
126
127   Timeline Classes
128       A timeline class places all of the schema patches into a single Perl
129       module, with each patch represented as a method name.
130
131       The following is an example of a trivial timeline class.
132
133         package t::lib::MyTimeline;
134
135         use strict;
136         use base 'ORLite::Migrate::Timeline';
137
138         my $UPGRADE1 = <<'END_SQL';
139
140         create table foo (
141             id integer not null primary key,
142             name varchar(32) not null
143         );
144
145         insert into foo values ( 1, 'foo' )
146
147         END_SQL
148
149         sub upgrade1 {
150             my $self = shift;
151             foreach ( split /;\s+/, $UPGRADE1 ) {
152                 $self->do($_);
153             }
154             return 1;
155         }
156
157         sub upgrade2 {
158             $_[0]->do("insert into foo values ( 2, 'bar' )");
159         }
160
161         sub upgrade3 {
162             $_[0]->do("insert into foo values ( 3, 'baz' )");
163         }
164
165         1;
166
167       As with the patch files, the current state of the "user_version" pragma
168       will be examined, and each "upgradeN" method will be called to advance
169       the schema forwards.
170
171       The main advantage of a timeline class is that you will not need to
172       execute sub-processes, and so a timeline class will continue to
173       function even in unusual or exotic process contents such as PAR
174       packaging or .exe wrappers.
175
176       The main disadvantage of a timeline class is that the entire timeline
177       code must be loaded into memory no matter how many patch steps are
178       needed (and stay in memory after the migration has completed), and all
179       patches share a common interpreter and thus can potentially pollute or
180       corrupt each other.
181

SUPPORT

183       Bugs should be reported via the CPAN bug tracker at
184
185       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=ORLite-Migrate>
186
187       For other issues, contact the author.
188

AUTHOR

190       Adam Kennedy <adamk@cpan.org>
191
193       Copyright 2009 - 2012 Adam Kennedy.
194
195       This program is free software; you can redistribute it and/or modify it
196       under the same terms as Perl itself.
197
198       The full text of the license can be found in the LICENSE file included
199       with this module.
200
201
202
203perl v5.36.0                      2023-01-20                ORLite::Migrate(3)
Impressum