postgres-nio

postgres-nio 技能概览

postgres-nio 是用来做什么的

postgres-nio 技能帮助你在 Swift 中使用 PostgreSQL，支持 async/await、连接池、prepared statements 和类型安全的查询模式。它最适合后端开发团队，用来构建需要真实 PostgreSQL 客户端的服务端应用，而不是泛泛地写一段 SQL 提示。

最适合哪些读者和任务

如果你需要把 Swift 服务连接到 Postgres，安全地解码行数据，或者在不手写脆弱字符串拼接的情况下建模查询参数，那么就该用 postgres-nio 技能。它特别适合你的目标是交付数据库访问代码，而不仅仅是理解 PostgreSQL 理论。

为什么值得安装这个技能

它的核心价值在于实操型实现指导：如何配置客户端、执行查询、管理生命周期，以及避免常见的 SQL 注入错误。postgres-nio 技能尤其适合你希望输出严格贴合该库 Swift-first API，而不是照搬其他语言建议的时候。

如何使用 postgres-nio 技能

安装技能并打开正确的文件

通过你的技能管理器运行 postgres-nio install，或者如果你的工作流更适合，也可以从 Joannis/claude-skills 添加。然后先读 SKILL.md，再读 references/postgres-patterns.md，因为这两个文件包含了 postgres-nio 使用中最有决策价值的信息。

给模型一个真实的 Swift 数据库任务

像“帮我用 postgres-nio”这种弱提示，通常只会得到泛泛的回答。更强的提示要说明环境、数据形状和操作：

Use postgres-nio to build a Swift async repository for users.
I need PostgreSQL connection pooling, TLS off in local dev, a query that returns id, email, and createdAt, and safe parameter binding for a lookup by email.
Show the client setup, one read query, and one insert.

这样更有效，因为它明确告诉技能要怎么配置、查询什么，以及哪些安全约束最重要。

先定客户端配置，再定查询形状

在 postgres-nio 的使用里，顺序很重要：先选 PostgresClient 或更底层的连接路径，再决定行数据应该如何解码，最后再细化错误处理。如果你只提供 SQL，模型可能会遗漏连接池、服务生命周期或行解码这些会直接影响代码能否顺利运行的细节。

注意会影响输出质量的仓库章节

想要更好的结果，在提问前先看 Quick Start、Installation、Basic Usage 和 Type-Safe Queries 这些部分。如果你的任务涉及绑定规则或 SQL 安全，也要查看 references/postgres-patterns.md，因为那里展示了该技能预期采用的插值方式。

postgres-nio 技能 FAQ

postgres-nio 只适合 Swift 后端开发吗？

大体上是。postgres-nio 技能面向需要访问 PostgreSQL 的 Swift 服务、API、worker 和命令行工具。它不太适合前端代码，也不适合其他语言里的数据库任务。

这和普通提示有什么不同？

普通提示可以描述“在 Swift 中使用 PostgreSQL”，但 postgres-nio 技能会加入库级别的预期：async 用法、连接池、prepared statement 模式和类型安全插值。这样通常能减少来回沟通，也能避免生成看起来合理、实际却不符合库用法的代码。

对新手友好吗？

如果你已经会基础 Swift 和 SQL，那就是友好的。postgres-nio 指南在你能描述 schema、查询意图，以及需要 insert、read 还是 bulk 操作时最有帮助。如果你还说不清这些输入，先从一个小查询开始。

什么时候不该用 postgres-nio？

如果你的项目不使用 Swift，或者你想要的是偏 ORM 的高层抽象，或者你只是想临时解释一段 SQL，就不要用 postgres-nio。它也不适合主要任务是 PostgreSQL 运维，而不是应用侧数据库访问的场景。

如何改进 postgres-nio 技能

提供 schema、查询意图和数据类型

postgres-nio 最强的输出，来自具体输入：表名、列名、预期返回类型，以及是否可能出现 null 或数组。例如，“按 email 查询 users(id: Int64, email: String, created_at: Date?) 并返回 User?”就比“写一个 select 查询”好得多。

先说明安全和性能约束

如果你在意 SQL 注入防护、连接池行为或事务一致性，就在提示里直接说明。postgres-nio 在你要求安全绑定，而不是简单拼接 SQL 时最强；同时也要明确代码应该使用 pooled client 还是单连接。

先要最小可运行切片

一个好的迭代路径是：客户端配置、一个查询、一个解码结果，然后再到事务或插入。如果第一版回答已经接近正确但还不完整，就只补缺失部分，不要重新要求整套集成，这样更容易保留 postgres-nio 用法里已经正确的部分。

SQL 是动态的，就用参考模式

如果你的查询会根据筛选条件变化，就不要让它自由拼字符串，而要直接要求插值模式。说明哪些内容可变、哪些必须参数化，以及你希望什么样的结果形状。这样 postgres-nio 技能才能生成更安全、也更容易维护的代码。