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

5.7. Quy định thay đổi cấu trúc dữ liệu (Entity & Database)


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


Chương này quy định cách kiểm soát các thay đổi liên quan đến cấu trúc dữ liệu nhằm:

  • Tránh mất dữ liệu hoặc lỗi hệ thống

  • Đảm bảo tương thích giữa các module

  • Ngăn xung đột schema khi nhiều đơn vị cùng phát triển

  • Bảo vệ các field và bảng dữ liệu chuẩn của hệ thống

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


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

  • Tất cả các entity trong hệ thống

  • Tất cả các bảng database

  • Core Team và Partner Team

  • Mọi thay đổi liên quan đến:

Các loại thay đổi cần kiểm soát

  • Thêm field mới

  • Xóa field

  • Sửa field

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

  • Thay đổi quan hệ entity

  • Thêm/xóa bảng database

5.7.3. Quy định chính


5.7.3.1. Không được tự ý thay đổi các field chuẩn

Các field chuẩn hệ thống:

  • id

  • created_at

  • created_by

  • updated_at

  • updated_by

  • deleted / status

  • tenant_id (nếu có)

Quy định bắt buộc

Không được:

  • Xóa field chuẩn

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

  • Đổi tên field

  • Thay đổi ý nghĩa nghiệp vụ của field

Các field này được coi là system fields và được dùng chung cho:

  • Audit

  • Logging

  • Multi-tenant

  • Phân quyền

  • Tích hợp hệ thống

5.7.3.2. Thêm field mới trong module

Partner chỉ được phép thêm field khi:

  • Phục vụ nghiệp vụ của module

  • Không trùng với dữ liệu core

  • Không phá vỡ cấu trúc hiện tại

  • Có migration script

  • Có mô tả trong Pull Request

  • Được Core Team review

5.7.3.3. Các thay đổi bắt buộc xin phép Core Team

Các thay đổi sau không được tự ý thực hiện:

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

  • Xóa field

  • Đổi tên field

  • Thay đổi quan hệ entity

  • Thêm field liên quan:

    • user

    • role

    • permission

    • tenant

    • audit

Tất cả các trường hợp trên phải qua:

Data Model Change Request

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


Trường hợp 1: Thêm field trong module

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

modules/<module>/entity/**


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

V<timestamp>__add_<field>_to_<table>.sql


Bước 3: Tạo Pull Request, trong PR phải có:

  • Mô tả field mới

  • Lý do nghiệp vụ

  • Migration script

Bước 4: Core Team review:

  • Không trùng core data

  • Không phá vỡ hệ thống

Bước 5: Merge vào develop

Trường hợp 2: Thay đổi field hoặc quan hệ entity

Bước 1: Tạo ticket: các phần mềm quản lý công việc liên quan (Jira / Redmine / YouTrack) hoặc nội bộ

[DATA MODEL CHANGE REQUEST] <mô tả thay đổi>

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

  • Entity bị ảnh hưởng

  • Field thay đổi

  • Kiểu dữ liệu cũ và mới

  • Migration script

  • Lý do thay đổi

Bước 3: Core Team review:

  • Đánh giá ảnh hưởng hệ thống

  • Kiểm tra backward compatibility

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

  • Core Team thực hiện thay đổi

  • Merge vào develop

5.7.5. Ví dụ minh họa


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

Partner thêm field vào entity module:

@Column(name = "PRIORITY")

private Integer priority;


Và có migration:

ALTER TABLE PLANNING ADD PRIORITY INT;


→ Được phép.

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

Partner sửa:

@Column(name = "CREATED_AT")

private String createdAt;


→ Đổi kiểu dữ liệu từ timestamp sang string.

→ Không được phép.

Phải tạo:

[DATA MODEL CHANGE REQUEST]


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

Partner muốn:

  • Xóa field status

  • Đổi tên description → detail

  • Thêm quan hệ với bảng user_account

5.7.6. Checklist áp dụng


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

  • Có thay đổi field chuẩn không?

    • Nếu có → phải tạo Data Model Change Request

  • Có đổi kiểu dữ liệu field không?

    • Nếu có → phải xin phép Core Team

  • Có migration script chưa?

  • Field mới có trùng dữ liệu core không?

  • PR đã mô tả rõ thay đổi chưa?

Lên đầu trang