Thiết kế schema & query database với Claude Code: hướng dẫn thực chiến (2026)

Claude Code có làm được việc thiết kế DB và viết query không?

Có - và làm rất tốt, vì thiết kế database và viết query đúng là kiểu việc mà một agentic tool như Claude Code sinh ra để làm. Claude Code không chỉ gợi ý code như autocomplete: nó đọc được file và cả repo của bạn, chạy được lệnh trong terminal (psql, mongosh, chạy test), đọc output rồi tự lặp để sửa. Với database, chuỗi "đọc bối cảnh → sinh DDL/query → chạy → đọc kết quả → chỉnh" chính là vòng lặp mạnh nhất của nó.

Bài này tập trung vào hai hệ phổ biến nhất ở Việt Nam: PostgreSQL (quan hệ) và MongoDB (document). Cả hai đều dùng được cách làm bên dưới. Nếu bạn mới bắt đầu và chưa rõ Claude Code là gì, đọc trước bài Claude Code là gì và dùng để làm gì rồi quay lại đây.

Một lưu ý thẳng thắn ngay từ đầu: AI làm database rất nhanh nhưng không tự nhiên an toàn. Nó có thể bịa tên cột, chọn sai kiểu dữ liệu cho tiền, hoặc sinh migration thiếu bước hoàn tác. Vì vậy toàn bộ hướng dẫn này gắn liền hai nguyên tắc: chỉ cấp quyền read-only lên prod và luôn cho Claude một cách tự kiểm chứng công việc của nó. Chúng ta sẽ đi trọn vòng: kết nối → thiết kế schema → viết query → index/hiệu năng → migration.

Chuẩn bị: kết nối Claude Code với database

Trước khi nhờ Claude làm gì, nó cần "nhìn thấy" dữ liệu của bạn. Có ba cách, từ an toàn nhất đến linh hoạt nhất:

Cách 1 - MCP server (khuyến nghị, đọc-only)

MCP (Model Context Protocol) là chuẩn để Claude Code kết nối tới công cụ ngoài, gồm cả database. Tài liệu MCP của Claude Code nêu thẳng ví dụ truy vấn dữ liệu "based on our PostgreSQL database" (Claude Code MCP docs, Anthropic, 2026). Lệnh thêm một MCP server dạng HTTP:

claude mcp add --transport http postgres-db https://your-mcp-endpoint

Điểm cực quan trọng về an toàn: MCP server Postgres tham chiếu chính chủ được mô tả là "Read-only database access with schema inspection" - tức chỉ đọc và soi cấu trúc, không ghi (modelcontextprotocol/servers, 2026; server này nay đã chuyển sang kho servers-archived). Đây đúng là điều bạn muốn khi để AI đụng vào DB: nó đọc được schema để hiểu bối cảnh, nhưng không thể tự tay xoá bảng của bạn. Nếu bạn chưa quen MCP, xem bài MCP là gì và cách kết nối công cụ ngoài cho Claude Code.

Cách 2 - psql / mongosh CLI

Đơn giản hơn: cứ để Claude chạy lệnh qua terminal. Nếu bạn đã có psql hoặc mongosh cấu hình sẵn, Claude gọi được trực tiếp. Cách này linh hoạt (chạy được cả lệnh ghi) nhưng vì thế cũng nguy hiểm hơn - chỉ nên trỏ vào DB dev/local, tuyệt đối không phải connection string production có quyền ghi.

Cách 3 - dán file schema bằng @

Khi chưa muốn nối DB thật, bạn chỉ cần đưa file schema.sql hoặc mô tả bảng cho Claude bằng cú pháp @:

Đọc @db/schema.sql và tóm tắt các bảng, khoá chính, quan hệ.
Sau đó liệt kê 3 rủi ro thiết kế bạn thấy.

Bước 1 - Thiết kế schema với Claude Code

Sai lầm phổ biến nhất là mở Claude ra và gõ ngay "tạo bảng users cho tôi". Làm thế bạn nhận về một schema generic mà AI đoán mò. Cách đúng là workload-first: quyết định kiểu tải trước, rồi mới để AI dựng bảng.

Phân loại workload trước

Hỏi chính bạn (và nói cho Claude biết) ứng dụng thuộc loại nào, vì mỗi loại tối ưu cho một hình dạng dữ liệu khác nhau:

