/ 
Mojolicious-Plugin-Fondation-MigrationDBIx-0.01
/ README.md

NAME

Mojolicious::Plugin::Fondation::MigrationDBIx - Migration and fixture management for DBIx::Class backends

VERSION

version 0.01

SYNOPSIS

# myapp.conf
{
    'Fondation' => {
        dependencies => [
            { 'Fondation::Model::DBIx::Async' => {
                backends => [ main => { ... } ],
            }},
            { 'Fondation::MigrationDBIx' => {
                backend => 'main',    # optional -- uses DBIx::Async default
            }},
        ],
    },
}

# Commands
$ myapp.pl db bootstrap-schema      # Create a minimal Schema class
$ myapp.pl db prepare               # Generate SQL + copy fixtures from plugins
$ myapp.pl db install               # Run pending migrations
$ myapp.pl db upgrade               # Upgrade one version
$ myapp.pl db downgrade             # Downgrade one version
$ myapp.pl db status                # Show current migration version
$ myapp.pl db populate [--set 1]    # Load fixture data

DESCRIPTION

Mojolicious::Plugin::Fondation::MigrationDBIx provides db commands for managing database migrations and fixtures for DBIx::Class backends managed by Fondation::Model::DBIx::Async.

Migration workflow

The typical workflow:

myapp.pl db bootstrap-schema  # Step 0 (optional): create Schema class if none
myapp.pl db prepare           # Step 1: generate SQL from schema classes
myapp.pl db install           # Step 2: apply migrations to the database
myapp.pl db populate          # Step 3: load initial data

For incremental changes, edit your schema, re-run db prepare, then db upgrade / db downgrade.

How it works

Plugin fixture discovery

Any Fondation plugin can ship fixtures in share/fixtures/. During db prepare, they are copied to the application's share/fixtures/ directory. The directory structure is:

share/fixtures/
└── 1/                     # schema version
    ├── conf/
    │   └── my_set.json    # fixture set configuration
    └── my_set/
        └── my_table/
            └── 1.fix      # fixture data

VERSION

0.01

HELPERS

schema_drift

my $drift = $c->schema_drift;

Returns a hashref describing schema changes since the last db prepare:

{ has_drift => 1, version => '2', changes => { users => { added => ['phone'] } } }

or { has_drift = 0 }> if nothing changed. Reads the .schema-sig.json file saved by db prepare and compares against the live schema signature from "schema_sig" in Fondation::Model::DBIx::Async.

Used automatically at application startup via fondation_finalyze: if a plugin Result class has changed (e.g. after a cpanm upgrade), a warning is logged suggesting db prepare -a && db upgrade. The application continues running -- the schema is not broken, just out of sync with the migration files.

CONFIGURATION

'Fondation::MigrationDBIx' => {
    backend        => 'main',    # optional -- defaults to DBIx::Async default
    migrations_dir => '/path',   # optional -- defaults to <app>/share/migrations
}

backend

Name of the DBIx::Async backend to target. When omitted, falls back to default_backend in DBIx::Async config, then to the first backend.

migrations_dir

Custom path for migration files. Defaults to <app home>/share/migrations.

COMMANDS

All commands are invoked as myapp.pl db COMMAND [OPTIONS].

db bootstrap-schema [--class ClassName] [--backend name] [--force]

Creates a minimal DBIx::Class::Schema class file under lib/. Use this when you have DBIx backends configured but no schema_class yet. After creating the file, add schema_class to your backend config and run db prepare to generate migration files.

The generated class uses load_namespaces to auto-discover any Result classes under the application's Schema::Result::* namespace. Result classes from Fondation plugins are registered separately by the DBIx action before workers fork -- both mechanisms coexist transparently.

When both the application and a plugin define a Result class for the same table, the application's class wins: load_namespaces runs during connect(), after the DBIx action has registered plugin sources. This lets you extend or replace a plugin's Result class by defining your own with the same __PACKAGE__->table(...).

db prepare [-y]

Generates SQL migration files from the schema classes and copies fixture directories from all loaded plugins into the application. Use -y to skip the overwrite prompt.

db install

Runs all pending migrations. Creates the version storage table on first run. If already at the latest version, prints a message and exits.

db upgrade

Applies the next pending upgrade (one version at a time). Useful for testing incremental migration steps.

db downgrade

Rolls back the last applied migration (one version at a time).

db status

Shows the current schema version (from source files) and the active database version.

db populate [--set SET]

Loads fixture data from share/fixtures/VERSION/. Use --set to filter by set name. Defaults to loading all sets under version 1.

SEE ALSO

AUTHOR

Daniel Brosseau dab@cpan.org

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Daniel Brosseau.

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