Feature Request: Support for config.toml.local (gitignored local configuration overrides)

[jacekpl]

Problem Statement

When working in team environments or managing multiple local Supabase projects simultaneously, developers need to customize port configurations without creating git conflicts or requiring manual config file management.

Current Challenges

1. Team Collaboration:

• Multiple developers need different port configurations locally (e.g., one developer uses default ports 54321-54324, another uses 55321-55324 to avoid conflicts with other projects)
• config.toml is committed to git, so local port changes either:
  • Create unwanted git diffs that shouldn't be committed
  • Require developers to manually stash/revert changes before committing
  • Risk accidentally committing local-only configurations

2. Multiple Local Projects:

• Developers often work on multiple Supabase projects that need to run simultaneously (e.g., main project + microservice + testing instance)
• Each instance requires unique ports to avoid conflicts
• Currently must manually edit config.toml and remember to change it back, or maintain separate git clones

3. Current Workarounds Are Inadequate:

• CLI flags (supabase start --api-port 55321 --db-port 55322 ...) - Tedious to type repeatedly, easy to forget
• Shell scripts - Extra tooling overhead, not cross-platform
• Separate git clones - Wastes disk space, complicates updates
• Environment variables - Not supported in config.toml (tested: port = "${PORT}" fails with parse error)

Proposed Solution

Add support for config.toml.local (or config.toml.override) that:

1. Is automatically gitignored by Supabase CLI (added to generated .gitignore)
2. Overrides values from config.toml when present
3. Uses standard TOML merge semantics (local values override base values)

Example Workflow

Committed (config.toml):

project_id = "aaa"

[api]
port = 54321

[db]
port = 54322

[studio]
port = 54323

Local only (config.toml.local, gitignored):

[api]
port = 55321

[db]
port = 55322

[studio]
port = 55323

Result: Developer runs supabase start → uses ports 55321-55323, no git conflicts.

Benefits

• Zero git conflicts - Local configs never tracked
• Team-friendly - Default ports in repo, custom ports per developer
• Multi-project friendly - Each project has unique local config
• No tooling overhead - Native Supabase CLI feature
• Cross-platform - Works on Windows/Mac/Linux
• Familiar pattern - Similar to .env / .env.local convention

Additional Context

• Similar patterns exist in: Vite (.env.local), Docker Compose (docker-compose.override.yml), Git (.git/config.local)
• This is a common pain point in discussions: Multiple projects in local Supabase #5968, Can I create separate local instances for the test suite and for development? #14329, How to change the default port 8000 #20683

Would this be considered for the roadmap?