Document using strapi instance for migrations

[nc1z]

What does it do?

Updated documentation for developers that decide to use strapi instead of knex to perform data migrations.

Why is it needed?

Often developers may want to use their custom strapi service methods to perform migrations.

Important

This serves as a caution for new Strapi developers who might overlook the lack of atomicity when using the strapi instance, unlike knex, which operates within a transaction state by default when received in the up() function.

Source: this happened to my team😄

Related issue(s)/PR(s)

N/A

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
documentation	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Apr 22, 2024 5:19pm

[pwizla]

Thanks, @nc1z.
I did the technical writing review but also asking @derrickmehaffy for a technical review, as I'm not sure this is something we'd like to recommend 🤔

[nc1z]

Thanks, @nc1z.

I did the technical writing review but also asking @derrickmehaffy for a technical review, as I'm not sure this is something we'd like to recommend 🤔

All good @pwizla, appreciate the review 😃

From what I see, the docs don't advise against other approaches besides knex, so it might be good to either explicitly mention the pitfalls or explicitly recommend knex somehow.

But let's see what derrick says, just sharing my opinion here since our team used strapi services as a quick way to reuse logic in our migrations without needing to build tables from scratch (especially when they have complex relations).

[derrickmehaffy]

This makes sense to me, the transaction thing won't be a problem afaik in Strapi 5 with the document service replacing the entity service and to my knowledge the docsrv will wrap everything in a transaction by default.

Typically you wouldn't use the migrations for normal CRUD operations just db schema modifications or something but it will work for both.

[nc1z]

This makes sense to me, the transaction thing won't be a problem afaik in Strapi 5 with the document service replacing the entity service and to my knowledge the docsrv will wrap everything in a transaction by default.

Typically you wouldn't use the migrations for normal CRUD operations just db schema modifications or something but it will work for both.

Exciting stuff in Strapi 5 I see! 😄

Yeah in our case we had to create/migrate some tables, relations and sync content localizations for several environments including prod, so we figured using our service with create functionality would avoid all the additional work since its tested.

Cool, @pwizla I'll leave you to decide if we want to merge, I'd think it's useful for v4 since most existing systems will still be on there for awhile. I've cleaned up according to your comments. Cheers 👍

[derrickmehaffy]

Overall looks good to me

[pwizla]

Thanks for the insightful discussion, @derrickmehaffy and @nc1z!
This is definitely helpful for v4 and indeed Strapi v4 will be maintained for 12-18 months so it's worth adding it to docs.

The PR is now approved, merged, should be live on docs.strapi.io in a few minutes, and will be mentioned in the next weekly snapshot release.