NAME

Doodle::Migration

ABSTRACT

Database Migration Class

SYNOPSIS

  # in lib/Migration.pm

  package Migration;

  use parent 'Doodle::Migration';

  # in lib/My/Migration/Step1.pm

  package Migration::Step1;

  use parent 'Doodle::Migration';

  no warnings 'redefine';

  sub up {
    my ($self, $doodle) = @_;

    my $users = $doodle->table('users');
    $users->primary('id');
    $users->string('email');
    $users->create;
    $users->index(columns => ['email'])->unique->create;

    return $doodle;
  }

  sub down {
    my ($self, $doodle) = @_;

    my $users = $doodle->table('users');
    $users->delete;

    return $doodle;
  }

  # in lib/My/Migration/Step2.pm

  package Migration::Step2;

  use parent 'Doodle::Migration';

  no warnings 'redefine';

  sub up {
    my ($self, $doodle) = @_;

    my $users = $doodle->table('users');
    $users->string('first_name')->create;
    $users->string('last_name')->create;

    return $doodle;
  }

  sub down {
    my ($self, $doodle) = @_;

    my $users = $doodle->table('users');
    $users->string('first_name')->delete;
    $users->string('last_name')->delete;

    return $doodle;
  }

  # elsewhere

  package main;

  my $self = Migration->new;

  my $results = $self->migrate('up', 'sqlite', sub {
    my ($sql) = @_;

    # e.g. $dbi->do($_) for @$sql;

    return 1;
  });

  1;

DESCRIPTION

This package provides a migrator class and migration base class in one package. The migrations method loads and collects the classes that exists as children of the namespace returned by the namespace method (which defaults to the current class) and returns the class names as an array-reference.

LIBRARIES

This package uses type constraints from:

Doodle::Library

METHODS

This package implements the following methods:

down

  down(Doodle $doodle) : Doodle

The migrate "DOWN" method is invoked automatically by the migrator Doodle::Migrator.

down example #1

  # given: synopsis

  my $doodle = Doodle->new;

  $doodle = $self->down($doodle);

migrate

  migrate(Str $updn, Str $grammar, CodeRef $callback) : Any

The migrate method collects all processed statements and iterates over the "UP" or "DOWN" SQL statements, passing the set of SQL statements to the supplied callback with each iteration.

migrate example #1

  # given: synopsis

  my $migrate = $self->migrate('up', 'sqlite', sub {
    my ($sql) = @_;

    # do something ...

    return 1;
  });

migrations

  migrations() : ArrayRef[Str]

The migrations method finds and loads child objects under the namespace and returns an array-reference which contains class names that have subclassed the Doodle::Migration base class.

migrations example #1

  # given: synopsis

  my $doodle = Doodle->new;

  my $migrations = $self->migrations;

namespace

  namespace() : Str

The namespace method returns the root namespace where all child Doodle::Migration classes can be found.

namespace example #1

  # given: synopsis

  my $namespace = $self->namespace;

statements

  statements(Str $grammar) : ArrayRef[Tuple[ArrayRef[Str], ArrayRef[Str]]]

The statements method loads and processes the migrations using the grammar specified. This method returns a set of migrations, each containing a set of "UP" and "DOWN" sets of SQL statements.

statements example #1

  # given: synopsis

  my $statements = $self->statements('sqlite');

up

  up(Doodle $doodle) : Doodle

The migrate "UP" method is invoked automatically by the migrator Doodle::Migrator.

up example #1

  # given: synopsis

  my $doodle = Doodle->new;

  $doodle = $self->up($doodle);

AUTHOR

Al Newkirk, awncorp@cpan.org

LICENSE

This is free software; you can redistribute it and/or modify it under the terms of the The Apache License, Version 2.0, as elucidated in the "license file".