| 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
| |||||||||||||
| 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
| |||||||||||||
| 41 | 0 | $extra = $extra_sub->(); | |||||||||||
| 42 | } | ||||||||||||
| 43 | 1 | ▶ | $extra //= {}; | ||||||||||
|
Condition50%1/2
$extra //= {}
MC/DC0%0/1
$extra //= {}
$extra
Truth table50%1/2
A
A= $extra
| |||||||||||||
| 44 | 1 | ▶ | if ( 'HASH' ne ref $extra ) { | ||||||||||
|
Branch: 1 branch
| |||||||||||||
| 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
| |||||||||||||
| 54 | 0 | $extra = $extra_sub->(); | |||||||||||
| 55 | } | ||||||||||||
| 56 | 0 | ▶ | $extra //= {}; | ||||||||||
|
Condition0%0/2
$extra //= {}
MC/DC0%0/1
$extra //= {}
$extra
Truth table0%0/2
A
A= $extra
| |||||||||||||
| 57 | 0 | ▶ | if ( 'HASH' ne ref $extra ) { | ||||||||||
|
Branch: 1 branch
| |||||||||||||
| 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
| |||||||||||||
| 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
| |||||||||||||
| 98 | 0 | warn "Something happened there, wrong migration number."; | |||||||||||
| 99 | } | ||||||||||||
| 100 | 1 | ▶ | if ( _get_current_migration($dbh) >= @migrations ) { | ||||||||||
|
Branch: 1 branch
| |||||||||||||
| 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
| |||||||||||||
| 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
MC/DC0%0/1
$result->{"value"} // 0
$result->{"value"}
Truth table50%1/2
A
A= $result->{"value"}
| |||||||||||||
| 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
| |||||||||||||
| 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
| |||||||||||||
| 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 | ||||||||||||