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

# Neon Postgres

> Database production serverless untuk AI Mentor.

Database production memakai **Neon** — Postgres serverless. Connection string disimpan di **`.env.production.local`** (bukan di `.env` shared kalau beda dengan DB lokal).

<Frame>
  <img src="https://neon.tech/brand/neon-logo-dark-color.svg" alt="Logo Neon" width="160" />
</Frame>

**Console:** [console.neon.tech](https://console.neon.tech)\
**Docs:** [neon.com/docs](https://neon.com/docs/get-started/connect-neon)

## Env di project

```bash theme={null}
# .env.production.local (override prod)
DATABASE_URL=postgresql://user:pass@ep-xxx-pooler.region.aws.neon.tech/neondb?sslmode=require
```

Dev lokal biasanya Postgres di laptop — override di `.env.development.local`:

```bash theme={null}
DATABASE_URL=postgresql://trainerhub_beta:...@127.0.0.1:5432/trainerhub_beta_clean
```

## Setup Neon (pertama kali)

<Steps>
  <Step title="Buat project">
    [Neon Console](https://console.neon.tech) → **New Project** → pilih region (dekat user / Cloudflare)
  </Step>

  <Step title="Ambil connection string">
    Project Dashboard → tombol **Connect** → pilih:

    * **Branch:** `main` / production
    * **Connection pooling:** ON (hostname berisi `-pooler`) — disarankan untuk Workers
    * Copy string `postgresql://...`
  </Step>

  <Step title="Simpan aman">
    Paste ke `.env.production.local` sebagai `DATABASE_URL`.\
    **Jangan commit** — file ini di-gitignore.
  </Step>

  <Step title="Migrate saat deploy">
    `./thub deploy` / `deploy-prod.sh` menjalankan migrate SQL ke `DATABASE_URL` production.
  </Step>
</Steps>

## Pooled vs direct

| Tipe                               | Kapan dipakai                                         |
| ---------------------------------- | ----------------------------------------------------- |
| **Pooled** (`-pooler` di hostname) | Runtime app, Workers via Hyperdrive                   |
| **Direct** (tanpa pooler)          | Migration berat, `psql`, tooling satu koneksi panjang |

Neon docs: [Connection pooling](https://neon.com/docs/connect/connection-pooling)

## Verifikasi koneksi

```bash theme={null}
./thub env merge --prod
psql "$DATABASE_URL" -c "SELECT 1"
./thub doctor
```

## CI/CD (GitHub Actions)

Secret `DATABASE_URL` di environment `production` — isi sama dengan Neon production. Script `ci-materialize-env.sh` menulis ke `.env.production.local` sebelum deploy.

## Troubleshooting

| Masalah                  | Solusi                                                    |
| ------------------------ | --------------------------------------------------------- |
| SSL required             | Pastikan `?sslmode=require` di URL                        |
| Too many connections     | Pakai pooled URL atau Hyperdrive                          |
| Migrate gagal di CI      | Cek IP allowlist Neon (biasanya open untuk Neon cloud)    |
| Doctor DB merah di lokal | Normal jika Postgres lokal belum jalan — override dev URL |