attach-db

attach-db 技能概览

attach-db 的作用

attach-db 技能可以帮你挂载一个 DuckDB 数据库文件，让你能立刻通过 /duckdb-skills:query 开始查询。它面向 Database Engineering 工作流，核心目标是把本地 .duckdb 文件快速变成可用会话，而不是从零开始手动摸索数据库。

适合谁使用

如果你已经有一个 DuckDB 文件，并且希望这个技能帮你校验文件、检查 schema、准备可复用的状态文件，那么就适合用 attach-db。当你需要在多次查询之间保持一致的分析环境，或者想把“我有一个数据库文件”快速推进到“我可以开始提问”时，它尤其合适。

它为什么不一样

attach-db 不只是一个连接工具。它会检查 DuckDB 是否已安装，验证文件是不是有效的 DuckDB 数据库，并写入会话状态，方便后续查询通过 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 细节，比如表、列和行数，并写出一个共享的 state.sql 文件，这样后续 DuckDB 命令就能通过 duckdb -init 复用会话。用户通常最在意的就是这一点：重复的初始化步骤更少了。

先读这些文件

先查看 skills/attach-db 下的 SKILL.md。如果你要把这个技能接入更大的工作流，也建议顺带检查相邻、会消费已保存状态文件的 DuckDB skills，尤其是这个挂载步骤要支持的查询类技能。实际使用中，当你同时理解了验证路径和下游查询流程，attach-db 才最有价值。

attach-db 技能常见问题

attach-db 只适用于已经存在的 DuckDB 文件吗？

不是。这个技能也能处理文件尚不存在、之后可能才会创建的情况，但它会在继续前暂停并确认。这一点很重要，尤其当你在判断 attach-db 是否适合你的工作流时：它对已有文件是安全的，但它不是那种会盲目“替你创建任何我要求的东西”的工具。

如果我已经能直接跑 DuckDB 命令，还需要它吗？

如果你想要一个可重复的挂载与校验流程，还希望带上 schema 发现和已保存的会话状态，那就需要。普通提示也能连上数据库，但 attach-db 技能会在路径解析、数据库验证和状态复用上增加保护措施。如果你只需要一次性的查询，它可能就有点超出需要了。

attach-db 对新手友好吗？

整体上是友好的，因为这个技能是按步骤执行的，遇到失败也会明确停下来。新手最大的风险在于路径不够精确，或者误以为任何 .db 文件都是 DuckDB 数据库。只要你能提供准确的文件路径和一个基本目标，attach-db 的使用就比较直接。

什么时候不该用 attach-db？

如果你没有本地 DuckDB 文件、并没有使用 DuckDB 工具，或者你只需要高层建议而不是一个可查询的会话，那就不要用它。如果你的真实需求是数据库迁移或 ETL，它也不是正确选择，因为 attach-db 的重点是挂载并准备数据库用于分析，而不是转换数据库本身。

如何改进 attach-db 技能

提供更具体的目标

提升效果最明显的一点，就是把确切文件名和你下一步想回答的问题说清楚。对比一下“attach this database”和“attach ./warehouse.duckdb and prepare it for investigating customer churn tables.” 后者更能帮助技能校验正确的文件，也让 schema 扫描更有针对性。

明确预期状态

如果数据库可能缺失、损坏，或者是新创建的，提前说明。attach-db 技能在这些情况下的行为会不同，你的提示词也应该反映这一点。把预期说清楚，可以减少来回确认，也能帮助技能判断是继续、停止，还是需要你确认。

用第一次输出来决定下一次查询

挂载这一步只是准备层。等它返回表、列和行数后，再据此组织下一条查询提示，不要一口气把所有问题都塞进去。想要更好的结果，可以接着发更聚焦的请求，比如“只查询 sales 表”或“总结这个 schema 里最重要的五个维度”。

留意常见失败模式

最常见的失败模式是路径错误、文件并不是 DuckDB 数据库，以及误以为安装状态已经正确。只要技能提示有问题，通常应该先修正输入，而不是原样重试同一条提示。对于 Database Engineering 场景里的 attach-db 来说，文件路径这一步的准确性，往往比提示词长度更重要。