/ 
App-JESP-0.005
/ README.md

NAME

App::JESP - Just Enough SQL Patches

SYNOPSIS

Use the command line utility:

jesp

Or use from your own program (in Perl):

my $jesp = App::JESP->new({ home => 'path/to/jesphome',
                            dsn => ...,
                            username => ...,
                            password => ...
                          });

$jsep->install();
$jesp->deploy();

CONFIGURATION

All JESP configuration must live in a JESP home directory.

This home directory must contain a plan.json file, containing the patching plan for your DB. See plan.json section below for the format of this file.

plan.json

This file MUST live in your JESP home directory. It has to contain a json datastructure like this:

{
  "patches": [
      { "id":"foobartable", "sql": "CREATE TABLE foobar(id INT PRIMARY KEY)"},
      { "id":"foobar_more", "file": "patches/morefoobar.sql" }
      { "id":"foobar_abs",  "file": "/absolute/path/to/patches/evenmore.sql" }
  ]
}

Patches MUST have a unique ID in all the plan, and they can either contain raw SQL (SQL key), or point to a file of your choice (in the JESP home) itself containing the SQL.

You are encouraged to look in https://github.com/jeteve/App-JESP/tree/master/t for examples.

COMPATIBILITY

Compatibility of the meta-schema with SQLite, MySQL and PostgreSQL is guaranteed through automated testing. To see which versions are actually tested, look at the CI build: https://travis-ci.org/jeteve/App-JESP/

DRIVERS

This comes with the following built-in drivers:

SQLite

Just in case. Note that your patches will be executed in the same connection this uses to manage the metadata.

mysql

This will use the mysql executable on the disk (will look for it in PATH) to execute your patches, exactly like you would do on the command line.

Pg

This will use a new connection to the Database to execute the patches. This is to allow you using BEGIN ; COMMIT; to make your patch transactional without colliding with the Meta data management transaction.

Your own driver.

Should you want to write your own driver, simply extend App::JESP::Driver and implement any method you like (most likely you will want apply_sql).

To use your driver, simply give its class to the constuctor:

my $jesp = App::JESP->new({ .., driver_class => 'My::App::JESP::Driver::SpecialDB' });

Or if you prefer to build an instance yourself:

my $jesp;
$jesp = App::JESP->new({ .., driver => My::App::JESP::Driver::SpecialDB->new({ jesp => $jesp,  ... ) });

MOTIVATIONS & DESIGN

Over the years as a developer, I have used at least three ways of managing SQL patches. The ad-hoc way with a hand-rolled system which is painful to re-implement, the DBIx::Class::Migration way which I didn't like at all, and more recently App::Sqitch which I sort of like.

All these systems somehow just manage to do the job, but unless they are very complicated (there are no limits to hand-rolled complications..) they all fail to provide a sensible way for a team of developers to work on database schema changes at the same time.

So I decided the world needs yet another SQL patch management system that does what my team and I really really want.

Here are some design principles this package is attempting to implement:

METHODS

install

Installs or upgrades the JESP meta tables in the database. This is idem potent. Note that the JESP meta table(s) will be all prefixed by **$this-**prefix()>.

Returns true on success. Will die on error.

Usage:

$this->install();

deploy

Deploys the unapplied patches from the plan in the database and record the new DB state in the meta schema. Dies if the meta schema is not installed (see install method).

Returns the number of patches applied.

Usage:

print "Applied ".$this->deploy()." patches";

Options:

DEVELOPMENT

COPYRIGHT

This software is released under the Artistic Licence by Jerome Eteve. Copyright 2016. A copy of this licence is enclosed in this package.