Dùng plan mode để Claude đọc trước khi viết

Bật plan mode (phím Shift+Tab để chuyển chế độ) và yêu cầu Claude đọc yêu cầu, hỏi lại chỗ chưa rõ, rồi mới sinh DDL. Điều này ngăn nó lao vào tạo bảng dựa trên giả định sai.

Prompt pattern: nêu invariant, không nêu cột

Thay vì liệt kê cột, hãy mô tả quy tắc nghiệp vụ bất biến để AI tự đặt đúng khoá chính, unique, foreign key:

Thiết kế schema PostgreSQL cho một shop nhỏ. Workload: OLTP.
Quy tắc bất biến:
- Một email chỉ thuộc một tài khoản (unique).
- Một đơn hàng phải thuộc về một user đang tồn tại (mồ côi = bug).
- Mỗi dòng order_items ghi giá TẠI THỜI ĐIỂM mua, không tham chiếu giá hiện tại.
- Tiền phải chính xác tuyệt đối, không sai số.
Hãy hỏi lại nếu thiếu thông tin trước khi viết DDL.

Checklist quan hệ (để review DDL Claude sinh)

• Đặt tên entity là danh từ; join table đặt theo quan hệ nó biểu diễn.
• Identity ổn định vào primary key; quy tắc nghiệp vụ duy nhất vào unique constraint.
• Dùng foreign key khi dữ liệu mồ côi là bug.
• Tiền, số lượng, thời gian dùng kiểu chính xác - không bao giờ float cho tiền (dùng numeric/decimal).
• Quan hệ n-n: tạo join table riêng, thêm cột metadata hữu ích.
• Chỉ thêm index cho predicate đã được chứng minh (đừng đánh index tất cả).

Ví dụ thật, schema e-commerce tối giản mà Claude sinh ra (đã sửa lại một chỗ - xem chú thích):

