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

Kiến Trúc Neon

graph TB
 subgraph NeonProject[" Neon Project: goodgo-platform"]
 Main["<b>Branch: main</b><br/> Development<br/>Auto-scaling<br/>Point-in-time restore"]
 Staging["<b>Branch: staging</b><br/> Staging<br/>Created from main<br/>Pre-production testing"]
 Production["<b>Branch: production</b><br/> Production<br/>Created from main<br/>Live environment"]
 end

 subgraph Features[" Tính Năng Chính"]
 F1[" Serverless<br/>No infrastructure"]
 F2[" Auto-scaling<br/>Handle spikes"]
 F3[" Backups<br/>Point-in-time"]
 F4[" Pooling<br/>PgBouncer"]
 end

 Main -->|Branch từ| Staging
 Main -->|Branch từ| Production

 Features -.->|Áp dụng cho| Main
 Features -.->|Áp dụng cho| Staging
 Features -.->|Áp dụng cho| Production

 style NeonProject fill:#1a1a2e,stroke:#16213e,stroke-width:2px,color:#fff
 style Main fill:#0f3460,stroke:#16213e,stroke-width:2px,color:#fff
 style Staging fill:#533483,stroke:#16213e,stroke-width:2px,color:#fff
 style Production fill:#c72c41,stroke:#16213e,stroke-width:2px,color:#fff
 style Features fill:#1a1a2e,stroke:#16213e,stroke-width:2px,color:#fff
 style F1 fill:#0f3460,stroke:#16213e,stroke-width:2px,color:#fff
 style F2 fill:#0f3460,stroke:#16213e,stroke-width:2px,color:#fff
 style F3 fill:#0f3460,stroke:#16213e,stroke-width:2px,color:#fff
 style F4 fill:#0f3460,stroke:#16213e,stroke-width:2px,color:#fff

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

Quy Trình Migration

flowchart TD
 Start([ Bắt đầu<br/>Schema thay đổi]) --> Dev[ Development<br/>Tạo migration mới<br/>migrate.sh dev]
 Dev --> Test{ Test<br/>Migration<br/>OK?}

 Test -->| Không| Fix[ Sửa lỗi<br/>Cập nhật schema]
 Fix --> Dev

 Test -->| Có| Commit[ Commit<br/>Migration files<br/>+ schema.prisma]
 Commit --> PR[ Pull Request<br/>Code review]

 PR --> CICD[ CI/CD Pipeline<br/>Kiểm tra migration]
 CICD --> Staging[ Staging Branch<br/>Auto-apply migration]

 Staging --> StagingTest{ Staging<br/>Test OK?}
 StagingTest -->| Không| Rollback1[↩ Rollback staging]
 Rollback1 --> Fix

 StagingTest -->| Có| Approval[ Approval<br/>Production deploy]
 Approval --> Prod[ Production Branch<br/>Apply migration]

 Prod --> ProdTest{ Production<br/>OK?}
 ProdTest -->| Không| Rollback2[ Emergency Rollback<br/>Restore point-in-time]
 ProdTest -->| Có| Complete([ Hoàn thành<br/>Migration thành công])

 style Start fill:#1a1a2e,stroke:#16213e,stroke-width:2px,color:#fff
 style Dev fill:#0f3460,stroke:#16213e,stroke-width:2px,color:#fff
 style Test fill:#16213e,stroke:#0f3460,stroke-width:2px,color:#fff
 style Fix fill:#c72c41,stroke:#16213e,stroke-width:2px,color:#fff
 style Commit fill:#0f3460,stroke:#16213e,stroke-width:2px,color:#fff
 style PR fill:#0f3460,stroke:#16213e,stroke-width:2px,color:#fff
 style CICD fill:#533483,stroke:#16213e,stroke-width:2px,color:#fff
 style Staging fill:#533483,stroke:#16213e,stroke-width:2px,color:#fff
 style StagingTest fill:#16213e,stroke:#533483,stroke-width:2px,color:#fff
 style Rollback1 fill:#c72c41,stroke:#16213e,stroke-width:2px,color:#fff
 style Approval fill:#16213e,stroke:#0f3460,stroke-width:2px,color:#fff
 style Prod fill:#c72c41,stroke:#16213e,stroke-width:2px,color:#fff
 style ProdTest fill:#16213e,stroke:#c72c41,stroke-width:2px,color:#fff
 style Rollback2 fill:#c72c41,stroke:#16213e,stroke-width:3px,color:#fff
 style Complete fill:#0f3460,stroke:#16213e,stroke-width:2px,color:#fff

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ố

Sơ Đồ Xử Lý Sự Cố

