blib/lib/DBIx/Auto/Migrate.pm

filter: Statementstmt 78.5% 77 / 98 Branchbran 45.4% 10 / 22 Conditioncond 33.3% 2 / 6 MC/DCmcdc 0.0% 0 / 3 Subroutinesub 89.4% 17 / 19 Podpod n/a totaltotal 71.6% 106 / 148 CC 15 SCAR 14.2
CC
15
Cov
71%
__ANON__
17.2
__ANON__
4.5
_migrate
3.4
CRAP 4.1
↑ Summary
1 package DBIx::Auto::Migrate;
2  
3 2 our $VERSION = "1.001";
4  
5 2 ▶use v5.16.3;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 2 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 2 ▶use DBI;
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 4 ▶sub _check_defined_sub {
Subroutine _check_defined_sub: called CC=2 SCAR=9.2
12 4 my ( $caller, $sub ) = @_;
13 4 ▶ if ( !$caller->can($sub) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $caller->can($sub)) 0 4 4
14 0 die
15 0 "To import '@{[__PACKAGE__]}' in '$caller' you must implement the '$sub' subroutine";
16 }
17 }
18  
19 3 ▶sub import {
Subroutine import: called CC=1 SCAR=0.0
20 3 my $caller = caller;
21 2 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
22 3 ▶ *{"${caller}::finish_auto_migrate"} = sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
23 1 _migrations_finish($caller);
24 3 };
25 }
26  
27 1 ▶sub _migrations_finish {
Subroutine _migrations_finish: called CC=1 SCAR=0.8
28 1 my ($caller) = @_;
29 1 _check_defined_sub( $caller, 'migrations' );
30 1 _check_defined_sub( $caller, 'dsn' );
31 1 _check_defined_sub( $caller, 'user' );
32 1 _check_defined_sub( $caller, 'pass' );
33  
34 {
35 2 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
36 2 ▶ no warnings 'redefine';
Subroutine BEGIN: called CC=1 SCAR=0.0
37 1 ▶ *{"${caller}::connect"} = sub {
Subroutine __ANON__: called CC=4 SCAR=15.0
38 1 my $self = shift;
39 1 my $extra;
40 1 ▶ if ( defined( my $extra_sub = $self->can('extra') ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined(my $extra_sub = $self->can("extra"))) 0 1 1
41 0 $extra = $extra_sub->();
42 }
43 1 ▶ $extra //= {};
Condition50%1/2
$extra //= {}
l!l
01
MC/DC0%0/1
$extra //= {}
$extra
Truth table50%1/2
A
A= $extra
Aresult
11
00
44 1 ▶ if ( 'HASH' ne ref $extra ) {
Branch: 1 branch
BranchTrueFalseTotal
if ("HASH" ne ref $extra) 0 1 1
45 0 die "${caller}::extra should return a hashref or undef";
46 }
47 1 my ( $dsn, $user, $pass ) = ( $self->dsn, $self->user, $self->pass );
48 1 _connect_wrapper( $self, $caller, 'connect', $dsn, $user, $pass, $extra );
49 1 };
50 1 ▶ *{"${caller}::connect_cached"} = sub {
Subroutine __ANON__: not called CC=4 SCAR=28.4
51 0 my $self = shift;
52 0 my $extra;
53 0 ▶ if ( defined( my $extra_sub = $self->can('extra') ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined(my $extra_sub = $self->can("extra"))) 0 0 0
54 0 $extra = $extra_sub->();
55 }
56 0 ▶ $extra //= {};
Condition0%0/2
$extra //= {}
l!l
00
MC/DC0%0/1
$extra //= {}
$extra
Truth table0%0/2
A
A= $extra
Aresult
11
00
57 0 ▶ if ( 'HASH' ne ref $extra ) {
Branch: 1 branch
BranchTrueFalseTotal
if ("HASH" ne ref $extra) 0 0 0
58 0 die "${caller}::extra should return a hashref or undef";
59 }
60 0 my ( $dsn, $user, $pass ) = ( $self->dsn, $self->user, $self->pass );
61 0 _connect_wrapper( $self, $caller, 'connect_cached', $dsn, $user, $pass,
62 $extra );
63 1 };
64  
65 }
66 }
67  
68 1 ▶sub _connect_wrapper {
Subroutine _connect_wrapper: called CC=2 SCAR=8.5
69 1 my ( $self, $caller, $sub, $dsn, $user, $pass, $extra ) = @_;
70 my $dbh = DBI->can($sub)->(
71 'DBI', $dsn, $user, $pass,
72 {
73 (
74 defined $extra
75 ? (%$extra)
76 : (
77 RaiseError => 1,
78 Callbacks => {
79 0 ▶ connected => sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
80 0 eval {shift->do('set timezone = UTC')};
81 0 return;
82 }
83 }
84 )
85 1 ▶ )
Branch: 1 branch
BranchTrueFalseTotal
defined $extra ? : 1 0 1
86 },
87 );
88 1 _migrate( $self, $caller, $dbh );
89 1 return $dbh;
90 }
91  
92 1 ▶sub _migrate {
Subroutine _migrate: called CC=3 SCAR=12.3
93 1 my ( $self, $caller, $dbh ) = @_;
94 1 local $dbh->{RaiseError} = 0;
95 1 local $dbh->{PrintError} = 0;
96 1 my @migrations = $self->can('migrations')->();
97 1 ▶ if ( _get_current_migration($dbh) > @migrations ) {
Branch: 1 branch
BranchTrueFalseTotal
if (_get_current_migration($dbh) > @migrations) 0 1 1
98 0 warn "Something happened there, wrong migration number.";
99 }
100 1 ▶ if ( _get_current_migration($dbh) >= @migrations ) {
Branch: 1 branch
BranchTrueFalseTotal
if (_get_current_migration($dbh) >= @migrations) 0 1 1
101 0 say STDERR "Migrations already applied.";
102 0 return;
103 }
104 1 _apply_migrations( $dbh, \@migrations );
105  
106 }
107  
108 1 ▶sub _apply_migrations {
Subroutine _apply_migrations: called CC=2 SCAR=6.9
109 1 my $dbh = shift;
110 1 my $migrations = shift;
111 1 ▶ for ( my $i = _get_current_migration($dbh) ; $i < @$migrations ; $i++ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($i < @$migrations) 3 1 4
112 3 local $dbh->{RaiseError} = 1;
113 3 my $current_migration = $migrations->[$i];
114 3 my $migration_number = $i + 1;
115 3 _apply_migration( $dbh, $current_migration, $migration_number );
116 }
117 }
118  
119 3 ▶sub _get_current_migration {
Subroutine _get_current_migration: called CC=2 SCAR=7.1
120 3 my $dbh = shift;
121 3 my $result = $dbh->selectrow_hashref( <<'EOF', undef, 'current_migration' );
122 SELECT value FROM options WHERE name = ?;
123 EOF
124 3 ▶ return int( $result->{value} // 0 );
Condition50%1/2
$result->{"value"} // 0
l!l
03
MC/DC0%0/1
$result->{"value"} // 0
$result->{"value"}
Truth table50%1/2
A
A= $result->{"value"}
Aresult
11
00
125 }
126  
127 3 ▶sub _apply_migration {
Subroutine _apply_migration: called CC=3 SCAR=11.4
128 3 my $dbh = shift;
129 3 my $current_migration = shift;
130 3 my $migration_number = shift;
131 {
132 3 eval { $dbh->do($current_migration); };
133 3 ▶ if ($@) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 0 3 3
134 0 die "$current_migration\n failed with: $@";
135 }
136 }
137 3 my $success = eval {
138 3 $dbh->do( <<'EOF', undef, 'current_migration', $migration_number );
139 INSERT INTO options (name, value)
140 VALUES (?, ?)
141 EOF
142 3 1;
143 };
144 3 ▶ if (!$success) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $success) 0 3 3
145 0 $dbh->do( <<'EOF', undef, $migration_number, 'current_migration' );
146 UPDATE options
147 SET value = ?
148 WHERE name = ?
149 EOF
150 }
151 }
152 2 1;
153  
154 =pod
155  
156 =encoding utf-8
157  
158 =head1 NAME
159  
160 DBIx::Auto::Migrate - Wrap your database connections and automatically apply db migrations.
161  
162 =head1 SYNOPSIS
163  
164 package MyCompany::DB;
165
166 use v5.16.3;
167 use strict;
168 use warnings;
169  
170 use DBIx::Auto::Migrate;
171  
172 finish_auto_migrate;
173  
174 sub create_index {
175 my ($table, $column) = @_;
176 if (!$table) {
177 die 'Index requires table';
178 }
179 if (!$column) {
180 die 'Index requires column';
181 }
182 return "CREATE INDEX index_${table}_${column} ON $table ($column)";
183 }
184  
185 sub migrations {
186 return (
187 'CREATE TABLE options (
188 id BIGSERIAL PRIMARY KEY,
189 name TEXT,
190 value TEXT,
191 UNIQUE (name)
192 )',
193 create_index(qw/options name/),
194 'CREATE TABLE users (
195 id BIGSERIAL PRIMARY KEY,
196 uuid TEXT NOT NULL,
197 username TEXT NOT NULL,
198 name TEXT NOT NULL,
199 surname TEXT NOT NULL,
200 UNIQUE(username)
201 )',
202 create_index(qw/users uuid/),
203 create_index(qw/users username/),
204 );
205 }
206  
207 sub dsn {
208 return 'dbi:Pg:dbname=my_fancy_app_db';
209 }
210  
211 sub user {
212 return 'user';
213 }
214  
215 sub pass {
216 return 'supertopsecretdbpass';
217 }
218  
219 sub extra {
220 {
221 PrintError => 1,
222 }
223 }
224  
225 And elsewhere:
226  
227 my $dbh = MyCompany::DB->connect;
228 my $dbh = MyCompany::DB->connect_cached;
229  
230 =head1 DESCRIPTION
231  
232 Sometimes is convenient to be able to make server or desktop programs that
233 use a database with the ability to be automatically have their database
234 upgraded in runtime.
235  
236 This module comes from a snippet of code I was copying all the time between
237 different projects with different database engines such as PostgreSQL and SQLite,
238 it is time to stop copying logic like this between projects and make public
239 my way to apply database migrations defined in code in a extensible way.
240  
241 It is only possible to migrate forward so be careful.
242  
243 To check an example project that uses this code you can check L<https://github.com/sergiotarxz/Perl-App-RSS-Social>
244  
245 =head1 SUBS TO IMPLEMENT IN YOUR OWN DATABASE WRAPPER
246  
247 =head2 migrations
248  
249 sub migrations {
250 return (
251 'CREATE TABLE options (
252 id BIGSERIAL PRIMARY KEY,
253 name TEXT,
254 value TEXT,
255 UNIQUE (name)
256 )',
257 'CREATE TABLE users (
258 id BIGSERIAL PRIMARY KEY,
259 uuid TEXT NOT NULL,
260 username TEXT NOT NULL,
261 name TEXT NOT NULL,
262 surname TEXT NOT NULL,
263 UNIQUE(username)
264 )',
265 );
266 }
267  
268 Returns a list of migrations, creating a options table in the first migration is
269 obligatory since it is internally used to keep track of the current migration number.
270  
271 =head2 dsn
272  
273 sub dsn {
274 return 'dbi:Pg:dbname=my_fancy_app_db';
275 }
276  
277 Returns a valid DSN for L<DBI>, you can use any logic to return this, even reading a database config file.
278  
279 =head2 user
280  
281 sub user { 'mydbuser' }
282  
283 Returns a valid user for L<DBI>, you can use any logic to return this, even reading a database config file.
284  
285 =head2 pass
286  
287 sub pass { 'mypass' }
288  
289 Returns a valid password for L<DBI>, you can use any logic to return this, even reading a database config file.
290  
291 =head2 extra
292  
293 sub extra {
294 {
295 PrintError => 1,
296 }
297 }
298  
299 You can optionally implement this method to pass extra options to L<DBI>, the
300 return must be a hashref or undef.
301  
302 =head1 FINALIZING THE DATABASE WRAPPER CLASS
303  
304 finish_auto_migrate();
305  
306 Calling this method will ensure your class is completely ready to be used,
307 you can do it at any point if every prerequisite is available.
308  
309 =head1 METHODS AUTOMATICALLY AVAILABLE IN YOUR WRAPPER
310  
311 =head2 connect
312  
313 my $dbh = MyCompany::DB->connect;
314  
315 Same as L<DBI>::C<connect> but without taking any argument.
316  
317 =head2 connect_cached
318  
319 my $dbh = MyCompany::DB->connect_cached;
320  
321 Same as L<DBI>::C<connect_cached> but without taking any argument.
322  
323 =head1 BUGS AND LIMITATIONS
324  
325 Tries to be database independent, but I cannot really ensure it.
326  
327 More testing is needed.
328  
329 =head1 AUTHOR
330  
331 SERGIOXZ - Sergio Iglesias
332  
333 =head1 CONTRIBUTORS
334  
335 SERGIOXZ - Sergio Iglesias
336  
337 =head1 COPYRIGHT
338  
339 Copyright © Sergio Iglesias (2025)
340  
341 =head1 LICENSE
342  
343 This library is free software and may be distributed under the same terms
344 as perl itself. See L<https://dev.perl.org/licenses/>.
345  
346 =cut
↑ Summary