Mojo::Pg::Migrations(3pm)

NAME
Mojo::Pg::Migrations - Migrations

SYNOPSIS
  use Mojo::Pg::Migrations;

  my $migrations = Mojo::Pg::Migrations->new(pg => $pg);
  $migrations->from_file('/home/sri/migrations.sql')->migrate;

DESCRIPTION
Mojo::Pg::Migrations is used by Mojo::Pg to allow database schemas to evolve easily over time. A migration file is just a collection of sql blocks, with one or more statements, separated by comments of the form "-- VERSION UP/DOWN".

  -- 1 up
  CREATE TABLE messages (message TEXT);
  INSERT INTO messages VALUES ('I ♥ Mojolicious!');
  -- 1 down
  DROP TABLE messages;

  -- 2 up (...you can comment freely here...)
  CREATE TABLE stuff (whatever INT);
  -- 2 down
  DROP TABLE stuff;

The idea is to let you migrate from any version, to any version, up and down. Migrations are very safe, because they are performed in transactions and only one can be performed at a time. If a single statement fails, the whole migration will fail and get rolled back. Every set of migrations has a "name", which is stored together with the currently active version in an automatically created table named "mojo_migrations".

ATTRIBUTES
Mojo::Pg::Migrations implements the following attributes.

  name
  my $name    = $migrations->name;
  $migrations = $migrations->name('foo');

Name for this set of migrations, defaults to "migrations".

  pg
  my $pg      = $migrations->pg;
  $migrations = $migrations->pg(Mojo::Pg->new);

Mojo::Pg object these migrations belong to. Note that this attribute is weakened.

METHODS
Mojo::Pg::Migrations inherits all methods from Mojo::Base and implements the following new ones.

  active
  my $version = $migrations->active;

Currently active version.

  from_data
  $migrations = $migrations->from_data;
  $migrations = $migrations->from_data('main');
  $migrations = $migrations->from_data('main', 'file_name');

Extract migrations from a file in the DATA section of a class with "data_section" in Mojo::Loader, defaults to using the caller class and "name".

  __DATA__
  @@ migrations
  -- 1 up
  CREATE TABLE messages (message TEXT);
  INSERT INTO messages VALUES ('I ♥ Mojolicious!');
  -- 1 down
  DROP TABLE messages;

  from_dir
  $migrations = $migrations->from_dir('/home/sri/migrations');

Extract migrations from a directory tree where each versioned migration is in a directory, named for the version, and each migration has one or both of the files named "up.sql" or "down.sql".

  migrations/1/up.sql
  migrations/1/down.sql
  migrations/2/up.sql
  migrations/3/up.sql
  migrations/3/down.sql

  from_file
  $migrations = $migrations->from_file('/home/sri/migrations.sql');

Extract migrations from a file.

  from_string
  $migrations = $migrations->from_string(
    '-- 1 up
     CREATE TABLE foo (bar INT);
     -- 1 down
     DROP TABLE foo;'
  );

Extract migrations from string.

  latest
  my $version = $migrations->latest;

Latest version available.

  migrate
  $migrations = $migrations->migrate;
  $migrations = $migrations->migrate(3);

Migrate from "active" to a different version, up or down, defaults to using "latest". All version numbers need to be positive, with version 0 representing an empty database.

  # Reset database
  $migrations->migrate(0)->migrate;

  sql_for
  my $sql = $migrations->sql_for(5, 10);

Get SQL to migrate from one version to another, up or down.

DEBUGGING
You can set the "MOJO_MIGRATIONS_DEBUG" environment variable to get some advanced diagnostics information printed to "STDERR".

  MOJO_MIGRATIONS_DEBUG=1

SEE ALSO
Mojo::Pg, Mojolicious::Guides, <https://mojolicious.org>.