CREATE TABLE users (
 id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
 email text NOT NULL UNIQUE,
 created_at timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE orders (
 id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
 user_id bigint NOT NULL REFERENCES users(id),
 status text NOT NULL DEFAULT 'pending',
 created_at timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE order_items (
 id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
 order_id bigint NOT NULL REFERENCES orders(id),
 product_id bigint NOT NULL,
 quantity int NOT NULL CHECK (quantity > 0),
 unit_price numeric(12,2) NOT NULL -- KHÔNG float: tiền phải chính xác
);

Lần đầu Claude để unit_price là real (float). Mình bắt sửa thành numeric(12,2) - đây chính là loại lỗi bạn phải tự canh, AI không phải lúc nào cũng nhớ.

PostgreSQL hay MongoDB? Chọn theo access pattern

Đừng chọn theo sở thích, chọn theo cách dữ liệu được đọc/ghi. Bảng nhanh:

Quy tắc vàng cho MongoDB khi phân vân embed hay reference:

• Embed khi dữ liệu con được đọc/ghi cùng parent và kích thước có giới hạn (ví dụ: địa chỉ giao hàng trong đơn hàng).
• Reference khi dữ liệu lớn vô hạn, được nhiều parent chia sẻ, hoặc cần vòng đời riêng (ví dụ: comment của một bài viết viral).

Bước 2 - Viết và tối ưu query với Claude Code

Đây là chỗ Claude Code toả sáng: bạn mô tả kết quả mong muốn bằng tiếng Việt, nó viết query, giải thích, rồi tối ưu. Với SQL, nó thạo JOIN, subquery, CTE, window function. Với MongoDB, nó dựng aggregation pipeline ($match → $group → $lookup).

Ví dụ thật - báo cáo doanh thu theo tháng. Prompt:

Viết query Postgres tính tổng doanh thu mỗi tháng năm 2026,
chỉ tính đơn có status = 'paid'. Dùng CTE cho dễ đọc, giải thích ngắn.

Claude trả về:

WITH paid_items AS (
 SELECT o.created_at, oi.quantity * oi.unit_price AS line_total
 FROM orders o
 JOIN order_items oi ON oi.order_id = o.id
 WHERE o.status = 'paid'
 AND o.created_at >= '2026-01-01'
 AND o.created_at < '2027-01-01'
)
SELECT date_trunc('month', created_at) AS month,
 SUM(line_total) AS revenue
FROM paid_items
GROUP BY 1
ORDER BY 1;

Output khi chạy (dữ liệu mẫu):

 month | revenue
--------------------+-----------
 2026-01-01 00:00:00 | 154200.00
 2026-02-01 00:00:00 | 187650.50
 2026-03-01 00:00:00 | 203110.00

Với MongoDB, cùng ý tưởng là một pipeline: $match lọc đơn paid, $unwind mảng items, $group theo tháng. Bạn nhờ Claude viết rồi bảo nó giải thích từng stage - cách nhanh nhất để vừa có query vừa hiểu nó.

Cảnh báo quan trọng: luôn đọc lại query Claude viết trước khi chạy trên dữ liệu thật. Một câu UPDATE/DELETE thiếu WHERE do AI sinh nhầm có thể xoá sạch bảng. Đọc, hiểu, rồi mới Enter.

Bước 3 - Index và hiệu năng với EXPLAIN ANALYZE

Query chạy đúng chưa đủ, nó phải chạy nhanh. Nhờ Claude chạy EXPLAIN ANALYZE (Postgres) hoặc .explain() (Mongo), đọc plan, rồi đề xuất index - nhưng đúng chỗ, không đánh bừa.

Chạy EXPLAIN ANALYZE cho query doanh thu ở trên.
Nếu thấy Seq Scan trên orders, đề xuất index phù hợp và giải thích tại sao.

Với bảng orders lớn, plan ban đầu thường có Seq Scan vì lọc theo status và created_at. Thêm index đúng:

CREATE INDEX idx_orders_status_created
 ON orders (status, created_at);

Chạy lại, plan chuyển sang Index Scan, thời gian query giảm rõ rệt. Điểm cần Claude giúp là chọn thứ tự cột trong composite index cho khớp predicate - đây là chỗ dev mới hay sai.

Nguyên tắc index để tránh over-index (chính Claude cũng hay lạm dụng): chỉ index cho foreign key, cột thường xuyên filter/sort, và ràng buộc unique. Mỗi index thêm vào làm chậm ghi và tốn dung lượng, nên đừng đánh index "cho chắc". Nếu bạn bảo Claude "thêm index cho nhanh", nó có xu hướng đánh quá tay - hãy yêu cầu nó chỉ đề xuất index có predicate chứng minh được.

Bước 4 - Migration an toàn với Claude Code

Thay đổi schema trên hệ thống đang chạy là việc dễ gây sự cố nhất. Quy trình an toàn khi để Claude sinh migration:

1. Luôn kèm rollback. Mỗi migration "lên" (up) phải có migration "xuống" (down) tương ứng. Yêu cầu Claude viết cả hai và giải thích cách hoàn tác.
2. Test trên bản sao trước. Chạy migration trên DB dev hoặc bản snapshot của prod, không chạy thẳng lên prod.
3. So hàng trước/sau. Đếm số dòng, kiểm vài bản ghi mẫu trước và sau migration để chắc không mất dữ liệu.
4. Review diff bằng subagent. Nhờ một subagent review migration như một PR độc lập, tìm thao tác destructive (DROP, ALTER kiểu dữ liệu) thiếu bước bảo vệ.

Best-practices của Anthropic gói nguyên tắc này trong một câu: "give Claude a way to verify its work" (Claude Code best practices, Anthropic, 2026). Với database, "verify" nghĩa cụ thể là: chạy test, chạy EXPLAIN, và so số hàng trước/sau - chứ không phải tin lời AI nói "đã xong".

Một guardrail đáng lập: dùng permission hook để chặn Claude tự ý ghi vào thư mục migrations/ hoặc chặn lệnh DDL destructive, buộc mọi thay đổi phải qua bạn duyệt. Xem thêm cách siết quyền an toàn ở bài audit bảo mật với Claude Code.

Cạm bẫy thật khi để AI làm database (đọc trước khi lên prod)

Phần này quan trọng nhất và gần như không docs nào nói thẳng. AI làm DB nhanh, nhưng đây là những chỗ nó sai thật sự - mình gặp đủ cả:

• Bịa tên cột/bảng. Claude đôi khi tham chiếu cột không tồn tại vì nó suy đoán schema. Luôn cho nó đọc schema thật (qua MCP hoặc @schema.sql) trước khi viết query.
• Sai kiểu cho tiền. Rất hay dùng float/real cho giá tiền, gây sai số cộng dồn. Bắt buộc numeric/decimal.
• Over-index. Đánh index tràn lan làm chậm ghi mà không tăng đọc đáng kể.
• Migration thiếu rollback. Sinh up mà quên down, khiến bạn kẹt khi cần hoàn tác.
• Query N+1 hoặc full scan. Viết vòng lặp truy vấn từng bản ghi thay vì một JOIN, hoặc quên điều kiện lọc.

Ba nguyên tắc bất di bất dịch: (1) chỉ cấp quyền read-only lên prod - để AI đọc, không cho ghi; (2) mọi thay đổi schema phải qua PR + test, không apply trực tiếp; (3) verify bằng EXPLAIN + so hàng, đừng tin "đã xong". Làm đúng ba điều này thì dùng AI cho DB an toàn hoàn toàn.

Làm nhanh hơn với skill ak-databases (AgentKit)

Nếu bạn thấy phải soạn lại prompt "workload-first, nêu invariant, kèm checklist" mỗi lần thì có một đường tắt trung thực: bộ Engineer Kit của AgentKit (chứa skill ak-databases) đóng gói sẵn đúng backbone trong bài này. Skill ak-databases gồm hướng dẫn thiết kế schema OLTP/OLAP, viết query Postgres/Mongo, aggregation, index, migration, kèm script như db_migrate.py, db_backup.py, db_performance_check.py. Bạn chỉ cần gõ tự nhiên "thiết kế schema cho…" là skill tự kích hoạt, không phải nhớ prompt pattern.

Câu hỏi thường gặp (FAQ)

Claude Code kết nối trực tiếp với database được không?

Được, qua hai đường: MCP server (khuyến nghị, thường ở chế độ read-only) hoặc để Claude chạy lệnh psql/mongosh qua terminal. Khi chưa muốn nối DB thật, bạn có thể dán file schema bằng cú pháp @.

Claude Code có tự chạy query lên production không?

Không nên để nó có quyền đó. Hãy chỉ cấp kết nối read-only lên prod, và giữ mọi thao tác ghi/DDL trên DB dev hoặc qua PR có review. Dùng permission hook để chặn lệnh destructive.

Nên chọn PostgreSQL hay MongoDB?

Chọn theo access pattern, không theo sở thích. PostgreSQL cho giao dịch cần ràng buộc chặt và báo cáo tổng hợp; MongoDB cho dữ liệu lồng nhau đọc/ghi theo cụm. Giao dịch tiền bạc gần như luôn nên là PostgreSQL.

Claude Code viết migration được không?

Được, nhưng phải yêu cầu nó viết cả bước rollback (down), test trên bản sao trước, và so số hàng trước/sau khi chạy. Đừng apply migration do AI sinh thẳng lên prod.

Để AI làm database có an toàn không?

An toàn nếu bạn tuân thủ ba nguyên tắc: read-only lên prod, mọi thay đổi qua PR + test, và verify bằng EXPLAIN ANALYZE + so hàng. Rủi ro thật đến từ việc cấp quyền ghi và tin AI mà không kiểm chứng.

Có bắt buộc phải mua Engineer Kit không?

Không. Toàn bộ quy trình trong bài làm được với Claude Code thuần. Skill ak-databases chỉ giúp nhanh và nhất quán hơn khi bạn làm DB thường xuyên hoặc theo team.

Kết luận và bước tiếp theo

Tóm lại bốn bước: kết nối DB (ưu tiên MCP read-only) → thiết kế schema theo workload → viết và tối ưu query có verify → migration kèm rollback. Chìa khoá không phải là để AI làm hộ mọi thứ, mà là cho nó đủ bối cảnh và luôn có cách tự kiểm chứng. Khi schema đã xong, bước hợp lý tiếp theo là ráp DB vào tầng API - xem bài dùng Claude Code xây backend và API. Còn nếu muốn tăng tốc phần thiết kế DB, có thể dùng thử skill ak-databases trong Engineer Kit.