Kiến trúc cho lập trình viên

Mã nguồn viết bằng Zig 0.17, không dùng C (@cImport, file .c). Mỗi file tối đa 600 dòng. Xem thêm CLAUDE.md ở thư mục gốc.

Luồng chính

main.zig           những gì các cửa sổ dùng chung: store, máy chủ MCP
 └─ app_window.Win  một cửa sổ, chứa nhiều Session
     ├─ Welcome     danh sách kết nối
     └─ Session     không gian làm việc của một kết nối
         ├─ session_sidebar.zig   thanh bên
         ├─ session_tabs.zig      thanh tab
         └─ Tab: TableTab, QueryTab, KeyTab, Dashboard, ...

Mỗi khung hình là một chuỗi lời gọi view(c: *ui.Context) đi xuống cây. Giao diện dạng immediate mode: view trả về điều người dùng đã làm, thay vì gọi ngược lên trên.

Lớp driver

driver.zig định nghĩa giao diện chung: Conn với VTable, ResultSet với ô dạng văn bản, Kind, Dialect.

Để thêm một engine, viết một file driver cài đặt Conn.VTable, rồi thêm vào Kind và connect.open.

masking.zig bọc một Conn để áp luật che lên mọi kết quả. Nó phải chuyển tiếp mọi mục tùy chọn của VTable.

Các driver mạng đọc và ghi qua transport.zig, gồm TCP và TLS của std.crypto. Tunnel không cần driver biết đến: ssh_tunnel.zig và socks_tunnel.zig mở một cổng cục bộ, và driver kết nối tới cổng đó.

Trạng thái dùng chung

Env trong env.zig là những gì mọi tab của một session dùng chung: connection, store, toast, cửa sổ. Hãy dùng Env.run hoặc Env.exec để câu lệnh được ghi vào lịch sử.

Chạy nền

worker.zig chạy câu lệnh của tab query trên một luồng và gửi kết quả về luồng chính qua plugin mainthread. Một tab query dùng kết nối riêng khi connect.canOpenTwice cho phép.

Các module theo tính năng

Tính năng	File
Lưới	grid.zig, grid_menu.zig, grid_frozen.zig, grid_marks.zig, grid_find.zig, grid_summary.zig
Bảng	table_tab.zig, table_actions.zig, filter_bar.zig, changes.zig, fk_picker.zig, highlight_view.zig
Query	query_tab.zig, query_results.zig, query_params.zig, explain_plan.zig, result_compare.zig
Trình soạn	completion.zig, sqlformat.zig, editor_tools.zig, vim.zig, editor_keys.zig, keymap.zig
Dữ liệu	formats.zig, xlsx.zig, parquet.zig, data_file.zig, data_open.zig, export_view.zig, import_view.zig, transfer.zig, transfer_ddl.zig, backup.zig, test_rows.zig
Kết nối	connect.zig, connect_job.zig, ssh_tunnel.zig, socks_tunnel.zig, conn_url.zig, conn_import.zig, welcome.zig, welcome_tunnel.zig
An toàn	safety.zig, masking.zig
Công cụ	object_sql.zig, db_search.zig, er_view.zig, dashboard_sql.zig, data_dictionary.zig, join_builder.zig
AI, MCP	ai_client.zig, ai_view.zig, ai_commands.zig, mcp_server.zig
Dòng lệnh	cli.zig

Kiểm thử

zig build test    # toàn bộ test
zig build         # luôn chạy cả lệnh này, test build không biên dịch code chỉ có trong app

Test được tìm qua khối test { _ = @import(...) } ở cuối src/main.zig. File mới có test phải được thêm vào đó.

Test cần database dùng SQLite :memory:, và trả về error.SkipZigTest nếu thiếu thư viện. Driver mạng được kiểm tra với máy chủ giả lập trong tiến trình (pg_test.zig, mysql_test.zig...).

Kiểm tra giao diện không mở cửa sổ:

zig-out/bin/mydatabase --myzig-snapshot=shot.png --myzig-script="click:Open Sample Database;click:customers"

Luôn dùng cờ snapshot khi kiểm tra

Chạy exe mà không có --myzig-snapshot sẽ mở app thật, và app có thể tự kết nối lại kết nối cuối cùng của bạn.

Tài liệu này

Nằm trong docs/, dùng VitePress:

cd docs
npm install
npm run dev      # xem trực tiếp
npm run build    # kết quả ở docs/.vitepress/dist