builder icon indicating copy to clipboard operation
builder copied to clipboard

Add standalone CLI tool for database migration

Open aofei opened this issue 4 months ago • 0 comments

Description

With the database migration system implemented in #2001, we now have automated migrations that run when the spx-backend starts. However, there are operational scenarios where a standalone migration tool would be valuable.

Currently, migration operations are tightly coupled with application startup:

  • Migrations only run when config.DatabaseConfig.AutoMigrate is enabled
  • No way to handle dirty state without direct database manipulation
  • Cannot execute migrations independently of application deployment

Possible solution

Create a standalone CLI tool spx-backend-migrate that provides:

  • status: Show current migration version and pending migrations
  • up [N]: Apply N pending migrations (default: all)
  • down [N]: Rollback N migrations (emergency use only)
  • goto <version>: Migrate to specific version (up or down as needed)
  • force <version>: Force set version to resolve dirty state
  • validate: Verify migration file integrity, up/down symmetry, and schema consistency with GORM models

[!NOTE] Following golang-migrate conventions, [N] represents the count of migrations to apply/rollback, not version numbers. Use goto <version> to migrate to a specific version.

aofei avatar Aug 25 '25 13:08 aofei