> ## Documentation Index
> Fetch the complete documentation index at: https://docs.builderbox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Supabase Setup

> This guide will walk you through setting up Supabase for both local development and production environments.

## Prerequisites

* Node.js 16+ installed
* Docker installed (for local development)
* Git installed
* A Supabase account (for cloud deployment)

## Local Development Setup

### 1. Install Supabase CLI

```bash theme={null}
npm install -g supabase
```

### 2. Initialize Supabase in Your Project

```bash theme={null}
cd your-project
supabase init
```

This creates a `supabase` directory with the following structure:

```
supabase/
├── config.toml
├── seed.sql
└── migrations/
```

### 3. Start Local Supabase Services

```bash theme={null}
supabase start
```

This command:

* Starts a local PostgreSQL database
* Starts the Supabase API
* Starts the Supabase Auth service
* Starts the Supabase Storage service
* Starts the Supabase Edge Functions service

### 4. Access Local Services

After starting the services, you'll see URLs for:

* API: `http://localhost:54321`
* Studio: `http://localhost:54323`
* Database: `postgresql://postgres:postgres@localhost:54322/postgres`

### 5. Configure Environment Variables

Create a `.env` file in your project root:

```env theme={null}
# Local Development
DATABASE_URL="postgresql://postgres:postgres@localhost:54322/postgres"
DIRECT_URL="postgresql://postgres:postgres@localhost:54322/postgres"
SUPABASE_URL="http://localhost:54321"
SUPABASE_ANON_KEY="your-anon-key"
SUPABASE_SERVICE_ROLE_KEY="your-service-role-key"
```

## Cloud Deployment

### 1. Create a Supabase Project

1. Go to [supabase.com](https://supabase.com)
2. Sign in or create an account
3. Click "New Project"
4. Fill in the project details:
   * Name
   * Database password
   * Region
   * Pricing plan

### 2. Get Project Credentials

After project creation, you'll get:

* Project URL
* API Keys (anon and service\_role)
* Database connection strings

### 3. Update Environment Variables

Update your `.env` file with production credentials:

```env theme={null}
# Production
DATABASE_URL="postgresql://postgres:[YOUR-PASSWORD]@db.[YOUR-PROJECT-REF].supabase.co:5432/postgres"
DIRECT_URL="postgresql://postgres:[YOUR-PASSWORD]@db.[YOUR-PROJECT-REF].supabase.co:5432/postgres"
SUPABASE_URL="https://[YOUR-PROJECT-REF].supabase.co"
SUPABASE_ANON_KEY="your-anon-key"
SUPABASE_SERVICE_ROLE_KEY="your-service-role-key"
```

### 4. Link Local Project to Remote

```bash theme={null}
supabase link --project-ref your-project-ref
```

## Database Management

### Using Supabase Studio

1. Access Studio:
   * Local: `http://localhost:54323`
   * Cloud: `https://app.supabase.com`

2. Features available:
   * Table editor
   * SQL editor
   * Database backups
   * User management
   * API documentation

### Database Migrations

1. Create a migration:

```bash theme={null}
supabase migration new your_migration_name
```

2. Apply migrations:

```bash theme={null}
supabase db push
```

3. Reset database:

```bash theme={null}
supabase db reset
```

## Security Best Practices

1. **API Keys**
   * Never commit API keys to version control
   * Use environment variables
   * Rotate keys regularly

2. **Database Security**
   * Use strong passwords
   * Enable SSL connections
   * Set up IP allow lists

3. **Row Level Security (RLS)**
   * Enable RLS on tables
   * Define appropriate policies
   * Test security policies

## Monitoring and Maintenance

### 1. Database Monitoring

* Use Supabase Dashboard for:
  * Query performance
  * Database size
  * Connection pool
  * Error rates

### 2. Regular Maintenance

* Monitor database size
* Check for unused indexes
* Review and optimize queries
* Regular backups

## Troubleshooting

### Common Issues

1. **Connection Problems**
   ```bash theme={null}
   # Check Supabase status
   supabase status

   # Restart services
   supabase stop
   supabase start
   ```

2. **Migration Issues**
   ```bash theme={null}
   # Reset database
   supabase db reset

   # Check migration status
   supabase migration list
   ```

3. **Performance Issues**
   * Check query performance in Studio
   * Review database indexes
   * Monitor connection pool

## Additional Resources

* [Supabase Documentation](https://supabase.com/docs)