Migration fails if already migrated up to target version

[haines]

We're running River migrations on each deployment with (*Migrator[TTx]).Migrate. As we are in the process of rolling out River Pro v0.24.0, we specify TargetVersion: 6 in the MigrateOpts for the pro line.

This worked fine the first time it was run, but on subsequent deployments we get an error

Error: version 6 is not in target list of valid migrations to apply

It seems to me that if the target version has already been reached, calling Migrate should be a no-op rather than an error, which would match the behaviour when TargetVersion is not specified.

[bgentry]

@haines Can you confirm the command that's being run here? My hunch is that you're trying to target v006 explicitly, and that's failing because the migrator logic today no longer sees it as a valid version to target when it's already been run. @brandur may have thoughts on whether we should change this.

GPT 5.5 high summary

I don’t think this is a v006/v007 exposure or SQL idempotency problem.

The reported error matches existing River migrator behavior in github.com/riverqueue/river@v0.37.1: Migrate(DirectionUp, TargetVersion: 6) deletes already-applied versions from the target list, then errors if 6 is no longer in that pending list. The test suite even has this as expected behavior for an already-applied target version.

Evidence:

• v006/v007 are embedded in both Pro drivers via //go:embed migration/*/*.sql.
• migration/pro/006_... and migration/pro/007_... exist in riverqueue.com/riverpro/driver/riverpropgxv5@v0.24.0.
• The user’s error proves version 6 is known to the migrator. If it weren’t exposed, the error would be version 6 is not a valid River migration version; instead it reaches the “not in target list” branch.
• v006/v007 SQL looks intentionally idempotent: CREATE ... IF NOT EXISTS, ADD COLUMN IF NOT EXISTS, CREATE OR REPLACE, guarded DROP INDEX IF EXISTS, and the generated-column conversion only runs when attgenerated = 's'.

So the issue is almost certainly in River’s TargetVersion semantics: targeting an already-applied up migration currently errors instead of returning a no-op. That’s awkward for the staged v6/v7 rollout because users reasonably want to keep deployment migration code pinned at v6 until they’re ready for v7.

Best fix is probably in rivermigrate: for DirectionUp, if TargetVersion exists and is already applied, return an empty successful result instead of erroring. Workaround for the user is to check river_migration for line = 'pro' and version >= 6 before calling targeted migration, then skip the TargetVersion: 6 call once it’s already recorded.

[haines]

Essentially

migrator, err := rivermigrate.New(riverpropgxv5.New(pool), &rivermigrate.Config{Line: riverprodriver.MigrationLinePro})
if err != nil { ... }

_, err = migrator.Migrate(context.Background(), rivermigrate.DirectionUp, &rivermigrate.MigrateOpts{TargetVersion: 6})
if err != nil { ... }

If you don't specify TargetVersion, then the Migrate call is idempotent. With TargetVersion specified, you wind up here, where the version is being validated against the list of yet-to-be applied migrations, so it fails if the target version has already been applied.

An error if the current version is greater than the target version when migrating up would be reasonable, but I think it should be a no-op if the current version equals the target version. Otherwise it is awkward to perform these migrations as part of an automated release workflow.