结构化查询

一个以安全、富有表现力且可组合的方式构建 SQL 的库。

了解更多

该库的动机和设计源于 Point-Free 的多个剧集，这是一个探索 Swift 语言高级编程主题的视频系列，由 Brandon Williams 和 Stephen Celis 主持。为了支持该库的持续开发，请立即订阅。

概述

StructuredQueries 提供了一套工具，使您能够使用 Swift 编写安全、富有表现力且可组合的 SQL。只需将宏附加到表示数据库架构的类型上：

@Table
struct Reminder {
  let id: Int
  var title = ""
  var isCompleted = false
  var priority: Int?
  var dueDate: Date?
}

您可以立即访问一套丰富的查询构建 API，从简单的：

Swift	SQL
`Reminder.all // => [Reminder]`	`SELECT "reminders"."id", "reminders"."title", "reminders"."isCompleted", "reminders"."priority", "reminders"."dueDate" FROM "reminders"`

过于复杂：

Swift SQL

Swift	SQL
`Reminder .select { ($0.priority, $0.title.groupConcat()) } .where { !$0.isCompleted } .group(by: \.priority) .order { $0.priority.desc() } // => [(Int?, String)]`	`SELECT "reminders"."priority", group_concat("reminders"."title") FROM "reminders" WHERE (NOT "reminders"."isCompleted") GROUP BY "reminders"."priority" ORDER BY "reminders"."priority" DESC`

Reminder
  .select {
     ($0.priority,
      $0.title.groupConcat())
  }
  .where { !$0.isCompleted }
  .group(by: \.priority)
  .order { $0.priority.desc() }
// => [(Int?, String)]

SELECT
  "reminders"."priority",
  group_concat("reminders"."title")
FROM "reminders"
WHERE (NOT "reminders"."isCompleted")
GROUP BY "reminders"."priority"
ORDER BY "reminders"."priority" DESC

这些 API 可帮助你避免由拼写错误和类型错误引发的运行时问题，但它们仍然忠实于 SQL 的本质。StructuredQueries 并非 ORM，也非你需要学习的新查询语言：其 API 的设计旨在与所生成的 SQL 高度相似，尽管通常更为简洁，且始终更安全。

你也不会受到查询构建器的限制。你可以使用 #sql 宏，以任意粒度自由引入 安全的 SQL 字符串。从小的表达式开始：

Reminder.where {
  !$0.isCompleted && #sql("\($0.dueDate) < date()")
}

到整个语句：

#sql(
  """
  SELECT \(Reminder.columns) FROM \(Reminder.self)
  WHERE \(Reminder.priority) >= \(selectedPriority)
  """,
  as: Reminder.self
)

该库支持构建从 SELECT、INSERT、UPDATE 和 DELETE 语句，到类型安全的外连接和递归公共表表达式。要了解有关使用 StructuredQueries 构建 SQL 的更多信息，请查阅文档。

[!IMPORTANT] 该库不包含用于发起实际数据库请求的任何数据库驱动程序，例如，用于 SQLite、Postgres、MySQL。该库仅专注于构建 SQL 语句并提供与发起实际数据库请求的其他库进行集成的工具。有关更多信息，请参阅数据库驱动程序。

文档

最新不稳定版本和稳定版本的文档可在此处获取：

main
0.x.x

文档中有许多文章，在你更熟悉该库时可能会发现它们很有帮助：

以及更全面的示例用法：

演示

在 SQLiteData 仓库中有一些示例应用程序，展示了如何使用 StructuredQueries。查看 this 目录以查看它们全部，包括：

案例研究: 一系列展示库内置功能的案例研究。
Reminders: 对 Apple 的 Reminders 应用的重建，使用 SQLite 数据库来建模提醒、列表和标签。它包含许多高级查询，例如搜索和统计聚合。
SyncUps: 我们还使用现代最佳实践重建了 Apple 的 Scrumdinger 演示应用程序，用于 SwiftUI 开发，包括使用此库通过 SQLite 查询和持久化状态。

数据库驱动程序

StructuredQueries 旨在支持任何 SQL 数据库（SQLite、MySQL、Postgres、等），但目前针对 SQLite 进行了优化。它目前有一个官方驱动程序：

SQLiteData: SwiftData 和 @Query 宏的轻量级替代品。SQLiteData 包含 StructuredQueriesGRDB，一个将本库与流行的 GRDB SQLite 库集成的库。

如果您有兴趣为其他数据库库构建 StructuredQueries 集成，请参阅 Integrating with database libraries，并发起讨论以告知我们您遇到的任何挑战。

安装

您可以通过将 StructuredQueries 作为包添加到项目中，将其添加到 Xcode 项目中。

https://github.com/pointfreeco/swift-structured-queries

如果您想在 SwiftPM 项目中使用 StructuredQueries，只需将其添加到您的 Package.swift 即可：

dependencies: [
  .package(url: "https://github.com/pointfreeco/swift-structured-queries", from: "0.32.0"),
]

然后，将该产品添加到任何需要访问该库的目标：

.product(name: "StructuredQueries", package: "swift-structured-queries"),

如果你使用的是 Swift 6.1 或更高版本，你可以启用包特性以扩展库的附加功能：

CasePaths：通过利用 CasePaths 库，为单表继承 via "enum" 表添加支持。
ColumnCoding：使表和选择的 Codable 一致性与其列名对齐。
LazyInitializableByDefault：使没有默认值的草稿属性可延迟初始化。
Tagged：通过 Tagged 库添加对类型安全标识符的 via 支持。

 dependencies: [
   .package(
     url: "https://github.com/pointfreeco/swift-structured-queries",
     from: "0.28.0",
+    traits: ["CasePaths", "ColumnCoding", "LazyInitializableByDefault"]
   ),
 ]

有关这些特性的更多信息，请参阅 Traits。

[!IMPORTANT] 在 6.3 之前的 Swift 工具链中，你_必须_根据启用的特性，显式依赖 swift-case-paths 和/或 swift-tagged，以解决 SwiftPM 的一个 bug，该 bug 导致由特性引入的依赖项未被解析：
+.package(
+  url: "https://github.com/pointfreeco/swift-case-paths",
+  from: "1.0.0"
+),
+.package(
+  url: "https://github.com/pointfreeco/swift-tagged",
+  from: "0.1.0"
+),
此 bug 已在 Swift 6.3 中修复，此时可以省略显式依赖项。

Community

如果你想讨论这个库，或者有关于如何使用它来解决特定问题的疑问，你可以与 Point-Free 爱好者在以下地方交流：

对于长篇讨论，我们推荐此仓库的 discussions 标签页。
对于随意聊天，我们推荐 Point-Free Community Slack。

License

本库根据 MIT 许可证发布。有关详细信息，请参阅 LICENSE。