attach-db

attach-db 技能總覽

attach-db 的用途

attach-db 技能可協助你把 DuckDB 資料庫檔附加進來，讓你能立即透過 /duckdb-skills:query 查詢。它是為 Database Engineering 工作流程設計的，重點是把本機 .duckdb 檔轉成可直接使用的 session，而不是從零開始手動摸索資料庫。

誰適合使用

如果你手上已經有 DuckDB 檔，並且希望技能幫你驗證檔案、檢查 schema，還能準備可重複使用的狀態檔，就很適合用 attach-db。當你需要跨多次查詢做可重現分析，或想快速從「我有一個資料庫檔」走到「我可以開始問問題」時，這個技能特別合適。

為什麼它不一樣

attach-db 指南不只是連線工具而已。它會檢查 DuckDB 是否已安裝、確認檔案是不是有效的 DuckDB 資料庫，並寫入 session state，讓之後的查詢可以透過 duckdb -init 自動還原。這讓它在你重視穩定性、又希望在查詢前減少設定摩擦時特別實用。

如何使用 attach-db 技能

安裝並呼叫 attach-db

先把 attach-db 技能安裝到 DuckDB skills 集合中，接著用資料庫檔案路徑呼叫它：attach-db <path-to-database.duckdb>。例如，請使用實際檔案路徑，不要只丟一句像「attach my database」這種模糊指令，因為這個技能需要明確路徑才能解析、驗證並開啟檔案。

提供正確的輸入

最好的輸入是精確的資料庫路徑，再加上一小段你的目的說明，例如這個檔案是否應該視為唯讀、你預期它是否已經存在、以及下一步想查什麼。更好的提示像是：「Attach ./data/sales.duckdb so I can inspect tables related to orders and revenue.」這樣能讓技能把 schema 探索聚焦在真正重要的地方。

實際工作流程會做什麼

attach-db 技能會解析相對路徑、檢查檔案是否存在、確認 DuckDB 可用，並在繼續前驗證資料庫。接著它會探索 schema 細節，例如 tables、columns 和 row counts，然後寫出共用的 state.sql 檔，讓未來的 DuckDB 指令可以透過 duckdb -init 重用同一個 session。這通常也是使用者最在意的部分：減少重複設定步驟。

先讀這些檔案

先從 skills/attach-db 裡的 SKILL.md 開始。如果你要把這個技能整合進更大的工作流程，也請查看旁邊會讀取已儲存狀態檔的其他 DuckDB skills，尤其是 attach-db 這一步原本要支援的查詢相關技能。實務上，當你同時理解驗證流程和後續查詢流程時，attach 這一步才最有價值。

attach-db 技能 FAQ

attach-db 只適用於已存在的 DuckDB 檔案嗎？

不是。這個技能也能處理檔案尚未存在、之後可能才會建立的情況，但它會先停下來確認再繼續。這點在你判斷 attach-db 是否符合流程時很重要：它對既有檔案是安全的，但它不是一個會毫無確認就「幫我隨便建立」的工具。

如果我已經可以直接跑 DuckDB 指令，還需要這個嗎？

如果你想要的是可重複的 attach-and-validate 工作流程，還要包含 schema 發現與已儲存的 session state，那答案是需要。一般提示也可以連上資料庫，但 attach-db 技能會在路徑解析、資料庫驗證和狀態重用上加上保護機制。如果你只是要一次性的查詢，這個技能可能就超出需求了。

attach-db 對初學者友善嗎？

大致上是，因為這個技能是流程導向的，而且一旦出錯會明確停下來。初學者最大的風險，是路徑給得不精準，或以為任何 .db 檔都一定是 DuckDB 資料庫。只要你能提供精確檔案路徑和基本目標，attach-db 指南其實很直覺。

什麼情況下不該用 attach-db？

如果你沒有本機 DuckDB 檔、沒有使用 DuckDB 工具鏈，或你要的只是高層次建議而不是可查詢的 session，就先不要用它。如果你的真正需求是資料庫遷移或 ETL，也不適合用它，因為 attach-db 的重點是附加並準備資料庫供分析，不是做資料轉換。

如何改進 attach-db 技能

提供更明確的目標

最大的品質提升，通常來自指定精確檔案，以及你下一個想回答的問題。把「attach this database」和「attach ./warehouse.duckdb and prepare it for investigating customer churn tables」相比，後者更能幫技能驗證正確檔案，也讓 schema 掃描更有關聯性。

把預期狀態講清楚

如果資料庫可能遺失、損毀，或是剛建立，請一開始就說明。attach-db 技能在這些情況下的行為不同，你的提示也應該反映這點。清楚的預期可以減少來回確認，並幫助技能判斷是該繼續、停止，還是要求你確認。

用第一次輸出去引導下一個查詢

attach 這一步只是準備層。當它回報 tables、columns 和 row counts 之後，請利用這些輸出來塑造下一個查詢提示，而不是一次把所有問題都丟出去。想要更好的結果，可以接著下這類聚焦請求：query only the sales tables 或 summarize the top five dimensions in this schema。

注意常見失敗模式

最常見的失敗模式包括路徑錯誤、非 DuckDB 檔案，以及誤以為安裝狀態已經正確。如果技能回報問題，應該修正輸入，而不是用完全相同的提示重試。對於 Database Engineering 工作裡的 attach-db 來說，在檔案路徑這一層的精準度，通常比提示長度更重要。