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

# Hướng Dẫn Neon Database

Project này sử dụng [Neon PostgreSQL](https://neon.tech) cho tất cả môi trường.

## Tại Sao Chọn Neon?

- ✅ **Serverless**: Không cần quản lý infrastructure
- ✅ **Branching**: Database riêng cho dev/staging/prod
- ✅ **Auto-scaling**: Tự động xử lý traffic spikes
- ✅ **Point-in-time restore**: Dễ dàng khôi phục từ lỗi
- ✅ **Free tier**: Hoàn hảo cho development
- ✅ **Connection pooling**: Hỗ trợ PgBouncer tích hợp

## Bắt Đầu Nhanh

### 1. Tạo Tài Khoản Neon

1. Đăng ký tại https://neon.tech
2. Tạo project mới: `goodgo-platform`

### 2. Tạo Branches

Trong Neon Console, tạo branches:
- `main` (development) - đã tồn tại
- `staging` - tạo từ main
- `production` - tạo từ main

### 3. Lấy Connection Strings

Cho mỗi branch, copy connection string:
- Định dạng: `postgresql://user:password@ep-xxx.region.neon.tech/dbname?sslmode=require`
- Thêm `?pgbouncer=true` cho connection pooling (khuyến nghị)

### 4. Cấu Hình Local Development

```bash
# Tạo .env.local
cp deployments/local/env.local.example deployments/local/.env.local

# Chỉnh sửa .env.local và thêm:
DATABASE_URL=postgresql://user:pass@ep-xxx.region.neon.tech/dbname?sslmode=require&pgbouncer=true
```

### 5. Chạy Migrations

```bash
./scripts/db/migrate.sh iam-service dev
```

## Định Dạng Connection String

```
postgresql://[user]:[password]@[endpoint]/[dbname]?sslmode=require&pgbouncer=true
```

**Tham số**:
- `sslmode=require` - Bắt buộc cho Neon
- `pgbouncer=true` - Bật connection pooling (khuyến nghị)

## Cấu Hình Môi Trường

### Local Development

File: `deployments/local/.env.local`

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

### Staging

Lưu trong GitHub Secrets: `NEON_DATABASE_URL_STAGING`

Hoặc trong Kubernetes:
```bash
kubectl create secret generic iam-service-secrets \
  --from-literal=database-url='postgresql://...' \
  -n staging
```

### Production

Lưu trong GitHub Secrets: `NEON_DATABASE_URL_PRODUCTION`

Hoặc trong Kubernetes:
```bash
kubectl create secret generic iam-service-secrets \
  --from-literal=database-url='postgresql://...' \
  -n production
```

## Migrations

### Development

```bash
# Tạo migration mới
./scripts/db/migrate.sh iam-service dev

# Điều này sẽ:
# 1. Tạo migration file
# 2. Áp dụng vào database
# 3. Cập nhật Prisma Client
```

### Staging/Production

Migrations chạy tự động trong CI/CD:
- Trước khi deploy lên staging
- Trước khi deploy lên production (cần approval)

Migration thủ công:
```bash
./scripts/db/migrate.sh iam-service deploy
```

## Backup & Restore

### Backup Tự Động

Neon cung cấp backup tự động. Truy cập qua Neon Console:
- Point-in-time restore
- Branch restore
- Export data

### Backup Thủ Công

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

Điều này tạo file SQL dump trong thư mục `backups/`.

### Restore

```bash
# Từ Neon Console (khuyến nghị)
# Hoặc sử dụng psql:
psql $DATABASE_URL < backup.sql
```

## Monitoring

Theo dõi databases qua Neon Console:
- Connection metrics
- Query performance
- Storage usage
- Branch status

## Xử Lý Sự Cố

### Vấn Đề Kết Nối

1. **Kiểm tra định dạng connection string**
   - Phải bao gồm `?sslmode=require`
   - Xác minh credentials

2. **Kiểm tra IP allowlist**
   - Neon có thể giới hạn IPs
   - Thêm IP của bạn trong Neon Console

3. **Kiểm tra branch status**
   - Đảm bảo branch đang active
   - Kiểm tra maintenance

### Vấn Đề Migration

1. **DATABASE_URL chưa set**
   ```bash
   export DATABASE_URL="your-neon-url"
   ```

2. **Schema không khớp**
   ```bash
   # Reset và migrate lại (chỉ dev!)
   pnpm prisma migrate reset
   ```

3. **Connection timeout**
   - Thêm `?pgbouncer=true` cho pooling
   - Kiểm tra Neon console cho limits

### Vấn Đề Hiệu Suất

1. **Bật connection pooling**
   - Thêm `?pgbouncer=true` vào connection string

2. **Kiểm tra query performance**
   - Sử dụng Neon Console query analyzer
   - Xem lại slow queries

3. **Tối ưu indexes**
   - Xem lại Prisma schema
   - Thêm indexes cho các query thường dùng

## Tối Ưu Chi Phí

- **Free tier**: 0.5 GB storage, đủ cho dev
- **Staging**: Sử dụng free tier hoặc plan trả phí tối thiểu
- **Production**: Scale dựa trên usage
- **Branching**: Free branches cho testing

## Best Practices

1. **Luôn sử dụng connection pooling**: `?pgbouncer=true`
2. **Sử dụng SSL**: `?sslmode=require`
3. **Tách branches**: Một branch cho mỗi môi trường
4. **Backup thường xuyên**: Sử dụng automatic backups của Neon
5. **Theo dõi usage**: Kiểm tra Neon Console thường xuyên

## Tài Nguyên

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