Migration Add API Broken

[jemtucker]

In version 1.2.15 the Migration.Add API has breaking changes that make it no longer usable.

I have been using migrations in Go like so:

ms.Add(migrate.Migration{
		Name:    "20241024-initial-migration",
		Comment: "init first model",
		Up: func(ctx context.Context, db *bun.DB) error {
           ...
        },
        Down: func(ctx context.Context, db *bun.DB) error {
           ...
        },
})

Since d92e29e this is no longer possible due to a private type being used in the definition of the Up and Down members.

Is there a migration path (pun not intended) from Add to Register that won't break compatibility with migrations that have already been run?

[jemtucker]

The Add API is currently documented on the main web page here https://bun.uptrace.dev/#migrations-that-scale in a way that will no longer compile with these changes too

func init() {
    migrations.Add("20230101_create_users", func(ctx context.Context, db *bun.DB) error {
        _, err := db.NewCreateTable().
            Model((*User)(nil)).
            IfNotExists().
            Exec(ctx)
        return err
    }, func(ctx context.Context, db *bun.DB) error {
        _, err := db.NewDropTable().
            Model((*User)(nil)).
            IfExists().
            Exec(ctx)
        return err
    })
}

[github-actions]

This issue 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 issue will be closed.

[Et3rnel]

Any updates on this issue, please?

[bevzzz]

I'm sorry, it's been a while since I checked these. Please expect an update by the end of the week.

[Et3rnel]

👋 Is there a way to contribute, or is the update expected soon? Thanks 🙏

[bevzzz]

hey @Et3rnel, working on this right now and I'll post my update here soon

[bevzzz]

@Et3rnel @jemtucker that is indeed a breaking change, and I'm a bit surprised it got merged so easily in the first place, as it changed the signature of a field that's a part of public API.

I should mention, however, that Register is the documented and, I assume, the only intended way for client code to register its Go-based migrations. My understanding is the Migration type and its Add method have "leaked" from the migrate package, which is rather unfortunate.

RN I am working on a PR to revert the signature for Up and Down functions, but I do not guarantee it will get merged, as that will also be a breaking change for any code depending on the newer versions.

Is there a migration path (pun not intended) from Add to Register that won't break compatibility with migrations that have already been run?

At the moment I cannot think of a satisfactory solution that does not include changing the code. We might consider making Up and Down fields any and downcasting them later in the code.

[bevzzz]

@Et3rnel @jemtucker I have opened a PR proposing a fix for the breaking change.

[jemtucker]

Thanks! Just a heads up that the homepage to your website still shows the Add migration API - this is where I followed the examples from

https://bun.uptrace.dev/#migrations-that-scale

[bevzzz]

the homepage to your website still shows the Add migration API

Yeah, I totally get why you'd use Add -- even our test suite uses Add to register new migrations, so if you looked there you'd make the same assumption. I'll fix the docs as well.