feat: add command to clone project to local

[sweatybridge]

What kind of change does this PR introduce?

feature

What is the new behavior?

The vision here is that each command should follow the unix philosophy of building small single task programs that are composable. Unfortunately, this introduces a lot of fragmentation that affects the overall UX.

Hence, we are adding new commands to quick start section which is a composable stack of other sipmle commands.

Additional context

Add any other context or screenshots.

[coveralls]

Pull Request Test Coverage Report for Build 18403653021

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

• For more information on this, see Tracking coverage changes with pull request builds.
• To avoid this issue with future PRs, see these Recommended CI Configurations.
• For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

• 14 of 107 (13.08%) changed or added relevant lines in 4 files are covered.
• 23 unchanged lines in 2 files lost coverage.
• Overall coverage decreased (-0.4%) to 54.315%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
internal/db/pull/pull.go	7	10	70.0%
internal/db/diff/diff.go	7	14	50.0%
cmd/clone.go	0	15	0.0%
internal/clone/clone.go	0	68	0.0%

Files with Coverage Reduction	New Missed Lines	%
internal/gen/keys/keys.go	5	12.9%
internal/db/start/start.go	18	82.68%

Totals
Change from base Build 18397580971:	-0.4%
Covered Lines:	6419
Relevant Lines:	11818

---

💛 - Coveralls

[avallete]

question

Why would a "pull" command "push" something up to the database ? This seems likely to cause error.

Also, what happen if the user "push" the migration, then continue to do changes on the dashboard and "clone" again ?

[sweatybridge]

I think we have to make it clear that clone command is only used for initial setup. Subsequently, they should be using the specialised commands, ie. db pull.

[jgoux]

I also have a hard time making sense of pushing migrations to the remote history table during clone. 🤔
Is the prompt wrong?

As you say clone is for going from an empty / non existing supabase folder to an existing one directly fetched from a remote project right? So why would we even have existing migrations locally?

What am I missing here?

[sweatybridge]

So why would we even have existing migrations locally?

The initial schema pulled from remote database would be the first migration isn't it?

[jgoux]

Yes, but to me it doesn't make sense to push it during clone. Clone is about dumping a remote project locally and should keep the remote untouched.

It would be pushed on first supabase db push instead?

[sweatybridge]

The envisioned DX for users with an existing project would be

1. supabase clone
2. supabase start

Now he makes schema changes through local studio, then

3. supabase db diff
4. supabase db push

The problem is at step 4, we have 2 migrations: the cloned migration from 1 and the diffed migration from 3.

Historically we've been skipping the first migration by consulting the history table. That's why we ask users to initialise the history table on first pull.

But perhaps there's a better way to do it?

[jgoux]

Or then we need to be more explicit about how we handle migrations and prompt the user something like:

It seems like you created changes in your database without using migrations. Would you like to turn these changes into a migration? <link to docs about migrations and why it's good for them>

Then with a global supabase push we would push anything new in the local project (functions, migrations...)

[sweatybridge]

Not sure. I'd really like clone to be a read only operation.

May be we can prompt whether to push the first migration (default behaviour right now) or simply mark it as applied?

[sweatybridge]

Another option is to clone into schemas directory so users adopt declarative schemas by default.

Supabase start would use declared schemas if migrations are empty.

Then local studio changes are diffed into migrations directory. This way only incremental changes are pushed to remote.

[avallete]

I think there are two cases here:

1. User just wants to spin up local dev for an existing remote project (changes live in dashboard).
   → In that case, clone should stay read-only, never push anything.

2. User wants to “eject” into code-based migrations.
   → We should make that transition explicit in the CLI, something like:

   You’ve cloned your project successfully
   Do you want to start managing migrations as code?
   
   • Make schema changes in local Studio →
      1. run `supabase db diff > supabase/migrations/xxxx_migrations.sql`
      2. Review the generated migration ensure it work locally with `supabase db reset` (will loose your local data)
   • Or write a migration manually →
     1. `supabase migration new <name>`
     3. Then apply locally → `supabase migration apply`
   And sync remote → `supabase db push`
   

That keeps clone idempotent (like git clone) while guiding users through the migration workflow.

We could also make db push smarter:
if the first migration fails because the remote DB isn’t empty and has no supabase_migrations schema, we can try/catch that case, inspect the DB, and prompt:

“It looks like this isn’t a fresh database. Do you want to mark the migration as applied instead of running it? (In the case the migration contain changes you already performed on the remote database via dashboard / third party)”

That’d make the DX clearer and keep clone safely read-only.

Edit: I know it's a bit vebose, but I'm leaning on the side of "explaining in the right context" rather than "put everyting in the docs" because at this point it might make more sense to the user. Also avoiding implicit behavior will increase the chances of having an user understanding what's done and how it works.

BTW, if possible, I would "print" the command we do for each migration every time.

(ex:

supabase db push
..Pushing migration to the database...
supabase db push -- supabase/migrations/XXXX_init.sql
It looks like this isn’t a fresh database. Do you want to mark the migration as applied instead of running it (y/n)? y
... Repairing migration mark it as passed on remote ...
supabase db repair -- supabase/migrations/XXXX_init.sql
 ..Pushing migration to the database...
supabase db push -- supabase/migrations/XXX_add_table.sql :: skipped
supabase db push -- supabase/migrations/XXX_add_table2.sql :: success
supabase db push -- supabase/migrations/XXX_add_table3.sql :: success
supabase db push -- supabase/migrations/XXX_add_table4.sql :: success
...
```)


I think even if more verbose, that'll allow user to more easily understand what's going on internally and also help them self-serve/debug when having troubles.