Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Rename init to baseline to avoid confusion #860
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.
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:
What do you think? Which option(s) make the most sense and why?
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.