motherduck-connect

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Connect to MotherDuck

连接至MotherDuck

Use this skill when establishing database connectivity from any application, script, or service to MotherDuck. Start here before running queries or loading data.

当从任意应用、脚本或服务建立与MotherDuck的数据库连接时，可使用本技能。在执行查询或加载数据前，请先阅读本文档。

Source Of Truth

权威来源

Prefer current MotherDuck connection, attach-mode, read-scaling, and multithreading docs.
If the MotherDuck MCP
```
ask_docs_question
```
feature is available, use it first for current connection behavior.
When it is unavailable, verify guidance against the public docs before making firm claims about connection strings, token types, or read-scaling behavior.

优先参考最新的MotherDuck连接、附加模式、读取扩展及多线程文档。
如果MotherDuck MCP的
```
ask_docs_question
```
功能可用，请先使用该功能获取当前连接行为的相关信息。
当该功能不可用时，在对连接字符串、令牌类型或读取扩展行为做出明确说明前，请先对照公开文档验证相关指引。

Default Posture

默认准则

Start with the PG endpoint for backend applications, BI tools, and serverless runtimes that want PostgreSQL wire compatibility.
For BI tools, treat the PG endpoint as the compatibility path for Power BI and Tableau Cloud when current docs list them as supported.
Use the native DuckDB API only when you need local files, hybrid local/cloud execution, or direct DuckDB control.
Use
```
md:
```
workspace connections for multi-database exploration, bootstrap flows, and temporary validation environments.
Reuse an existing connection, connector, or environment-managed token when the user's context already provides one; do not ask for secrets that can be discovered from the active workspace.
Start with one connection. Add pooling or read scaling only when real concurrent-read pressure exists.
Use native DuckDB
```
custom_user_agent
```
where supported; for PG endpoint clients, prefer the client's
```
application_name
```
setting when available.

对于需要PostgreSQL协议兼容性的后端应用、BI工具及无服务器运行时，优先使用PG端点。
对于BI工具，当现有文档列出Power BI和Tableau Cloud为支持工具时，将PG端点作为它们的兼容路径。
仅当需要本地文件、混合本地/云端执行或直接控制DuckDB时，才使用原生DuckDB API。
对于多数据库探索、引导流程及临时验证环境，使用
```
md:
```
工作区连接。
当用户上下文已提供现有连接、连接器或环境管理的令牌时，请复用这些资源；不要询问可从活跃工作区获取的机密信息。
初始建立一个连接。仅当存在实际并发读取压力时，再添加连接池或读取扩展。
在支持的情况下使用原生DuckDB的
```
custom_user_agent
```
；对于PG端点客户端，优先使用客户端的
```
application_name
```
设置（如果可用）。

Workflow

工作流程

Choose one connection method and do not mix methods in the same application.
Put the MotherDuck token in environment-managed secrets, not in source code.
Establish the connection with explicit SSL settings where required.
Verify the connection with
```
SELECT 1 AS connected
```
and then list reachable tables.
If the workload is read-heavy and concurrent, evaluate read scaling and
```
session_hint
```
.

选择一种连接方式，不要在同一应用中混合使用多种方式。
将MotherDuck令牌存储在环境管理的机密中，不要放入源代码。
在需要的情况下，使用明确的SSL设置建立连接。
通过执行
```
SELECT 1 AS connected
```
验证连接，然后列出可访问的表。
如果工作负载以读取为主且存在并发情况，请评估读取扩展和
```
session_hint
```
。

Open Next

后续参考

```
references/CONNECTION_GUIDE.md
```
for connection-method selection, PG endpoint and native DuckDB examples, token handling, read scaling, attach modes, and common failure modes

```
references/CONNECTION_GUIDE.md
```
：包含连接方式选择、PG端点与原生DuckDB示例、令牌处理、读取扩展、附加模式及常见故障模式的内容