New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rename init to baseline to avoid confusion #860

Closed
flavor8 opened this Issue Oct 10, 2014 · 2 comments

Comments

Projects
None yet
2 participants
@flavor8
Copy link

flavor8 commented Oct 10, 2014

The documentation implies that your first migration can be V1. However, a migration with version 1.0.0 is not ever run; in mergeAvailableAndAppliedMigrations, the migration with version 1.0.0 is merged with the already applied init migration, and thus not picked up. Please either fix the merge logic (to never merge the init) or the documentation to be clearer about the first migration name.

@axelfontaine

This comment has been minimized.

Copy link
Contributor

axelfontaine commented Oct 10, 2014

The documentation and the merge logic are fine.

The problem is people run init (only meant for tagging existing databases as having a specific version) on new databases. The init version is 1.0. This then rightly prevents a migration with version 1.0 from being applied.

I don't know exactly why people insist on running init. (You are far from being alone here)

My suspicion is that people don't read the docs about init, yet due to the name it seems logical to execute it.

Is this what happened in your case? Please help me understand the thought process so I have a better chance at making this more intuitive in the future.

I am thinking about addressing this in a future release by either:

  • renaming init to something less attractive to blindly run/more descriptive of the intention
  • change the initVersion default away from 1.0
  • prevent init from being run against a blank database

What do you think? Which option(s) make the most sense and why?

Cheers
Axel

@flavor8

This comment has been minimized.

Copy link

flavor8 commented Oct 10, 2014

Aha - yes, that's what I did. Init seems logical - it sounds like the first thing you want to do is install the metadata table. I think the issue is that the init documentation isn't particularly findable on the site; the "commands" table at the bottom of the page seem like logical and complete descriptions, and the "(existing database)" part of the init description doesn't particularly jump out. Even knowing that there should be a specific section about init on the site, I can't find it at a quick glance; I do see that you have an "Existing database setup" page, but a) as somebody with a new database I'm not going to read that and b) even scanning it quickly, it looks like it's using a super-advanced variant of init, i.e. it's not clear that this is exactly what init is for.

I would suggest a new sidebar section with each of the commands, above "execution modes". You should also link to them from the commands table. I think that'll make it more likely that people like me who skim docs will discover that init is not necessary.

But, worth also making a code change -- I would suggest that your 2nd option is the best; set init to be version -1, perhaps? Ugly, but then even if somebody started with V0 their migration would still be applied.

@axelfontaine axelfontaine added this to the Flyway 3.1 milestone Oct 20, 2014

@axelfontaine axelfontaine changed the title Migration with version 1.0.0 incorrectly merged with flyway init and marked as SUCCESS without being run Rename init to baseline to avoid confusion Nov 24, 2014

axelfontaine added a commit that referenced this issue Nov 24, 2014

axelfontaine added a commit that referenced this issue Nov 24, 2014

axelfontaine added a commit that referenced this issue Nov 25, 2014

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