Đặt vấn đề

Markdown là một ngôn ngữ đánh dấu nhẹ được sử dụng để định dạng văn bản theo cách dễ đọc và dễ viết. Nó thường được cộng đồng lập trình viên sử dụng để tạo các tệp readme, tài liệu và các loại văn bản khác cần được định dạng theo cách nhất quán. Markdown sử dụng cú pháp đơn giản, chẳng hạn như thẻ bắt đầu bằng # cho tiêu đề và dấu hoa thị để nhấn mạnh, để tạo nhiều tùy chọn định dạng, chẳng hạn như tiêu đề, danh sách và liên kết. Nó có thể dễ dàng chuyển đổi sang HTML, PDF và các định dạng khác.

Mermaid là một thư viện JavaScript cho phép bạn tạo sơ đồ và lưu đồ bằng cú pháp đơn giản, giống như đánh dấu. Nó hỗ trợ nhiều loại sơ đồ, bao gồm lưu đồ, sơ đồ trình tự, sơ đồ lớp và sơ đồ trạng thái. Các sơ đồ được tạo bằng cách sử dụng mã dựa trên văn bản, sau đó được kết xuất thành một sơ đồ dựa trên SVG, tương tác, có thể dễ dàng tích hợp vào các trang web và các tài liệu khác. Mermaid được sử dụng rộng rãi trong các tài liệu kỹ thuật và thuyết trình.

Chú ý: Mermaid là dùng code để thể hiện nội dung biểu đồ. Mermaid không sử dụng định dạng ảnh binary như PNG, JPG.

Mã mermaid có thể được nhúng vào trong Markdown để biểu diễn đồ thị, biểu đồ, lược đồ…

graph TD
A[Christmas] -->|Get money| B(Go shopping)
B --> C{Let me think}
C -->|One| D[Laptop]
C -->|Two| E[iPhone]
C -->|Three| F[fa:fa-car Car]

Khi viết một văn bản kỹ thuật bằng Markdown, tôi cần vẽ lai quan hệ các bảng trong cơ sở dữ liệu quan hệ. Vậy làm cách nào nhanh nhất để sinh mã Mermaid từ các bảng có sẵn?

SchemaCrawler

SchemaCrawler là một thư viện viết bằng Java. Nó sẽ kết nối vào nhiều cơ sở dữ liệu khác nhau, sau đó sinh ra mã Mermaid.

Cài đặt SchemaCrawler

Có hai cách chạy SchemaCrawler:

  1. Tải SchemaCrawler về máy, cần đảm bảo bạn đã cài Java JDK trước đó.
  2. Chạy SchemaCrawler trong Docker container

Ví dụ theo cách 1, tôi sẽ làm những bước sau đây

  1. Cài đặt SDKMan công cụ để quản lý các gói phần mềm Java
  2. Cài đặt JDK 17 hoặc mới hơn
  3. Cài đặt SchemaCrawler bằng lệnh sdk install schemacrawler. SchemaCrawler sẽ được cài vào thư mục ~/.sdkman/candidates/schemacrawle/current
  4. Các file chạy của SchemaCrawler sẽ nằm trong thư mục con /bin. Chi tiết cấu trúc thư mục của thư viện SchemaCrawler
    ├── bin
├── config
├── dbml.py
├── lib
├── licenses
├── logos
├── mermaid.py
├── plantuml.py
└── sc.db

Dùng SchemaCrawler để sinh mã Mermaid

Giả sử tôi có CSDL MySQL đang phục vụ datatabase demo ở localhost và cổng 3306, user root và password là @123

Trong database demo tôi tạo 2 bảng customers và orders. Lệnh DDL như sau

CREATE TABLE customers (
    id INT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL
);

CREATE TABLE orders (
    id INT AUTO_INCREMENT PRIMARY KEY,
    customer_id INT NOT NULL,
    order_date DATE NOT NULL,
    total_amount DECIMAL(10,2) NOT NULL,
    FOREIGN KEY (customer_id) REFERENCES customers(id)
);

sql

Trong terminal, ở thư mục SchemaCrawler tôi gõ lệnh sau:

./bin/schemacrawler.sh \
--server mysql \
--host localhost \
--port 3306 \
--user root \
--password=@123 \
--database demo \
--info-level=standard \
--command script \
--script-language python \
--script mermaid.py

Kết quả trả về trong terminal

erDiagram

  demo-customers {
    INT id
    VARCHAR name
    VARCHAR email
  }

  demo-orders {
    INT id
    INT customer_id
    DATE order_date
    DECIMAL total_amount
  }

  demo-customers ||--o{ demo-orders : "foreign key"

Hiển thị biểu đồ Mermaid kết quả là

erDiagram

  demo-customers {
    INT id
    VARCHAR name
    VARCHAR email
  }

  demo-orders {
    INT id
    INT customer_id
    DATE order_date
    DECIMAL total_amount
  }

  demo-customers ||--o{ demo-orders : "foreign key"

Kết luận

SchemaCrawler là một công cụ hữu ích giúp vẽ biểu đồ Mermaid quan hệ bảng (ER: Entity Relationship) trong tài liệu Markdown rất nhanh, đẹp, chính xác. Hiện tại tôi chưa biết cách để loại bớt tên database đứng trước tên bảng khi chạy SchemaCrawler. Tuy nhiên có thể loại bỏ bằng cách Find And Replace bằng bất kỳ công cụ editor nào.