# lotimmy/database_connection_toolkit architecture

> Architecture diagram of the GitHub repository lotimmy/database_connection_toolkit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lotimmy/database_connection_toolkit
- Repository: https://github.com/lotimmy/database_connection_toolkit

## Overview

這個專案是一個用於連接 SQL Server、SQLite 與 MySQL 的 Python 資料庫連線工具包，其主要目的是提供一套簡易又統一的資料庫連線與測試介面，同時協助使用者透過環境變數管理與初始化連線所需的設定。根據專案的檔案結構與 README，下面提供如何畫出系統設計圖的建議：

##### 主要元件識別：
- 資料庫連線工具庫（db_toolkit）：主要包含三個模組
- db_connector.py：封裝不同資料庫(SQL Server、SQLite、MySQL)的連線類別與邏輯
- database_connection_test.py：用於測試連線是否正常
- setup_env.py：從 .env.example 建立 .env 的工具，用於初始化環境參數
- 測試模組（tests）：包含單元測試檔案（test_database_connection.py），確保各資料庫連線功能正常。
- 配置與專案打包元件：
- .env.example：基本環境變數設定範例
- pyproject.toml：專案的打包與依賴設定，整合使用者專案所依賴的外部套件（例如：loguru、records、pandas、python-dotenv）

##### 建立系統設計圖應該強調的部分：
- 將專案分為幾個明確的區塊：
- 資料庫連線模組（db_toolkit）區塊：在此區域可以再細分為三個子元件，其內部涵蓋不同資料庫的連線處理。
- 環境變數初始化：setup_env.py 與 .env.example 之間的關係，顯示如何從範例初始化環境參數。
- 測試腳本：database_connection_test.py 與 tests 資料夾中的單元測試，表示測試層級的運作與驗證流程。
- 外部依賴與打包流程：
- 描述 pyproject.toml 的設定，並將打包生成的 .whl 或 .tar.gz 文件視為發布元件，說明使用 pip 安裝後即能在目標環境中使用。
- 說明相依套件與它們提供的功能（例如，loguru 用於日誌記錄，records 用來簡化 SQL 操作，pandas 可用於資料處理，python-dotenv 處理環境變數）。

##### 建議系統設計圖的畫法：
- 用不同形狀或顏色區分主要元件，例如：
- 用方塊表示主要模組：db_toolkit 模組、測試模組、環境變數初始化模組與打包流程。
- 用圓形或不同背景色標示外部依賴或工具套件。
- 使用方向箭頭來表示：
- 從 setup_env（環境初始化工具）指向 .env（實際環境設定檔）。
- 從 db_connector 各個資料庫連線類別指向外部資料庫（SQL Server、SQLite、MySQL）的圖標，顯示連線與交互流程。
- 從連線測試模組指向 db_connector，顯示測試調用的關係。
- 標準標籤與結構標註：
- 清楚標記每個元件的名稱與簡要功能說明。
- 用連結線標示依賴關係與資料流，強調打包與部署流程（pyproject.toml 生成分發包後可供 pip 安裝）。

##### 注意事項與架構模式：
- 強調單一職責原則，讓每個模組（連線處理、環境設定、測試）專注於一個功能。
- 畫出資料流與執行順序，如初始化環境變數後呼叫連線腳本進行資料庫連線測試，再透過單元測試確保正確運作。
- 如果可能，可以加上額外的文字註解，說明各個元件間的集成流程與整體系統部署流程。

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% 工具模組
    subgraph "工具模組"
        direction TB
        A["資料庫連線工具庫 (db_toolkit)"]:::module
        B["資料庫連線處理 (db_connector)"]:::module
        C["環境變數初始化工具 (setup_env)"]:::module
        D["連線測試工具 (database_connection_test)"]:::module
        A --> B
        A --> C
        A --> D
    end

    %% 測試模組
    subgraph "測試模組"
        direction TB
        E["單元測試 (test_database_connection.py)"]:::test
    end

    %% 配置與打包
    subgraph "配置與打包"
        direction TB
        F["環境設定範例 (.env.example)"]:::config
        G["專案打包與依賴設定 (pyproject.toml)"]:::config
        H["發行包 (pip安裝分發包)"]:::config
        X["環境設定檔 (.env)"]:::config
        %% 說明：setup_env 利用 .env.example 產生環境設定檔
        F -- "提供範例" --> C
        C -- "生成設定檔" --> X
        G --> H
    end

    %% 外部資源
    subgraph "外部資源"
        direction TB
        I["SQL Server 資料庫"]:::database
        J["SQLite 資料庫"]:::database
        K["MySQL 資料庫"]:::database
        L["loguru(日誌記錄)"]:::external
        M["records(SQL工具)"]:::external
        N["pandas(資料處理)"]:::external
        O["python-dotenv(環境變數)"]:::external
    end

    %% 連線關係
    D -->|"調用連線"| B
    B -->|"連線"| I
    B -->|"連線"| J
    B -->|"連線"| K

    %% 外部依賴於打包設定
    G --> L
    G --> M
    G --> N
    G --> O

    %% 測試模組調用連線測試工具
    E -->|"測試運作"| D

    %% Click Events
    click A "https://github.com/lotimmy/database_connection_toolkit/tree/main/src/db_toolkit"
    click B "https://github.com/lotimmy/database_connection_toolkit/blob/main/src/db_toolkit/db_connector.py"
    click C "https://github.com/lotimmy/database_connection_toolkit/blob/main/src/db_toolkit/setup_env.py"
    click D "https://github.com/lotimmy/database_connection_toolkit/blob/main/src/db_toolkit/database_connection_test.py"
    click E "https://github.com/lotimmy/database_connection_toolkit/blob/main/tests/test_database_connection.py"
    click F "https://github.com/lotimmy/database_connection_toolkit/blob/main/.env.example"
    click G "https://github.com/lotimmy/database_connection_toolkit/blob/main/pyproject.toml"

    %% 樣式定義
    classDef module fill:#A6CEE3,stroke:#000,stroke-width:2px;
    classDef test fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef config fill:#CDEB8B,stroke:#000,stroke-width:2px;
    classDef external fill:#FF9F9B,stroke:#000,stroke-width:2px;
    classDef database fill:#B3E2CD,stroke:#000,stroke-width:2px;
```
