How to Install Supabase Locally on Mac and Import a PostgreSQL Dump

Migrating your existing PostgreSQL database into Supabase can be tricky, especially with permissions and system schemas. In this guide, I’ll walk you through exactly how I did it on macOS using Docker, from installing Supabase locally to importing a SQL dump.

Prerequisites

• macOS with Homebrew installed
• Docker Desktop installed
• Local PostgreSQL database running (or Dockerized)
• Supabase account (optional for hosted version)

Step 1: Install Supabase CLI

Supabase CLI helps you run Supabase locally and manage your projects.

brew install supabase/tap/supabase

Verify installation:

supabase --version

Step 2: Initialize a Local Supabase Project

1. Create a new folder for your project:

mkdir supabase_local_project
cd supabase_local_project

2. Initialize Supabase:

supabase init

This creates a supabase folder with necessary configuration files.

Step 3: Start Supabase Locally Using Docker

Run the local Supabase stack:

supabase start

• This will spin up Postgres, Studio, and Realtime services in Docker.
• Check your Postgres container name:

docker ps

You’ll see a container like supabase_db_<project_name>.

Step 4: Export Your Local PostgreSQL Database

If your PostgreSQL is running in Docker:

docker exec -i <your_postgres_container_name> pg_dump -U <db_user> -d <db_name> --no-owner --no-privileges > local_dump.sql

Example from your workflow:

docker exec -i supabase_db_nisalgunawardhana pg_dump -U postgres -d postgres --no-owner --no-privileges > local_dump.sql

The flags --no-owner and --no-privileges are crucial for avoiding permission errors in Supabase.

Step 5: Connect to Supabase Database

Get your local Supabase Postgres connection info:

supabase status

Typically, the connection string looks like:

postgresql://postgres:postgres@localhost:5432/postgres

Step 6: Import the Dump into Supabase

Use psql to import:

psql "postgresql://postgres:postgres@localhost:5432/postgres" -f local_dump.sql

What to expect:

• Supabase system schemas (auth, storage, graphql) already exist.
• Your tables will be restored in the public schema.
• Permission errors for Supabase-managed schemas can usually be ignored.
• Foreign key issues may appear if system tables conflict, but your main data should import correctly.

Step 7: Verify the Import

1. Connect to Supabase:

docker exec -it supabase_db_nisalgunawardhana psql -U postgres -d postgres

2. Disable pager for clean output:

\pset pager off

3. List tables:

\dt public.*

4. Check table contents:

SELECT * FROM enterprises LIMIT 5;
SELECT COUNT(*) FROM invoices;

Everything should be there as in your original database.

Step 8: Tips and Best Practices

• Only restore custom tables if you want to avoid conflicts with Supabase internal schemas.
• For large databases, split your dump by tables.
• Always use --no-owner and --no-privileges.
• Verify foreign keys after import.

Step 9: Optional — Export from Supabase CLI

Once your local database is ready, you can export a new dump from Supabase itself:

docker exec -i supabase_db_nisalgunawardhana pg_dump -U postgres -d postgres --no-owner --no-privileges > supabase_export.sql

This dump is now portable to any hosted Supabase project.

Conclusion

By following this workflow on macOS:

1. Install Supabase CLI → supabase init → supabase start
2. Export local PostgreSQL → pg_dump via Docker
3. Import into Supabase → psql -f local_dump.sql
4. Verify your tables

you can successfully migrate your database without touching system schemas or hitting permission errors.

Supabase makes local development easy, and this workflow ensures your production data is ready to go.