view release on metacpan or  search on metacpan

lib/Mojolicious/Plugin/Fondation/MigrationDBIx/Command/db.pm  view on Meta::CPAN

=head1 NAME

Mojolicious::Plugin::Fondation::MigrationDBIx::Command::db - Database migration and fixture commands for DBIx::Class backends

=head1 VERSION

version 0.02

=head1 SYNOPSIS

  $ myapp.pl db bootstrap-schema
  $ myapp.pl db prepare
  $ myapp.pl db install
  $ myapp.pl db status
  $ myapp.pl db populate --set 1

=head1 DESCRIPTION

Command-line interface for managing database migrations and fixtures
for DBIx::Class backends managed by L<Fondation::Model::DBIx::Async>.

Migrations use L<DBIx::Class::DeploymentHandler> directly with C<ignore_ddl = 1>.
Upgrade and downgrade SQL are generated on-the-fly from C<_source/> YAML files --
no C<db dump> step is needed.

=head1 NAME

Mojolicious::Plugin::Fondation::MigrationDBIx::Command::db - Database migration and fixture commands

=head1 COMMANDS

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

Creates a minimal L<DBIx::Class::Schema> class file under C<lib/>. Use this
when you have DBIx backends configured but no C<schema_class> yet, or when
C<schema_class> is configured but the file does not exist. After creating
the file, add C<schema_class> to your backend config (if not already set)
and run C<db prepare> to generate migration files.

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

If C<schema_class> is already configured in your backend, C<bootstrap-schema>
uses that class name automatically (no C<--class> needed).

=head3 Options

=over

=item C<--class ClassName>

Full class name for the schema. Defaults to C<< <Moniker>::Schema >>
(e.g. C<MyApp::Schema> when the application moniker is C<my_app>), or to
the already-configured C<schema_class> if the backend defines one.

=item C<--backend name>

Backend name to reference in the post-creation instructions. When omitted,
resolves via C<default_backend_name> (same cascade as other C<db> commands:
explicit C<Fondation::MigrationDBIx> C<backend> config -> DBIx::Async
C<default_backend> -> first backend).

=item C<--force>

Overwrite the schema file if it already exists.

=back

=head3 Local vs plugin Result priority

When both the application and a plugin define a C<Schema::Result::*> class
for the same table, the application's class wins: C<load_namespaces> runs
during C<connect()>, I<after> the C<DBIx> action has registered plugin sources.
The later registration overwrites the earlier one.

This means you can extend or replace a plugin's Result class by defining
your own under C<< $AppSchema::Result::* >> with the same
C<< __PACKAGE__->table(...) >>.

=head2 db prepare [-y] [-a]

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

Before generating, compares the live schema signature against the
C<.schema-sig.json> file saved after the last prepare. If the schema has
drifted -- for example because a plugin Result class changed after a
C<cpanm> upgrade -- the changed sources are reported and the command exits.

Use C<-a> to auto-bump the schema C<$VERSION> and generate the migration.
The version is incremented in the class file and in memory; previous
migration versions are preserved.

=head1 AUTHOR

Daniel Brosseau <dab@cpan.org>

=head1 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.

=cut