Quy ước format SQL: keyword IN HOA và indent JOIN/WHERE【2026】

Trong team outsource Việt Nam, SQL “hỏng đọc” ít khi vì thiếu JOIN — mà vì mỗi người một kiểu: người viết select * from... một dòng, người xuống dòng lung tung, người Select lẫn SELECT. Reviewer mất 10 phút chỉ để tìm WHERE, rồi mới kịp hỏi “sao thiếu index”.

Bài này tập trung quy ước keyword + indent — cái bạn thống nhất một lần rồi để formatter thực thi — không phải giáo trình tối ưu query.

Bài viết này giúp bạn

• Chốt quy ước hoa/thường cho keyword vs identifier
• Mẫu indent cho SELECT list, JOIN…ON, WHERE…AND
• Biết khi nào Format vs Minify
• Checklist trước khi merge PR chứa SQL
• Case study query một dòng từ production log
• Dùng định dạng SQL không upload schema

---

Vì sao quy ước format quan trọng hơn “gu cá nhân”

Engine không quan tâm bạn viết hoa. Con người thì có:

• Mắt quét clause: WHERE / JOIN ở đầu dòng → tìm điều kiện nhanh.
• Diff PR sạch: cùng quy ước → diff chỉ hiện thay đổi logic, không hiện cả file đổi indent.
• Onboarding: junior đọc query senior đã format sẽ học cấu trúc nhanh hơn đọc một dòng 800 ký tự.

---

Quy ước keyword: hoa cho cấu trúc, thường cho tên

Đề xuất mặc định (phổ biến)

Thành phần	Quy ước	Ví dụ
Keyword SQL	IN HOA	SELECT, FROM, LEFT JOIN, WHERE, GROUP BY
Bảng / cột	snake_case thường	users, order_date
Alias	ngắn, thường	u, o, hoặc users AS u
Chuỗi literal	giữ nguyên	'completed'

Không bắt buộc tuyệt đối — một số style guide (như một phần cộng đồng PostgreSQL) thích keyword thường. Điều quan trọng: một repo một kiểu. Formatter có option uppercase keyword giúp ép về cùng chuẩn sau khi dán query lộn xộn.

Tránh

• Select / from / WHERE lẫn trong cùng câu.
• Viết hoa tên cột (Order_Date) chỉ vì “nhìn quan trọng” — dễ lệch schema thật.
• Đổi quy ước giữa các file migration và query app.

---

Quy ước indent: nhìn clause, không nhìn “đẹp”

Mẫu trước / sau

Trước (một dòng từ log):

select u.id, u.name, o.order_date, p.product_name from users u join orders o on u.id = o.user_id join products p on o.product_id = p.id where o.status = 'completed' and o.created_at > '2023-01-01' order by o.created_at desc limit 100;

Sau (keyword hoa + indent theo mệnh đề):

SELECT
  u.id,
  u.name,
  o.order_date,
  p.product_name
FROM
  users u
JOIN
  orders o ON u.id = o.user_id
JOIN
  products p ON o.product_id = p.id
WHERE
  o.status = 'completed'
  AND o.created_at > '2023-01-01'
ORDER BY
  o.created_at DESC
LIMIT
  100;

Luật indent thực dụng

1. SELECT list: ≥3 cột → mỗi cột một dòng, dấu phẩy cuối dòng (hoặc đầu dòng — chọn một).
2. FROM / JOIN: mỗi nguồn dữ liệu một khối; ON đi với điều kiện join, không chôn trong WHERE nếu có thể.
3. WHERE: AND / OR thẳng hàng — dễ thấy thiếu ngoặc điều kiện phức tạp.
4. Subquery: tăng một cấp indent; coi subquery như “bảng tạm” có alias rõ.
5. Không indent theo cảm xúc (“cột quan trọng thụt vào thêm”) — phá diff.

---

Format vs Minify — hai chế độ, hai việc

Ví dụ nhúng sau khi đã hiểu logic:

query = (
    "SELECT u.id, u.name FROM users u "
    "JOIN orders o ON u.id = o.user_id "
    "WHERE o.status = 'active'"
)
# hoặc một dòng minify thuần — tránh raw newline trong quote lỗi

Lỗi hay gặp: copy SQL đã Format (nhiều dòng) vào shell một quote → xuống dòng phá lệnh. Minify trước khi đưa vào CI.

---

Checklist quy ước trước khi merge

• Keyword cùng kiểu hoa/thường trong file (hoặc cả repo)
• JOIN có ON rõ; không “lọt” điều kiện quan hệ sang WHERE nếu team cấm
• AND/OR thẳng hàng — review được short-circuit logic
• Không SELECT * trên query production mới (trừ khi có lý do ghi chú)
• Alias bảng nhất quán (u/o vs tên dài — chọn một phong cách)
• Nếu file là migration: giữ format ổn định để diff lần sau nhỏ
• Schema/PII: format bằng tool local, không dán lên formatter online lạ

---

Case study: query một dòng từ Slack khách

Bối cảnh: Khách gửi log chậm API — một SELECT 3 JOIN, toàn bộ một dòng, keyword thường lẫn hoa.

Việc làm trong 5 phút:

1. Dán vào SQL formatter → Format + uppercase keyword.
2. Nhìn khối JOIN / WHERE: phát hiện status so sánh sai bảng (u.status thay vì o.status).
3. Sửa logic, format lại, gửi khách bản đọc được + bản minify cho họ paste vào code.

Không cần cài extension IDE trên máy khách; trình duyệt đủ. Phù hợp freelancer nhận việc ad-hoc.

Case study 2: hai người format hai kiểu trong cùng PR

Dev A dùng 2-space, keyword hoa; Dev B format tay 4-space, keyword thường. Diff Git hiện “đổi cả file” dù chỉ thêm một cột. Cách chặn: ghi một dòng trong CONTRIBUTING — “SQL: uppercase keywords, 2-space; chạy formatter trước commit” — và dùng cùng tool/option.

---

Giới hạn formatter (để không bất ngờ)

• Cú pháp sai (thiếu ), quote mở) → kết quả lệch hoặc không parse. Sửa ngoặc trước.
• Dialect mở rộng (hint Oracle, biến @@ đặc thù) → có thể không đẹp hoàn hảo; format phần chuẩn rồi chỉnh tay phần đặc thù.
• File DDL khổng lồ → chia nhỏ; trình duyệt có giới hạn bộ nhớ.
• Formatter không tối ưu plan / index — chỉ làm rõ cấu trúc để bạn tối ưu.

---

Thao tác trên Kawa Dev Tools

1. Mở định dạng SQL.
2. Dán query thô (một dòng cũng được).
3. Chọn Format — kiểm tra keyword đã hoa và indent clause.
4. Cần nhúng script → Minify một dòng, copy.
5. Đối chiếu với quy ước team; chỉnh tay chỗ dialect rồi format lại nếu cần.

Công cụ chạy trên trình duyệt — phù hợp query nội bộ có tên bảng/cột nhạy cảm hơn dịch vụ upload server lạ.

---

Gợi ý ghi quy ước một đoạn (copy vào wiki)

SQL style (repo này):
- Keywords: UPPERCASE
- Identifiers: snake_case
- Indent: 2 spaces; one major clause per block
- Format before review; Minify only when embedding
- Tool: local SQL formatter (Kawa or IDE) — same options for all

Ba dòng này tiết kiệm hơn một buổi tranh luận “hoa hay thường” trên PR.

---

Liên kết liên quan

• Công cụ SQL formatter
• JSON formatter — cùng ý tưởng Format/Minify cho payload API
• Danh sách công cụ