The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Mojolicious-Plugin-Migration-Sqitch-0.01
River stage zero No dependents
/ Mojolicious::Plugin::Migration::Sqitch

NAME

Mojolicious::Plugin::Migration::Sqitch - Run Sqitch database migrations from a Mojo app

SYNOPSIS

  # Register plugin
  $self->plugin('Migration::Sqitch' => {
    dsn       => 'dbi:mysql:host=localhost;port=3306;database=myapp',
    registry  => 'sqitch_myapp',
    username  => 'sqitch',
    password  => 'world-banana-tuesday',
    directory => '/schema',
  });

  # use from command-line (normally done by startup script to ensure db up to date before app starts)
  tyrrminal@prodserver:/app$ script/myapp schema-initdb
  [2024-04-30 11:26:47.91166] [8982] [info] Database initialized

  tyrrminal@prodserver:/app$ script/myapp schema-migrate
  Deploying changes to db:MariaDB://sqitch@db/myapp_dev
    + initial_schema .. ok
  [2024-04-30 11:29:13.80192] [8985] [info] Database migration complete

  # Revert a migration in dev
  tyrrminal@devserver:/app$ script/myapp schema-migrate schema-migrate revert
  Revert all changes from db:MariaDB://sqitch@db/myapp_dev? [Yes] 
    - initial_schema .. ok
  [2024-04-30 11:26:47.91166] [8982] [info] Database migration complete

  # Start over from scratch
  tyrrminal@devserver:/app$ script/myapp schema-initdb --reset
  This will result in all data being deleted from the database. Are you sure you want to continue? [yN] y
  [2024-04-30 11:28:10.73379] [8983] [info] Database reset
  [2024-04-30 11:28:10.73501] [8983] [info] Database initialized

DESCRIPTION

Mojolicious::Plugin::Migration::Sqitch enables the use of sqitch via Mojolicious commands. The primary advantage of this is single-point configuration: just pass the appropriate parameters in at plugin registration and then you don't have to worry about passwords, DSNs, and filesystem locations for running sqitch commands thereafter.

This plugin also provides some additional functionality for initializing the database, which can't easily be done strictly through sqitch migrations without hardcoding database names, which can be troublesome depending on the deployment.

METHODS

Mojolicious::Plugin::Migration::Sqitch inherits all methods from Mojolicious::Plugin and implements the following new ones

register( $args )

Register plugin in Mojolicious application. The following keys are required in $args

dsn

The data source name for connecting to the application database.

E.g., dbi:mysql:host=db;port=3306;database=myapp_prod

registry

The name of the database used by sqitch for tracking migrations

E.g., myapp_prod_sqitch

username

Database username for sqitch migrations. As this account needs to run arbitrary SQL code (both DDL and DML), it must have sufficiently high privileges. This can be the same account used by the application, if this consideration is taken into account.

password

The password corresponding to the sqitch migration database account

directory

The on-disk location of the sqitch migrations directory. Sqitch expects to find deploy, revert, and verify subdirectories there, as well as the sqitch.plan file. It must also contain a sqitch.conf file, but the only contents of this file needed are:

    [core]
      engine = $ENGINE

With $ENGINE replaced by the actual engine name, e.g., mysql or pgsql. This plugin handles the rest of the configuration that would normally be found in that file.

E.g., /schema (in a containerized environment), or /home/mojo/myapp/schema

run_schema_initialization( \%args )

Create the configured application and migration databases, if either or both do not already exist. One key is regarded in the args HashRef:

reset

If this key is given and is assigned a "truthy" value, the application and migration databases will be dropped (if either or both exists) before being re-created. This is a destructive operation!

run_schema_migration( $sqitch_subcommand )

Run the specified $sqitch_subcommand including any additional parameters (e.g., deploy or revert -to @HEAD^1). Returns the exit status of the sqitch command to indicate success (zero) or failure (non-zero).

COMMANDS

schema-initdb [--reset]

Mojolicious command to execute "run_schema_initialization"

If the --reset flag is given, corresponding to the methods's "reset" arg key, a console warning is given alerting the user of the destructive nature of this operation and must be manually approved before continuing.

schema-migrate [args]

Mojolicious command to execute "run_schema_migration". Any additional args given are whitespace-joined and passed on to that method. If no args are provided, deploy is assumed.

AUTHOR

Mark Tyrrell <mark@tyrrminal.dev>

LICENSE

Copyright (c) 2024 Mark Tyrrell

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.