"Dirty database version" error.

[divan]

Hi,

first of all, thanks for great project. I now trying to work with v3, and having some issues related to, well, understanding error messages. For example, during normal development workflow, creating new SQL-files, there was an error in one of them and migration failed. After fixing the error, on the next run, I got message:

Dirty database version 4. Fix and force version.

And the problem is it's not clear what does mean "dirty database" in this context and how to "fix it" and what does mean "force version". I haven't found explanation in the docs or issues. Of course, as it's development env, I can just drop the db and recreate from scratch, but I suppose there should be "official" way to fix dirty database :)

PS. I'm running migrations from code, not from CLI, if it matters.

Thanks in advance!

UPD: After some digging, I ended up updating schema_migrations table manually, by UPDATE .. SET dirty=false and playing with version, but it's not how it supposed to work, is it?

[mattes]

Hey Divan,

thanks for bringing this up. I wrote this tiny little piece about it: https://github.com/mattes/migrate/blob/master/FAQ.md#what-does-dirty-database-mean

With force I mean: https://godoc.org/github.com/mattes/migrate#Migrate.Force

or when using the cli: migrate force V -- Set version V but don't run migration (ignores dirty state)

Does that answer your question? Can you help to make the docs more clear?

[divan]

Thanks @mattes! It's weird (or maybe not) how I didn't find this part in FAQ, deliberately searching for the explanation of dirty state.

Generally I think what really should help is more verbose errors descriptions. Descriptions written with zero knowledge user reading them in mind. Like instead of "no change" it could be something like "Your database already is up to date and this command makes no change. Probably you wanted to run bla-bla-bla" . :)

In case of "Dirty database version. Fix and force version." I guess it's enough to tell how exactly to "force the version". Something like "After unsuccessful migration, database is marked as dirty at migration version V. Fix the issue and use 'migrate force V' to forcefully update version".

I'm not doing PR on this, because I'm sure I'm not aware of all use cases where these errors might occur and you can come up with much better error message text. But idea is that more verbose self-explanatory errors would be a huge step forward in usability of migrate.

[mattes]

I like that. I'll open a new ticket for it.

[luciomr]

Anybody could explain how to fix this via CLI? The docs and the error msg are still not exactly very verbose.

Thanks in advance!