Posted inDatabase

Ngừng vẽ sơ đồ ER: Cách tự động hóa tài liệu cơ sở dữ liệu với SchemaSpy và dbdocs

Database tutorial - IT technology blog
Database tutorial - IT technology blog

Bản đồ bị mất: Điều hướng hơn 250 bảng một cách mù quáng

Quay lại năm 2021, tôi tham gia một startup fintech và nhiệm vụ đầu tiên là gỡ lỗi một báo cáo giao dịch bị hỏng. Tôi đăng nhập vào database production và cảm thấy một nỗi sợ hãi ập đến. Có tới 264 bảng, nhiều bảng có những cái tên khó hiểu như txn_log_v2_final_final, và hoàn toàn không có tài liệu đi kèm. Khi tôi hỏi lập trình viên trưởng về sơ đồ thực thể – quan hệ (ER diagram), anh ấy chỉ cho tôi một file PDF 40 trang trong thư mục dùng chung. Nó đã không được cập nhật kể từ năm 2014.

Tôi đã làm việc với mọi thứ từ MySQL và PostgreSQL đến MongoDB. Mỗi dự án đều có những đặc thù riêng. Tuy nhiên, tất cả đều có chung một lỗ hổng chí mạng: schema thay đổi rất nhanh. Tài liệu thủ công sẽ “chết” ngay khi ai đó chạy lệnh git push. Dành cả buổi chiều thứ Ba để vẽ các ô vuông trong Lucidchart là một sự lãng phí thời gian của các kỹ sư đắt giá. Chúng ta cần những công cụ buộc cơ sở dữ liệu phải tự giải thích chính nó.

Sự suy tàn của tài liệu: Tại sao nỗ lực thủ công thất bại

Tài liệu kém thường không phải do lười biếng, mà do sự cản trở về quy trình. Khi bạn phát hành mã nguồn ba lần một tuần, việc cập nhật sơ đồ thủ công trở thành gánh nặng bất khả thi. Đây là lý do tại sao các phương pháp truyền thống thất bại:

  • Mất đồng bộ: Chỉ cần thay đổi một khóa ngoại (foreign key), sơ đồ tĩnh của bạn sẽ trở thành một lời nói dối.
  • Kiến thức nội bộ (Tribal Knowledge): Chỉ các dev “senior” mới biết rằng user_id trong bảng orders thực tế liên kết với legacy_customers do một đợt migration từ năm 2019.
  • Khả năng tiếp cận: Sơ đồ ER thường mục nát bên trong các file .vsdx độc quyền yêu cầu bản quyền cụ thể để xem, khiến các quản lý sản phẩm (PM) và QA không thể tiếp cận.

Việc thiếu các mối quan hệ dẫn đến các câu truy vấn sai và lỗi toàn vẹn dữ liệu. Quá trình onboarding (làm quen dự án) mất hàng tuần thay vì hàng ngày. Chúng ta cần coi tài liệu như mã nguồn (documentation as code) — tự động, được quản lý phiên bản và mang tính trực quan.

So sánh các đối thủ: SchemaSpy vs. dbdocs

Tôi đã thử nghiệm hàng tá công cụ, nhưng có hai cái tên nổi lên như những người chiến thắng rõ rệt. Chúng giải quyết vấn đề từ các góc độ khác nhau. Tùy thuộc vào tech stack, tôi thường sử dụng cả hai cùng lúc.

1. SchemaSpy: Nhà thám hiểm chuyên sâu

SchemaSpy là một công cụ mạnh mẽ dựa trên Java. Nó phân tích metadata của cơ sở dữ liệu và tạo ra một trang web HTML tương tác, có thể tìm kiếm được. Nó hoàn hảo cho việc kiểm thử kỹ thuật (technical audit). SchemaSpy đi sâu vào các ràng buộc (constraints), chỉ mục (indexes) và thậm chí gắn cờ các bảng “mồ côi” không có bất kỳ mối quan hệ nào.

Ưu điểm:

  • Chạy cục bộ hoặc trực tiếp trong pipeline CI/CD của bạn.
  • Tạo ra các sơ đồ tương tác cực kỳ chi tiết.
  • Phát hiện các điểm bất thường như bảng thiếu khóa chính (primary key).
  • Dữ liệu không bao giờ rời khỏi mạng nội bộ, điều này rất quan trọng cho các dự án nhạy cảm về bảo mật.

