Bối cảnh: Tại sao không nên vẽ tay tài liệu Database?
Cảm giác nhảy vào một dự án “legacy” với hơn 100 bảng mà không có lấy một trang documentation thực sự là ác mộng. Anh em chắc đã quá quen với việc ngồi soi từng bảng trong MySQL Workbench để đoán quan hệ khóa ngoại. Cách làm này cực kỳ tốn thời gian và dễ sai sót khi hệ thống phình to.
Vẽ tay sơ đồ ERD (Entity Relationship Diagram) qua Draw.io hay Lucidchart là một giải pháp, nhưng database thì thay đổi theo từng bản code. Chỉ cần anh em quên cập nhật một cột index hay đổi kiểu dữ liệu, bộ tài liệu đó sẽ lập tức trở thành “đống rác” lỗi thời. Đó là lý do mình tin dùng SchemaSpy để tự động hóa toàn bộ quy trình này.
Về bản chất, SchemaSpy là công cụ Java giúp quét database và xuất ra một dashboard HTML chi tiết. Nó không chỉ liệt kê bảng mà còn tự vẽ sơ đồ quan hệ, chỉ ra các bảng “mồ côi” (không liên kết) hay thống kê các cột thiếu index. Thay vì mất 2 ngày để hiểu cấu trúc, giờ đây anh em chỉ cần 5 phút lướt web là nắm trọn hệ thống.
Một mẹo nhỏ cho anh em làm dữ liệu: Khi cần convert nhanh CSV sang JSON để test schema, mình hay dùng công cụ tại toolcraft.app/vi/tools/data/csv-to-json. Nó chạy client-side nên cực kỳ bảo mật, không sợ lộ dữ liệu dự án lên server.
Chuẩn bị môi trường cài đặt
Để SchemaSpy “lên hình” mượt mà, máy anh em cần bộ combo: Java Runtime (JRE), JDBC Driver và đặc biệt là Graphviz để vẽ sơ đồ.
1. Cài đặt Java và Graphviz
SchemaSpy yêu cầu Java 8 trở lên. Với Ubuntu hoặc Debian, anh em chỉ cần một dòng lệnh:
sudo apt update && sudo apt install openjdk-11-jre graphviz -yĐừng quên Graphviz! Nếu thiếu nó, báo cáo xuất ra sẽ chỉ toàn chữ là chữ, mất đi 80% sức mạnh trực quan của công cụ.
2. Tải SchemaSpy và JDBC Driver
Hãy lên GitHub chính thức để lấy file schemaspy.jar mới nhất. Sau đó, tải JDBC Driver tương ứng với loại DB đang dùng (như MySQL, PostgreSQL hay SQL Server).
- PostgreSQL: Sử dụng file
postgresql-x.x.x.jartừ trang chủ. - MySQL: Sử dụng
mysql-connector-java-x.x.x.jar.
Mình thường gom tất cả vào một thư mục cho dễ quản lý:
mkdir ~/schemaspy-tool && cd ~/schemaspy-tool
wget https://github.com/schemaspy/schemaspy/releases/download/v6.1.0/schemaspy-6.1.0.jar -O schemaspy.jar
# Ví dụ tải driver cho Postgres 42.5.0
wget https://jdbc.postgresql.org/download/postgresql-42.5.0.jarVận hành SchemaSpy qua file cấu hình
Thay vì gõ dòng lệnh dài dằng dặc dễ sai sót, mình khuyên dùng file schemaspy.properties. Cách này giúp anh em dễ dàng chia sẻ cấu hình cho mọi người trong team qua Git.
Nội dung file schemaspy.properties mẫu
schemaspy.t=pgsql
schemaspy.dp=./postgresql-42.5.0.jar
schemaspy.host=127.0.0.1
schemaspy.port=5432
schemaspy.db=my_project_db
schemaspy.u=db_user
schemaspy.p=secret_password
schemaspy.s=public
schemaspy.o=./output
schemaspy.vizjs=trueSau khi chuẩn bị xong, anh em kích hoạt lệnh thần thánh:
java -jar schemaspy.jar -configFile schemaspy.propertiesSchemaSpy sẽ quét toàn bộ metadata. Khi hoàn tất, hãy mở output/index.html để tận hưởng thành quả trực quan.
Triển khai nhanh với Docker
Nếu ngại cài cắm Java lên máy, Docker là cứu cánh tuyệt vời. Phương pháp này cực gọn, nhất là khi chạy trên server CI/CD:
docker run --v $(pwd):/output --net=host schemaspy/schemaspy:6.1.0 \
-t pgsql -host localhost:5432 -db my_db -u user -p pass -o /output -dp /drivers/postgresql.jarKhai thác thông tin từ báo cáo
Giao diện của SchemaSpy có 3 tab mà mình luôn soi kỹ để tối ưu hệ thống:
- Relationships: Linh hồn của tài liệu. Sơ đồ ERD cho phép zoom in/out và click vào từng bảng để xem quan hệ cha-con cực kỳ nhanh.
- Anomalies: Tab “bắt bệnh” cho DB. Nó liệt kê bảng thiếu Primary Key, cột trùng tên nhưng lệch kiểu dữ liệu, hay các bảng mồ côi. Đây là nơi lý tưởng để dọn dẹp nợ kỹ thuật (technical debt).
- Columns: Search engine cho database. Bạn chỉ cần gõ tên trường, nó sẽ chỉ đích danh bảng chứa cột đó.
Tích hợp CI/CD để tài liệu luôn tươi mới
Documentation mà để lâu không cập nhật thì chỉ có bỏ đi. Tốt nhất là ném nó vào luồng GitLab CI hoặc GitHub Actions. Mỗi khi có bản Migration mới được merge, hệ thống sẽ tự chạy SchemaSpy và đẩy file lên GitHub Pages.
Bằng cách này, từ Frontend đến BA đều có thể check schema mới nhất qua một URL duy nhất. Anh em DBA cũng đỡ bị réo tên mỗi khi có thay đổi nhỏ trong database.
Lưu ý bảo mật: Khi chạy trên Production, hãy tạo một user chỉ có quyền SELECT trên information_schema. Tuyệt đối không dùng user root để đảm bảo an toàn cho dữ liệu nhạy cảm.
Tài liệu hóa database thường là việc nhàm chán, nhưng SchemaSpy đã biến nó thành trải nghiệm tự động hóa chuyên nghiệp. Hy vọng công cụ này sẽ giúp dự án của anh em trở nên sáng sủa và dễ bảo trì hơn!
