writing-mysql-migrations
Viết migration MySQL cho Cluvix (golang-migrate, Go + GORM): quy ước timestamp, idempotent ADD/DROP COLUMN, FK constraint thật, decimal tiền, MySQL 9.7 LTS syntax mới/cũ, và luật CẤM tuyệt đối test/migrate chạm DB dev/prod thật. Dùng skill này TRƯỚC KHI tạo file migration mới, sửa schema, thêm cột/FK, backfill dữ liệu, hoặc trước khi chạy `cmd/migrate`/integration test đụng tới database — kể cả migration chỉ 1-2 dòng.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-02
- Stars
- ★ 21
- Forks
- 20
01 前言 Front Matter
- name
- writing-mysql-migrations
- description
- Viết migration MySQL cho Cluvix (golang-migrate, Go + GORM): quy ước timestamp, idempotent ADD/DROP COLUMN, FK constraint thật, decimal tiền, MySQL 9.7 LTS syntax mới/cũ, và luật CẤM tuyệt đối test/migrate chạm DB dev/prod thật. Dùng skill này TRƯỚC KHI tạo file migration mới, sửa schema, thêm cột/FK, backfill dữ liệu, hoặc trước khi chạy `cmd/migrate`/integration test đụng tới database — kể cả migration chỉ 1-2 dòng.
02 资源文件 3
- 参考文档reference/migration-idempotent.md11.2 KB
- 参考文档reference/mysql97.md14.9 KB
- 参考文档reference/upgrade-lts.md6.8 KB
03 SKILL.md 正文
Migration (Go + GORM)
Quy ước timestamp/decimal/FK/template + luật CẤM chạm DB thật nằm ngay trong file này.
reference/migration-idempotent.md— chi tiết pattern idempotent ADD/DROP COLUMN/FK/INDEX.reference/mysql97.md— cú pháp MySQL 9.7 LTS mới dùng được / vẫn cấm / cố ý không dùng.reference/upgrade-lts.md— ghi chép quá trình upgrade lên MySQL 9.7 LTS.
Server đang chạy MySQL 9.7 LTS (dev + prod). Trước khi viết migration, đọc
skill/skills/writing-mysql-migrations/reference/mysql97.mdnếu định dùng cú pháp/tính năng mà file này chưa nói tới — nó ghi rõ cái gì 9.7 mới dùng được (functional unique index,SIGNALtrong procedure, hypergraph), cái gì vẫn không dùng được (ADD COLUMN IF NOT EXISTSvẫnERROR 1064), và cái gì 9.7 cho phép nhưng dự án cố ý cấm (inlineREFERENCESnay tạo FK thật nhưng tên_ibfk_Nphá guard idempotent). Quy ước hằng ngày (timestamp, decimal, FK, template) thì ở ngay file này — không cần đọcmysql97.md.
Tool
golang-migrate:migrate -path migrations/ -database "mysql://..." up- Tool luôn áp DB theo
DB_NAMEtrong.env— verify bằngmysqlcli thủ công phải connect ĐÚNG DB đó, không phải DB nào khác đang mở sẵn (dễ nhầm "chưa lên", "không hit") - Files:
backend/migrations/{timestamp}_{description}.up.sql— CHỈ tạo file.up.sql, KHÔNG tạo.down.sql - Tạo file bằng tay — KHÔNG dùng
-cmd=create: nó vẫn sinh kèm.down.sql(trái rule, phải xoá tay) -cmd=downlà code chết: repo không có.down.sqlnào nênm.Steps(-n)luôn lỗi "file does not exist". Không có đường rollback bằng tool — sai thì viết migration mới bù- Timestamp:
YYYYMMDDHHmmss— 14 ký tự đến giây (VD:20260520150544) - Trước khi tạo:
ls migrations/ | sort | tail -3— timestamp mới phải lớn hơn file mới nhất - Dùng
date +%Y%m%d%H%M%Snếu kết quả lớn hơn file mới nhất; nếu không thì tăng từ file mới nhất - Không dùng số tròn như
130000,000000— dễ trùng - Trước khi
migrate up: chạy lạils migrations | sort | tail -3— nếu có file mới hơn timestamp của mình (agent/session khác vừa tạo+apply song song), phải regenerate timestamp và rename file trước khi apply, nếu khôngmigrate upsẽ báo "không có migration mới" và bỏ qua âm thầm (version DB đã vượt qua timestamp cũ của mình). - Cổng thật là DB, không phải danh sách file:
SELECT MAX(version) FROM schema_migrationstrên DB đích (mỗi DB khách một con số khác nhau).lschỉ thấy file trong checkout của mình — DB có thể đã vượt qua timestamp đó do phiên/máy khác apply. Tên file ≤ version hiện tại ⇒ golang-migrate bỏ qua vĩnh viễn: không lỗi, không cảnh báo, và nếu đó là migration dọn dữ liệu sai thì dữ liệu sai nằm lại mãi. - KHÔNG hỏi được "migration X đã apply chưa" từ
schema_migrations— bảng chỉ có MỘT dòng (version+dirty), không phải nhật ký;WHERE version IN (…)trả 0 KHÔNG có nghĩa chưa apply. Kiểm bằng hiện vật:information_schema.STATISTICS/COLUMNSxem chỉ mục/cột đã tồn tại và đủ cột chưa. - Trước mỗi
-cmd=up: liệt kê file có version >MAX(version)của DB đích để biết chính xác sắp áp gì —-cmd=upáp TẤT CẢ file pending, gồm cả việc dang dở của phiên khác. migrations/(schema mới CRM standalone, story-62): mỗi bảng 1 file20260928093138…_create_<bảng>.up.sql(CREATE TABLE IF NOT EXISTS, idempotent) +…_add_fk_appointment+ 4 file seed2026092809471x_seed_{business_profile,location,lookup,admin}+ migration viết sau đó. KHÔNG còn baseline/squash.- (Lịch sử, bộ ERP cũ — nay nằm ở
backend/migrations_backup/, migrate KHÔNG đọc:00000000000000_baseline+seed_data+fix_json_string_columns+20260814091602_squash_20260406_to_20260814gộp 326 migration. Hai gạch đầu dưới chỉ áp cho DB còn chạy bộ cũ.) - TUYỆT ĐỐI KHÔNG đổi version của file squash.
schema_migrationschỉ giữ MỘT con số: giữ20260814091602→ DB ở headErrNoChange; đổi sang timestamp mới → mọi DB ở head chạy lại toàn dải và chết ở đoạn20260427120000(Error 1054 company_type_id), để lại dirty - File squash KHÔNG idempotent (72/326 migration gốc 04–07/2026 dùng
CREATE TABLEtrần /ADD COLUMNkhông guard) ⇒-auto-recovervô dụng với nó. Provisioning DB mới hỏng giữa chừng →DROP DATABASElàm lại (~25s), KHÔNG force
⛔ CẤM test/migrate chạm DB thật — CATASTROPHIC (bài học 2026-07-18)
Sự cố: trong 1 session BMAD dài fan-out nhiều subagent tự verify integration test, DB dev thật của 1 khách (DB_NAME trong .env) bị wipe sạch về baseline (mất toàn bộ bảng + data) rồi kẹt schema_migrations dirty ở version 1 (chết khi apply seed_data.up.sql), chặn toàn bộ ~250 migration sau. Không dựng lại được thủ phạm chính xác vì migrate stderr không được log.
Nguyên nhân gốc (3 lớp, không phải 1 lệnh đơn):
testhelpers.New(internal/testhelpers/suite.go) gọidropAllTables=DROP TABLEMỌI bảng trong DB màTEST_MYSQL_DSNtrỏ tới. Trỏ nhầm vào DB thật = mất sạch data ngay, không undo.seed_data.up.sqlKHÔNG idempotent (raw dumpINSERT INTO ... VALUES(id cố định)) → chạy lại lên DB đã có data → dup-key → migrate dirty → chặn deploy.- Plan/story ghi thẳng tên DB dev thật (
DB_NAMEtrong .env) làm target verify backfill → cấp "giấy phép" cho agent trỏ migrate/test vào DB thật. Cộng root creds trong memory + fan-out cô lập, mỗi subagent tự tạo DB → không ai đặt guard.
LUẬT (áp cho MỌI agent, kể cả fix nhỏ):
- Integration test /
testhelpers.New/cmd/migratekhi verify CHỈ chạy trên DB dùng-một-lần (CREATE DATABASE ..._test/_tmpđầu →DROPcuối). TUYỆT ĐỐI KHÔNG trỏTEST_MYSQL_DSNhay-dbvàoDB_NAME(DB dev/prod thật). - Plan/story KHÔNG BAO GIỜ ghi tên DB thật làm target verify. Cần data thật để kiểm backfill → clone:
CREATE DATABASE cluvix_verify_tmp+ nạp dump → verify →DROP. Không đụng bản thật. - Mọi migration idempotent — kể cả seed:
INSERT IGNORE/ON DUPLICATE KEY UPDATE, không rawINSERTid cố định (xem mục Idempotent bên dưới). - Guard code đã cài (lưới cuối, KHÔNG thay kỷ luật):
testhelpers.Newfatal nếu DB trong DSN ==DB_NAME;seed_datađãINSERT IGNORE;cmd/migrateforce/downcần-confirm.-auto-recoverKHÔNG cần-confirm— là flag opt-in tường minh cho deploy tự phục hồi dirty-state chạy nền; bắt-confirmsẽ phá pipeline deploy (regression 2026-07-18).
Nếu chuyện này xảy ra trên PRODUCTION (mô hình DB-per-customer):
- Mất toàn bộ dữ liệu 1 khách hàng ngay lập tức:
dropAllTablesxóa mọi bảng của DB đó — customer, hóa đơn, bệnh án EMR, sổ kế toán, bảng lương — không có undo tầng app. Blast radius = trọn 1 khách (không leak cross-tenant nhưng khách đó mất sạch). Nếu script "migrate all tenants" loop qua mọi DB → mất TẤT CẢ khách. - Migration dirty = outage: app không boot / deploy kế bị chặn cho tới khi có người xử tay
force. - Không backup = mất vĩnh viễn; có backup thì vẫn mất phần data từ mốc backup gần nhất (RPO gap).
- Bắt buộc trước khi bất cứ thứ gì chạm gần prod: (a) creds/network test tách hẳn prod — code test không thể mở nổi connection tới prod; (b) backup tự động + đã test restore (binlog/PITR); (c) migration idempotent + cổng dry-run staging; (d)
dropAllTableschỉ chạy được trên DB tên*_test. GuardDB_NAME-equality ở trên là điều kiện cần tối thiểu, chưa đủ cho prod.
Decimal columns
- Số tiền lớn (payment, revenue, debt):
decimal(20,2) - Số tiền nhỏ/giá thuốc/giá vật tư:
decimal(15,2) - Lương:
decimal(15,0) - Phần trăm/tỷ lệ:
decimal(5,2) - Chỉ số sinh tồn (BMI, cân nặng):
decimal(5,2) - Ngày công/giờ:
decimal(5,1)hoặcdecimal(6,1) - KHÔNG dùng
floathaydoublecho tiền
GORM tag phải khớp migration
// Tiền/decimal: decimal.Decimal (shopspring), KHÔNG float64
Amount decimal.Decimal `gorm:"type:decimal(20,2);not null;default:0.00" json:"amount"`
ImportPrice *decimal.Decimal `gorm:"column:import_price;type:decimal(15,2);default:0.00" json:"import_price"`
Percentage *decimal.Decimal `gorm:"type:decimal(5,2)" json:"percentage"`
Column conventions
- FK nullable:
INT NULL+INDEX+FOREIGN KEY ... ON DELETE SET NULL(hoặcRESTRICTnếu business không cho phép mất tham chiếu) - FK not null:
INT NOT NULL+INDEX+FOREIGN KEY ... ON DELETE RESTRICT(mặc định — không cho xóa parent khi còn con; chỉ dùngCASCADEkhi đã xác nhận business muốn xóa dây chuyền) - Timestamp:
BIGINT(Unix), KHÔNGDATETIME - JSON:
JSONtype, KHÔNGTEXT - String có giới hạn:
VARCHAR(n), KHÔNGTEXTtrừ khi cần created_at,updated_at:BIGINT(Unix)status:TINYINT(1) DEFAULT 1- KHÔNG thêm cột
version— optimistic lock theoupdated_at(D6/D21, tập bảng ởpkg/optlock) sort_order:INT DEFAULT 0branch_id:INT+INDEX+ FK tớibranch(NULL = dùng chung mọi chi nhánh — Hard Rules). KHÔNG còn cộtcompany_id(D15/story-62: 1 thương hiệu/DB).
FK phải khớp signed/unsigned với id bảng cha (Error 3780)
- Kiểu cột FK PHẢI khớp CHÍNH XÁC signed/unsigned với id bảng cha — lệch → MySQL Error 3780 khi ADD FK, chặn toàn chuỗi migrate.
- Schema hiện tại:
idcác bảng cha (appointment,customer,branch,user…) làintSIGNED; bảng mới hay quen tayint unsigned→ kiểm trước:grep -m1 '\id`' migrations/*create<bảng cha>.up.sql`. - Kiểm ĐỦ mọi cột FK trong file (kể cả
measured_by/created_by) — sót 1 cột vẫn chặn migrate.
CREATE VIEW phải khai DEFINER tường minh
CREATE [OR REPLACE] VIEW thiếu DEFINER → MySQL tự gán definer = user chạy migration lúc tạo lần đầu. Máy/DB khác không có đúng user đó → mọi SELECT qua view lỗi Error 1449 (HY000): The user specified as a definer ... does not exist. Luôn khai CREATE OR REPLACE DEFINER=CURRENT_USER VIEW ... (không hardcode username, chạy đúng trên mọi máy).
Template up.sql
CREATE TABLE `table_name` (
`id` int unsigned NOT NULL AUTO_INCREMENT,
`branch_id` int DEFAULT NULL COMMENT 'Chi nhánh (NULL = dùng chung)',
`category_id` int unsigned DEFAULT NULL COMMENT 'FK ví dụ — tham chiếu bảng khác',
`status` tinyint(1) DEFAULT '1',
`amount` decimal(20,2) NOT NULL DEFAULT '0.00' COMMENT 'Số tiền',
`note` text COMMENT 'Ghi chú',
`created_at` bigint DEFAULT NULL,
`updated_at` bigint DEFAULT NULL,
`created_by` int DEFAULT NULL,
`updated_by` int DEFAULT NULL,
PRIMARY KEY (`id`),
KEY `idx_branch_id` (`branch_id`),
KEY `idx_category_id` (`category_id`),
CONSTRAINT `fk-table_name-branch_id` FOREIGN KEY (`branch_id`) REFERENCES `branch` (`id`) ON DELETE RESTRICT ON UPDATE CASCADE,
CONSTRAINT `fk-table_name-category_id` FOREIGN KEY (`category_id`) REFERENCES `category` (`id`) ON DELETE RESTRICT ON UPDATE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
FOREIGN KEY bắt buộc cho mọi cột tham chiếu bảng khác (CRITICAL)
Mọi cột dạng xxx_id tham chiếu tới 1 row cụ thể ở bảng khác — kể cả self-reference (parent_id) — PHẢI có FOREIGN KEY thật trong CREATE TABLE (không chỉ KEY/INDEX). Áp dụng CẢ branch_id (schema mới story-62: các bảng có branch_id như customer, appointment… đều có FK tới branch; branch_id NULL = dùng chung — FK cho phép NULL). Ngoại lệ DUY NHẤT: created_by/updated_by (xem CLAUDE.md). (Ngoại lệ company_id cũ đã bỏ cùng cột, D15.)
Lý do (CRITICAL — không phải style, là bug thật): models.DeleteWithCheck (internal/models/base.go) — cơ chế DUY NHẤT chặn xóa record đang bị bảng khác tham chiếu — chỉ đơn giản DELETE rồi bắt lỗi MySQL 1451 (FK violation). Bảng thiếu FK thật → hàm này không có gì để bắt lỗi → xóa "thành công" nhưng để lại con mồ côi (con vẫn giữ id đã bị xóa, không báo lỗi ở đâu cả). Case thật: payment.cash_flow_category_id tham chiếu cash_flow_category.id không có FK — phát hiện 2026-07-12.
Chọn ON DELETE:
RESTRICT(mặc định) — không cho xóa parent khi còn con, đúng nghĩaDeleteWithCheckđang cố làm.SET NULL— chỉ khi cột nullable và business chấp nhận con "mất tham chiếu" khi cha bị xóa (vd optional category).CASCADE— chỉ khi đã xác nhận rõ business muốn xóa dây chuyền (hiếm, rủi ro cao — cân nhắc kỹ trước khi dùng).
Bảng đã có data: trước khi ADD FOREIGN KEY (ALTER trên bảng cũ, xem pattern "Add FK nếu chưa tồn tại" ở phần Idempotent bên dưới) — BẮT BUỘC query check orphan trước:
SELECT COUNT(*) FROM child_table c
LEFT JOIN parent_table p ON c.parent_id = p.id
WHERE c.parent_id IS NOT NULL AND p.id IS NULL;
Có orphan → xử lý theo business (SET NULL hàng loạt / gán lại parent hợp lệ) trong CÙNG migration, TRƯỚC statement ADD CONSTRAINT — nếu không ADD FOREIGN KEY sẽ fail ngay khi migrate.
- ⚠
ADD FOREIGN KEYkhiFOREIGN_KEY_CHECKS=1= thuật toán COPY ⇒ chặn ghi cả bảng suốt thời gian chép (153k dòng: 24s). Dữ liệu đã chắc sạch (vừa dọn orphan ngay trước trong cùng file, hoặc cột vốn có FK tới đúng bảng cha) ⇒ bọc riêng lệnh ADD:SET @old_fkc = @@SESSION.FOREIGN_KEY_CHECKS; SET SESSION FOREIGN_KEY_CHECKS = 0;…SET SESSION FOREIGN_KEY_CHECKS = @old_fkc;⇒ INPLACE 0.02s. Chưa dọn orphan thì cấm — MySQL không kiểm dữ liệu cũ. - Backfill
UPDATE … JOINbảng lớn:SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED(không khoá đọc dòng bảng được JOIN); lưu@@SESSION.transaction_isolationđầu file, trả lại cuối file.
Bỏ index thừa kiểu tiền-tố-trái — phải THỬ, không được suy luận
Index có tập cột là tiền tố trái của một index khác trên cùng bảng thì bỏ được, kể cả khi nó đang đỡ FOREIGN KEY (MySQL chấp nhận index có cột FK làm tiền tố trái). Đã bỏ 50 index như vậy ở 20260906114555 — 0 FK và 0 UNIQUE bị đụng. Loại bỏ mọi index UNIQUE khỏi danh sách: bỏ index unique là mất ràng buộc duy nhất, không phải tối ưu.
Ba cái bẫy, cả ba đều cho kết luận SAI mà không báo lỗi:
GROUP_CONCAT(COLUMN_NAME)trêninformation_schema.STATISTICSBỎ QUA NULL. Index biểu thức (functional index) cóCOLUMN_NAME = NULLnên các cột biểu thức tàng hình, khiến index trông như bắt đầu bằng cột khác ⇒ kết luận "tiền tố trái" sai ⇒ERROR 1553 … needed in a foreign key constraintlúc drop. Câu quét PHẢI loại index cóSUM(COLUMN_NAME IS NULL) > 0ở CẢ hai vế.- "Tiền tố trái ⇒ chắc chắn drop được" là suy luận. Chốt danh sách bằng cách thử drop TỪNG CÁI trên DB dùng-một-lần rồi chỉ giữ cái thành công.
- ⚠ "Drop được" ≠ "nên drop" — phép thử trên chỉ đo FK, KHÔNG đo hiệu năng. InnoDB nối PK vào đuôi mọi chỉ mục phụ, nên
(company_id)thực chất là(company_id, id)và phục vụORDER BY id DESCmiễn phí; bỏ nó đo được phân trang sâu 869ms → 4.793ms. Chỉ mục một cột dẫn đầu bằng cột scope (nay làbranch_id; số đo gốc làm trêncompany_idtrước D15) trên bảng list lớn ⇒ giữ, và ghi lý do ngay trong migration để lần quét sau không bỏ lại. Số đo + cách bench:../debugging-backend-queries/reference/perf-list-endpoints.md§"Đừng bỏ chỉ mục một cột(company_id)". group_concat_max_lenmặc định 1024 làm script đối chứng cắt cụt danh sách id ⇒ báo lệch giả. Nâng ở đầu phiên đo.
Chi phí đáng bỏ: một bảng từng mang index 231MB trên data 48MB (gấp 4.8 lần) vì 32 index — mỗi INSERT ghi từng ấy entry, và index không nhét vừa innodb_buffer_pool_size.
Backfill phải khớp TỪNG guard của runtime, không khớp bản mô tả
Runtime luôn có điều kiện NGẦM mà bản mô tả bằng lời không nêu. Backfill viết theo lời ("tin staff sớm nhất") nghe đúng mà quy kết sai — không lỗi, không cảnh báo.
- AC của story backfill phải trích thẳng câu persist (
file:dòng); reviewer đối chiếuWHEREcủa backfill với từng guard runtime, không đối chiếu với câu mô tả. - Sự cố 2026-08-20 (
omi_conversation.first_responder_id): runtime chỉ quy kết sau khi gửi THÀNH CÔNG và không tính tin chiến dịch — 2 điều kiện không ai viết ra. Backfill thiếu cả 2 ⇒ 3/6 hội thoại trên DB dev quy kết bằng tinstatus=1(gửi lỗi). Lọt qua Dev lẫn SM, chỉ lộ khi QA đọc code persist thay vì đọc mô tả. - Cùng lớp: tin của nhiều luồng khác nhau có thể trùng
src/created_by/status— trước khi tin vào một cột phân biệt, duyệt mọi điểm dựng row trong code sản phẩm rồi ghi lại kết luận.
Verify migration trên DB tạm — clone schema THẬT, không tự gõ lại bảng cha
- Dựng DB dùng-một-lần bằng
mysqldump --no-datatừ DB dev, KHÔNG tựCREATE TABLElại bảng cha rút gọn. - Bảng cha tự gõ luôn permissive hơn thật (thiếu NOT NULL/UNIQUE/kiểu cột lệch) → migration "pass" trên DB tạm rồi fail lúc chạy thật.
- Apply file migration 2 lần liên tiếp để nghiệm thu idempotent; drop DB tạm ngay sau khi xong.
- ⚠ Bảng có chỉ mục FULLTEXT thì clone bằng
mysqldumpCHƯA XONG ở bước nạp schema. Dump chỉ chép lại định nghĩa index; nạp vào DB tạm là nó được dựng lại dưới@@GLOBAL.innodb_ft_enable_stopword(mặc định = 1), trong khi migration thật dựng nó vớiSET SESSION … = OFF. Hệ quả: DB tạm tìm kiếm sót âm thầm — 2026-09-07 một bench báo bản vá đúng là "sót 1.088–2.744 dòng", suýt loại nhầm. Phải dựng lại FULLTEXT trong DB tạm cho đúng rồi đối chứngMATCH=LIKEvới DB thật TRƯỚC khi tin bất kỳ số nào. Quy trình dựng đúng (phải DROP HẾT fulltext trên bảng, không chỉ một cái):../debugging-backend-queries/reference/patterns-gotchas.md§"Chỉ mục ngram dựng sai stopword". - Viết migration tạo mới FULLTEXT ⇒ đọc mục đó TRƯỚC: stopword gắn theo BẢNG (cố định bởi index
FULLTEXT đầu tiên),
SET GLOBALKHÔNG ăn, và chỉ mục dựng sai làm tìm kiếm sai mà không ném lỗi. - ⚠ Đặt file vào
migrations/= APPLY LUÔN lên DB dev:airchạyrun_dev.sh→migrate upvài giây sau khi file xuất hiện, không hỏi gì. Migration nặng/khoá bảng (ADD FULLTEXT,ALTERbảng lớn) phải soạn và verify ởbackend/tmp/TRƯỚC, chỉ chuyển vàomigrations/khi đã đạt trên DB dùng-một-lần. Số đo để lập cửa sổ bảo trì:ADD FULLTEXT … WITH PARSER ngramtrên cột TEXT tự do dài = 3 phút 06 giây / 524k dòng, gấp ~4 lần mốc ~42,7s của cột ngắn — nhân theo số khách vì DB-per-customer. Giảm rủi ro: code gọiMATCHphải tự lùi vềLIKEkhi gặp lỗi 1191, nhờ đó endpoint không vỡ trong lúcALTERchạy và thứ tự apply không quan trọng.
Idempotent migrations (CRITICAL)
→ migration-idempotent.md — PREPARE/EXECUTE, CREATE PROCEDURE, INFORMATION_SCHEMA lookup,
NOT NULL + FK, golang-migrate gotchas, auto-recovery dirty state.
Lưu ý
- KHÔNG dùng
AutoMigratecho production - GORM tag
type:decimal(x,y)phải khớp migration - Sau thêm decimal column vào bảng dùng
map[string]interface{}: query thủ công.Find(&rows)phải gọihelpers.ParseDecimalFields(row, "field")thủ công - Schema gốc:
backend/migrations/<timestamp>_create_<bảng>.up.sql(không còn file baseline — bản ERP cũ ởmigrations_backup/, migrate không đọc)
UNIQUE KEY + NULL column — dùng sentinel 0, không NULL (CRITICAL)
UNIQUE KEY (template_type, branch_id) với branch_id NULL → MySQL cho phép nhiều row vì NULL ≠ NULL → ON CONFLICT không trigger → duplicate records âm thầm.
-- ❌ NEVER
branch_id BIGINT UNSIGNED NULL
UNIQUE KEY uq (template_type, branch_id) -- nhiều row (X, NULL) được phép
-- ✅ ALWAYS — sentinel 0 = mẫu chung toàn thương hiệu (vd print_templates.branch_id)
branch_id BIGINT UNSIGNED NOT NULL DEFAULT 0
UNIQUE KEY uq (template_type, branch_id) -- (X, 0) enforce unique
Migration chuyển NULL → sentinel 0:
UPDATE table SET branch_id = 0 WHERE branch_id IS NULL;
ALTER TABLE table MODIFY branch_id BIGINT UNSIGNED NOT NULL DEFAULT 0;
-- ADD UNIQUE KEY nếu chưa có
Query: WHERE branch_id = 0 thay vì WHERE branch_id IS NULL.
Fallback (branch → mẫu chung toàn thương hiệu; trước D15 gọi là company-level): WHERE branch_id IN (?, 0) ORDER BY branch_id DESC LIMIT 1.
Ngoại lệ — cột PHẢI giữ NULL (có FOREIGN KEY thật: sentinel 0 vỡ FK vì không có row id=0): dùng functional key part (MySQL ≥ 8.0.13):
ALTER TABLE account_balance ADD UNIQUE KEY uq_ab ((COALESCE(customer_id, 0)), account_id, period);
Dedupe dữ liệu trước khi ADD — xem section "Đổi unique key trên bảng có dữ liệu". Đã áp (ERP, bảng kế toán — đã bỏ cùng D2/D15): uq_account_balance_dim0, uq_coa_company_code.
Chiều NGƯỢC lại — cột CỐ Ý giữ NULL để UNIQUE cho phép nhiều row: phải chuẩn hoá '' → NULL TRƯỚC khi ADD UNIQUE. MySQL coi chuỗi rỗng là một GIÁ TRỊ, nên nhiều NULL thì hợp lệ còn nhiều '' là Error 1062. Code ghi NULL không có nghĩa dữ liệu cũ/seed cũng NULL.
UPDATE t SET col = NULL WHERE col = ''; -- idempotent, chạy TRƯỚC
-- rồi mới ADD UNIQUE KEY (col)
Ca biên của một ràng buộc UNIQUE phải phủ cả hai biểu diễn "không có giá trị" (NULL và '') — thử mỗi NULL rồi kết luận an toàn là bỏ lọt. Thật (2026-08-31, meta_page_config.ig_business_account_id): verify chỉ thử NULL nên pass, tới khi test khác seed '' mới lộ; nếu lọt lên DB khách thì migration fail và chặn cả đợt deploy.
Atomic counter upsert — cột cộng dồn (balance/counter)
- KHÔNG
First → Savecho cột cộng dồn — read-modify-write bị lost-update khi 2 request song song. Chuẩn: UPDATE tăng trực tiếp →RowsAffected == 0→ INSERT → INSERT dính 1062 (thua đua) → retry UPDATE lần cuối. - MySQL đánh giá
SETtrái→phải: cột dẫn xuất đặt SAU dùng giá trị MỚI của các cột trước.
UPDATE account_balance
SET debit_total = debit_total + ?, credit_total = credit_total + ?,
closing = IF(? = 2, credit_total - debit_total, debit_total - credit_total) -- đã là giá trị MỚI
WHERE ...;
- Nhánh INSERT cần unique index backstop (cột nullable → functional key part, xem section trên). Mẫu Go:
engine.ApplyBalanceDelta(accountant/ledger/engine).
GORM Raw Query — args ordering (CRITICAL)
? placeholder được bind theo thứ tự xuất hiện trong SQL string, từ trên xuống, trái sang phải — kể cả trong SELECT clause.
// ❌ SAI — tưởng WHERE trước, CASE WHEN sau
args = append(args, consultTypeIDs, from, to, CheckedIn, CheckedOut, IsAccepted)
// ✅ ĐÚNG — CASE WHEN trong SELECT xuất hiện TRƯỚC WHERE trong SQL
args = append(args,
CheckedIn, CheckedOut, // CASE WHEN a.status IN (?,?) ← ở SELECT
IsAccepted, // CASE WHEN a.is_accepted = ? ← ở SELECT
consultTypeIDs, from, to) // WHERE type IN ?, BETWEEN ? AND ? ← ở WHERE
- Subquery lồng nhau: args của subquery phía trên được bind trước subquery phía dưới
IN ?với[]intslice: GORM tự expand thành(1,2,3)— không cần làm thủ côngIN ?với empty slice[]int{}: GORM sinhIN (NULL)— query không lỗi nhưng không match row nào
Đổi unique key trên bảng có dữ liệu
- golang-migrate chạy MỌI migration pending liên tiếp trong 1 lần
-cmd=up— KHÔNG thiết kế "migration A → script ngoài → migration B"; backfill bằng SQL thuần (REPLACE/UPPERlồng nhau đủ mạnh) trong CÙNG file. - Trước
ADD UNIQUE KEY: bắt buộc dedupe dữ liệu hiện có bằng SQL (giữMIN(id), row trùng đổi giá trị hậu tố_DUP<id>— không xóa cứng); bỏ sót → constraint fail → dirty state block deploy.
(đã bỏ, D15) Seed bảng scope theo company — per-company, không anchor 1 company duy nhất
Lịch sử: bảng
company+ cộtcompany_idkhông còn (1 thương hiệu/DB). Seed nay chỉ cần idempotentWHERE NOT EXISTS/INSERT IGNOREtrong phạm vi 1 DB (Hard Rules); bài học còn giá trị: đừng neo seed vào 1 dòngMIN(id)của bảng cha khi bảng cha có thể có nhiều dòng (vdbranch).
(Lịch sử, D15) Seed config_code (hay bảng nào cần 1 row/company_id) KHÔNG dùng SELECT MIN(id) FROM company làm anchor — chỉ seed đúng 1 company, DB nhiều company (multi-brand cùng 1 khách) sẽ có company thiếu row, rơi vào fallback "bất kể company" sai tenant.
-- (lịch sử, D15) ❌ SAI — chỉ seed company nhỏ nhất
INSERT INTO config_code (company_id, ...) SELECT (SELECT MIN(id) FROM company), ... -- (lịch sử, D15)
WHERE NOT EXISTS (SELECT 1 FROM config_code WHERE parent_table = 'service');
-- ✅ ĐÚNG — seed đủ mọi company
INSERT INTO config_code (company_id, ...) -- (lịch sử, D15)
SELECT c.id, ... FROM company c
WHERE NOT EXISTS (SELECT 1 FROM config_code WHERE parent_table = 'service' AND company_id = c.id); -- (lịch sử, D15)
- Cột nhận hậu tố dedupe phải khai đủ rộng (vd VARCHAR(20) thay vì VARCHAR(10)) — strict mode nổ
Data too longngay trong migration.
Kiểm "đã seed chưa" — dò theo KHOÁ SEED, KHÔNG theo id
Audit "record X đã có migration seed chưa" phải dò theo khoá seed thật (name, key, handler_key), KHÔNG theo id.
INSERT IGNORE INTO t (name, ...) không có cột id ⇒ mọi phép dò dựa trên id mù hoàn toàn: con số id không xuất hiện ở bất kỳ đâu trong file migration.
id là AUTO_INCREMENT ⇒ không ổn định giữa các DB khách — cùng câu seed cho id 41 ở DB này, 45 ở DB khác.
INSERT IGNORE trùng khoá im lặng không làm gì ⇒ "chạy 2 lượt mà giá trị không đổi" KHÔNG phân biệt được idempotent với câu lệnh chưa bao giờ chạy; xoá dòng rồi chạy lại để chứng minh lệnh có tác dụng.
Data-fix cột JSON array — additive, idempotent
Thêm phần tử vào cột JSON array (vd departmentList) để gỡ chặn nghiệp vụ: dùng
JSON_ARRAY_APPEND bọc NOT JSON_CONTAINS — chạy lại không double-add, không đụng phần tử cũ.
UPDATE t SET col = JSON_ARRAY_APPEND(col, '$', <value>)
WHERE id = ? AND NOT JSON_CONTAINS(col, '<value>');
UNION ALL bảng cũ + bảng mới → MySQL 1271 "Illegal mix of collations"
Bảng cũ không khai COLLATE tường minh kế thừa collation mặc định server; bảng mới khai rõ
(vd utf8mb4_unicode_ci) → UNION ALL 2 nhánh lẫn collation khác nhau, lỗi CHỈ lộ khi chạy
query thật (không phải lỗi Go/build). Fix: ép COLLATE utf8mb4_unicode_ci tường minh trên
MỌI cột string (kể cả literal) ở TẤT CẢ nhánh UNION, không chỉ nhánh mới.
KHÔNG SET col = '[...]' ghi đè nguyên mảng — mất phần tử cũ nếu tính base sai.
Cột SINH (generated column) + khoá ngoại: phải VIRTUAL, KHÔNG STORED
Đo thật trên MySQL 9.7.1 (2026-08-25, omi_message_reaction): MySQL từ chối MỌI FOREIGN KEY
đặt trên cột nền của một generated column STORED — thử đủ 3 tổ hợp
ON DELETE SET NULL/CASCADE × ON UPDATE CASCADE/RESTRICT, tất cả đều ERROR 1215 (HY000): Cannot add foreign key constraint. Cùng biểu thức đó để VIRTUAL thì FK tạo được bình thường, và UNIQUE
trên cột ảo VẪN chặn trùng thật (ERROR 1062) — InnoDB cho phép index phụ trên cột ảo.
Vì sao dễ mất thời gian ở đây: lỗi 1215 không nói cột nào gây ra, và SHOW ENGINE INNODB STATUS
trên MySQL 9.x không còn khối LATEST FOREIGN KEY ERROR. Cách chẩn đoán nhanh: tạo bảng thử với
từng FK riêng lẻ (đều chạy được) rồi thêm cột sinh vào → lộ ngay thủ phạm.
Khi nào cần cột sinh: MySQL KHÔNG có partial/filtered index. Muốn một UNIQUE phủ hai loại chủ
thể loại trừ nhau (vd người thả cảm xúc: nhân viên nội bộ có FK user_id ↔ khách chỉ có chuỗi uid),
hội tụ chúng về một cột sinh rồi UNIQUE trên đó:
reactor_key VARCHAR(120) GENERATED ALWAYS AS (IF(user_id IS NULL, channel_uid, CONCAT('u:', user_id))) VIRTUAL
⚠ Tiền tố (u:) là bắt buộc — thiếu nó thì user_id = 123 và channel_uid = "123" đụng nhau.
Entity GORM: cột sinh phải gorm:"->" (chỉ đọc). Thiếu tag ⇒ GORM đưa cột vào INSERT ⇒ mọi
Create lỗi, và chỉ lộ ra khi có code thật dùng entity (tức là muộn).
⚠ Ghi file vào migrations/ = ĐÃ APPLY lên DB dev trong vài giây (đo 2026-09-08)
backend/scripts/run_dev.sh chạy migrate up mỗi lần air rebuild, và air rebuild ngay khi có
file mới. Nghĩa là: không có bước "viết xong rồi mới quyết định chạy" — vừa Write file
.up.sql là nó đã chạy trên DB dev thật, trước khi kịp verify trên DB dùng-một-lần.
Bằng chứng (backend/tmp/run.log):
[16:33:36] run_dev.sh: migrate OK — migrate up: không có migration mới (version 20260908155444)
[16:36:43] run_dev.sh: migrate OK — migrate up: 20260908155444 → 20260908163530 thành công
File 20260908163530_*.up.sql được ghi lúc 16:36 và tự apply lúc 16:36:44.
Hệ quả bắt buộc nhớ:
- Verify TRƯỚC khi ghi vào
migrations/. Soạn nội dung ở scratchpad của phiên, chạy thử trên DB*_tmp(2 lần cho idempotency + 1 lần trên DB có dữ liệu vi phạm để xem cổng chặn có fail thật không), rồi mớiWritevàomigrations/. Làm ngược lại thì DB dev là nơi thử nghiệm đầu tiên — đúng thứ luật ⛔ đầu file này cấm. - Migration hỏng ⇒
dirty=1và dev server của user chết cho tới khi có người dọn tay. KiểmSELECT dirty, version FROM schema_migrationssau khi ghi file. - Sửa nội dung một migration ĐÃ apply thì DB dev không chạy lại (golang-migrate chỉ nhớ version, không có checksum) — nhưng DB khách khác sẽ nhận bản MỚI. Chỉ sửa khi nội dung mới tương đương về ngữ nghĩa, và phải verify lại bản mới trên DB dùng-một-lần.
Rẽ nhánh có điều kiện: cách bắt migration DỪNG với thông báo đọc được
Cổng kiểm dữ liệu (vd "còn bản sao thì đừng thêm UNIQUE") mà chỉ IF NOT EXISTS rồi im lặng không
tạo sẽ báo thành công trên DB vẫn còn lỗ hổng — xanh giả. Phải fail thật.
SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = '…'cho thông báo đẹp nhất và chạy được ngoài stored program, NHƯNG không dùng được ở đây:ERROR 1295 … not supported in the prepared statement protocol. MàPREPARE/EXECUTElại là cách duy nhất để rẽ nhánh có điều kiện trong file.sqlkhông có stored program. Đã đo cả hai chiều 2026-09-08.- Cách còn lại: tham chiếu một bảng không tồn tại mà TÊN chính là thông báo:
'SELECT 1 FROM \MIGRATION_ABORT_duplicate_customer_id_in_customer_warranty_code`'⇒ERROR 1146 … Table 'db.migration_abort_duplicate_customer_id_in_customer_warranty_code' doesn't exist`, exit code 1, và các câu lệnh sau KHÔNG chạy. Tên ≤64 ký tự (giới hạn identifier).
⚠ Khi kiểm exit code trong shell: mysql … | grep -v "Using a password" trả exit code của grep,
không phải của mysql. Đo đúng phải bỏ pipe (mysql … > /dev/null 2>&1; echo $?) hoặc đọc
PIPESTATUS. Đã suýt kết luận "cổng chặn không fail" vì đọc nhầm số 0 của grep.
⚠ Cùng nguyên nhân, hậu quả khác: mysql … | grep -v "Using a password" && <lệnh kế> — không dòng
nào lọt qua grep ⇒ exit 1 ⇒ lệnh kế bị bỏ qua im lặng. Nối nhiều bước DB thì tách từng lệnh
riêng, và luôn SELECT COUNT(*) xác nhận bước trước đã ghi được dữ liệu.
Thứ tự bắt buộc khi đổi chỉ mục mà FK đang dựa vào
ALTER TABLE … DROP INDEX trên cột có FOREIGN KEY sẽ bị MySQL từ chối
(ERROR 1553 … needed in a foreign key constraint) nếu không còn chỉ mục nào khác đỡ FK. Nên khi
thay chỉ mục thường bằng UNIQUE trên CÙNG cột: ADD UNIQUE trước, DROP index thường sau — thứ tự
ngược lại fail. Kiểm sau khi chạy: FK phải còn trong information_schema.KEY_COLUMN_USAGE.
04 同仓库更多 Skills
writing-backend-resources
Hướng dẫn quy trình 6 bước TẠO MỚI resource backend Go (entity, dao, repository, service, handler, router, DTO, module layout) cho ERP Cluvix. Dùng skill này TRƯỚC KHI tạo resource CRUD mới hoặc module mới trong internal/modules/, khi cần biết Handler DI/Router/Repository Reader/DTO pattern chuẩn, hoặc trước khi đụng module service (status filter 2 tầng, cascade, optimistic lock). KHÔNG dùng skill này để debug/sửa query đang sai — xem debugging-backend-queries cho việc đó.
working-on-ops
Hướng dẫn nghiệp vụ dashboard CRM, export, và import dữ liệu trong module ops của backend Cluvix. Dùng skill này KHI đụng report/dashboard CRM, thêm cột export (`?columns=`), hoặc import khách hàng (migration onboard SAAS client) — đọc trước khi đổi bất kỳ hành vi nào trong các luồng này.
working-on-hr
Quy tắc và pattern nghiệp vụ HR Cluvix trong CRM standalone: user nội bộ, role/RBAC, đổi/đặt lại mật khẩu, import user. Dùng skill này KHI làm feature/sửa bug đụng module hr (chỉ còn `hr/user`) — trước khi đọc code.
working-on-crm
Quy tắc và pattern nghiệp vụ CRM Cluvix: khách hàng, lịch hẹn, liệu trình, đơn hàng, thanh toán. Dùng skill này KHI làm feature/sửa bug đụng module crm (customer, appointment, order, treatment, payment) — trước khi đọc code, để tránh phá vỡ business rule đã có (tái khai thác, customer status IN(...)).
working-on-config
Quy tắc và pattern nghiệp vụ Config Cluvix còn sống trong CRM standalone: mẫu in (print_template), control field trong bảng (control_field_in_table), IndexedDB sync của config. Dùng skill này KHI làm feature/sửa bug đụng các module đó — trước khi đọc code. Tổng đài/chữ ký số/AI config đã bỏ (chỉ còn mô tả lịch sử trong skill, KHÔNG áp dụng).
testing-backend
Hạ tầng test Go: unit test, integration test với TEST_MYSQL_DSN (MySQL disposable thật, KHÔNG dockertest), FreshTenant helper, HTTP handler test qua httptest, và mutation test (`go test -overlay`) để chứng minh test thật sự neo hành vi. Dùng skill này TRƯỚC KHI viết test mới cho backend Go, khi cần biết cách dựng DB test sạch mỗi lần chạy, trước khi báo một AC dạng phủ định/mặc định là Done, hoặc trước khi verify build/test theo Development Protocol bước 4 (Validate).