tablestudioapp/plugins

透過 TableStudio 進行資料庫操作

TableStudio 是使用者在 Mac 上的資料庫應用程式。其 MCP 工具無需憑證即可存取已儲存的連線，並且具備原始 psql 工作階段所沒有的安全措施：針對實際資料列的精確寫入預演、可拋棄的沙箱副本，以及一個使用者可核准變更的檢閱收件匣。請使用這些工具進行資料庫工作，而不是使用 psql、mysql、sqlite3 或自行建立連線的腳本。

以下列出的工具名稱是 TableStudio 的。你的客戶端可能會顯示它們帶有前綴（在 Claude Code 中為：mcp__plugin_tablestudio_tablestudio__list_connections）。如果它們是延遲載入的，請在首次呼叫前先根據該名稱載入。

1. 開始任何操作前，先找到正確的資料庫

工作階段的資料庫上下文註記（來自 TableStudio 外掛程式）通常會指明該儲存庫每個資料庫設定背後的 TableStudio 連線名稱，以及其 ID 和環境。請使用該 ID 作為 connection_id。該註記也會說明何時無法使用 TableStudio 的工具，以及使用者應如何處理。

如果沒有註記，或針對註記未提及的資料庫：

1. 呼叫 list_connections。每個連線可能帶有使用者告訴 TableStudio 的資訊：
   • project：它屬於哪個專案。優先選擇專案與你正在處理的儲存庫相符的連線。
   • environment：development、staging 或 production。若無則表示未標記，而非開發環境。
   • read_only：TableStudio 會拒絕對其進行寫入。Staging 仍可寫入。
   • location：local（此 Mac）、remote 或 sandbox（可拋棄的副本，可安全進行實驗）。
   • agent_writes：direct 表示 execute_query 可能會在該處寫入（當寫入功能開啟時）；review 表示每個變更都會透過 stage_migration 交由使用者套用。這由 TableStudio 決定，而非你：生產環境，以及使用者未標記為 development 或 staging 的任何遠端資料庫，都會是 review。
   • notes：使用者對該資料庫慣例的備註（軟刪除、金額單位為分、命名規則）。請遵循這些備註。
2. 首先比對專案，然後根據專案自己的設定（.env、config）使用 host、port 和 database 進行確認。
3. 如果兩個連線都可能是使用者所指的，或者你無法判斷某個連線是否為生產環境，請詢問。不要猜測。

然後：

• 在規劃任何讀取以外的操作之前，先呼叫一次 describe_capabilities。它會說明目前是否允許直接寫入、暫存和沙箱功能，並指出每個功能背後的設定。請據此規劃，而不是在遭到拒絕時才發現限制。
• agent_writes: review（生產環境，或遠端且未標記）表示永遠不要直接對其寫入：請將變更暫存以供檢閱。無論如何，TableStudio 都會拒絕對其進行直接寫入，因此請從一開始就計劃使用暫存。
• 在撰寫 SQL 之前，請檢查 engine（postgres、mysql、sqlite、d1、clickhouse），並使用該方言撰寫。
• 未儲存在 TableStudio 中的資料庫無法透過其工具存取。請使用者在 TableStudio 中新增它。切勿在聊天中要求密碼。
• 如果因為資料庫無法連線而導致呼叫失敗，請呼叫 connection_status。當它顯示本機伺服器已停止時，請使用它提供的 instance_id 呼叫 start_local_database。

2. 讀取與調查

• 查詢資訊，不要猜測名稱：search_schema 可依名稱片段尋找資料表和欄位，而 get_table_ddl 則提供完整的結構、索引、外部鍵和 referenced_by。
• 使用 execute_query 執行讀取。選取你需要的欄位、過濾、聚合，並加上 LIMIT。結果有上限（max_rows，預設為 200），因此 truncated 的結果並非完整答案。
• 讀取操作在唯讀交易中執行，限制 30 秒，即使在生產環境也是如此，因此讀取無法透過函數改變資料。但仍請保持輕量：對於大型生產環境資料表，請使用索引欄位進行過濾，或使用 database_overview 的資料列估算，而不是 count(*)。
• 資料錯誤： 首先在資料中重現它。找出有問題的資料列、計算數量，並找出它們何時開始出現（min(created_at)）。然後讀取寫入它們的程式碼。向使用者展示證明此問題的查詢。修復程式碼，如果需要修復資料列，那就是資料變更（第 3 節）。
• 切勿將機密、密碼或連線字串貼到 SQL、程式碼、文件或聊天中。連線字串唯一應屬的地方是專案的 gitignored 環境變數檔案，用於本機資料庫（本機資料庫技能涵蓋了 get_connection_url）。

