pos-system/docs/en/guides/neon-database.md

# Neon Database Guide

This project uses [Neon PostgreSQL](https://neon.tech) for all environments.

## Why Neon?

- **Serverless**: No infrastructure management
- **Branching**: Separate databases for dev/staging/prod
- **Auto-scaling**: Handles traffic spikes automatically
- **Point-in-time restore**: Easy recovery from mistakes
- **Free tier**: Perfect for development
- **Connection pooling**: Built-in PgBouncer support

## Architecture Overview

```mermaid
graph TD
 Project[" Neon Project<br/>goodgo-platform"]

 Dev[" Development Branch<br/>main"]
 Staging[" Staging Branch<br/>staging"]
 Prod[" Production Branch<br/>production"]

 LocalDev[" Local Dev<br/>.env.local"]
 K8sStaging[" Kubernetes<br/>staging namespace"]
 K8sProd[" Kubernetes<br/>production namespace"]

 Project --> Dev
 Project --> Staging
 Project --> Prod

 Dev -.->|DATABASE_URL| LocalDev
 Staging -.->|Secret| K8sStaging
 Prod -.->|Secret| K8sProd

 style Project fill:#1e293b,stroke:#3b82f6,stroke-width:3px,color:#fff
 style Dev fill:#0f172a,stroke:#10b981,stroke-width:2px,color:#fff
 style Staging fill:#0f172a,stroke:#f59e0b,stroke-width:2px,color:#fff
 style Prod fill:#0f172a,stroke:#ef4444,stroke-width:2px,color:#fff
 style LocalDev fill:#475569,stroke:#94a3b8,stroke-width:2px,color:#fff
 style K8sStaging fill:#475569,stroke:#94a3b8,stroke-width:2px,color:#fff
 style K8sProd fill:#475569,stroke:#94a3b8,stroke-width:2px,color:#fff
```

## Quick Start

### 1. Create Neon Account

1. Sign up at https://neon.tech
2. Create a new project: `goodgo-platform`

### 2. Create Branches

In Neon Console, create branches:
- `main` (development) - already exists
- `staging` - create from main
- `production` - create from main

### 3. Get Connection Strings

For each branch, copy the connection string:
- Format: `postgresql://user:password@ep-xxx.region.neon.tech/dbname?sslmode=require`
- Add `?pgbouncer=true` for connection pooling (recommended)

### 4. Configure Local Development

```bash
# Create .env.local
cp deployments/local/env.local.example deployments/local/.env.local

# Edit .env.local and add:
DATABASE_URL=postgresql://user:pass@ep-xxx.region.neon.tech/dbname?sslmode=require&pgbouncer=true
```

### 5. Run Migrations

```bash
./scripts/db/migrate.sh iam-service dev
```

## Connection String Format

```
postgresql://[user]:[password]@[endpoint]/[dbname]?sslmode=require&pgbouncer=true
```

**Parameters**:
- `sslmode=require` - Required for Neon
- `pgbouncer=true` - Enable connection pooling (recommended)

## Environment Configuration

### Local Development

File: `deployments/local/.env.local`

```bash
DATABASE_URL=postgresql://user:pass@ep-xxx.region.neon.tech/dbname?sslmode=require&pgbouncer=true
```

### Staging

Store in GitHub Secrets: `NEON_DATABASE_URL_STAGING`

Or in Kubernetes:
```bash
kubectl create secret generic iam-service-secrets \
 --from-literal=database-url='postgresql://...' \
 -n staging
```

### Production

Store in GitHub Secrets: `NEON_DATABASE_URL_PRODUCTION`

Or in Kubernetes:
```bash
kubectl create secret generic iam-service-secrets \
 --from-literal=database-url='postgresql://...' \
 -n production
```

## Migrations

### Migration Workflow

```mermaid
graph LR
 subgraph Local[" Local Development"]
 Schema[" Update Schema<br/>prisma/schema.prisma"]
 CreateMig[" Create Migration<br/>migrate dev"]
 TestLocal[" Test Locally"]
 end

 subgraph CI[" CI/CD Pipeline"]
 Push[" Git Push"]
 Build[" Build"]
 TestCI[" Run Tests"]
 end

 subgraph Staging[" Staging"]
 MigStaging[" Run Migrations<br/>migrate deploy"]
 TestStaging[" Verify Schema"]
 end

 subgraph Prod[" Production"]
 Approval[" Manual Approval"]
 MigProd[" Run Migrations<br/>migrate deploy"]
 Rollback[" Rollback Plan"]
 end

 Schema --> CreateMig
 CreateMig --> TestLocal
 TestLocal --> Push

 Push --> Build
 Build --> TestCI
 TestCI --> MigStaging

 MigStaging --> TestStaging
 TestStaging --> Approval

 Approval --> MigProd
 MigProd -.->|If Failed| Rollback

 style Local fill:#1e293b,stroke:#3b82f6,stroke-width:2px,color:#fff
 style CI fill:#1e293b,stroke:#8b5cf6,stroke-width:2px,color:#fff
 style Staging fill:#1e293b,stroke:#f59e0b,stroke-width:2px,color:#fff
 style Prod fill:#1e293b,stroke:#ef4444,stroke-width:2px,color:#fff

 style Schema fill:#0f172a,stroke:#10b981,color:#fff
 style CreateMig fill:#0f172a,stroke:#10b981,color:#fff
 style TestLocal fill:#0f172a,stroke:#10b981,color:#fff
 style Push fill:#475569,stroke:#94a3b8,color:#fff
 style Build fill:#475569,stroke:#94a3b8,color:#fff
 style TestCI fill:#475569,stroke:#94a3b8,color:#fff
 style MigStaging fill:#0f172a,stroke:#f59e0b,color:#fff
 style TestStaging fill:#0f172a,stroke:#f59e0b,color:#fff
 style Approval fill:#475569,stroke:#94a3b8,color:#fff
 style MigProd fill:#0f172a,stroke:#ef4444,color:#fff
 style Rollback fill:#7f1d1d,stroke:#ef4444,color:#fff
```

### Development

```bash
# Create new migration
./scripts/db/migrate.sh iam-service dev

# This will:
# 1. Create migration file
# 2. Apply to database
# 3. Update Prisma Client
```

### Staging/Production

Migrations run automatically in CI/CD:
- Before deployment to staging
- Before deployment to production (with approval)

Manual migration:
```bash
./scripts/db/migrate.sh iam-service deploy
```

## Backup & Restore

### Automatic Backups

Neon provides automatic backups. Access via Neon Console:
- Point-in-time restore
- Branch restore
- Export data

### Manual Backup

```bash
./scripts/db/backup.sh iam-service
```

This creates a SQL dump file in `backups/` directory.

### Restore

```bash
# From Neon Console (recommended)
# Or using psql:
psql $DATABASE_URL < backup.sql
```

## Monitoring

Monitor your databases via Neon Console:
- Connection metrics
- Query performance
- Storage usage
- Branch status

## Troubleshooting

### Connection Issues

1. **Check connection string format**
 - Must include `?sslmode=require`
 - Verify credentials

2. **Check IP allowlist**
 - Neon may restrict IPs
 - Add your IP in Neon Console

3. **Check branch status**
 - Ensure branch is active
 - Check for maintenance

### Migration Issues

1. **DATABASE_URL not set**
 ```bash
 export DATABASE_URL="your-neon-url"
 ```

2. **Schema mismatch**
 ```bash
 # Reset and re-migrate (dev only!)
 pnpm prisma migrate reset
 ```

3. **Connection timeout**
 - Add `?pgbouncer=true` for pooling
 - Check Neon console for limits

### Performance Issues

1. **Enable connection pooling**
 - Add `?pgbouncer=true` to connection string

2. **Check query performance**
 - Use Neon Console query analyzer
 - Review slow queries

3. **Optimize indexes**
 - Review Prisma schema
 - Add indexes for frequent queries

## Cost Optimization

- **Free tier**: 0.5 GB storage, sufficient for dev
- **Staging**: Use free tier or minimal paid plan
- **Production**: Scale based on usage
- **Branching**: Free branches for testing

## Best Practices

1. **Always use connection pooling**: `?pgbouncer=true`
2. **Use SSL**: `?sslmode=require`
3. **Separate branches**: One per environment
4. **Regular backups**: Use Neon's automatic backups
5. **Monitor usage**: Check Neon Console regularly

## Quick Tips

### Mermaid Diagram Color Palette

| Element | Color | Usage |
|---------|-------|-------|
| **Project/Main** | `#1e293b` + `#3b82f6` | Primary containers |
| **Development** | `#0f172a` + `#10b981` | Dev environment (green) |
| **Staging** | `#0f172a` + `#f59e0b` | Staging environment (orange) |
| **Production** | `#0f172a` + `#ef4444` | Prod environment (red) |
| **Infrastructure** | `#475569` + `#94a3b8` | K8s, CI/CD (gray) |
| **Error/Rollback** | `#7f1d1d` + `#ef4444` | Critical actions (dark red) |

### Common Mermaid Issues

**Syntax Errors:**
- Use quotes for labels with special chars: `["Label<br/>text"]`
- Escape HTML entities: `&amp;` not `&`
- Use `<br/>` for line breaks inside labels
- Avoid `<br>` without closing slash

**Rendering Issues:**
- If diagram doesn't render, check for matching brackets `[]` or `{}`
- Verify all style declarations use valid CSS colors
- Ensure subgraph names are unique

### Visual Indicators

| Icon | Meaning |
|------|---------|
| | Project/Package |
| | Development/Tools |
| | Testing/Staging |
| | Production/Deploy |
| | Local Environment |
| | Kubernetes |
| | CI/CD Pipeline |
| | Configuration/Schema |
| | Database/Data |
| | Success/Validation |
| | Error/Failed |
| | Rollback/Retry |
| | Manual Action |
| | Push/Upload |
| | Build Process |

## Resources

- [Neon Documentation](https://neon.tech/docs)
- [Neon Console](https://console.neon.tech)
- [Prisma + Neon Guide](https://neon.tech/docs/guides/prisma)