feat/multi-version-schema-migrations #349
Conversation
|
Check out the preview at https://xata-docs-pr-349.vercel.app |
Co-authored-by: Philip Krauss <[email protected]>
| @@ -0,0 +1,56 @@ | |||
| --- | |||
| title: Multi Schema Migrations | |||
There was a problem hiding this comment.
| title: Multi Schema Migrations | |
| title: Multi schema migrations |
Sentence format to match other docs pages
There was a problem hiding this comment.
As I read this blog, I'm realizing that this is being productized as multi-schema migrations. We've always used this internally to discuss the feature, but I'm not sure if it'll be confusing externally. What are yours and @andrew-farries @exekias @tsg on calling this "Reversible schema migrations" or "Simultaneous schema migrations" or "Virtual schema migrations". Just brainstorming here. Part of the problem is we have two was to do migrations at the moment. When there's one, we don't really have to differentiate in the docs. We could also combine into the same migrations page, and differentiate for postgres dbs vs. not.
There was a problem hiding this comment.
Maybe we can also call it "Online / Live Schema Migrations"? That's the term I am aware of with products that feel the most similar to pgroll like https://github.com/github/gh-ost
There was a problem hiding this comment.
I dropped in a few comments primarily about the naming and differentiation from the existing migrations. The rest of the docs look good overall. I also like having a manage section, but we may want @snide's input since he came up with the original IA.
What's missing for me here are copy and pasteable examples. I want to change my column name, here's some code to copy, etc. Last time we spoke about this, we talked about referencing the pgroll operations or even actually pulling them in directly (similar to mdx-blog, mdx-docs, etc.). The problem with just pointing to the repo, is that "changing a column type" isn't searchable in our docs.
This is a great overview and walk through! Since we are lacking UI around the actual operations and are relying on JSON, I have a feeling we'll need examples for the most common schema changes you'd make.
I'm also thinking we may want to include any and all limitations in the docs.
| status: beta | ||
| --- | ||
|
|
||
| Multi Schema migrations address the pain point of having to keep your application code in sync with your database schema by allowing you two active database schemas at once. With Multi Schema migrations, running a migration means being able to preview the new version of your schema alongside the old one. Reading and writing data in both schemas continues to work normally. As a result of having two active schema versions, rollbacks become seamless operations which is particularly useful in the case of an unwanted schema change or backfill. |
There was a problem hiding this comment.
It's probably worth highlighting and linking to pgroll int this intro blog, just so folks know what the underlying technology is
There was a problem hiding this comment.
Added. Just need to verify the link is correct
| @@ -0,0 +1,56 @@ | |||
| --- | |||
| title: Multi Schema Migrations | |||
There was a problem hiding this comment.
As I read this blog, I'm realizing that this is being productized as multi-schema migrations. We've always used this internally to discuss the feature, but I'm not sure if it'll be confusing externally. What are yours and @andrew-farries @exekias @tsg on calling this "Reversible schema migrations" or "Simultaneous schema migrations" or "Virtual schema migrations". Just brainstorming here. Part of the problem is we have two was to do migrations at the moment. When there's one, we don't really have to differentiate in the docs. We could also combine into the same migrations page, and differentiate for postgres dbs vs. not.
eemmiillyy
changed the title
|
@alexfrancoeur I made the requested changes, please let me know if I missed anything :) Using the term "multi-version schema migrations" now. I also added some examples of common pgroll ops, and merged this page with the existing migrations page. |
There was a problem hiding this comment.
Sorry for the delay here @eemmiillyy ! The docs look great. I added a few minor suggestions and ideas. I forget where we landed for July, but if we can apply multi-version schema migrations through the CLI, it's worth documenting.
I hope this helps, let me know if you have any questions or need clarification on any of my feedback. It's all pretty minor.
Co-authored-by: AlexF <[email protected]>
|
@alexfrancoeur Thanks! For multi-version (using start/complete/rollback) for migrations in CLI we haven't started AFAIK. I think it would require some UX changes. I started a thread about it here: https://xata-hq.slack.com/archives/C05TR0HPQ9Y/p1720607406000149?thread_ts=1720606948.589919&cid=C05TR0HPQ9Y |
There was a problem hiding this comment.
Overall this LGTM. I think we can iterate if needed down the road. Thanks @eemmiillyy !
Documentation for multi-version schema migrations