motherduck-connect

MotherDuck に接続する

信頼できる情報源

• MotherDuck の接続、アタッチモード、読み取りスケーリング、マルチスレッドに関する最新のドキュメントを優先してください。
• MotherDuck MCP の ask_docs_question ツールを利用できる場合は、まずそれを使って最新の接続動作を確認してください。
• 利用できない場合は、接続文字列、トークンの種類、読み取りスケーリングの動作について断定する前に、公開ドキュメントで指針を確認してください。

基本方針

• PostgreSQL のワイヤープロトコル互換性を求めるバックエンドアプリケーション、BI ツール、サーバーレスランタイムには、まず PG エンドポイント（MotherDuck の PostgreSQL 互換エンドポイント）を使ってください。
• BI ツールでは、最新のドキュメントで対応が明記されている場合、Power BI と Tableau Cloud との互換性を確保する方法として PG エンドポイントを扱ってください。
• ローカルファイル、ローカルとクラウドのハイブリッド実行、または DuckDB の直接制御が必要な場合は、ネイティブ DuckDB API を使ってください。
• 複数データベースの探索、ブートストラップのフロー、一時的な検証環境には、md: ワークスペース接続を使ってください。
• ユーザーのコンテキストに既存の接続、コネクター、または環境で管理されているトークンがある場合は、それを再利用してください。アクティブなワークスペースから確認できるシークレットをユーザーに尋ねないでください。MotherDuck MCP サーバーだけが接続されていて、一時的なローカルセッションに認証情報が必要な場合は、get_short_lived_token が一時トークンとエンドポイントの詳細を返します。プロセス環境経由で渡し、ファイル、コード、ログには絶対に書き込まないでください。デプロイ済みのサービスには、引き続きサービスアカウントトークンが必要です。
• まずは接続を 1 つだけ使ってください。実際に同時読み取りの負荷が生じた場合にのみ、プーリングまたは読み取りスケーリングを追加してください。
• Duckling の起動中に待機するのではなくフェイルオーバーする必要があるサービスでは、ネイティブの md: 接続に connection_timeout を設定してタイムアウトを設けてください（md:my_db?connection_timeout=30s、MOTHERDUCK_CONNECTION_TIMEOUT、または最初の ATTACH 'md:' の前に SET motherduck_connection_timeout = '30s' を実行）。この設定が適用されるのは、MotherDuck 拡張機能を備えた DuckDB クライアントであり、PG エンドポイントや Wasm ではありません。この設定がない場合、上限が設けられるのはネットワークの再試行のみです。
• 対応している場合は、ネイティブ DuckDB の custom_user_agent を使ってください。PG エンドポイントのクライアントでは、利用できる場合、クライアントの application_name 設定を優先してください。このタグは Duckling Overview でクエリごとに表示されるため、どのワークロードが Duckling を使用しているかを最も手早く確認できます。

ランタイムの選択

接続方法（上記）とランタイムは別々に選んでください。ランタイムは、実際にクエリを実行するものです。MotherDuck MCP、MotherDuck CLI、Python または Node のプロセス、DuckDB CLI などがあります。

回答、レビュー、計画の依頼では、利用可能なランタイムを確認し、何もインストールせずに方法を提案してください。ランタイムのインストールや設定は、ユーザーが接続、構築、またはアプリケーションの変更を依頼した場合にのみ行ってください。

プロジェクトの言語、依存関係、既存の接続を再利用してください。チャットのみでの探索には MCP を、ファイル形式の Dive／Flight 作業や大規模な出力には MotherDuck CLI を優先してください。アプリケーションコードでは既存のランタイムを使い、確立されていない場合にのみ新しいランタイムを選んでください。

DuckDB クライアントをインストールする前に、https://motherduck.com/docs/duckdb-versions.json を確認し、MotherDuck がサポートするバージョンに固定してください。既存の互換性のあるバージョン固定は、タスクでアップグレードが必要な場合を除き維持してください。インストール例については、ランタイムリファレンスを参照してください。

ワークフロー

1. ワークロードに合わせて接続方法を選びます。ニーズが異なる場合は、取り込み経路と提供経路を分けてください。
2. MotherDuck トークンはソースコードではなく、環境で管理されるシークレットに保存します。
3. 必要な場合は SSL 設定を明示して接続を確立します。
4. SELECT 1 AS connected で接続を確認し、続けてアクセス可能なテーブルを一覧表示します。
5. ワークロードが読み取り中心で同時実行される場合は、読み取りスケーリングと、エンドユーザーごとに安定した session_name を使用することを検討します。

参考資料

現在のタスクに必要な参考資料のセクションだけを読んでください。

• 接続方法の選択、PG エンドポイントとネイティブ DuckDB の例、トークンの扱い、読み取りのスケーリング、アタッチモード、よくある失敗については、references/CONNECTION_GUIDE.md を読んでください
• MCP と Python、Node、CLI の選択フローチャート、検出コマンド、インストール例、DuckDB のバージョン固定の手順については、references/RUNTIME_SELECTION.md を読んでください

関連スキル

不足している機能を補う場合に限り、関連スキルを読み込んでください。確立済みのコンテキストを再利用してください。

• 接続確立後のデータベース、テーブル、列、共有の検出には、motherduck-explore を使用します
• 接続済みのデータベースに対して DuckDB SQL を実行するには、motherduck-query を使用します
• DuckDB の構文や関数を調べるには、motherduck-duckdb-sql を使用します
• コントロールプレーンの管理操作には、motherduck-rest-api を使用します。これらの操作では MOTHERDUCK_ADMIN_TOKEN を使用します。このトークンはデータベース接続には決して使用しません
• ターミナルでのクエリや、ファイルベースの Dive／Flight の作成には、motherduck-cli を使用します