terraform/
├── modules/
│   └── supabase/           # Shared Supabase configuration module
│       ├── main.tf         # Resource definitions
│       ├── variables.tf    # Module inputs
│       ├── outputs.tf      # Module outputs
│       └── templates/      # Email templates
├── environments/
│   ├── prod/               # Production (ckjcrkjpmhqhiucifukx)
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   ├── versions.tf
│   │   └── outputs.tf
│   └── non-prod/           # Non-production (itbzhrvlgvdmzbnhzhyx)
│       ├── main.tf
│       ├── variables.tf
│       ├── versions.tf
│       └── outputs.tf
└── README.md

What's Managed

Resource	Description
`supabase_settings`	API config, Auth settings, Connection pooler

Not managed by Terraform (managed via migrations/CLI):

Database schema & migrations
Edge functions
Storage buckets
RLS policies

Initial Setup

1. Install Terraform

# macOS
brew install terraform

# Or download from https://terraform.io/downloads

2. Get Supabase Access Token

Go to https://supabase.com/dashboard/account/tokens
Create a new token
Save it securely

3. Initialize an Environment

cd terraform/environments/non-prod  # or prod
export TF_VAR_supabase_access_token=sbp_xxxxx
terraform init

4. Import Existing Settings

For each environment, import the existing Supabase settings:

# Non-prod
cd terraform/environments/non-prod
terraform import module.supabase.supabase_settings.main itbzhrvlgvdmzbnhzhyx

# Prod
cd terraform/environments/prod
terraform import module.supabase.supabase_settings.main ckjcrkjpmhqhiucifukx

5. Verify Configuration

terraform plan

If the plan shows changes, update the module to match the current settings, then re-run plan until it shows no changes.

Workflow: Making Changes

Always test in non-prod first, then promote to prod.

1. Make Changes to the Module

Edit files in terraform/modules/supabase/ to change shared configuration.

2. Apply to Non-Prod

cd terraform/environments/non-prod
export TF_VAR_supabase_access_token=sbp_xxxxx
terraform plan   # Review changes
terraform apply  # Apply changes

3. Verify in Non-Prod

Test the changes in the non-prod environment.

4. Apply to Prod

cd terraform/environments/prod
export TF_VAR_supabase_access_token=sbp_xxxxx
terraform plan   # Review changes
terraform apply  # Apply changes

5. Commit Changes

git add terraform/
git commit -m "Update Supabase settings: <description>"
git push

Environment-Specific Settings

Some settings differ between environments. These are controlled by the is_production variable in the module:

Setting	Production	Non-Prod
SMTP	Resend (custom)	Default
Email rate limit	25/hour	3/hour

CI/CD

The GitHub Action (.github/workflows/deploy-supabase.yml) can be configured to:

Run terraform plan on PRs
Run terraform apply on merge to master

Required secret: SUPABASE_ACCESS_TOKEN

Update the workflow to use the new directory structure:

- name: Apply to Non-Prod
  working-directory: terraform/environments/non-prod
  run: terraform apply -auto-approve

- name: Apply to Prod
  working-directory: terraform/environments/prod
  run: terraform apply -auto-approve

Remote State (Recommended)

For team environments, configure a remote backend in each environment's versions.tf:

Terraform Cloud (free for small teams)
S3 backend (if you have AWS)

Secrets

Never commit secrets to git!

Use environment variables: export TF_VAR_supabase_access_token=...
Use GitHub Secrets for CI/CD
OAuth provider credentials are set in Supabase Dashboard, not Terraform

Migration from Workspace-Based Setup

If you previously used Terraform workspaces, migrate as follows:

Export state from old setup:

cd terraform  # old location
terraform workspace select production
terraform state pull > prod.tfstate
terraform workspace select non-production
terraform state pull > non-prod.tfstate

Import state to new environments:

cd environments/prod
terraform init
terraform state push ../../prod.tfstate

cd ../non-prod
terraform init
terraform state push ../../non-prod.tfstate

Verify with terraform plan in each environment
Delete old workspace-based files from terraform root