5.0 KiB
5.0 KiB
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
- Đăng ký tại https://neon.tech
- Tạo project mới:
goodgo-platform
2. Tạo Branches
Trong Neon Console, tạo branches:
main(development) - đã tồn tạistaging- tạo từ mainproduction- 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=truecho 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 auth-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 Neonpgbouncer=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 auth-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 auth-service-secrets \
--from-literal=database-url='postgresql://...' \
-n production
Migrations
Development
# Tạo migration mới
./scripts/db/migrate.sh auth-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 auth-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 auth-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
-
Kiểm tra định dạng connection string
- Phải bao gồm
?sslmode=require - Xác minh credentials
- Phải bao gồm
-
Kiểm tra IP allowlist
- Neon có thể giới hạn IPs
- Thêm IP của bạn trong Neon Console
-
Kiểm tra branch status
- Đảm bảo branch đang active
- Kiểm tra maintenance
Vấn Đề Migration
-
DATABASE_URL chưa set
export DATABASE_URL="your-neon-url" -
Schema không khớp
# Reset và migrate lại (chỉ dev!) pnpm prisma migrate reset -
Connection timeout
- Thêm
?pgbouncer=truecho pooling - Kiểm tra Neon console cho limits
- Thêm
Vấn Đề Hiệu Suất
-
Bật connection pooling
- Thêm
?pgbouncer=truevào connection string
- Thêm
-
Kiểm tra query performance
- Sử dụng Neon Console query analyzer
- Xem lại slow queries
-
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
- Luôn sử dụng connection pooling:
?pgbouncer=true - Sử dụng SSL:
?sslmode=require - Tách branches: Một branch cho mỗi môi trường
- Backup thường xuyên: Sử dụng automatic backups của Neon
- Theo dõi usage: Kiểm tra Neon Console thường xuyên