database-migration

Tổng quan về skill database-migration

Skill database-migration giúp bạn làm được gì

Skill database-migration dùng để lập kế hoạch và tạo các thay đổi migration cho schema cũng như dữ liệu cơ sở dữ liệu trong những quy trình ORM và SQL phổ biến, với trọng tâm đặc biệt vào khả năng rollback an toàn và triển khai zero-downtime. Skill này hữu ích nhất khi bạn cần nhiều hơn một prompt kiểu chung chung như “write a migration”; ví dụ khi thay đổi tác động đến dữ liệu production đang chạy, cần triển khai theo nhiều giai đoạn, hoặc phải bám theo một framework migration cụ thể như Sequelize hay TypeORM.

Ai nên dùng skill database-migration này

Nhóm phù hợp nhất là các team Database Engineering, backend engineer, platform engineer và developer dùng AI hỗ trợ nhưng vẫn cần đầu ra migration có tính vận hành thực tế, chứ không chỉ đúng cú pháp. Nếu bạn đang sửa bảng, backfill dữ liệu, đổi tên cột theo cách an toàn, hoặc chuyển giữa các pattern ORM, skill này cho model một khung làm việc mặc định mạnh hơn nhiều so với prompt trống.

Job-to-be-done mà skill này làm tốt nhất

Hãy dùng database-migration khi công việc thực sự của bạn là tạo ra một kế hoạch migration có thể đem đi chạy được: file migration, các bước rollout theo pha, phương án rollback và những điểm cần tính đến khi biến đổi dữ liệu. Giá trị cốt lõi không chỉ nằm ở việc sinh code. Quan trọng hơn là giảm phần phỏng đoán trong migration về thứ tự thao tác, khoảng thời gian tương thích và cách phục hồi khi có lỗi.

Điểm khác biệt chính so với một prompt code thông thường

So với prompt thông thường, skill database-migration có định hướng rõ ràng hơn ở các điểm:

• ví dụ migration hiểu theo ORM
• pattern up và down được nêu rõ
• tư duy zero-downtime
• workflow xử lý cả thay đổi schema lẫn thay đổi dữ liệu
• quy trình rollback được xem là yêu cầu hạng nhất

Vì vậy, nó phù hợp với thay đổi trên production hơn là một yêu cầu chung kiểu “generate SQL”.

Phạm vi skill làm tốt và những gì không nằm trong phạm vi

Nội dung skill hiện tại mạnh nhất ở các pattern migration và cấu trúc ví dụ, đặc biệt cho Sequelize và TypeORM. Phần liên quan đến tự động hóa theo repository cụ thể, script validation và rule ra quyết định thì mỏng hơn, vì thư mục skill chỉ lộ ra SKILL.md. Điều đó có nghĩa là skill này hướng dẫn và phác thảo migration khá tốt, nhưng để có đầu ra đáng tin cậy, bạn vẫn nên cung cấp chi tiết stack, ràng buộc và mô hình triển khai của riêng mình.

Cách dùng skill database-migration

Thiết lập ngữ cảnh cài đặt cho skill database-migration

Nếu bạn dùng hệ thống Skills từ repository này, hãy cài skill từ repo rồi gọi nó trong một phiên agent đã có quyền truy cập vào codebase và ngữ cảnh schema của bạn. Cách cài điển hình như sau:

npx skills add https://github.com/wshobson/agents --skill database-migration

Vì skill này chủ yếu được đóng gói dưới dạng một SKILL.md, giá trị của nó sẽ phụ thuộc nhiều vào cách bạn đặt bài toán và lượng ngữ cảnh schema mà bạn cung cấp.

Nên đọc file này trước khi sử dụng

Hãy bắt đầu với:

• plugins/framework-migration/skills/database-migration/SKILL.md

Vì không có các thư mục hỗ trợ hiển thị như rules/, resources/ hay script cho skill này, bạn không cần mất nhiều thời gian đọc repo trước. Cách đọc thực tế khá đơn giản: xem SKILL.md, rồi nhanh chóng chuyển sang schema file, cấu hình ORM và lịch sử migration hiện có của chính dự án bạn.

Skill cần đầu vào gì để hoạt động tốt

Skill database-migration cho kết quả tốt hơn hẳn khi bạn cung cấp:

• ORM hoặc công cụ migration hiện tại: Sequelize, TypeORM, Prisma, raw SQL, v.v.
• schema hiện tại hoặc định nghĩa model
• thay đổi schema mục tiêu
• có cần backfill dữ liệu hay không
• kích thước bảng hoặc mức nhạy cảm với traffic
• mức chấp nhận downtime
• kỳ vọng rollback
• database engine mục tiêu: PostgreSQL, MySQL, v.v.
• kiểu triển khai: one-shot, phased, blue/green, canary

Nếu thiếu các chi tiết này, model có thể trả về một migration trông có vẻ hợp lệ nhưng lại không an toàn cho production.

Biến một mục tiêu thô thành prompt database-migration tốt hơn

Prompt yếu:

Create a migration to rename a column.

Prompt tốt hơn:

