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

Architecture Overview

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

# 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

Migration Workflow

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

# 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

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