--migrate: CLI surface (entrypoint, file discovery, flags, migration file template)

Part of #37237. Depends on the Core migration engine ticket — the --dry-run/--yes flags don't do much until real apply logic exists to preview/gate, even though this ticket is conceptually "the command-line shape of the tool."

Summary

The entrypoint, file discovery/parsing, the migration file template convention, and the three CLI flags (--up-to, --dry-run, --yes) — all in dotCMS/dot-ca-event-manager.

Scope

1. --migrate startup mode on EventManagerApplication
An alternate entrypoint that skips starting the web server (spring.main.web-application-type=none or equivalent), runs the migration flow, and exits. Reuses the existing adminJdbcTemplate bean (AdminDataSourceConfig) — the only pool with DDL privileges. Default behavior (no flags): apply everything pending, in strict version order.

2. ch-migrations/ file convention + discovery
Read src/main/resources/db/ch-migrations/V<seq>__<description>.sql, parse version/description from the filename, read raw bytes for checksumming (used by the Ledger ticket), sort by version with a gap/duplicate-version check. A filename that doesn't match the pattern (or a duplicate version number) is a fail-fast error, never a silent skip.

3. ON CLUSTER guard
Reject a migration script containing ON CLUSTER with a clear error (a simple content check, not full SQL parsing) — this repo's Replicated database engine already handles DDL fan-out via Keeper; mixing in ON CLUSTER is a misconfiguration signal, not something to silently allow.

4. Risk-tier header + migration file template
A lightweight, optional -- RISK: high|routine header comment, parsed alongside the file and surfaced distinctly in --dry-run output (⚠ V4 is flagged HIGH RISK: ...). Not enforced by the tool beyond parsing/display — the author decides the tier.

A standard header-comment template, e.g. src/main/resources/db/ch-migrations/TEMPLATE.sql (documentation only — only RISK is machine-read):

-- Title: <short, human-readable description>
-- RISK: routine|high
-- Ticket: <issue/PR reference, or N/A>
--
-- Description:
--   <what this migration does and why>
--
-- Verification:
--   <how correctness was/will be confirmed, or "N/A" for a purely
--   additive change with nothing meaningful to verify>
--
-- Revert plan:
--   <what "undo" looks like for this specific migration>

Field values:

• RISK: routine | high — high for anything like a PARTITION BY hash reshuffle, a key-changing full rebuild, or anything else deserving explicit approver sign-off beyond the routine case.
• Verification: free text; N/A is an accepted, expected value for a purely additive change.
• Revert plan: free text, but should generally name one of: additive (roll back consuming app code only, leave schema in place), bounded-window (safe to rename back only within the dual-write/revert window; fix-forward after), mv-cheap (materialized view revert, cheap DROP+CREATE), or fix-forward-only (no clean revert exists — e.g. a one-time backfill mutation).
• Title, Ticket, Description: free text, no fixed values.

5. CLI flags

• --up-to <version> — apply pending migrations in order, but stop once that version is reached. Gives an operator pacing control for a runbook split across multiple files with a manual verification step in between (e.g. apply the create-table-and-MV file, eyeball the sums by hand, only then run again for the swap file) — without allowing arbitrary/out-of-order selection.
• --dry-run — runs the same pre-flight checks a real run would (checksum comparison, V0/REFRESH EVERY checks — see Ledger ticket) and reports what would actually run and where it would stop, without applying anything. Not a shallow file listing.
• --yes — required to proceed past a confirmation prompt for any pending migration tagged RISK: high when running interactively (TTY attached); without a TTY (the Kubernetes Job path), --yes is required outright, since there's nothing to prompt.

Out of scope here

• The actual apply loop, mutation tracking, and lock (previous ticket — this ticket's flags call into that).
• The ledger table and checksum/V0 logic (Ledger ticket).

Repo

dotCMS/dot-ca-event-manager

Start with EventManagerApplication and AdminDataSourceConfig to understand the alternate startup path and the database connection it must reuse. Then inspect src/main/resources/db/ch-migrations/ and the Core migration engine and Ledger ticket for the interfaces this CLI depends on. Done means discovery, validation, template handling, and the three flags work without implementing the apply loop or ledger logic.