用途:为在 Swift 项目中使用 PostgreSQL 提供指导,核心是 postgres-nio 库。该库是 Swift 的 PostgreSQL 客户端,支持 async/await、类型安全的查询构建、连接池与预编译语句。
安装:在 Package.swift 中加入依赖 .package(url: "https://github.com/vapor/postgres-nio.git", from: "1.21.0")。
主要能力:
- 客户端与连接池。推荐使用 PostgresClient,按 Configuration 填写 host、port、username、password、database、tls;可在 withThrowingTaskGroup 中通过 client.run() 作为服务运行,并执行 client.query。
- 参数绑定。查询使用字符串插值生成 $1、$2 等绑定,防止 SQL 注入;表名/列名等标识符需用 (unescaped:) 且必须是可信值,不能来自用户输入。
- 行解码。可按位置 row.decode((Int.self, String.self, ...)),也可按列名 row["id"].decode(Int.self),支持可选与自定义 Decodable 类型。
- 预编译语句。实现 PostgresPreparedStatement,定义 sql、makeBindings 与 decodeRow,通过 connection.execute 执行。
- 事务。用 withConnection 获取连接后执行 BEGIN、业务语句与 COMMIT,出错时 ROLLBACK。
- 批量导入。用 copyFrom(table:columns:format:) 配合 CSV 格式与 writer 写入,返回插入行数。
- 大结果流式处理,逐行消费,内存占用较低。
配置要点:连接池可设置 minimumConnections、maximumConnections、connectionIdleTimeout、keepAliveBehavior;TLS 支持 .disable、.prefer、.require;也支持 Unix 域套接字路径。
错误处理:捕获 PSQLError 并按 code 区分 uniqueViolation、foreignKeyViolation 等情况。
适用场景:Swift 服务端或应用访问 PostgreSQL,执行查询、事务、批量导入与流式读取。限制:unescaped 仅用于可信标识符;具体版本行为与平台支持暂未提供。