Skip to content

AUTOMATION.md

Latest commit

 

History

History
82 lines (55 loc) · 6.56 KB

AUTOMATION.md

File metadata and controls

82 lines (55 loc) · 6.56 KB
Raw

自動執行作業

mySQLPunk 可以把常用的唯讀查詢、查詢結果匯出與資料庫 SQL 備份保存成作業，立即執行或註冊到 Windows 工作排程器每天執行。入口在「工具 > 自動執行作業」。

支援的作業

類型 行為 執行紀錄
查詢 執行單一唯讀 SQL，不輸出檔案 成功／失敗、資料列數、耗時、原因
匯出 執行單一唯讀 SQL，輸出 CSV、XLSX、TSV、JSON、XML、HTML、Markdown 或 SQL 成功／失敗、資料列數、輸出路徑、耗時、原因
備份 使用既有 DatabaseDumpService 建立指定資料庫的邏輯 SQL 備份 成功／失敗、輸出路徑、耗時、原因
匯入 CSV 把 CSV 附加到既有資料表（RFC 4180 引號與換行、標題列依名稱對應、依欄位型別轉換、空欄位寫入 NULL） 成功／失敗、匯入列數、檔案路徑、耗時、原因
資料傳輸 把資料表傳到同一設定檔中的另一個連線與資料庫，沿用資料傳輸精靈的檢查點與列數驗證 成功／失敗、傳輸列數、耗時、各表失敗原因
資料字典 依作業保存的範本設定（完整／精簡／欄位總表、標題、主色、篩選）輸出 HTML 資料字典 成功／失敗、輸出路徑、耗時、原因

查詢與匯出會先經過保守的唯讀檢查，只接受單一 SELECT、WITH ... SELECT、SHOW、EXPLAIN、DESC 或 DESCRIBE。多段 SQL、DML／DDL、SELECT INTO 與可能實際執行查詢的 EXPLAIN ANALYZE 都會被拒絕。

匯入與傳輸設定

  • 匯入 CSV：在「匯入 CSV」分頁指定檔案（相對路徑放在「文件\mySQLPunk\automation-input」，可用與輸出路徑相同的替代文字）、目標資料表、分隔符號（逗號、分號、Tab、|）與是否有標題列。有標題列時欄位依名稱（不分大小寫）對應，CSV 有目標資料表沒有的欄位名稱時直接失敗；沒有標題列時依目標欄位順序對應。
  • 資料傳輸：在「傳輸」分頁選擇目標連線與資料庫，每行一張表：來源 => 目標 : create、append 或 replace（目標與方式可省略，預設附加），整個清單留空代表來源的所有資料表。傳輸進度存在 automation\transfers\<job-id>，失敗後下一次執行或重試會從中斷處續傳。含 replace 時會刪除目標表的全部資料，儲存作業前必須輸入目標資料庫名稱確認；目標資料庫改名後需重新確認。

重試與通知

  • 「失敗重試」可設 0–5 次與間隔秒數。傳輸作業重試時從檢查點續傳；CSV 匯入如果已經寫入部分資料就不會自動重試，避免重複匯入，執行紀錄會寫出已匯入的列數。
  • 「Webhook」會在作業結束後以 POST 送出 JSON：job、jobId、type、status、rows、attempts、message、startedUtc、finishedUtc、elapsedMs，不含 SQL、連線字串或密碼。網址必須是 https（http 只允許 localhost／127.0.0.1），且不可內含帳號密碼；可勾選「只在失敗時通知」。通知結果（HTTP 狀態或失敗原因）會寫入執行紀錄，通知失敗不影響作業本身的成功與否。

郵件通知

在自動執行作業畫面按「郵件設定」設定 SMTP 主機、連接埠、STARTTLS、帳號與寄件人，可先寄測試信確認。密碼存在 Windows 認證管理員（mySQLPunk:automation:smtp），automation\smtp.json 不含密碼；只有寄到 localhost／127.0.0.1 的伺服器可以關閉 STARTTLS。每個作業在「重試與通知」分頁填入收件人（逗號分隔，最多 10 位），作業結束後寄出純文字通知，內容與 Webhook 相同、不含 SQL 或認證；「只在失敗時通知」同時套用在郵件與 Webhook。勾選「成功時附加輸出檔」會把匯出、備份或資料字典的輸出檔（10 MB 以內）附加在信中。

建立與排程

  1. 先在連線設定中保存可使用的連線與密碼。
  2. 開啟「工具 > 自動執行作業」，按「新增」。
  3. 選擇作業類型、連線設定檔、連線與資料庫；查詢或匯出再填入 SQL。
  4. 匯出或備份需指定輸出路徑。相對路徑會放在「文件\mySQLPunk\automation-output」下。
  5. 如要定期執行，勾選「啟用排程」並選擇方式：每天、每週（勾選星期）、每 N 小時（自設定時間起，1–24 小時）或登入 Windows 時（延遲一分鐘），儲存後按「註冊排程」建立或更新 Windows 工作排程。

輸出路徑可以使用下列替代文字：

  • {job}：移除不合法檔名字元後的作業名稱
  • {yyyyMMdd}：執行日期
  • {yyyyMMdd_HHmmss}：執行日期與時間

例如 exports\{job}-{yyyyMMdd_HHmmss}.csv。

認證與執行權限

  • 作業 JSON 只保存連線設定檔名稱與連線顯示名稱，不保存主機連線字串、使用者密碼或 API 金鑰。
  • Windows 工作使用 InteractiveToken 與最低權限執行，不要求系統管理員權限。
  • 排程必須在建立排程的同一個 Windows 使用者已登入時執行，才能讀取該使用者的 Windows Credential Manager。
  • 若連線使用 SSL/TLS 或 SSH Tunnel，排程會沿用相同設定；SSH 密碼、私鑰密語與憑證密碼也由同一個 Windows 使用者的 Credential Manager 讀取。
  • 若搬動或重新安裝 mySQLPunk.exe，請在管理畫面重新註冊排程，讓執行檔路徑同步更新。

作業與紀錄位置

預設根目錄為 %LOCALAPPDATA%\mySQLPunk\automation：

automation/
├─ jobs/                 一個作業一個 JSON
└─ runs/<job-id>/        每次執行一個 JSON 紀錄

執行紀錄不複製 SQL 或認證，只保存作業識別、狀態、時間、耗時、資料列數、輸出路徑與錯誤原因。在管理畫面按「開啟作業資料夾」可以直接查看這些檔案；JSON 作業也可複製到另一台電腦後重新選用當地同名連線。

命令列執行

Windows 工作排程器實際呼叫同一個 CLI 入口，也可以手動測試：

.\mySQLPunk.exe --run-scheduled-job "$env:LOCALAPPDATA\mySQLPunk\automation\jobs\<job-id>.json"

成功回傳 exit code 0，作業執行失敗回傳 1，參數格式錯誤回傳 2。不論由畫面、CLI 或工作排程器啟動，都會寫入相同的執行紀錄。

目前限制

  • 第一版只有每日固定時間，還沒有每小時、每週或複雜觸發條件。
  • 尚未加入匯入、跨資料庫傳輸、郵件／Webhook 通知與失敗重試。
  • 排程採「使用者已登入才執行」，不適合無人登入的 Windows Server 服務帳號情境。