3. 變更資料（INSERT、UPDATE、DELETE）

對於 PostgreSQL：

1. 撰寫陳述式，然後使用該陳述式呼叫 preflight_statement。你會收到一個 verdict（looks_fine、review 或 would_fail）、dry_run.rows（它會精確影響多少資料列，唯讀）、級聯到其他資料表的影響，以及可能導致失敗的原因。
2. 用白話告訴使用者它會做什麼：「這會更新 invoices 中的 142 筆資料列；不會級聯到其他資料表。」如果 verdict 是 would_fail，請先修正該陳述式。如果是 review，請說明原因。
3. 然後選擇其中一種方式：
   • agent_writes: direct，且允許直接寫入： 使用 expected_rows 設為 dry_run.rows 的 execute_query。只有當恰好有這麼多資料列受到影響時，它才會提交，否則會復原。在遠端 PostgreSQL 資料庫上，如果沒有 expected_rows，TableStudio 會拒絕資料變更。
   • agent_writes: review、不允許寫入，或使用者應先看到的任何內容： 使用清晰的 title、SQL 以及包含乾執行計數的 rationale（「清除由……找到的 142 筆重複發票」）來呼叫 stage_migration。它會進入使用者在 TableStudio 代理中心裡的檢閱佇列，並且不會執行。

對於其他引擎，沒有乾執行：首先使用相同的 WHERE 執行 SELECT count(*)，回報計數，然後遵循相同的執行或暫存規則。

在對重要的資料庫執行破壞性操作（大型 DELETE、DROP、TRUNCATE）之前，如果沙箱功能已啟用，請呼叫 create_restore_point，並告知使用者你已這麼做。

4. 變更結構描述

如果儲存庫使用了遷移工具（Prisma、Drizzle、Rails、Django、Alembic、Laravel、Supabase、Knex、Ecto、TypeORM、Wrangler D1 或純編號 SQL 檔案；當外掛程式檢測到時，工作階段上下文會命名它），則變更應屬於該工具：

1. 以該工具的方式進行變更：編輯結構描述並產生遷移，或撰寫遷移檔案。
2. 使用該工具的開發命令將其套用到本機開發資料庫。
3. 根據真實資料進行檢查（如下所述）。
4. 將其應用到其他任何地方則留給使用者正常的部署流程。切勿自行針對生產環境執行該工具的部署命令。

當遷移工具擁有結構描述時，直接執行 ALTER TABLE 會使工具的歷史記錄與資料庫不同步，從而中斷下一次部署。

如果沒有遷移工具，或使用者要求對現有資料庫進行一次性變更：

1. 首先使用 get_table_ddl 讀取資料表。在刪除或重新命名任何內容之前，請檢查 referenced_by。
2. 在副本上嘗試：create_sandbox（data：none 僅用於結構描述，sample 用於部分真實資料列），使用 execute_query 在沙箱的連線上執行 DDL，並檢查它是否如你所願。
3. 使用 compare_schemas（沙箱作為 source_connection_id，真實資料庫作為 target_connection_id）顯示差異。
4. 使用真實連線上的 stage_migration 提出變更。使用者會從 TableStudio 套用它。

根據真實資料檢查遷移

在本機資料庫上通過的遷移，仍可能因為真實資料列而失敗或鎖定應用程式。在宣布遷移完成之前，請以唯讀方式針對它將部署到的資料庫（通常是 staging 或 production，來自工作階段註記或 list_connections）進行檢查：

1. 為每個它會修改的資料表執行 get_table_ddl：包含多少資料列、其索引，以及哪些東西參照它。

2. 對於它新增的每個限制條件，使用 execute_query 執行 SELECT 來找出會違反它的資料列：

   • NOT NULL：SELECT count(*) FROM t WHERE col IS NULL
   • UNIQUE：SELECT col, count(*) FROM t GROUP BY col HAVING count(*) > 1 LIMIT 20
   • 外部鍵：父資料列不存在的子資料列（LEFT JOIN … WHERE parent.id IS NULL）
   • CHECK，或更嚴格的型別或長度：超出新範圍的資料列

   任何資料列都表示部署會失敗。請在遷移中新增回填或清理步驟，並說明。

