Connecting Your First Supabase Instance

Before you can create backups or run migrations, you need to connect at least one Supabase instance to Stack2X. This guide covers both connection methods and helps you choose the right one.

Two Ways to Connect

Stack2X supports two connection methods depending on where your Supabase instance is hosted:

• OAuth -- For Supabase Cloud projects. This is the fastest and easiest method.
• Manual Credentials -- For self-hosted Supabase instances or situations where OAuth isn't available.

Connecting a Supabase Cloud Instance with OAuth

If your Supabase project is hosted on Supabase Cloud (supabase.com), OAuth is the recommended method. It securely links your accounts without requiring you to copy and paste credentials.

1. From your Stack2X dashboard, click Add Instance in the sidebar or on the instances page.
2. Select Supabase Cloud (OAuth) as the connection method.
3. You'll be redirected to Supabase to authorize Stack2X. Sign in to your Supabase account if prompted.
4. Review the permissions Stack2X is requesting and click Authorize.
5. You'll be redirected back to Stack2X, and your instance will appear in your dashboard.

OAuth gives Stack2X read access to your project's database, auth users, storage, and edge functions. You can revoke this access at any time from your Supabase account settings.

Connecting a Self-Hosted Instance with Manual Credentials

If you're running Supabase on your own servers, you'll need to provide connection details manually.

1. From your Stack2X dashboard, click Add Instance.
2. Select Self-Hosted / Manual Credentials.
3. Enter the required fields:
   • Instance Name -- A friendly label so you can identify this instance later.
   • Database Host -- The hostname or IP address of your PostgreSQL database.
   • Database Port -- Usually 5432 unless you've configured a different port.
   • Database Password -- The password for your database user.
   • Service Role Key -- Your Supabase service role key, found in your project's API settings.
4. Click Test Connection to verify everything is working.
5. Once the test passes, click Save Instance.

Testing the Connection

Regardless of which method you use, Stack2X runs a connection test before saving. This test verifies that Stack2X can reach your database, authenticate with the provided credentials, and read your project's structure.

If the test fails, double-check your credentials and make sure your database is accessible from the internet. For self-hosted instances, you may need to whitelist Stack2X's IP addresses in your firewall rules. These addresses are listed on the connection page.

Your Instance in the Dashboard

Once connected, your instance appears on the dashboard with its name, connection method, and status. A green indicator means the connection is healthy. If you see a yellow or red indicator, click on the instance to view connection details and troubleshoot.

You can connect multiple instances to a single organization. This is especially useful when you need to migrate data between two projects -- you'll need both the source and target instances connected.

What's Next

With your instance connected, you're ready to create your first backup or run a migration. Check out Creating Your First Backup or Running Your First Migration to continue.