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 会返回临时令牌和端点详情；通过进程环境传递它，绝不要将其写入文件、代码或日志。已部署的服务仍需要服务账号令牌。
• 从单个连接开始。只有在确实存在并发读取压力时，才添加连接池或读取扩展。
• 对于应在 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。

参考资料

仅阅读当前任务所需的参考章节。

• 阅读 references/CONNECTION_GUIDE.md，了解连接方式的选择、PG 端点和原生 DuckDB 示例、令牌处理、读取扩展、附加模式和常见故障
• 阅读 references/RUNTIME_SELECTION.md，了解 MCP、Python、Node 和 CLI 的决策树、检测命令、安装片段以及 DuckDB 版本固定工作流

相关技能

仅在缺少相关能力时加载相关技能；复用已有上下文。

• motherduck-explore：建立连接后，用于发现数据库、表、列和共享
• motherduck-query：用于对已连接的数据库执行 DuckDB SQL
• motherduck-duckdb-sql：用于查询 DuckDB 语法和函数
• motherduck-rest-api：用于控制平面管理操作；这些操作使用 MOTHERDUCK_ADMIN_TOKEN，该令牌绝不用于数据库连接
• motherduck-cli：用于执行终端查询，以及以文件为基础编写 Dive/Flight