3. 在 PostgreSQL 上，標記會鎖定或重寫大型資料表的步驟（見下文），並切換到安全模式。

4. 當變更較棘手時，在副本上實際執行它：從該連線使用 data: "sample" 建立 create_sandbox，在沙箱上使用 execute_query 執行遷移的 SQL，然後執行 compare_schemas。

告訴使用者你檢查了什麼以及發現了什麼（「orders.status 在 120 萬筆資料列中沒有 NULL 值，因此 SET NOT NULL 是安全的。」）。所有這些都是唯讀的：除了本機開發資料庫之外，絕對不要在任何地方套用遷移。

PostgreSQL 上的鎖定

• 在大型繁忙的資料表上建立索引：使用 CREATE INDEX CONCURRENTLY。它無法在交易內部執行，因此不要將該陳述式包在 BEGIN … COMMIT 中。
• 新增帶有 volatile 預設值的 NOT NULL 欄位、變更欄位型別或新增外部鍵，可能會重寫或鎖定資料表。請在 rationale 中說明，並考慮將其拆分為安全的步驟（先新增可為 null 的欄位，分批回填，然後 SET NOT NULL；先新增 NOT VALID 的外部鍵，然後 VALIDATE CONSTRAINT）。
• schema_issues 會傳回每個問題的修復 SQL 及其 lock_impact。在提出修復方案之前請先閱讀它。

5. 暫存某些內容之後

• 告訴使用者它正在 TableStudio 中等待他們的檢閱，並且尚未執行，並將結果中的 review_url 作為連結提供給他們。它會開啟檢閱頁面，顯示變更的影響（它影響的資料列、鎖定、可能失敗的原因）、變更後的結構描述圖表，以及復原計畫。永遠不要說暫存的變更已被套用。
• 如果使用者要求變更，list_staged_migrations 會顯示 status: changes_requested 以及他們在 review_feedback 中的備註。使用 update_staged_migration（相同的 migration_id）進行修訂，而不是暫存第二個副本，然後告訴他們可以再次查看了。要撤回它，請使用 remove_staged_migration。
• list_staged_migrations 也會顯示使用者是否套用、忽略或失敗了該遷移。

當使用者詢問有什麼在等待他們（「你暫存了什麼？」、「我的遷移執行成功了嗎？」）時，請為此儲存庫的連線呼叫 list_staged_migrations。首先回報待處理的項目，最新的優先：標題、連線、暫存時間、其 review_url，以及一行說明其作用及風險程度（它會鎖定或重寫大型資料表、刪除資料，或缺少 WHERE 嗎？）。然後回報任何已要求變更的項目（附帶使用者的備註），以及任何失敗的項目（附帶錯誤）。直接說明使用者可以在 TableStudio 的代理中心套用、退回或忽略它們；你不能自行套用它們。

6. 當 TableStudio 拒絕時

• 指定了某個設定（例如，寫入功能已關閉）的拒絕，是使用者的選擇。告訴他們哪個設定可以允許它，改為提供暫存變更的選項，然後停止。不要繞過它。
• 如果 TableStudio 的工具完全不可用，工作階段註記會說明原因：應用程式已關閉、其 MCP 伺服器已關閉（設定 → MCP），或客戶端尚未連接到它。傳達它提供的修復方式。在 Claude Code 中，使用者可以在 TableStudio 開啟後使用 /mcp 重新連接。
• 帶有 blocked: production_review_required 或 review_required 的拒絕，表示該連線僅接受透過檢閱進行的變更：請暫存它。dry_run_required 表示先執行 preflight_statement 並傳入 expected_rows。side_effect_function 表示該陳述式呼叫了在交易外部作用的內容；請改向使用者展示 SQL。
• 此外掛程式的 shell 守護程式會封鎖寫入生產環境的 shell 命令。請將封鎖視為使用上述步驟的信號，而不是需要繞過的東西。
• 你透過 TableStudio 所做的一切都會在其代理中心中向使用者顯示，並按此對話分組。