Better Docs Needed for link and migration repair

[tmountain]

Link

https://supabase.com/docs/reference/cli/supabase-link

https://supabase.com/docs/reference/cli/supabase-migration-repair

Describe the problem

The docs for link and migration repair do not provide a clear or detailed enough explanation of what these commands do. Take link for example:

Link your local development project to a hosted Supabase project.

PostgREST configurations are fetched from the Supabase platform and validated against your local configuration file.

What does this do exactly? Why would I want to link to my remote DB? Do changes locally affect a remote DB when it is linked? Or, vice versa? My intuitive understanding of this command is that it synchronizes versions of services to make environments consistent between the remote host and my local dev environment, and it also makes certain commands act against the remote host (i.e., supabase migration), but I have not seen that stated anywhere. For me, linking feels "scary", as I don't want to inadvertently cause changes in production without a clear understanding of what is going on.

In my mind, this command deserves thorough documentation to help users understand exactly what is going on.

Regarding migration repair, the docs say:

Repairs the remote migration history table.

Requires your local project to be linked to a remote database by running supabase link.

If your local and remote migration history goes out of sync, you can repair the remote history by marking specific migrations as --status applied or --status reverted. Marking as reverted will delete an existing record from the migration history table while marking as applied will insert a new record.

Again, this command acts against a production DB, and I really can't fully understand the implications based on what is provided here. Example, does --status applied prevent a specific migration from running on the remote host? Details are shared about the actual DB operation being performed (i.e., deleting and inserting records into the migration history table), but no specifics are given regarding how the migration history table works internally.

This leaves me, as a user, to make assumptions about the actual underlying behavior, and inconveniently, this command only seems to work against a linked database, so the only way to really understand the behavior would be to set up a supabase sandbox db and run a bunch of experiments. More detailed docs would be a better solution.

Describe the improvement

The improvement would be for to provide detailed docs regarding the intention and behavior of these commands along with some rationale on why you would use them. I would like to see a more detailed document illustrating how the migration system works and how the supabase migration repair influences its behavior.

Additional context

It's scary to operate on your production DB without fully understanding what is going on. The Supabase CLI is the primary tool for interacting with key parts of the Supabase infrastructure, so the docs should be more rigorous. I find myself digging through the Golang source code to understand specific behaviors, and that's something most users are not willing to do.

I've provided a few examples, but I really believe the entire set of commands needs more detail regarding the docs.