# Restoring a Supabase Database Dump
### `MCRO_Supabase__20260303.dump` → New Supabase Project

This guide covers two independent methods for loading a Supabase `.dump` file into a fresh Supabase project. Follow **either Method A or Method B** — both produce the same end result.

---

## Prerequisites (Both Methods)

Before starting either method, you need a **new, empty Supabase project** to restore into.

1. Log in at [supabase.com](https://supabase.com)
2. Click **New Project** and fill in the name/password — save the database password somewhere, you'll need it
3. Wait for the project to finish initializing (usually 1-2 minutes)
4. Go to **Settings → Database** and note down:
   - **Host** (looks like `aws-0-us-west-2.pooler.supabase.com`)
   - **User** (looks like `postgres.yourprojectref`)
   - **Port:** `5432`
   - **Database:** `postgres`

> ⚠️ **Important:** Check your actual database disk size at **Settings → Database → Database Size** before attempting to restore into a free-tier project. Free projects have a **500MB limit** — if the source database exceeds this, you'll need a paid project ($25/month Pro plan).

---

## Method A — Using the Supabase CLI

The Supabase CLI is the official tool and handles Supabase-specific schema quirks automatically.

### Step 1 — Install the Supabase CLI

#### macOS
```bash
brew install supabase/tap/supabase
```
> Requires [Homebrew](https://brew.sh). If you don't have it, install it first with:
> `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`

#### Windows
Download and run the latest `.msi` installer from the [Supabase CLI releases page](https://github.com/supabase/cli/releases) — look for the file ending in `windows-amd64.msi`.

Alternatively, if you have [Scoop](https://scoop.sh) installed:
```powershell
scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase
```

#### Linux (Ubuntu)
```bash
sudo apt update
sudo apt install -y curl
curl -fsSL https://raw.githubusercontent.com/supabase/cli/main/install.sh | sudo bash
```

Or via `apt` directly if available:
```bash
sudo apt install supabase
```

### Step 2 — Verify the Installation
```bash
supabase --version
```
You should see a version number printed. If you get "command not found", restart your terminal and try again.

### Step 3 — Log In to Your Supabase Account
```bash
supabase login
```
This opens a browser window asking you to authorize the CLI with your Supabase account. Click **Authorize** and return to the terminal.

### Step 4 — Link to Your New Project

Find your **Project Reference ID** — it's the string in your project's URL on the Supabase dashboard:
`https://supabase.com/dashboard/project/YOUR_PROJECT_REF`

```bash
supabase link --project-ref YOUR_PROJECT_REF
```
When prompted, enter the database password you set when creating the project.

### Step 5 — Restore the Dump

Navigate to the folder containing your dump file, then run:

```bash
supabase db restore --db-url "postgresql://postgres.YOUR_PROJECT_REF:YOUR_DB_PASSWORD@YOUR_HOST:5432/postgres" MCRO_Supabase__20260303.dump
```

Replace `YOUR_PROJECT_REF`, `YOUR_DB_PASSWORD`, and `YOUR_HOST` with the values from your project's **Settings → Database** page.

> 💡 You can also build the full connection URL directly from the dashboard by clicking the **Connect** button at the top of your project page and copying the **Session pooler** string.

### Step 6 — Verify the Restore

Connect to the database and run a quick sanity check:
```bash
psql "postgresql://postgres.YOUR_PROJECT_REF:YOUR_DB_PASSWORD@YOUR_HOST:5432/postgres" \
  -c "SELECT COUNT(*) FROM children_doc_strings;"
```
Expected result: `181556` rows. If you see that number, the restore completed successfully.

---

## Method B — Using `pg_restore` Directly

This method uses the standard PostgreSQL tool `pg_restore` and does not require the Supabase CLI. It is equally reliable and slightly simpler to set up.

### Step 1 — Install PostgreSQL Client Tools

You only need the client tools — you are **not** installing a full PostgreSQL server.

#### macOS
```bash
brew install postgresql
```
This installs `pg_restore`, `psql`, and related tools without running a server.

#### Windows
1. Download the PostgreSQL installer from [postgresql.org/download/windows](https://www.postgresql.org/download/windows/)
2. Run the installer — when asked which components to install, you can **uncheck "PostgreSQL Server"** and keep only **"Command Line Tools"**
3. After installation, open a new **Command Prompt** or **PowerShell** window

Verify it worked:
```powershell
pg_restore --version
```

#### Linux (Ubuntu)
```bash
sudo apt update
sudo apt install -y postgresql-client
```

Verify:
```bash
pg_restore --version
```

### Step 2 — Run the Restore

Navigate to the folder containing `MCRO_Supabase__20260303.dump`, then run:

#### macOS / Linux (Ubuntu)
```bash
pg_restore \
  -h YOUR_HOST \
  -p 5432 \
  -U postgres.YOUR_PROJECT_REF \
  -d postgres \
  --no-owner \
  --no-privileges \
  -F c \
  MCRO_Supabase__20260303.dump
```

#### Windows (Command Prompt)
```cmd
pg_restore -h YOUR_HOST -p 5432 -U postgres.YOUR_PROJECT_REF -d postgres --no-owner --no-privileges -F c MCRO_Supabase__20260303.dump
```

#### Windows (PowerShell)
```powershell
pg_restore `
  -h YOUR_HOST `
  -p 5432 `
  -U postgres.YOUR_PROJECT_REF `
  -d postgres `
  --no-owner `
  --no-privileges `
  -F c `
  MCRO_Supabase__20260303.dump
```

When prompted for a password, enter your Supabase project's database password.

> ⚠️ **Don't panic about error messages.** You will likely see a stream of errors like `ERROR: schema "auth" already exists` or `ERROR: relation "storage.buckets" already exists`. This is completely normal and expected — Supabase pre-creates its own internal schemas in every new project, and `pg_restore` just skips those and continues. Your actual data and schema will load correctly.

### Step 3 — Verify the Restore

```bash
psql -h YOUR_HOST -p 5432 -U postgres.YOUR_PROJECT_REF -d postgres \
  -c "SELECT COUNT(*) FROM children_doc_strings;"
```

Enter your password when prompted. Expected result: `181556` rows.

You can also run a broader check:
```sql
SELECT table_name, (xpath('/row/cnt/text()', xml_count))[1]::text::int AS row_count
FROM (
  SELECT table_name,
         query_to_xml(
           format('SELECT COUNT(*) AS cnt FROM %I', table_name),
           false, true, ''
         ) AS xml_count
  FROM information_schema.tables
  WHERE table_schema = 'public'
  ORDER BY table_name
) t;
```
This lists every table with its row count so you can confirm everything landed correctly.

---

## Connecting the Claude MCP Connector to Your New Project

Once the restore is complete, you can wire up the Supabase MCP connector to Claude.ai in a few clicks — no CLI required.

1. In your new Supabase project, go to **Settings → Integrations** and locate the Claude / MCP section. Your project's MCP server URL will be: `https://mcp.supabase.com/mcp`
2. In Claude.ai, go to **Settings → Connectors**
3. Click **"Add custom connector"**
4. Paste in `https://mcp.supabase.com/mcp`
5. Click **Add** — an OAuth authorization window will open
6. Authorize Claude to access your Supabase account and select the correct project
7. Done — Claude can now query your restored database directly

> ℹ️ The MCP connector is available on **all Claude.ai plans** including free. Free accounts are limited to one custom connector total.

---

## Quick Reference — Flag Glossary

| Flag | Meaning |
|---|---|
| `-h` | Host (your Supabase pooler address) |
| `-p` | Port (always `5432` for session mode) |
| `-U` | Username (`postgres.yourprojectref`) |
| `-d` | Database name (always `postgres`) |
| `--no-owner` | Don't restore original ownership (required for Supabase) |
| `--no-privileges` | Don't restore original GRANT/REVOKE statements (required for Supabase) |
| `-F c` | Custom binary format (matches how the dump was created) |

---

## Troubleshooting

**"command not found: pg_restore"**
Close and reopen your terminal after installation. On Windows, make sure PostgreSQL's `bin` folder is in your PATH (the installer usually handles this automatically).

**"connection refused" or "could not connect"**
Double-check that you're using port `5432` and the session pooler host from **Settings → Database**, not the direct connection host. Also confirm your project has finished initializing.

**"password authentication failed"**
Re-check the database password. Note this is the **database password** you set when creating the project — not your Supabase account login password. You can reset it at **Settings → Database → Reset database password**.

**Restore appears to hang with no output**
It's working — `pg_restore` runs silently while processing. At 85MB the restore typically completes in 2-5 minutes depending on your connection speed.

**Row counts don't match after restore**
If counts are lower than expected, the restore may have hit a genuine error (not just the expected Supabase schema errors). Re-run with the `-v` (verbose) flag to see detailed output:
```bash
pg_restore -v -h YOUR_HOST -p 5432 -U postgres.YOUR_PROJECT_REF -d postgres --no-owner --no-privileges -F c MCRO_Supabase__20260303.dump 2>&1 | tee restore_log.txt
```
This saves full output to `restore_log.txt` for review.