資料庫管理

Database Management 是管理介面中維護資料庫連線的區域，之後 MCP 金鑰會綁定到這些連線。每筆資料庫設定會保存資料庫類型與連線資訊；MCP 用戶端不會在每次請求中自行提供任意 connection string。

支援的資料庫

hs-sql-agent 透過共用 SQL provider 執行階段支援：

• PostgreSQL
• MySQL
• SQL Server
• Oracle
• SQLite
• Firebird

選定的 provider 同時決定 Query / DML 執行時使用的 SQL 方言與能力設定。

連線欄位

hs-sql-agent 的資料庫請求模型包含：

CreatedBy、UpdatedBy 也存在於 service request model，但屬於管理端中繼資料，不是 MCP 用戶端可以控制的欄位。

建立連線

在 Runtime → Database Management：

1. 建立資料庫項目，使用清楚且穩定的管理名稱。
2. 選擇 provider。
3. 輸入該 provider 所需的連線欄位。
4. 使用只具備 hs-sql-agent 實際需要權限的專用資料庫帳號。
5. 儲存後先驗證連線，再綁定正式環境的 MCP 金鑰。

後端會拒絕空白的 Name。除 SQLite 外，其餘 provider 也會拒絕缺少密碼的建立要求。

測試連線

管理端提供連線測試。測試既有 Database Management 項目時，伺服器會載入已保存的連線資料、解密密碼、重新建立 provider connection string，再執行對應 provider 的連線測試。

如果這一步失敗，應先從連線或設定問題著手，而不是直接追查 MCP SQL 行為。

常見原因包括：

• hs-sql-agent 程序無法連到指定 host / port；
• database / catalog 名稱錯誤；
• 登入憑證無效；
• ExtraSettings 缺少必要的 TLS / encryption 設定；
• 資料庫防火牆或網路政策阻擋；
• provider 有額外的身分驗證需求。

瀏覽資料庫中繼資料

具備 /runtime/db-management 的 view 權限時，Admin API 可以透過已保存的連線讀取 provider metadata：

• schemas；
• 指定 schema 下的資料表；
• 指定資料表的欄位。

這些操作會使用保存的 Database Management 項目重新建立 provider 連線。它和 MCP schema discovery 不完全相同；MCP discovery 還會套用已驗證 MCP 金鑰的資料表白名單與語意中繼資料。

綁定 MCP 金鑰

正式環境使用的 MCP 金鑰必須指向一個 Database Management 項目，該連線就會成為這把金鑰的資料庫邊界。

MCP 金鑰還可以進一步縮小權限：

• 工具允許清單；
• 資料表白名單；
• CORS 來源；
• 到期時間；
• 速率限制模式與覆寫值。

請見 MCP 金鑰。

資料表白名單不設定在 Database Management

Database Management 定義的是連線；資料表授權則套用在 MCP 金鑰上。

因此，多把 MCP 金鑰可以共用同一個實體資料庫連線，但各自擁有不同的資料表與工具範圍。例如報表用金鑰可以只開放報表資料表，另一把給操作流程使用的金鑰則可以擁有不同資料表集合與 DML 能力。

語意中繼資料綁定 Database Management

資料表與欄位的顯示名稱、說明、同義詞、關聯與指標，都會關聯到 Database Management 項目。因此 schema discovery 可以在不修改實體資料庫 schema 的情況下，提供更豐富的 MCP 中繼資料。

請見 語意中繼資料。

權限

hs-sql-agent Admin API 對 Database Management 操作使用明確權限：

因此，管理端使用者已登入不代表自動具備所有操作權限；每個操作仍會個別執行授權檢查。

操作建議

Database Management 項目應使用穩定名稱，也不要在仍有有效 MCP 金鑰綁定時，悄悄改變該連線所代表的資料庫意義。如果金鑰必須移動到另一個資料庫邊界，建議明確走一次金鑰生命週期流程，並重新確認資料表與工具範圍。

資料庫憑證與 provider 專用密鑰都應視為敏感資訊。不要把它們寫進 Custom Tool 範本或用戶端設定；用戶端只需要 MCP endpoint 與 MCP 金鑰。