Use the database-migration skill. We use TypeORM with PostgreSQL.
Current table: users(id, full_name, created_at).
Goal: replace full_name with first_name and last_name.
Constraints: production table has 20M rows, cannot block writes, rollout must be zero-downtime, app and migration may be deployed separately.
Need:
1. phased migration plan
2. TypeORM migration files
3. data backfill strategy
4. rollback plan
5. application compatibility notes during transition

Phiên bản thứ hai cung cấp cho skill đủ thông tin để chọn hướng expand-migrate-contract an toàn hơn, thay vì đổi tên trực tiếp theo cách nhiều rủi ro.

Quy trình làm việc tốt nhất cho các tác vụ migration thực tế

Một luồng database-migration usage thực tế là:

1. Trước hết yêu cầu chiến lược migration.
2. Rà soát rủi ro, hành vi lock và các giả định về rollback.
3. Sau đó mới yêu cầu file migration cụ thể trong framework của bạn.
4. Nếu rollout theo nhiều giai đoạn, hãy yêu cầu thêm các thay đổi tương thích ở tầng ứng dụng.
5. Yêu cầu query xác minh và các bước rollback.
6. Chạy thử trên staging với hình dạng dữ liệu gần production trước khi tin hoàn toàn vào đầu ra.

Thứ tự này rất quan trọng vì nếu sinh code migration quá sớm, kết quả thường bị “đóng khung” theo một mô hình rollout sai ngay từ đầu.

Các pattern ORM mà skill làm tốt nhất

Dấu hiệu từ repository cho thấy có ví dụ rõ ràng cho:

• Sequelize migrations
• TypeORM migrations

Phần mô tả cũng nhắc đến migration ở nhiều ORM/nền tảng hơn, nhưng các ví dụ hiển thị rõ nhất vẫn tập trung ở hai hệ sinh thái này. Nếu bạn dùng stack khác, hãy yêu cầu model chuyển cùng ý định migration đó sang toolchain của bạn, thay vì mặc định cho rằng skill có độ sâu tương đương một cách tự nhiên.

Khi nào nên yêu cầu hướng dẫn zero-downtime một cách rõ ràng

Đừng mặc định model lúc nào cũng tự tối ưu cho an toàn migration online. Hãy nói rõ khi rơi vào bất kỳ trường hợp nào sau đây:

• bảng lớn
• lưu lượng ghi cao
• triển khai app và DB độc lập
• đổi tên cột hoặc đổi kiểu dữ liệu
• backfill trên đường đi nóng
• thay đổi constraint trên traffic production

Với database-migration cho các team Database Engineering, đây thường là khác biệt giữa một câu trả lời mang tính minh họa và một phương án có thể triển khai.

Nên yêu cầu skill trả về những đầu ra gì

Để dùng với độ tin cậy cao, hãy yêu cầu skill database-migration trả về một gói hoàn chỉnh, không chỉ một file:

• mã migration
• trình tự rollout
• trình tự rollback
• logic backfill dữ liệu
• các giả định và rủi ro
• checklist validation
• các bước dọn dẹp sau migration

Cách này giúp tránh bỏ sót các phần việc vận hành quan trọng nhưng thường bị ẩn đi.

Lưu ý thực tế về các thay đổi phá hủy trực tiếp

Skill này đặc biệt hữu ích để tránh các thay đổi một bước thiếu an toàn như:

• xóa cột cũ ngay lập tức
• đổi tên cột nóng trực tiếp mà không có lớp tương thích
• đổi kiểu dữ liệu mà không có chiến lược chuyển đổi
• thêm ràng buộc non-null trước khi backfill
• ghi lại bảng lớn mà không tính trước ảnh hưởng của lock

Nếu đầu ra đầu tiên của bạn làm bất kỳ điều nào ở trên trong đường triển khai production, hãy yêu cầu một phương án theo nhiều giai đoạn.

Câu hỏi thường gặp về skill database-migration

Skill database-migration này có chỉ dành cho migration ORM không

Không. Skill này được định hình cho migration schema và dữ liệu cơ sở dữ liệu trên nhiều ORM và nền tảng. Trong thực tế, các ví dụ hiển thị thiên về ORM, đặc biệt là Sequelize và TypeORM, nên để có kết quả tốt nhất, bạn nên nêu rõ stack cụ thể của mình và yêu cầu chuyển sang SQL hoặc framework tương ứng khi cần.

Skill database-migration có phù hợp cho người mới bắt đầu không

Có, nhưng có giới hạn. Skill này tương đối dễ tiếp cận vì ví dụ đủ cụ thể, nhưng nó vẫn giả định rằng bạn có thể tự đánh giá một migration có an toàn về mặt vận hành hay không. Người mới có thể dùng skill để phác thảo file migration và kế hoạch rollout, nhưng không nên xem câu trả lời đầu tiên là sẵn sàng cho production nếu chưa được review.

Khi nào không nên dùng database-migration

