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

## 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

### 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

## Resources

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