Bắt đầu với Database Migration

1. Chuẩn bị bản CLI và môi trường thử

Migration v1 mặc định chưa bật; trong đợt thử có thể chỉ mở cho một số Project được chọn. Kiểm tra whypik db --help trong bản CLI đã cài và Project → Database → Migration. Project khác trong cùng tài khoản có thể vẫn chưa được mở. Nếu tính năng chưa mở, không dùng lệnh cũ hoặc SQL trực tiếp để vượt kiểm tra. Bài này mô tả bản triển khai có Migration, không cam kết mọi máy chủ WhyPik đã được nâng cấp.

Local dùng PostgreSQL/PostgREST và backend WhyPik thật trong Docker. Cần Docker Engine hoặc Docker Desktop ở chế độ Linux containers, Compose v2.20 trở lên và source bundle WhyPik tương thích. Hiện phải chỉ rõ --bundle PATH_TO_WHYPIK_SOURCE; chưa có image/package local được phát hành tự động. CLI không tự cài Docker hay WSL. Docker rootless được nhận diện tự động; daemon dùng userns-remap cần đổi sang rootless hoặc daemon local không remap trước khi chạy.

Chọn thư mục ứng dụng riêng. Chỉ thử hosted trên Project thử đã có Database và credential được chủ Project cấp. Không đưa credential vào Git, file migration, log hoặc ví dụ. Nhãn staging không tạo thêm Database và không làm dữ liệu trong đó tự an toàn.

whypik db --help
whypik db init
whypik db start --bundle PATH_TO_WHYPIK_SOURCE
whypik db doctor

Kết quả cần thấy:CLI có nhóm db; bạn biết source bundle local và Project thử được phép sử dụng.

2. Khai báo bảng đầu tiên

Mở whypik/schema.json và thay nội dung bằng ví dụ dưới. Đây là cấu trúc mong muốn; CLI dùng cùng định dạng definition với Database hiện có. Bảng mới chưa cấp quyền client: Admin có thể thử CRUD, còn ứng dụng cần policy được phê duyệt riêng.

Lưu file rồi chạy whypik db diff --name create_products và whypik db validate. diff so sánh head dựng lại từ các file migration trong Git với schema.json; không đọc hoặc thay đổi production. CLI tự sinh UUID, parent và checksum, không sửa bằng tay.

{
  "tables": [
    {
      "name": "products",
      "columns": [
        {
          "name": "id",
          "type": "uuid",
          "primary": true,
          "default": {
            "kind": "uuid"
          }
        },
        {
          "name": "name",
          "type": "text",
          "nullable": false
        }
      ],
      "indexes": [],
      "policies": []
    }
  ]
}

Kết quả cần thấy:Có một file JSON mới trong whypik/migrations; validate xác nhận chuỗi khớp schema.json.

3. Áp dụng local và kiểm tra lịch sử

Lệnh migrate --env local tự validate và tạo plan trước apply. start không tự chạy migration. Khi stack local đã chạy, start khởi động lại các process và giữ dữ liệu cùng lịch sử; đợi lệnh hoàn tất rồi dùng ứng dụng. Đọc đích, thay đổi và rủi ro trước xác nhận; --yes chỉ bỏ câu hỏi tương tác, không bỏ kiểm quyền hoặc backup.

Chỉ exit 0 khi các migration cần chạy đã commit và API sẵn sàng. Nếu mất kết nối hoặc còn đối soát, giữ operation ID được trả về và dùng whypik db operation OPERATION_UUID --env local; không xóa volume hay chạy lại DDL để sửa lỗi.

whypik db migrate --env local
whypik db status --env local
whypik db history --env local

Kết quả cần thấy:status có mode migration, head trùng file; history có migration đã commit.

4. Chạy ứng dụng với đúng Database

Ứng dụng Mini Server chạy bằng whypik run --db-env local. --host và --port là địa chỉ server Python local; chúng không đổi endpoint Database. --env-file vẫn dùng cho Variables ứng dụng, khác --db-env chọn Database.

Local hỏng thì lệnh báo lỗi, không dùng khóa hosted hoặc tự chuyển sang Database thật. Workspace cũ chưa cấu hình Database giữ luồng hosted đã có; đọc rõ đích trước khi thử thao tác ghi. stop giữ volume; reset local là thao tác xóa riêng có xác nhận workspace.

Workspace đã có [database] mặc định chọn local khi chạy run; chỉ rõ --db-env local để dễ review. Workspace cũ chưa có [database] giữ cấu hình hosted. Muốn chọn một nhãn hosted đã liên kết, truyền --db-env LABEL có chủ đích.

whypik run --db-env local --host 127.0.0.1 --port 8000
# Ctrl+C dừng ứng dụng; dừng stack khi không cần:
whypik db stop

Kết quả cần thấy:Ứng dụng dùng danh tính local riêng của workspace; không gọi nhầm Database hosted.

5. Liên kết Project thử và xem plan

Đặt WHYPIK_MIGRATION_KEY hoặc WHYPIK_ADMIN_KEY được cấp cho đúng Project trong môi trường terminal. Không dùng deploy key, public key hay server secret tuân policy. link xác minh Project và lưu UUID/endpoint công khai trong whypik.toml; không provision dịch vụ hoặc đổi gói.

Nếu Database đã có bảng nhưng chưa có lịch sử migration, dùng quy trình baseline ở bài nâng cao. Không apply chuỗi CREATE lên bảng có sẵn. Plan ràng buộc nội dung file, Database/generation/lineage/head, security revision và quyền hiện tại; sửa schema, role hoặc đích thì phải đọc plan mới.

whypik db link --env staging --project PROJECT_UUID
whypik db plan --env staging --out .whypik/staging-plan.json

Kết quả cần thấy:Bạn có plan của đúng Project thử, thấy head hiện tại/head đích và các rủi ro.

6. Áp dụng kế hoạch đã review

Hosted bắt buộc --env và --plan. Kiểm tra endpoint, Project UUID, Database và generation/lineage trước xác nhận. Không tự chọn production từ nhánh Git hoặc khóa đang có. Khi có rủi ro policy/destructive, chỉ thêm phê duyệt riêng sau khi đã review đủ quyền và backup.

Mở Project → Database → Migration để xem chế độ, head, lịch sử, operation và drift. Nhập đúng nhãn môi trường đã liên kết trên máy bạn rồi dùng icon sao chép lệnh. Dashboard chỉ theo dõi, không chạy migration.

Trong mode migration, Cấu trúc bảng, Quyền truy cập và nhập cấu trúc trực tiếp bị khóa. CRUD, nhập bản ghi vào bảng có sẵn và Auth vẫn giữ quyền hiện có. Đưa whypik.toml, schema và migration vào Git; không commit .whypik hoặc secret.

whypik db migrate --env staging --plan .whypik/staging-plan.json
whypik db status --env staging
whypik db history --env staging

Kết quả cần thấy:CLI exit 0 và Dashboard xác nhận head mới, API ready; nếu chưa có kết quả cuối, có operation ID để tiếp tục đối soát.