019c79b898
- Renamed auth-service to iam-service across various files for consistency. - Updated deployment workflows, database migration scripts, and documentation to reflect the service name change. - Enhanced bilingual documentation for clarity on the new service structure and usage. - Removed outdated references to auth-service in scripts and configuration files to streamline the project structure.
126 lines
2.7 KiB
Markdown
126 lines
2.7 KiB
Markdown
# Neon Database Setup
|
|
|
|
This project uses [Neon PostgreSQL](https://neon.tech) 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:
|
|
|
|
```bash
|
|
# 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`:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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
|