[Support][Documentation] Confused about how to use fix

[eeshugerman]

First, let me state my understanding of the issue with timestamp versioning (aka the versioning problem), because it may be the source of my confusion. (I posted a clarifying question here).

1. Alice does goose create on 2018-01-01, thereby generating 2018-01-01_first_migration.sql. She is working on a big task, so it will be a couple days before this migration is deployed to the STAGING environment.
2. The next day, Joe does goose create, generating 2018-01-02_second_migration.sql. His task is just a quick fix, so this migration is deployed to STAGING later that day.
3. On 2018-01-03, Alice completes her task and 2018-01-01_first_migration.sql is deployed to STAGING. However this migration is not actually executed against STAGING, because its timestamp is less than that of 2018-01-02_second_migration.sql, which was already executed against STAGING. This is crux of the issue.
4. When STAGING is released to PRODUCTION, both migrations will be executed against PRODUCTION.

Does that accurately express the versioning problem? Moving on to my questions about fix...

Question 1

The README contains the following blurb:

When you're ready to deploy your migrations in a production environment, we also provide a helpful fix command to convert your migrations into sequential order, while preserving the timestamp ordering. We recommend running fix in the CI pipeline, and only when the migrations are ready for production.

To me, this seems to say that fix should be called as part of the deploy from STAGING to PRODUCTION, but that would not address the issue described above -- 2018-01-01_first_migration.sql will still not be executed against STAGING. Instead, I would think that fix should be called as part of the deploy to STAGING. Do I have the right idea here?

Question 2

I would think that the changes made by fix (renamed migrations) should be checked in to source control, committed to the appropriate branch, and pushed to the main repo as part of the deployment. Is that correct? Perhaps this is self evident, but I think it would be good to note somewhere considering this is probably the most involved aspect of integrating fix into a CI/CD setup.

Overall I think there is a need for more documentation around fix and hybrid versioning. Perhaps if I am able to get these questions sorted I can make some additions to the README.

[VojtechVitek]

@1vn mind helping out?

[1vn]

Thank you for such a detailed and clear question. I appreciate you taking the time to do this.

1. This is a valid concern because our fix is process-oriented. With hybrid versioning you know exactly what migration is in prod (sequential) and in dev (timestamp). With this information, what we did was roll back all timestamped migrations on every staging deploy (before pulling new code), if staging is on a different branch than the target. In this case, Alice's deployment would've rolled back to a DB version before Joe's last deployment and her migration would be applied after.

2. You are correct, that is exactly what we did and I agree we can be better with the documentation/best practices around that.

I've been away from Pressly for a while so I may be rusty with the details. @VojtechVitek please correct me if I'm wrong or missing something 😄

[eeshugerman]

Thanks for your response! I have a couple follow up questions, I will try to make them quick.

1. Would you say my summary of the versioning problem captures it, more or less? I just want to make sure there aren't additional issues with timestamp-based versioning that I am not aware of which could come back to bite if I don't consider them when integrating fix into our CI/CD.

2. our fix is process-oriented

   Could you expand on that a little? I'm not sure I know what you mean. Perhaps you're saying that how a dev team uses fix will depend a lot on that team's process? The rest of the paragraph makes perfect sense to me though.

3. I think for my team the simplest way forward is to run fix on the deploy to STAGING. Do you foresee any issues with this? I realize there's no way you can say for sure without knowledge of our full setup/flow, and I wouldn't ask for a guarantee anyway... but does it sound like a plausible solution?

[1vn]

1. Yes, we ran into something similar in our process.
2. Batteries not included, in this case the batteries are the CI/CD pipeline work involved to run fix, branch development, and most important a good process around using staging.
3. That sounds reasonable if your staging is only reserved for whatever goes to prod. For us we had to do the rollback mechanism because we didn't have a good process around only reserving prod code for staging, for multiple internal reasons.

[eeshugerman]

Got it. Thanks again! I will open a pull request to add this information to the README once I finish up integrating fix into our pipeline.