How to fix PGRST000: Could not connect to the database in Supabase

Free-tier Supabase projects automatically pause after 7 days of inactivity. This is the most common cause of PGRST000 errors.

1. Log in to Supabase Dashboard:
- Visit [app.supabase.com](https://app.supabase.com)
- Select your project

2. Check project status:
- Look for a banner indicating the project is paused
- You'll see options to restore/unpause the project

3. Restore the project:
- Click the "Restore" or "Resume" button
- Wait for the project to fully restart (1-2 minutes)
- Try your API request again

4. Keep your project active:
- Access your project at least once every 7 days
- Or upgrade to Pro tier which has no inactivity pauses

Incorrect credentials are the second most common cause of PGRST000 errors.

1. Get correct credentials from Supabase Dashboard:
- Go to Project Settings → API Keys
- Copy your Project URL (SUPABASE_URL)
- Copy your anon key or service role key (SUPABASE_KEY)

2. Check your environment variables:

# In your .env.local or environment
   NEXT_PUBLIC_SUPABASE_URL=https://xxxxx.supabase.co
   NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
   SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

3. Ensure URLs are exact matches:
- No trailing slashes: https://xxxxx.supabase.co (not https://xxxxx.supabase.co/)
- Correct project ID in URL
- https protocol (not http)

4. Verify you're using the correct key:
- SUPABASE_ANON_KEY for client-side requests
- SUPABASE_SERVICE_ROLE_KEY for server-side operations
- Never use service role key in browser/public code

5. Regenerate credentials if needed:
- If you suspect credentials are leaked or corrupted
- Go to Project Settings → API Keys → Rotate Keys
- Update all applications with new credentials

Verify that the PostgreSQL server is actually running.

1. Check Supabase Dashboard status:
- Go to Project Settings → Infrastructure
- Look at the "Database" section
- Check if the database status shows "Healthy", "Unhealthy", or "Starting"

2. Restart the database:
- In Project Settings → Infrastructure
- Find the database service
- Click the restart button (if available)
- Wait 2-3 minutes for the database to fully restart

3. Check service logs:
- Go to Project Settings → Logs
- Look for PostgreSQL or PostgREST errors
- Search for "connection" or "refused" errors

4. If database continues to fail:
- Check available disk space (go to Storage metrics)
- Check memory usage in Infrastructure settings
- Contact Supabase support if the database won't start

Ensure your application can reach the Supabase database.

1. Test basic connectivity:

# Test if you can reach the Supabase server
   ping db.xxxxx.supabase.co

   # Test PostgreSQL ports (5432 for direct, 6543 for pooler)
   nc -zv db.xxxxx.supabase.co 5432
   nc -zv db.xxxxx.supabase.co 6543

   # For macOS (if nc not available)
   telnet db.xxxxx.supabase.co 5432

2. Check for IP bans:
- After 2 failed login attempts, your IP is temporarily blocked for 30 minutes
- Wait 30 minutes before retrying with correct credentials
- Or unban your IP in Project Settings → Database → IP Allowlist

3. To unban an IP via CLI:

supabase network-bans remove --db-unban-ip YOUR_IP_ADDRESS --experimental

4. Check firewall/proxy:
- Ensure your firewall allows outbound traffic to Supabase
- Check if you're behind a corporate proxy that might block connections
- If behind proxy, configure it in your application's database client

5. Check DNS resolution:

# Verify DNS can resolve the Supabase domain
   nslookup db.xxxxx.supabase.co
   dig db.xxxxx.supabase.co

   # If DNS fails, try flushing DNS cache
   sudo systemd-resolve --flush-caches  # Linux
   sudo killall -HUP mDNSResponder     # macOS
   ipconfig /flushdns                   # Windows

Verify your database credentials are correct and not causing authentication failures.

1. Reset your database password:
- Go to Project Settings → Database
- Scroll down to "Database Password"
- Click "Reset password"
- Copy the new password
- Update your environment variables with the new password
- Wait 1-2 minutes for the change to propagate

2. URL-encode special characters in passwords:
- Passwords with special characters (@, %, $, #, &) must be URL-encoded
- Supabase cloud generates passwords that may include these characters

# Example: If password is "abc@123%def"
   # URL encode it as: "abc%40123%25def"
   # Full connection string: postgresql://postgres:abc%40123%25def@db.xxxxx.supabase.co:5432/postgres

3. Check character encoding of password:
- Ensure the password doesn't contain invisible characters
- Copy password directly from dashboard, don't manually retype
- Avoid copy-pasting with extra whitespace

4. Verify username is correct:
- Default user is postgres
- Check that username matches what's in your connection string

Ensure your database has sufficient resources.

1. Check connection limits:

-- Run this in Supabase SQL Editor to check limits
   SHOW max_connections;

   -- Check current connections
   SELECT count(*) as current_connections FROM pg_stat_activity;

   -- Check database size
   SELECT pg_database_size(current_database());

2. Plan comparison:
| Plan | Max Connections | Storage | Compute |
|------|-----------------|---------|---------|
| Free | 20 | 500 MB | Shared |
| Pro | 500 | 8 GB | Dedicated |
| Enterprise | Custom | Custom | Dedicated |

3. If limits exceeded:
- Upgrade your Supabase plan
- Reduce number of concurrent connections in your application
- Implement connection pooling (already enabled by default)
- Use transaction mode for serverless functions (port 6543)

4. Check disk space:
- Go to Project Settings → Infrastructure
- Look at Storage section
- If disk is full (100%), delete unused data or upgrade storage

Confirm the Supabase platform is working and test a basic query.

1. Check Supabase status page:
- Visit [status.supabase.com](https://status.supabase.com)
- Look for any ongoing incidents or maintenance
- Check if your region has service disruptions

2. Test with a simple query in Supabase Editor:
- Go to Project → SQL Editor
- Run a simple query:

SELECT 'connection successful' as status;

- If this works, PostgREST is working and the issue is in your app config

3. Test your application credentials:

import { createClient } from '@supabase/supabase-js';

   const supabase = createClient(
     process.env.NEXT_PUBLIC_SUPABASE_URL,
     process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY
   );

   // Test a simple request
   const { data, error } = await supabase.from('_supabase_test').select('1');
   if (error) {
     console.error('Connection error:', error.message);
   } else {
     console.log('Connection successful!');
   }

4. Check PostgREST logs:
- Go to Project Settings → Logs
- Filter for PostgREST
- Look for detailed error messages explaining the connection failure