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

Neon Database Guide

This project uses Neon PostgreSQL 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

# 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

./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

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:

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:

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

Migrations

Development

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

./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

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

This creates a SQL dump file in backups/ directory.

Restore

# 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

   export DATABASE_URL="your-neon-url"
   

2. Schema mismatch

   # 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
• Neon Console
• Prisma + Neon Guide