pos-system/infra/databases/neon/README.md

Neon Database Setup

This project uses Neon PostgreSQL for all environments (dev, staging, production).

Why Neon?

• ✅ Serverless PostgreSQL with auto-scaling
• ✅ Branching support (dev, staging, production branches)
• ✅ Point-in-time restore
• ✅ Free tier for development
• ✅ Built-in connection pooling
• ✅ No infrastructure management needed

Setup Instructions

1. Create Neon Project

1. Sign up at https://neon.tech
2. Create a new project: goodgo-platform
3. Note your connection string from the main branch

2. Create Branches

Create branches for each environment:

# Using Neon Console or CLI
# Main branch = development
# Create: staging branch
# Create: production branch

3. Get Connection Strings

For each branch, get the connection string:

• Format: postgresql://user:password@ep-xxx.region.neon.tech/dbname?sslmode=require
• Add ?pgbouncer=true for connection pooling (recommended)

4. Configure Environment Variables

Local Development

Create deployments/local/.env.local:

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

Staging/Production

Store in GitHub Secrets:

• NEON_DATABASE_URL_STAGING
• NEON_DATABASE_URL_PRODUCTION

Or in Kubernetes Secrets (see deployments/staging/kubernetes/secrets.yaml.example)

Connection Pooling

Neon provides built-in connection pooling. Add ?pgbouncer=true to your connection string:

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

Migration

Development

cd services/iam-service
pnpm prisma migrate dev

Staging/Production

Migrations run automatically in CI/CD workflows before deployment.

Backup & Restore

Neon provides automatic backups and point-in-time restore via their console.

For manual backup:

# Using pg_dump
pg_dump $DATABASE_URL > backup.sql

# Restore
psql $DATABASE_URL < backup.sql

Monitoring

Monitor your databases via Neon Console:

• Connection metrics
• Query performance
• Storage usage
• Branch status

Cost Optimization

• Free tier: Sufficient for development
• Staging: Use free tier or minimal paid plan
• Production: Scale based on usage

Troubleshooting

Connection Issues

1. Check connection string format
2. Verify SSL mode: ?sslmode=require
3. Check IP allowlist in Neon console (if enabled)
4. Verify credentials

Migration Issues

1. Ensure DATABASE_URL is set correctly
2. Check Prisma schema matches database
3. Review migration files

Performance Issues

1. Enable connection pooling: ?pgbouncer=true
2. Check query performance in Neon console
3. Review indexes in Prisma schema