Nhảy đến nội dung chính

5.Quy định về Database, Schema và Migration

5.1. Mục tiêu chương


Chương này quy định cách quản lý cấu trúc database và các thay đổi schema nhằm:

  • Đảm bảo tính ổn định của dữ liệu hệ thống

  • Tránh xung đột schema giữa các module và các đơn vị phát triển

  • Đảm bảo khả năng triển khai tự động qua các môi trường

  • Kiểm soát lịch sử thay đổi database

5.2. Khái niệm / phạm vi áp dụng


Quy định này áp dụng cho:

  • Toàn bộ database của hệ thống

  • Core Team và Partner Team

  • Tất cả các thay đổi liên quan đến:

    • Bảng dữ liệu

    • Cột dữ liệu

    • Constraint

    • Index

    • Trigger

Hệ thống phân loại bảng dữ liệu thành hai nhóm:

1. Core tables (dùng chung toàn hệ thống)

Bao gồm các bảng:

  • app_user

  • theme_config

  • feature_management

Đây là các bảng dữ liệu lõi, được dùng chung cho:

  • Xác thực

  • Phân quyền

  • Cấu hình hệ thống

2. Module tables

Bao gồm:

  • Các bảng thuộc từng module riêng

  • Nằm trong phạm vi nghiệp vụ của module

Ví dụ:

  • planning

  • document

  • task

  • notification

5.3. Quy định chính

5.3.1. Quy định với Core tables

Partner không được phép:

  • Thay đổi cấu trúc bảng

  • Thêm cột

  • Xóa cột

  • Đổi kiểu dữ liệu

  • Sửa constraint

  • Sửa index

  • Sửa trigger

Mọi thay đổi liên quan đến core tables phải thông qua:

DB Core Change Request -> sử dụng jira/… hoặc các phần mềm quản lý công việc nội bộ

Và do Core Team thực hiện.

5.3.2. Quy định với Module tables

Partner được phép:

  • Tạo bảng mới cho module

  • Thêm cột

  • Sửa cấu trúc bảng module

Nhưng phải tuân thủ:

  • Không ảnh hưởng core tables

  • Có migration script

  • Có mô tả rõ trong Pull Request

  • Được Core Team review

5.3.3. Migration bắt buộc

Mọi thay đổi database phải tuân thủ các nguyên tắc sau:

  • Không sửa trực tiếp database production

  • Không chỉnh sửa thủ công trên DB staging

  • Tất cả thay đổi phải qua migration script

  • Migration phải được commit vào source code

Công cụ sử dụng:

  • Flyway hoặc Liquibase

Format migration

Tên file migration:

V<timestamp>__<description>.sql


Ví dụ:

V20260209__create_planning_table.sql

V20260210__add_priority_to_planning.sql

5.4. Cách thực hiện / quy trình


Trường hợp 1: Thêm hoặc sửa bảng trong module

Bước 1: Cập nhật entity trong:

modules/<module>/entity/**


Bước 2: Tạo migration script:

V<timestamp>__<description>.sql


Bước 3: Commit:

  • Entity

  • Migration script

Bước 4: Tạo Pull Request

Bước 5: Core Team review:

  • Migration hợp lệ

  • Không ảnh hưởng core tables

Bước 6: Merge vào develop

Trường hợp 2: Thay đổi core tables

Bước 1: Tạo ticket:

[DB CORE CHANGE REQUEST] <mô tả thay đổi>

Bước 2: Cung cấp thông tin:

  • Bảng bị ảnh hưởng

  • Cột thay đổi

  • Kiểu dữ liệu

  • Migration script đề xuất

  • Lý do thay đổi

Bước 3: Core Team review

Bước 4: Nếu được duyệt:

  • Core Team thực hiện migration

Merge vào develop

5.5. Ví dụ minh họa


Trường hợp hợp lệ

Partner thêm bảng mới:

CREATE TABLE PLANNING (

    ID BIGINT PRIMARY KEY,

    NAME VARCHAR(255),

    DESCRIPTION VARCHAR(1000)

);


→ Thuộc module table → được phép.

Trường hợp không hợp lệ

Partner chạy trực tiếp trên production:

ALTER TABLE USER_ACCOUNT ADD PHONE VARCHAR(20);


→ Sai quy định vì:

  • Sửa core table

  • Sửa trực tiếp DB production

  • Không có migration

Trường hợp cần xin phép

Partner muốn:

ALTER TABLE ROLE ADD DESCRIPTION VARCHAR(255);


→ Đây là core table.

Phải tạo: trên phần mềm quản lý công việc nội bộ hoặc phần mềm nghiệp vụ tương đương

[DB CORE CHANGE REQUEST]

5.6. Checklist áp dụng


Trước khi commit hoặc tạo PR:

  • Có thay đổi database không?

    • Nếu có → phải có migration script

  • Có sửa core table không?

    • Nếu có → phải tạo DB Core Change Request

  • Migration có đúng format tên file không?

  • Không sửa trực tiếp DB production

  • Migration đã được commit vào source code

Lên đầu trang