supabase-db-model
Chuẩn hoá cách đọc/viết DB 模型 Supabase(迁移 + TS 类型 + 服务)trong repo này。
📖 中文导读:Chuẩn hoá cách đọc/viết DB 模型 Supabase(迁移 + TS 类型 + 服务)trong repo này。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: supabase-db-model description: Chuẩn hoá cách đọc/viết DB model Supabase (migrations + TS types + services) trong repo này.
Mục tiêu
- Giữ source of truth ở Supabase (DB-first) và truy cập dữ liệu qua
apps/web/src/services/*-service.ts. - Dùng type-safe schema từ
apps/web/src/types/database.tskhi thao tác với Row/Insert/Update.
Nguồn sự thật trong repo
- Schema/migrations:
apps/web/supabase/migrations/*.sql - Types (generated/committed):
apps/web/src/types/database.ts - Query patterns:
- Blog:
apps/web/src/services/blog-service.ts - Docs:
apps/web/src/services/docs-service.ts
- Blog:
Type pattern (khuyến nghị)
- Row type:
Database['public']['Tables']['blog_posts']['Row']
- Insert type:
Database['public']['Tables']['blog_posts']['Insert']
- Update type:
Database['public']['Tables']['blog_posts']['Update']
Ví dụ đang dùng trong repo:
- Blog joins:
blog_posts+profiles(author) +media(cover/og) +tags(quablog_post_tags).
Query patterns quan trọng
1) Joins + flatten junction table
- Repo dùng join kiểu:
tags:blog_post_tags(tag:tags(*))
- Sau đó flatten bằng helper (xem
flattenTagstrongapps/web/src/services/blog-service.ts).
2) Full-text search (FTS)
- Blog list dùng
textSearch('search_vector', term, { type: 'websearch', config: 'simple' }). - Khi thêm field mới vào tìm kiếm, cần cập nhật:
- Migration tạo/đổi
search_vector(index GIN nếu có) - Service query (tên column phải khớp)
- Migration tạo/đổi
3) Date range filter cho admin
- Pattern trong repo: dùng
.or(...)để match cảcreated_atvàpublished_at/updated_at. - Xem
applyOrDateFiltertrongblog-service.tsvàdocs-service.ts.
4) Docs slug normalization
- Public docs dùng
slugParts.join('/')và map'' -> 'index'(xemgetPublicDocBySlugtrongdocs-service.ts). - Khi thiết kế URL docs, ưu tiên giữ quy ước
indexnày để tránh 2 nguồn truth.
Workflow khi đổi DB
- Tạo migration mới dưới
apps/web/supabase/migrations/(DDL/RLS/indexes). - Apply migration bằng Supabase MCP:
- DDL: dùng
apply_migration - Debug dữ liệu: dùng
execute_sql
- DDL: dùng
- Regenerate TypeScript types:
- Ưu tiên dùng Supabase tooling (CLI hoặc MCP
generate_typescript_types) để cập nhậtapps/web/src/types/database.ts.
- Ưu tiên dùng Supabase tooling (CLI hoặc MCP
- Cập nhật services (
apps/web/src/services/*-service.ts) và types helper nếu cần.
Lưu ý
- Không hardcode secrets/keys.
- RLS: thay đổi policy phải có migration rõ ràng.
- App Router Next.js 16: pages phải
await params/searchParams(liên quan khi query theo locale/slug).