Hãy bỏ qua skill này nếu tác vụ của bạn chỉ mang tính khái niệm, không liên quan đến việc thực thi thay đổi schema/dữ liệu thực tế. Nó cũng không phù hợp nếu bạn kỳ vọng repository tự cung cấp đầy đủ validation theo môi trường cụ thể, vì skill này không kèm thêm script, rules hay test harness trong thư mục được công khai.

Skill này tốt hơn việc chỉ yêu cầu AI viết SQL ở điểm nào

Giá trị của database-migration guide nằm ở chỗ nó đóng khung bài toán theo toàn bộ vòng đời migration, không chỉ theo cú pháp. Một prompt SQL đơn thuần thường bỏ sót rollback, khoảng thời gian tương thích, backfill theo nhiều giai đoạn và các quy ước migration của ORM. Skill này phù hợp hơn khi độ an toàn triển khai quan trọng ngang với tính đúng đắn của code.

Skill này có hỗ trợ triển khai zero-downtime không

Có, đây là một trong những trường hợp sử dụng được nhắm đến khá rõ. Nhưng bạn vẫn cần mô tả zero-downtime có nghĩa gì trong môi trường của mình. Bản thân cụm từ này quá rộng; model cần biết thứ tự deploy, đặc điểm traffic đọc/ghi và các ràng buộc tương thích của bạn.

Cách cải thiện skill database-migration

Cung cấp cả schema diff lẫn ràng buộc vận hành cho skill

Cách nhanh nhất để nâng chất lượng đầu ra của database-migration là đưa cả thay đổi schema lẫn ràng buộc runtime cùng lúc. Ví dụ:

Current: orders.status VARCHAR nullable
Target: orders.status ENUM not null
DB: PostgreSQL
Rows: 80M
Traffic: constant writes
Requirement: no downtime, rollback available, deploy app separately

Điều này sẽ đẩy model theo hướng thiết kế migration theo pha thay vì viết một câu lệnh alter đơn giản hóa quá mức.

Hãy yêu cầu expand-migrate-contract khi yếu tố an toàn là ưu tiên

Nếu bản nháp đầu tiên trông quá phá hủy, hãy yêu cầu rõ một kế hoạch expand-migrate-contract. Cách này thường cải thiện kết quả cho:

• đổi tên
• chuyển đổi kiểu dữ liệu
• thêm non-null
• tách bảng
• thay đổi theo hướng denormalization hoặc normalization

Đây là một trong những cách đáng tin cậy nhất để có database-migration usage tốt hơn từ skill.

Yêu cầu validation và rollback ngay trong phản hồi đầu tiên

Một lỗi thường gặp là nhận được migration up đúng cú pháp nhưng phần down lại yếu hoặc thiếu thực tế. Bạn có thể cải thiện bằng cách yêu cầu:

• điều kiện rollback
• cảnh báo mất dữ liệu
• query xác minh
• tiêu chí thành công sau từng giai đoạn

Như vậy model sẽ phải suy nghĩ về tính đảo ngược ngay từ sớm.

Cung cấp style migration hiện có từ repo của bạn

Nếu dự án của bạn đã có quy ước migration riêng, hãy dán một hoặc hai file tiêu biểu và yêu cầu skill làm theo. Điều này cải thiện rõ rệt về cách đặt tên, xử lý transaction, style timestamp và idiom của framework. Cách này đặc biệt hữu ích với Sequelize và TypeORM, nơi nhiều team thường có pattern nội bộ vượt ra ngoài mặc định của framework.

Lặp lại theo rủi ro lock, không chỉ theo độ đúng của code

Sau đầu ra đầu tiên, hãy hỏi tiếp những câu như:

• Bước nào có thể lock bảng?
• Bước nào vẫn chạy được khi hệ thống tiếp tục ghi?
• Phần nào nên tách thành các đợt deploy riêng?
• Phần nào không thể đảo ngược sau khi backfill?
• Trong lúc rollout cần theo dõi monitoring gì?

Đây thường là lúc skill database-migration bắt đầu thực sự có giá trị cho công việc Database Engineering, thay vì chỉ sinh boilerplate.

Theo dõi các failure mode phổ biến này

Hãy cẩn trọng nếu migration được sinh ra:

• giả định bảng rất nhỏ
• bỏ qua rollback
• xóa field cũ quá sớm
• gộp thay đổi schema và backfill khối lượng lớn vào một bước rủi ro
• bỏ qua tính tương thích của ứng dụng trong giai đoạn chuyển tiếp
• dùng cú pháp framework không khớp với version của bạn

Đây là những lý do rất bình thường để tinh chỉnh lại prompt, không phải dấu hiệu cho thấy skill không dùng được.

Cách tốt nhất để cải thiện kết quả sau bản nháp đầu tiên

Hãy xem câu trả lời đầu tiên như một đề xuất migration, không phải hiện vật cuối cùng. Sau đó yêu cầu skill chỉnh sửa dựa trên:

• kích thước bảng thực tế của bạn
• tình trạng index
• thứ tự deploy dự kiến
• kết quả từ canary hoặc staging
• bất kỳ giả định nào đã bị review bác bỏ

Vòng phản hồi này là cách thực tế nhất để lấy được giá trị ở mức production từ quy trình database-migration install và usage.