Skip to content

Restore Migration.Up and Migration.Down signatures#1356

Open
bevzzz wants to merge 5 commits into
masterfrom
fix/migrations-add
Open

Restore Migration.Up and Migration.Down signatures#1356
bevzzz wants to merge 5 commits into
masterfrom
fix/migrations-add

Conversation

@bevzzz
Copy link
Copy Markdown
Collaborator

@bevzzz bevzzz commented Mar 21, 2026

Resolves #1297

In an attempt to support templated SQL migration files #1188 changed the signature for Migration.Up and Migration.Down fields, breaking a part of the migrate package's public contract. This had the effect of breaking all external code that relied on Migrations.Add API previous to this change.

My understanding is that Migrations.Add was never meant to be used outside of the migrate package, Migrations.Register being the officially documented and, I assume, the only intended way for client code to register its Go-based migrations. Based on the reactions to the linked issue, there seems to be a number of users who discovered Add (which is exported) and started using it.

I propose we revert the breaking changes. Both migrate.Migration and migrate.Migrations.Add have been a part of the public API for a long time and breaking them isn't right. The reason internalMigrationFunc was introduced was to support templated migrations and before/after hooks. For each of these the PR presents alternative, b/c-compatible solutions:

  1. Migrator can pass template data via context. This makes sense, because it is a piece of data scoped to a single migrate/rollback "request".
  2. Before/After hooks are handled in a single place. The code which is calling Up and Down is responsible for applying the hooks, just like it is responsible for calling MarkApplied/MarkUnapplied.

I also added the missing tests for these two features, see testSQLMigrations and testHooks.

@bevzzz bevzzz force-pushed the fix/migrations-add branch from a5c7ae4 to 5f5b8cc Compare March 21, 2026 09:37
@bevzzz bevzzz force-pushed the fix/migrations-add branch from 5f5b8cc to 293bb30 Compare March 21, 2026 09:52
@bevzzz bevzzz requested a review from vmihailenco March 21, 2026 11:43
@bevzzz bevzzz changed the title refactor(migrate): apply Go and SQL migrations via the same code path Restore Migration.Up and Migration.Down signatures Mar 21, 2026
@bevzzz bevzzz marked this pull request as ready for review March 21, 2026 11:45
@bevzzz bevzzz requested a review from j2gg0s March 22, 2026 11:39
@bevzzz
Copy link
Copy Markdown
Collaborator Author

bevzzz commented Apr 7, 2026

@vmihailenco if possible, I'd like to include this in the next release, WDYT? Do you agree this is a breaking change worth fixing?

@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 8, 2026

This pull request has been automatically marked as stale because it has not had activity in the last 30 days. If there is no update within the next 7 days, this pr will be closed. Please feel free to give a status update now, ping for review, when it's ready. Thank you for your contributions!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Migration Add API Broken

1 participant