2. dbdocs: Người cộng tác hiện đại

Nếu bạn muốn các tài liệu mượt mà, dễ chia sẻ, hãy dùng dbdocs.io. Nó sử dụng file .dbml (Database Markup Language) và chuyển đổi thành một trang tài liệu hiệu suất cao. Nó được xây dựng để cộng tác. Bạn có thể bảo vệ tài liệu bằng mật khẩu và chia sẻ URL trực tiếp với toàn đội chỉ trong vài giây.

Ưu điểm:

  • Tốc độ cực nhanh và giao diện bóng bẩy.
  • Tích hợp tìm kiếm toàn cầu.
  • Hỗ trợ lịch sử phiên bản.
  • Dễ dàng tích hợp với các bộ chuyển đổi SQL sang DBML.

Triển khai SchemaSpy: Trực quan hóa cấu trúc bên trong

Tôi chạy SchemaSpy qua Docker để tránh rắc rối khi quản lý các dependency của Java và JDBC driver. Một câu lệnh duy nhất sẽ tạo báo cáo đầy đủ cho cơ sở dữ liệu PostgreSQL:

docker run -v "$(pwd)/output:/output" --net="host" schemaspy/schemaspy:6.1.0 \
  -t pgsql \
  -host localhost:5432 \
  -db my_app_db \
  -u postgres \
  -p mypassword \
  -s public

Sau khi container chạy xong, hãy mở output/index.html trong trình duyệt. Bạn sẽ tìm thấy tab “Relationships” hiển thị mọi kết nối khóa ngoại. Tính năng yêu thích của tôi là bộ lọc “Degree of Separation” (Mức độ phân tách). Nó cho phép bạn tập trung vào một bảng và chỉ xem các bảng lân cận trực tiếp — một “phao cứu sinh” khi điều hướng trong một hệ thống monolith 300 bảng.

Triển khai dbdocs: Tài liệu dưới dạng mã nguồn

Quy trình làm việc của dbdocs hơi khác một chút. Đầu tiên, trích xuất schema vào một file DBML bằng @dbml/cli. Sau đó, đẩy nó lên cloud.

Đầu tiên, cài đặt các công cụ:

npm install -g @dbml/cli dbdocs

Sau đó, xuất schema và xuất bản:

# Xuất SQL sang DBML
sql2dbml dump_schema.sql --postgres -o schema.dbml

# Đẩy lên dbdocs
dbdocs build schema.dbml --project billing-service

Điều này tạo ra một URL gọn gàng, ví dụ: dbdocs.io/myteam/billing-service. Tôi thường tích hợp nó vào GitHub Actions. Giờ đây, mỗi khi một bản migration được merge vào nhánh main, tài liệu sẽ cập nhật ngay lập tức. Sẽ không còn những câu hỏi kiểu “sơ đồ này có phải bản mới nhất không?” trên Slack nữa.

Chiến lược: Cách tiếp cận hỗn hợp

Các đội ngũ hiệu quả nhất thường sử dụng kết hợp cả hai công cụ một cách chiến lược. Tôi triển khai SchemaSpy cho các DBA và kỹ sư backend, những người cần tìm kiếm các nút thắt cổ chai về hiệu suất hoặc thiếu sót trong index. Chúng tôi host các báo cáo này trên một server Nginx nội bộ sau mạng VPN.

Đối với những người khác — dev frontend, nhà phân tích dữ liệu và chủ sở hữu sản phẩm (product owner) — chúng tôi sử dụng dbdocs. Việc một dev frontend tìm kiếm một trường trên dbdocs sẽ nhanh hơn nhiều so với việc săn tìm trong một báo cáo kỹ thuật phức tạp.

Tự động hóa việc này biến tài liệu từ một công việc nhàm chán thành một sản phẩm phụ tự nhiên. Khi một nhân viên mới gia nhập, đừng đưa cho họ một cái nhún vai và một file PDF từ năm 2014. Hãy trao cho họ một bản đồ trực tiếp và tương tác của “vương quốc dữ liệu”. Đó là cách bạn mở rộng quy mô một đội ngũ kỹ thuật mà không bị quá tải.

Share:
Tags: