ORLite...imeline(3pm)

💖 ORLite::Migrate::Timeline — bestie edition 💖

okay so you're here for ORLite::Migrate::Timeline (that's the 3pm page, perl module docs, you know the vibe), and honestly? It's giving "ORLite::Migrate timelines contained in a single class." That's the whole NAME energy. Periodt. 💅

---

✨ NAME ✨

ORLite::Migrate::Timeline — ORLite::Migrate timelines contained in a single class 🎀

---

🌸 SYNOPSIS 🌸

package My::Timeline;

use strict;
use base 'ORLite::Migrate::Timeline';

sub upgrade1 { $_[0]->do(<<'END_SQL') }
CREATE TABLE foo (
    bar INTEGER NOT NULL PRIMARY KEY,
)
END_SQL

sub upgrade2 {
    my $self = shift;
    $self->do('TRUNCATE TABLE foo');
    foreach ( 1 .. 10 ) {
        $self->do( 'INSERT INTO foo VALUES ( ? )', {}, $_ );
    }
}

1;

like. look at it. iconic. 😌

---

🦋 DESCRIPTION 🦋

So the default ORLite::Migrate timeline situation uses separate Perl "patch" scripts to scoot your database schema timeline forwards. 🚂

And tbh that's the preferred way, because separate scripts give you process isolation between your migration code and your run-time code. Translation: the code that migrates the schema one single step forwards is guaranteed to never share variables with, load the same modules as, or interact weirdly with any of the other patch scripts, or with your main program. no crossover episodes. 🙅‍♀️

BUT (and it's a big but) — to actually execute a sub-script, your program needs to reliably know where the Perl executable that launched it lives. And sometimes? That is difficult or straight up infeasible. 💀

Enter ORLite::Migrate::Timeline. It hands you an alternative mechanism for specifying the migration timeline, and it adds the ability to run migration timelines in strange Perl environments — at the cost of losing that process isolation for your patch code. tradeoff, bestie. 💔

⚠️ When you use this method, take extra caution: avoid all use of global variables, and strictly avoid loading large amounts of data into memory, and strictly avoid using magic Perl modules such as Aspect or UNIVERSAL::isa which might have a global impact on your program. no cap, this part is serious. 😭

To use this method, create a new class which inherits from ORLite::Migrate::Timeline, and create an upgrade1 method. When it encounters a new unversioned SQLite database, the migration planner will execute that upgrade1 method and set the schema version to 1 once it's completed. 🎉

Want more changes to the schema? You just add more methods: upgrade2, upgrade3, and so on. one for every step. slay. 🌈

---

👑 METHODS 👑

The base class provides a whole series of convenience methods for you, so your schema patch code stays simpler and easier. we love a helpful base class. 🫶

🎀 new

my $timeline = My::Class->new(
    dbh => $DBI_db_object,
);

The new method is called internally by ORLite::Migrate on the timeline class you specify, to construct the timeline object.

The constructor takes a single parameter, which should be a DBI::db database connection to your SQLite database. 🍓

Returns an instance of your timeline class — or throws an exception (dies) if it wasn't passed a DBI connection object, or if the database handle is not AutoCommit. 💀

🎀 upgrade

$timeline->upgrade(10);

The update method is called on the timeline object by ORLite::Migrate to trigger the sequential execution of the individual upgradeN methods. 🪄

The first method to be called will be the method one greater than the current value of the user_revision pragma, and the last method to be called will be the target revision — which is the first parameter to the method.

Now listen: because all the upgrade methods live inside a single class, a high level of control is assumed, and so the execution plan is not calculated in advance. The upgrade method just starts rolling forwards and keeps going until it reaches the target version. (or dies trying 😭)

Returns true if all (zero or more) upgrade methods executed without throwing an exception. ✨

Throws an exception (dies) if any upgradeN method throws an exception, or if the migration process expects to find a particular numeric upgradeN method and cannot do so. 🙈

🎀 do

The do method is a convenience which provides a direct wrapper over the DBI method do. It takes the same parameters and returns the same results. 💅

🎀 selectall_arrayref

The selectall_arrayref method is a convenience which provides a direct wrapper over the DBI method selectall_arrayref. It takes the same parameters and returns the same results. 💅

🎀 selectall_hashref

The selectall_hashref method is a convenience which provides a direct wrapper over the DBI method selectall_hashref. It takes the same parameters and returns the same results. 💅

🎀 selectcol_arrayref

The selectcol_arrayref method is a convenience which provides a direct wrapper over the DBI method selectcol_arrayref. It takes the same parameters and returns the same results. 💅

🎀 selectrow_array

The selectrow_array method is a convenience which provides a direct wrapper over the DBI method selectrow_array. It takes the same parameters and returns the same results. 💅

🎀 selectrow_arrayref

The selectrow_arrayref method is a convenience which provides a direct wrapper over the DBI method selectrow_arrayref. It takes the same parameters and returns the same results. 💅

🎀 selectrow_hashref

The selectrow_hashref method is a convenience which provides a direct wrapper over the DBI method selectrow_hashref. It takes the same parameters and returns the same results. 💅

🎀 pragma

# Get a pragma value
my $locking = $self->pragma('locking_mode');

# Set a pragma value
$self->pragma( synchronous => 0 );

The pragma method is a convenience sitting right on top of the PRAGMA SQL statement, and it lets you conveniently query and change SQLite pragmas. 🧚

So like, say your application wanted to switch SQLite auto vacuuming off and instead control vacuuming of the database manually — you could do something like this:

# Disable auto-vacuuming because we'll only fill this once.
# Do a one-time vacuum so we start with a clean empty database.
$dbh->pragma( auto_vacuum => 0 );
$dbh->do('VACUUM');

🎀 table_exists

The table_exists method is a convenience to check whether a table already exists. Most of the time you won't need it, because the schema revisioning itself guarantees there either is or isn't an existing table of a particular name. 🤷‍♀️

However — occasionally you'll hit a situation where your ORLite module is sharing a SQLite database with other code, or you're taking over control of a table from a plugin, or something similar.

In those situations it provides a small amount of added safety, so you can say stuff like:

sub upgrade25 {
    my $self = shift;
    if ( $self->table_exists('foo') ) {
        $self->do('DROP TABLE foo');
    }
}

Returns true (1) if the table exists or false (0) if not. ✅❌

🎀 column_exists

The column_exists method is a convenience to check whether a column already exists. It has somewhat fewer uses than the similar table_exists, and it's mainly used when a column may exist on various miscellaneous developer versions of databases, or where the table structure may be variable across different groups of users. 🌀

Returns true (1) if the table exists or false (0) if not.

🎀 dbh

If you need to do something to the database outside the scope of the methods described above, the dbh method can be used to get access to the database connection directly. 🔑

⚠️ This is discouraged, because it can allow your migration code to create changes that might cause unexpected problems. However, in the 1% of cases where the methods above are not enough, using it with caution will allow you to make changes that would not otherwise be possible.

---

🫶 SUPPORT 🫶

Bugs should be reported via the CPAN bug tracker at

<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=ORLite-Migrate>

For other issues, contact the author. 📬

---

⭐ AUTHOR ⭐

Adam Kennedy <adamk@cpan.org>

---

🌈 COPYRIGHT 🌈

Copyright 2009 - 2012 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

---

okay and that's the whole thing bestie, you ate it up 💖 this was perl v5.36.0, dated 2023-07-01, and the page is ORLite...imeline(3pm) — go forth and migrate your schema, main character energy only 👑✨