Migration Docs ?

[MentalGear]

First: Amazing Work on payload! It's the best code-first customizable CMS solution I have found yet. (I was in the process to build my own on top of sveltekit, but it's great that I found this!).

That everything is code, DB definitions are well structured and especially having a single source of truth, plus open-source and explainable, is exactly what I was looking for. Also terrific job on the minimalistic yet straight to the point docs!

After a quick browse, it seems like almost everything is there, but Migration:
How are migrations handled? This seems crucial, but I found nothing in the guide about it.
For example, what happens if I start out with a db structure/collection "Items" with description fields, then add the localize property to the description field? Does payload handle migrations automagically?

[MattRvt]

For anyone reading this, consider having a look to this topic: #625

The case you describe does not seem to be handled, as the answer is “it depends”, or actually, Payload admin is in sync with collection .ts file and DB is not updated until admin overwrite it's content. So it goes like that.

• if you create a field => field is present in admin but keys is not added in the DB until you add a value to the field.
• If you rename a field => the old one is not deleted in DB but removed from admin, and you get a new field with the new name
• if you change field type or localize => admin will update but you will still have the old values until overwritten.
• if you delete a field => field is removed from admin and still present in DB

same goes for collection

[DanRibbens]

Searching the discussions here you will find a ton of conversations about migrations, like #857. It is a high area of demand and very important to get right.

I don't have anything to add that hasn't already been said, except that we did move up our roadmap item for alternate #287 of which migration support is a part of.