django-cloud-sql-postgres

# Django on Google Cloud SQL PostgreSQL

**Status**: Production Ready
**Last Updated**: 2026-01-24
**Dependencies**: None
**Latest Versions**: `Django@5.1`, `psycopg2-binary@2.9.9`, `gunicorn@23.0.0`, `google-cloud-sql-connector@1.12.0`

---

## Quick Start (10 Minutes)

### 1. Install Dependencies

```bash
pip install Django psycopg2-binary gunicorn
```

**For Cloud SQL Python Connector (recommended for local dev):**
```bash
pip install "cloud-sql-python-connector[pg8000]"
```

**Why this matters:**
- `psycopg2-binary` is the PostgreSQL adapter for Django
- `gunicorn` is required for App Engine Standard (Python 3.10+)
- Cloud SQL Python Connector provides secure connections without SSH tunneling

### 2. Configure Django Settings

**settings.py** (production with Unix socket):
```python
import os

# Detect App Engine environment
IS_APP_ENGINE = os.getenv('GAE_APPLICATION', None)

if IS_APP_ENGINE:
    # Production: Connect via Unix socket
    DATABASES = {
        'default': {
            'ENGINE': 'django.db.backends.postgresql',
            'NAME': os.environ['DB_NAME'],
            'USER': os.environ['DB_USER'],
            'PASSWORD': os.environ['DB_PASSWORD'],
            'HOST': f"/cloudsql/{os.environ['CLOUD_SQL_CONNECTION_NAME']}",
            'PORT': '',  # Empty for Unix socket
        }
    }
else:
    # Local development: Connect via Cloud SQL Proxy
    DATABASES = {
        'default': {
            'ENGINE': 'django.db.backends.postgresql',
            'NAME': os.environ.get('DB_NAME', 'mydb'),
            'USER': os.environ.get('DB_USER', 'postgres'),
            'PASSWORD': os.environ.get('DB_PASSWORD', ''),
            'HOST': '127.0.0.1',
            'PORT': '5432',
        }
    }
```

**CRITICAL:**
- App Engine connects via **Unix socket** at `/cloudsql/PROJECT:REGION:INSTANCE`
- Local development requires **Cloud SQL Auth Proxy** on `127.0.0.1:5432`
- Never hardcode connection strings - use environment variables

### 3. Create app.yaml

```yaml
r