flowchart TD
 Problem([ Vấn Đề Neon<br/>Không kết nối được?]) --> Type{Loại<br/>Vấn Đề?}

 Type -->| Kết nối| ConnIssue[Vấn Đề Kết Nối]
 Type -->| Migration| MigIssue[Vấn Đề Migration]
 Type -->| Hiệu suất| PerfIssue[Vấn Đề Hiệu Suất]

 ConnIssue --> CheckURL{Connection<br/>String OK?}
 CheckURL -->| Không| FixURL[ Kiểm tra:<br/>• sslmode=require<br/>• Credentials đúng<br/>• Endpoint active]
 CheckURL -->| Có| CheckIP{IP trong<br/>allowlist?}
 CheckIP -->| Không| AddIP[ Thêm IP vào<br/>Neon Console]
 CheckIP -->| Có| CheckBranch{Branch<br/>active?}
 CheckBranch -->| Không| ActivateBranch[ Kích hoạt branch<br/>hoặc tạo mới]
 CheckBranch -->| Có| ContactSupport[ Liên hệ<br/>Neon Support]

 MigIssue --> CheckEnv{DATABASE_URL<br/>đã set?}
 CheckEnv -->| Không| SetEnv[ Export<br/>DATABASE_URL]
 CheckEnv -->| Có| CheckSchema{Schema<br/>đồng bộ?}
 CheckSchema -->| Không| ResetMig[ DEV ONLY:<br/>prisma migrate reset]
 CheckSchema -->| Có| CheckTimeout{Connection<br/>timeout?}
 CheckTimeout -->| Có| AddPooling[ Thêm<br/>?pgbouncer=true]
 CheckTimeout -->| Không| CheckLimits[ Kiểm tra<br/>Neon Console limits]

 PerfIssue --> HasPooling{Connection<br/>Pooling ON?}
 HasPooling -->| Không| EnablePooling[ Thêm<br/>?pgbouncer=true]
 HasPooling -->| Có| CheckQueries{Slow<br/>queries?}
 CheckQueries -->| Có| AnalyzeQueries[ Neon Console<br/>Query Analyzer]
 CheckQueries -->| Không| CheckIndexes{Indexes<br/>tối ưu?}
 CheckIndexes -->| Không| AddIndexes[ Thêm indexes<br/>vào Prisma schema]
 CheckIndexes -->| Có| ScalePlan[ Nâng cấp<br/>Neon plan]

 FixURL --> Solved([ Đã giải quyết])
 AddIP --> Solved
 ActivateBranch --> Solved
 ContactSupport --> Solved
 SetEnv --> Solved
 ResetMig --> Solved
 AddPooling --> Solved
 CheckLimits --> Solved
 EnablePooling --> Solved
 AnalyzeQueries --> Solved
 AddIndexes --> Solved
 ScalePlan --> Solved

 style Problem fill:#c72c41,stroke:#16213e,stroke-width:3px,color:#fff
 style Type fill:#16213e,stroke:#0f3460,stroke-width:2px,color:#fff

 style ConnIssue fill:#533483,stroke:#16213e,stroke-width:2px,color:#fff
 style MigIssue fill:#533483,stroke:#16213e,stroke-width:2px,color:#fff
 style PerfIssue fill:#533483,stroke:#16213e,stroke-width:2px,color:#fff

 style CheckURL fill:#16213e,stroke:#533483,stroke-width:2px,color:#fff
 style CheckIP fill:#16213e,stroke:#533483,stroke-width:2px,color:#fff
 style CheckBranch fill:#16213e,stroke:#533483,stroke-width:2px,color:#fff
 style CheckEnv fill:#16213e,stroke:#533483,stroke-width:2px,color:#fff
 style CheckSchema fill:#16213e,stroke:#533483,stroke-width:2px,color:#fff
 style CheckTimeout fill:#16213e,stroke:#533483,stroke-width:2px,color:#fff
 style HasPooling fill:#16213e,stroke:#533483,stroke-width:2px,color:#fff
 style CheckQueries fill:#16213e,stroke:#533483,stroke-width:2px,color:#fff
 style CheckIndexes fill:#16213e,stroke:#533483,stroke-width:2px,color:#fff

 style FixURL fill:#0f3460,stroke:#16213e,stroke-width:2px,color:#fff
 style AddIP fill:#0f3460,stroke:#16213e,stroke-width:2px,color:#fff
 style ActivateBranch fill:#0f3460,stroke:#16213e,stroke-width:2px,color:#fff
 style ContactSupport fill:#0f3460,stroke:#16213e,stroke-width:2px,color:#fff
 style SetEnv fill:#0f3460,stroke:#16213e,stroke-width:2px,color:#fff
 style ResetMig fill:#0f3460,stroke:#16213e,stroke-width:2px,color:#fff
 style AddPooling fill:#0f3460,stroke:#16213e,stroke-width:2px,color:#fff
 style CheckLimits fill:#0f3460,stroke:#16213e,stroke-width:2px,color:#fff
 style EnablePooling fill:#0f3460,stroke:#16213e,stroke-width:2px,color:#fff
 style AnalyzeQueries fill:#0f3460,stroke:#16213e,stroke-width:2px,color:#fff
 style AddIndexes fill:#0f3460,stroke:#16213e,stroke-width:2px,color:#fff
 style ScalePlan fill:#0f3460,stroke:#16213e,stroke-width:2px,color:#fff

 style Solved fill:#0f3460,stroke:#16213e,stroke-width:2px,color:#fff

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

Quick Tips

Mermaid Diagram Colors

Tất cả Mermaid diagrams sử dụng bảng màu tối (dark palette) với chữ trắng:

Loại Node	Màu	Mục Đích
Primary	#0f3460	Actions, Steps, Solutions
Purple	#533483	Staging, Categories, Warnings
Red	#c72c41	Production, Errors, Critical
Dark	#1a1a2e	Backgrounds, Containers
Darker	#16213e	Decision Points, Questions

Pattern:

style NodeName fill:#0f3460,stroke:#16213e,stroke-width:2px,color:#fff

Neon Common Issues & Solutions

Vấn đề	Giải pháp nhanh	Emoji
Connection timeout	Thêm ?pgbouncer=true
SSL error	Thêm ?sslmode=require
IP bị chặn	Thêm IP vào Neon Console allowlist
Branch inactive	Kích hoạt lại trong Console
Migration lỗi	Reset dev: prisma migrate reset
Slow queries	Bật Query Analyzer trong Console
Storage đầy	Nâng cấp plan hoặc cleanup data

Visual Indicators

• = Neon Project
• = Development
• = Staging
• = Production
• = Performance/Speed
• = Connection
• = Storage/Backup
• = Retry/Rollback
• = Success/OK
• = Error/Failed
• = Critical/Emergency
• = Metrics/Analytics

Tài Nguyên

• Neon Documentation
• Neon Console
• Prisma + Neon Guide