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

Hướng Dẫn Neon Database

Project này sử dụng Neon PostgreSQL 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

# 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

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

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:

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:

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

Migrations

Development

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

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

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

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

Restore

# 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

   export DATABASE_URL="your-neon-url"
   

2. Schema không khớp

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