attach-db

attach-db スキルの概要

attach-db でできること

attach-db スキルは、DuckDB のデータベースファイルを接続し、/duckdb-skills:query で直ちにクエリできる状態にするためのスキルです。これは Database Engineering のワークフロー向けに作られており、ローカルの .duckdb ファイルを、手探りで調べる対象ではなく、すぐ使えるセッションへ変えることを主目的にしています。

どんな人に向いているか

すでに DuckDB ファイルを持っていて、その妥当性確認、スキーマの確認、再利用可能な state ファイルの準備まで任せたい場合に attach-db スキルを使ってください。複数のクエリにまたがって再現性のある分析をしたいときや、「データベースファイルはある」から「その中身について質問できる」までを素早く進めたいときに向いています。

何が違うのか

attach-db のガイドは、単なる接続補助ではありません。DuckDB がインストールされているかを確認し、ファイルが有効な DuckDB データベースかどうかを検証し、あとで duckdb -init によってセッションを自動復元できるよう状態を書き込みます。つまり、信頼性を重視し、クエリ前のセットアップ負担を減らしたい場面で役立つスキルです。

attach-db スキルの使い方

attach-db をインストールして呼び出す

attach-db スキルを DuckDB skills セットにインストールし、データベースファイルへのパスを指定して呼び出します: attach-db <path-to-database.duckdb>。たとえば、「データベースを attach して」といった曖昧な依頼ではなく、実際のファイルパスを使ってください。スキルは、そのパスをもとにファイルを解決し、検証し、開く必要があるためです。

スキルに正しい入力を渡す

最も良い入力は、正確なデータベースパスに加えて、意図を短く補足することです。たとえば、そのファイルを read-only として扱うのか、すでに存在しているはずなのか、次に何をクエリしたいのかを伝えます。より良いプロンプトの例は「./data/sales.duckdb を attach して、注文と売上に関連するテーブルを確認したい」です。こうすると、スキーマ探索を本当に重要な部分に絞りやすくなります。

実際のワークフローで何が起きるか

attach-db スキルは、相対パスの解決、ファイルの存在確認、DuckDB の利用可否チェック、データベースの検証を順に行ってから処理を進めます。その後、テーブル、カラム、行数などのスキーマ情報を調べ、共有可能な state.sql ファイルを書き出して、今後の DuckDB コマンドが duckdb -init 経由で同じセッションを再利用できるようにします。ユーザーにとって特に価値があるのはここで、繰り返しのセットアップ手順を減らせます。

まず読むべきファイル

まずは skills/attach-db の SKILL.md を確認してください。より大きなワークフローに組み込む場合は、保存された state ファイルを利用する隣接の DuckDB skills も見ておくとよいです。特に、attach の次に続く query 系のスキルは重要です。実務では、検証の流れと、その後のクエリ実行フローの両方を理解しておくと、attach-db の価値が最大化します。

attach-db スキル FAQ

attach-db は既存の DuckDB ファイル専用ですか？

いいえ。ファイルがまだ存在しない場合でも、後で作成される可能性があるケースを扱えますが、その場合は先に確認を挟んでから進みます。これは attach-db があなたのワークフローに合うかを判断するうえで重要です。既存ファイルには安全に使えますが、何でも勝手に作るタイプの補助ではありません。

すでに DuckDB コマンドを実行できるなら、これも必要ですか？

はい。再現性のある attach-and-validate ワークフロー、スキーマ探索、保存済みセッション状態が欲しいなら必要です。通常のプロンプトでもデータベースに接続はできますが、attach-db スキルにはパス解決、データベース検証、状態の再利用に関するガードレールがあります。単発のクエリだけなら、このスキルは過剰かもしれません。

attach-db は初心者向けですか？

概ねはい。手順が明確で、失敗したときもはっきり止まるからです。初心者がつまずきやすいのは、パスを曖昧にすること、あるいは .db ファイルなら何でも DuckDB データベースだと思い込むことです。正確なファイルパスと基本的な目的を伝えられるなら、attach-db ガイドは使いやすいはずです。

attach-db を使わないほうがよいのはどんなときですか？

ローカルの DuckDB ファイルがない場合、DuckDB ツールを使っていない場合、あるいはクエリ可能なセッションではなく高レベルの助言だけが欲しい場合は避けてください。また、実際の目的がデータベース移行や ETL であれば、これも不向きです。attach-db はデータベースを attach して分析できる状態に整えるためのもので、変換処理を行うものではありません。

attach-db スキルを改善するには

対象をもっと具体的にする

最も大きな品質向上は、正確なファイル名と、次に知りたい質問を明示することです。「このデータベースを attach して」よりも、「./warehouse.duckdb を attach して、顧客離反のテーブル調査に使えるよう準備して」と書くほうがよいでしょう。後者なら、スキルが正しいファイルを検証しやすくなり、スキーマの確認もより関連性の高いものになります。

想定される状態をはっきり伝える

データベースが見つからない可能性があるのか、破損しているのか、新規作成されたばかりなのかは、あらかじめ伝えてください。attach-db スキルはそうした状況で挙動が変わるため、プロンプトにもそれを反映させるべきです。期待状態を明確にすると、やり取りの往復が減り、続行するのか停止するのか確認を求めるのかをスキルが判断しやすくなります。

最初の出力を次のクエリに活かす

attach の段階はあくまで準備です。テーブル、カラム、行数が出力されたら、その結果を次のクエリの設計に使い、一度に何でも聞こうとしないでください。より良い結果を得るには、「sales テーブルだけをクエリして」や「このスキーマの上位 5 つの次元を要約して」といった、焦点を絞った依頼で続けるのが効果的です。

ありがちな失敗パターンに注意する

主な失敗パターンは、パスの誤り、DuckDB ではないファイル、そしてインストール状態がすでに正しいと思い込むことです。スキルが問題を報告したら、同じプロンプトをそのまま再実行するのではなく、入力を直してください。Database Engineering の作業で attach-db を使うなら、プロンプトの長さよりもファイルパスの正確さのほうが重要になることが多いです。