一个 SQLite 数据库工具包，专注于应用程序开发
自 2015 年以来，自豪地为社区服务

最新版本：2025 年 2 月 12 日 • 7.2.0 版本 • 更新日志 • 从 GRDB 6 迁移到 GRDB 7

要求：iOS 13.0+ / macOS 10.15+ / tvOS 13.0+ / watchOS 7.0+ • SQLite 3.20.0+ • Swift 6+ / Xcode 16+

联系方式:

• 发布公告和使用技巧：在 Mastodon 上关注 @groue@hachyderm.io。
• 在 Github issue 中报告错误。 请确保首先检查现有问题。
• 有问题？ 寻求建议？ 想知道如何贡献？ 想聊聊天？ 请访问 GitHub discussions，或者 GRDB forums。

使用此库将应用程序的永久数据保存到 SQLite 数据库中。 它带有内置工具，可满足常见需求

• SQL 生成

  使用持久性和获取方法增强您的应用程序模型，这样您就不必在不想处理 SQL 和原始数据库行时处理它们。

• 数据库观察

  当数据库值被修改时获取通知。

• 强大的并发性

  多线程应用程序可以有效地使用其数据库，包括支持并发读写的 WAL 数据库。

• 迁移

  随着应用程序新版本的发布，不断发展数据库的 schema。

• 利用您的 SQLite 技能

  并非所有开发人员都需要高级 SQLite 功能。 但是当您需要时，GRDB 会像您希望的那样敏锐。 带着您的 SQL 和 SQLite 技能来，或者随着您的进步学习新的技能！

用法 • 文档 • 安装 • 常见问题解答

import GRDB

// 1. Open a database connection
let dbQueue = try DatabaseQueue(path: "/path/to/database.sqlite")

// 2. Define the database schema
try dbQueue.write { db in
    try db.create(table: "player") { t in
        t.primaryKey("id", .text)
        t.column("name", .text).notNull()
        t.column("score", .integer).notNull()
    }
}

// 3. Define a record type
struct Player: Codable, FetchableRecord, PersistableRecord {
    var id: String
    var name: String
    var score: Int
}

// 4. Write and read in the database
try dbQueue.write { db in
    try Player(id: "1", name: "Arthur", score: 100).insert(db)
    try Player(id: "2", name: "Barbara", score: 1000).insert(db)
}

let players: [Player] = try dbQueue.read { db in
    try Player.fetchAll(db)
}

try dbQueue.write { db in
    try db.execute(sql: """
        CREATE TABLE place (
          id INTEGER PRIMARY KEY AUTOINCREMENT,
          title TEXT NOT NULL,
          favorite BOOLEAN NOT NULL DEFAULT 0,
          latitude DOUBLE NOT NULL,
          longitude DOUBLE NOT NULL)
        """)
    
    try db.execute(sql: """
        INSERT INTO place (title, favorite, latitude, longitude)
        VALUES (?, ?, ?, ?)
        """, arguments: ["Paris", true, 48.85341, 2.3488])
    
    let parisId = db.lastInsertedRowID
    
    // Avoid SQL injection with SQL interpolation
    try db.execute(literal: """
        INSERT INTO place (title, favorite, latitude, longitude)
        VALUES (\("King's Cross"), \(true), \(51.52151), \(-0.12763))
        """)
}

try dbQueue.read { db in
    // Fetch database rows
    let rows = try Row.fetchCursor(db, sql: "SELECT * FROM place")
    while let row = try rows.next() {
        let title: String = row["title"]
        let isFavorite: Bool = row["favorite"]
        let coordinate = CLLocationCoordinate2D(
            latitude: row["latitude"],
            longitude: row["longitude"])
    }
    
    // Fetch values
    let placeCount = try Int.fetchOne(db, sql: "SELECT COUNT(*) FROM place")! // Int
    let placeTitles = try String.fetchAll(db, sql: "SELECT title FROM place") // [String]
}

let placeCount = try dbQueue.read { db in
    try Int.fetchOne(db, sql: "SELECT COUNT(*) FROM place")!
}

struct Place {
    var id: Int64?
    var title: String
    var isFavorite: Bool
    var coordinate: CLLocationCoordinate2D
}

// snip: turn Place into a "record" by adopting the protocols that
// provide fetching and persistence methods.

try dbQueue.write { db in
    // Create database table
    try db.create(table: "place") { t in
        t.autoIncrementedPrimaryKey("id")
        t.column("title", .text).notNull()
        t.column("favorite", .boolean).notNull().defaults(to: false)
        t.column("longitude", .double).notNull()
        t.column("latitude", .double).notNull()
    }
    
    var berlin = Place(
        id: nil,
        title: "Berlin",
        isFavorite: false,
        coordinate: CLLocationCoordinate2D(latitude: 52.52437, longitude: 13.41053))
    
    try berlin.insert(db)
    berlin.id // some value
    
    berlin.isFavorite = true
    try berlin.update(db)
}

try dbQueue.read { db in
    // Place
    let paris = try Place.find(db, id: 1)
    
    // Place?
    let berlin = try Place.filter(Column("title") == "Berlin").fetchOne(db)
    
    // [Place]
    let favoritePlaces = try Place
        .filter(Column("favorite") == true)
        .order(Column("title"))
        .fetchAll(db)
    
    // Int
    let favoriteCount = try Place.filter(Column("favorite")).fetchCount(db)
    
    // SQL is always welcome
    let places = try Place.fetchAll(db, sql: "SELECT * FROM place")
}

// Define the observed value
let observation = ValueObservation.tracking { db in
    try Place.fetchAll(db)
}

// Start observation
let cancellable = observation.start(
    in: dbQueue,
    onError: { error in ... },
    onChange: { (places: [Place]) in print("Fresh places: \(places)") })

// Combine
let cancellable = observation.publisher(in: dbQueue).sink(
    receiveCompletion: { completion in ... },
    receiveValue: { (places: [Place]) in print("Fresh places: \(places)") })

// RxSwift
let disposable = observation.rx.observe(in: dbQueue).subscribe(
    onNext: { (places: [Place]) in print("Fresh places: \(places)") },
    onError: { error in ... })

GRDB 在 SQLite 之上运行：您应该熟悉 SQLite 常见问题解答。 有关一般和详细信息，请跳转到 SQLite 文档。

• 演示应用程序
• 常见问题

• 📖 GRDB 参考

• 安装
• 数据库连接：连接到 SQLite 数据库

• SQLite API：底层 SQLite API • 执行更新 • 获取查询 • SQL 插值

• 记录：用于自定义结构和类层次结构的获取和持久化方法
• 查询接口：一种生成 SQL 的 Swift 方法 • 创建表、索引等 • 请求 • 记录类型之间的关联

• 迁移：随着应用程序的演变转换您的数据库。
• 全文搜索：执行高效且可定制的全文搜索。
• 数据库观察：观察数据库更改和事务。
• 加密：使用 SQLCipher 加密您的数据库。
• 备份：将数据库的内容转储到另一个数据库。
• 中断数据库：中止任何挂起的数据库操作。
• 共享数据库：如何在多个进程之间共享 SQLite 数据库 - 应用程序组容器、应用程序扩展、应用程序沙箱和文件协调的建议。

• 并发：如何在多线程应用程序中访问数据库。
• Combine：使用 Combine 发布者访问和观察数据库。
• 避免 SQL 注入
• 错误处理
• Unicode
• 内存管理
• 数据保护
• 💡 从 GRDB 6 迁移到 GRDB 7
• 💡 为什么要采用 GRDB？
• 💡 设计记录类型的推荐实践

• GRDBQuery：从 SwiftUI 视图访问和观察数据库。
• GRDBSnapshotTesting：测试您的数据库。

常见问题

示例代码

以下安装过程使 GRDB 使用目标操作系统附带的 SQLite 版本。

有关使用 SQLCipher 的 GRDB 安装过程，请参阅 加密。

有关使用 SQLite 的自定义构建的 GRDB 安装过程，请参阅 自定义 SQLite 构建。

Swift Package Manager 自动执行 Swift 代码的分发。 要将 GRDB 与 SPM 一起使用，请添加对 https://github.com/groue/GRDB.swift.git 的依赖

GRDB 提供两个库，GRDB 和 GRDB-dynamic。 只选择一个。 如有疑问，请首选 GRDB。 如果您要将其与应用程序中的多个目标链接，并且只想链接到共享的动态框架一次，则 GRDB-dynamic 库可以显示出有用。 有关更多信息，请参见如何将 Swift Package 链接为动态库 。

注意：目前不支持 Linux。

CocoaPods是 Xcode 项目的依赖项管理器。 要将 GRDB 与 CocoaPods（1.2 或更高版本）一起使用，请在您的 Podfile 中指定

pod 'GRDB.swift'

GRDB 可以作为框架或静态库安装。

CocoaPods 安装的重要提示

由于 CocoaPods 中的一个问题，目前无法将新版本的 GRDB 部署到 CocoaPods。 CocoaPods 上提供的最新版本是 6.24.1。 要使用 CocoaPods 安装更高版本的 GRDB，请使用以下解决方法之一

• 依赖于 GRDB6 分支。 这或多或少等效于 pod 'GRDB.swift', '~> 6.0' 通常会执行的操作，如果 CocoaPods 接受发布新的 GRDB 版本

  # Can't use semantic versioning due to https://github.com/CocoaPods/CocoaPods/issues/11839
  pod 'GRDB.swift', git: 'https://github.com/groue/GRDB.swift.git', branch: 'GRDB6'

• 显式依赖于特定版本（用您要使用的版本替换标签）

  # Can't use semantic versioning due to https://github.com/CocoaPods/CocoaPods/issues/11839
  # Replace the tag with the tag that you want to use.
  pod 'GRDB.swift', git: 'https://github.com/groue/GRDB.swift.git', tag: 'v6.29.0' 

Carthage 不受支持。 有关此决定的上下文，请参见 #433。

1. 下载 GRDB 的副本，或者克隆其存储库并确保您检出最新的标记版本。

2. 将 GRDB.xcodeproj 项目嵌入到您自己的项目中。

3. 在应用程序目标（WatchOS 的扩展目标）的“构建阶段”选项卡的“目标依赖项”部分中添加 GRDB 目标。

4. 将 GRDB.framework 添加到应用程序目标（WatchOS 的扩展目标）的“常规”选项卡的“嵌入式二进制文件”部分。

GRDB 提供了两个用于访问 SQLite 数据库的类：DatabaseQueue 和 DatabasePool

import GRDB

// Pick one:
let dbQueue = try DatabaseQueue(path: "/path/to/database.sqlite")
let dbPool = try DatabasePool(path: "/path/to/database.sqlite")

区别在于

• 数据库池允许并发数据库访问（这可以提高多线程应用程序的性能）。
• 数据库池以 WAL 模式 打开您的 SQLite 数据库（除非是只读）。
• 数据库队列支持 内存数据库。

如果您不确定，请选择 DatabaseQueue。 您始终可以稍后切换到 DatabasePool。

有关打开连接的更多信息和提示，请参见 数据库连接。

在本节文档中，我们将讨论 SQL。 如果 SQL 不是您的菜，请跳转到 查询接口。

• 执行更新
• 获取查询
  • 获取方法
  • 行查询
  • 值查询
• 值
  • 数据
  • 日期和日期组件 (Date and DateComponents)
  • NSNumber, NSDecimalNumber 和 Decimal
  • Swift 枚举
  • DatabaseValueConvertible: 自定义值类型的协议
• 事务和保存点
• SQL 插值

高级主题

• 预处理语句
• 自定义 SQL 函数和聚合
• 数据库模式内省
• 行适配器
• 原始 SQLite 指针

一旦获得数据库连接，execute(sql:arguments:) 方法就会执行不返回任何数据库行的 SQL 语句，例如 CREATE TABLE、INSERT、DELETE、ALTER 等。

例如

try dbQueue.write { db in
    try db.execute(sql: """
        CREATE TABLE player (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            name TEXT NOT NULL,
            score INT)
        """)
    
    try db.execute(
        sql: "INSERT INTO player (name, score) VALUES (?, ?)",
        arguments: ["Barbara", 1000])
    
    try db.execute(
        sql: "UPDATE player SET score = :score WHERE id = :id",
        arguments: ["score": 1000, "id": 1])
    }
}

SQL 查询中的 ? 和冒号前缀的键 (如 :score) 是**语句参数**。 可以使用数组或字典传递参数，如上例所示。 有关支持的参数类型（Bool、Int、String、Date、Swift 枚举等）的更多信息，请参见值；有关 SQLite 参数的详细文档，请参见 StatementArguments。

你也可以使用 execute(literal:) 将查询参数直接嵌入到 SQL 查询中，如下例所示。 有关更多详细信息，请参见 SQL 插值。

try dbQueue.write { db in
    let name = "O'Brien"
    let score = 550
    try db.execute(literal: """
        INSERT INTO player (name, score) VALUES (\(name), \(score))
        """)
}

永远不要将值直接嵌入到原始 SQL 字符串中。 有关更多信息，请参见避免 SQL 注入

// WRONG: don't embed values in raw SQL strings
let id = 123
let name = textField.text
try db.execute(
    sql: "UPDATE player SET name = '\(name)' WHERE id = \(id)")

// CORRECT: use arguments dictionary
try db.execute(
    sql: "UPDATE player SET name = :name WHERE id = :id",
    arguments: ["name": name, "id": id])

// CORRECT: use arguments array
try db.execute(
    sql: "UPDATE player SET name = ? WHERE id = ?",
    arguments: [name, id])

// CORRECT: use SQL Interpolation
try db.execute(
    literal: "UPDATE player SET name = \(name) WHERE id = \(id)")

用分号连接多个语句:

try db.execute(sql: """
    INSERT INTO player (name, score) VALUES (?, ?);
    INSERT INTO player (name, score) VALUES (?, ?);
    """, arguments: ["Arthur", 750, "Barbara", 1000])

try db.execute(literal: """
    INSERT INTO player (name, score) VALUES (\("Arthur"), \(750));
    INSERT INTO player (name, score) VALUES (\("Barbara"), \(1000));
    """)

如果要确保执行单个语句，请使用预处理的 Statement。

在 INSERT 语句之后，可以使用 lastInsertedRowID 获取插入行的行 ID

try db.execute(
    sql: "INSERT INTO player (name, score) VALUES (?, ?)",
    arguments: ["Arthur", 1000])
let playerId = db.lastInsertedRowID

不要错过 记录，它提供了经典的 持久化方法

var player = Player(name: "Arthur", score: 1000)
try player.insert(db)
let playerId = player.id

数据库连接 可以让你获取数据库行、纯值和自定义模型（也称为“记录”）。

行是 SQL 查询的原始结果

try dbQueue.read { db in
    if let row = try Row.fetchOne(db, sql: "SELECT * FROM wine WHERE id = ?", arguments: [1]) {
        let name: String = row["name"]
        let color: Color = row["color"]
        print(name, color)
    }
}

值是存储在行中的列中的 Bool、Int、String、Date、Swift 枚举等

try dbQueue.read { db in
    let urls = try URL.fetchCursor(db, sql: "SELECT url FROM wine")
    while let url = try urls.next() {
        print(url)
    }
}

记录是可以从行初始化自身的应用程序对象

let wines = try dbQueue.read { db in
    try Wine.fetchAll(db, sql: "SELECT * FROM wine")
}

• 获取方法 和 游标
• 行查询
• 值查询
• 记录

在整个 GRDB 中，您可以始终获取任何可获取类型（数据库行、简单值或自定义记录）的游标、数组、集合或单个值。

try Row.fetchCursor(...) // A Cursor of Row
try Row.fetchAll(...)    // [Row]
try Row.fetchSet(...)    // Set<Row>
try Row.fetchOne(...)    // Row?

• fetchCursor 返回一个在获取的值上的 游标

  let rows = try Row.fetchCursor(db, sql: "SELECT ...") // A Cursor of Row

• fetchAll 返回一个 数组

  let players = try Player.fetchAll(db, sql: "SELECT ...") // [Player]

• fetchSet 返回一个 集合

  let names = try String.fetchSet(db, sql: "SELECT ...") // Set<String>

• fetchOne 返回一个 单个可选值，并消耗单个数据库行（如果有）。

  let count = try Int.fetchOne(db, sql: "SELECT COUNT(*) ...") // Int?

所有这些获取方法都需要一个包含单个 SQL 语句的 SQL 字符串。 如果要从用分号连接的多个语句中获取数据，请迭代 SQL 字符串中找到的多个 预处理语句。

📖 Cursor

每当从数据库中使用多个行时，可以获取数组、集合或游标.

fetchAll() 和 fetchSet() 方法返回常规的 Swift 数组和集合，可以像迭代所有其他数组和集合一样迭代它们

try dbQueue.read { db in
    // [Player]
    let players = try Player.fetchAll(db, sql: "SELECT ...")
    for player in players {
        // use player
    }
}

与数组和集合不同，fetchCursor() 返回的游标会逐步加载其结果

try dbQueue.read { db in
    // Cursor of Player
    let players = try Player.fetchCursor(db, sql: "SELECT ...")
    while let player = try players.next() {
        // use player
    }
}

• 游标不能在任何线程上使用：必须在其创建的调度队列中使用游标。 特别是，不要从数据库访问方法中提取游标

  // Wrong
  let cursor = try dbQueue.read { db in
      try Player.fetchCursor(db, ...)
  }
  while let player = try cursor.next() { ... }

  相反，数组和集合可以在任何线程上使用

  // OK
  let array = try dbQueue.read { db in
      try Player.fetchAll(db, ...)
  }
  for player in array { ... }

• 游标只能迭代一次。 数组和集合可以迭代多次。

• 游标以延迟方式迭代数据库结果，并且不占用太多内存。 数组和集合包含数据库值的副本，并且当有很多获取的结果时，可能会占用大量内存。

• 与数组和集合必须花费时间复制数据库值不同，游标可以直接访问 SQLite。 如果追求更高的性能，则可能更喜欢游标。

• 游标可以为 Swift 集合提供数据。

  大多数时候，你会在想要数组或集合时使用 fetchAll 或 fetchSet。 对于更具体的需求，您可能更喜欢下面的初始化程序之一。 它们都接受一个额外的可选 minimumCapacity 参数，当您了解游标中的元素数量时，该参数有助于优化你的应用程序（内置的 fetchAll 和 fetchSet 不执行这种优化）。

  数组和所有符合 RangeReplaceableCollection 的类型

  // [String]
  let cursor = try String.fetchCursor(db, ...)
  let array = try Array(cursor)

  集合:

  // Set<Int>
  let cursor = try Int.fetchCursor(db, ...)
  let set = try Set(cursor)

  字典:

  // [Int64: [Player]]
  let cursor = try Player.fetchCursor(db)
  let dictionary = try Dictionary(grouping: cursor, by: { $0.teamID })
  
  // [Int64: Player]
  let cursor = try Player.fetchCursor(db).map { ($0.id, $0) }
  let dictionary = try Dictionary(uniqueKeysWithValues: cursor)

• 游标采用 Cursor 协议，该协议非常类似于 Swift 的标准 lazy sequences。 因此，游标附带了许多便捷方法：compactMap、contains、dropFirst、dropLast、drop(while:)、enumerated、filter、first、flatMap、forEach、joined、joined(separator:)、max、max(by:)、min、min(by:)、map、prefix、prefix(while:)、reduce、reduce(into:)、suffix

  // Prints all Github links
  try URL
      .fetchCursor(db, sql: "SELECT url FROM link")
      .filter { url in url.host == "github.com" }
      .forEach { url in print(url) }
  
  // An efficient cursor of coordinates:
  let locations = try Row.
      .fetchCursor(db, sql: "SELECT latitude, longitude FROM place")
      .map { row in
          CLLocationCoordinate2D(latitude: row[0], longitude: row[1])
      }

• 游标不是 Swift 序列。 这是因为 Swift 序列无法处理迭代错误，而读取 SQLite 结果可能随时失败。

• 游标需要小心使用:

  • 不要在游标迭代期间修改结果

    // Undefined behavior
    while let player = try players.next() {
        try db.execute(sql: "DELETE ...")
    }

  • 不要将 Row 游标转换为数组或集合。 你将无法获得你期望的不同的行。 要获取行数组，请使用 Row.fetchAll(...)。 要获取行集合，请使用 Row.fetchSet(...)。 一般来说，请确保在每次从游标中提取行以供以后使用时复制行：row.copy()。

如果你看不到或不关心差异，请使用数组。 如果你关心内存和性能，请在适当的时候使用游标。

• 获取行
• 列值
• DatabaseValue
• 作为字典的行
• 📖 Row

获取行的 游标 、 数组 、 集合 或 单个 行（请参见 获取方法）

try dbQueue.read { db in
    try Row.fetchCursor(db, sql: "SELECT ...", arguments: ...) // A Cursor of Row
    try Row.fetchAll(db, sql: "SELECT ...", arguments: ...)    // [Row]
    try Row.fetchSet(db, sql: "SELECT ...", arguments: ...)    // Set<Row>
    try Row.fetchOne(db, sql: "SELECT ...", arguments: ...)    // Row?
    
    let rows = try Row.fetchCursor(db, sql: "SELECT * FROM wine")
    while let row = try rows.next() {
        let name: String = row["name"]
        let color: Color = row["color"]
        print(name, color)
    }
}

let rows = try dbQueue.read { db in
    try Row.fetchAll(db, sql: "SELECT * FROM player")
}

参数是可选的数组或字典，用于填充查询中的位置 ? 和冒号前缀的键（如 :name）

let rows = try Row.fetchAll(db,
    sql: "SELECT * FROM player WHERE name = ?",
    arguments: ["Arthur"])

let rows = try Row.fetchAll(db,
    sql: "SELECT * FROM player WHERE name = :name",
    arguments: ["name": "Arthur"])

有关支持的参数类型（Bool、Int、String、Date、Swift 枚举等）的更多信息，请参见值；有关 SQLite 参数的详细文档，请参见 StatementArguments。

与包含数据库行副本的行数组不同，行游标更接近 SQLite 本身，需要小心使用

注意：不要将 Row 游标转换为数组或集合。 你将无法获得你期望的不同的行。 要获取行数组，请使用 Row.fetchAll(...)。 要获取行集合，请使用 Row.fetchSet(...)。 一般来说，请确保在每次从游标中提取行以供以后使用时复制行：row.copy()。

通过索引或列名读取列值

let name: String = row[0]      // 0 is the leftmost column
let name: String = row["name"] // Leftmost matching column - lookup is case-insensitive
let name: String = row[Column("name")] // Using query interface's Column

确保在值可能为 NULL 时请求一个可选值

let name: String? = row["name"]

row[] 下标返回你请求的类型。 有关支持的值类型的更多信息，请参见值

let bookCount: Int     = row["bookCount"]
let bookCount64: Int64 = row["bookCount"]
let hasBooks: Bool     = row["bookCount"] // false when 0

let string: String     = row["date"]      // "2015-09-11 18:14:15.123"
let date: Date         = row["date"]      // Date
self.date = row["date"] // Depends on the type of the property.

你还可以使用 as 类型转换运算符

row[...] as Int
row[...] as Int?

警告：避免使用 as! 和 as? 运算符

if let int = row[...] as? Int { ... } // BAD - doesn't work
if let int = row[...] as Int? { ... } // GOOD

警告：避免 nil 合并行值，而应首选 coalesce 方法

let name: String? = row["nickname"] ?? row["name"]     // BAD - doesn't work
let name: String? = row.coalesce(["nickname", "name"]) // GOOD

一般来说，只要可以从底层 SQLite 值转换，就可以提取所需的类型

• 成功的转换包括

  • 所有数值 SQLite 值转换为所有数值 Swift 类型和 Bool（零是唯一的 false 布尔值）。
  • 文本 SQLite 值转换为 Swift String。
  • Blob SQLite 值转换为 Foundation Data。

  有关支持的类型（Bool、Int、String、Date、Swift 枚举等）的更多信息，请参见值

• NULL 返回 nil。

  let row = try Row.fetchOne(db, sql: "SELECT NULL")!
  row[0] as Int? // nil
  row[0] as Int  // fatal error: could not convert NULL to Int.

  但是，有一个例外：DatabaseValue 类型

  row[0] as DatabaseValue // DatabaseValue.null

• 缺少的列返回 nil。

  let row = try Row.fetchOne(db, sql: "SELECT 'foo' AS foo")!
  row["missing"] as String? // nil
  row["missing"] as String  // fatal error: no such column: missing

  你可以使用 hasColumn 方法显式检查列是否存在。

• 无效的转换会引发致命错误。

  let row = try Row.fetchOne(db, sql: "SELECT 'Mom’s birthday'")!
  row[0] as String // "Mom’s birthday"
  row[0] as Date?  // fatal error: could not convert "Mom’s birthday" to Date.
  row[0] as Date   // fatal error: could not convert "Mom’s birthday" to Date.
  
  let row = try Row.fetchOne(db, sql: "SELECT 256")!
  row[0] as Int    // 256
  row[0] as UInt8? // fatal error: could not convert 256 to UInt8.
  row[0] as UInt8  // fatal error: could not convert 256 to UInt8.

  可以使用 DatabaseValue 类型避免这些转换致命错误

  let row = try Row.fetchOne(db, sql: "SELECT 'Mom’s birthday'")!
  let dbValue: DatabaseValue = row[0]
  if dbValue.isNull {
      // Handle NULL
  } else if let date = Date.fromDatabaseValue(dbValue) {
      // Handle valid date
  } else {
      // Handle invalid date
  }

  这种额外的冗长是由于必须处理不受信任的数据库所致：你可以考虑改为修复数据库的内容。 有关更多信息，请参见致命错误。

• SQLite 具有弱类型系统，并提供便捷转换，可以将 String 转换为 Int，将 Double 转换为 Blob 等。

  GRDB 有时会允许这些转换通过

  let rows = try Row.fetchCursor(db, sql: "SELECT '20 small cigars'")
  while let row = try rows.next() {
      row[0] as Int   // 20
  }

  不要惊慌：这些转换并没有阻止 SQLite 成为你想使用的极其成功的数据库引擎。 GRDB 添加了上面描述的安全检查。 你也可以通过使用 DatabaseValue 类型完全阻止这些便捷转换。

📖 DatabaseValue

DatabaseValue 是 SQLite 和你的值之间的中间类型，它提供有关存储在数据库中的原始值的信息。

你可以像获取其他值类型一样获取 DatabaseValue

let dbValue: DatabaseValue = row[0]
let dbValue: DatabaseValue? = row["name"] // nil if and only if column does not exist

// Check for NULL:
dbValue.isNull // Bool

// The stored value:
dbValue.storage.value // Int64, Double, String, Data, or nil

// All the five storage classes supported by SQLite:
switch dbValue.storage {
case .null:                 print("NULL")
case .int64(let int64):     print("Int64: \(int64)")
case .double(let double):   print("Double: \(double)")
case .string(let string):   print("String: \(string)")
case .blob(let data):       print("Data: \(data)")
}

你可以使用 fromDatabaseValue() 方法从 DatabaseValue 中提取常规值（Bool、Int、String、Date、Swift 枚举等）

let dbValue: DatabaseValue = row["bookCount"]
let bookCount   = Int.fromDatabaseValue(dbValue)   // Int?
let bookCount64 = Int64.fromDatabaseValue(dbValue) // Int64?
let hasBooks    = Bool.fromDatabaseValue(dbValue)  // Bool?, false when 0

let dbValue: DatabaseValue = row["date"]
let string = String.fromDatabaseValue(dbValue)     // "2015-09-11 18:14:15.123"
let date   = Date.fromDatabaseValue(dbValue)       // Date?

fromDatabaseValue 对无效转换返回 nil

let row = try Row.fetchOne(db, sql: "SELECT 'Mom’s birthday'")!
let dbValue: DatabaseValue = row[0]
let string = String.fromDatabaseValue(dbValue) // "Mom’s birthday"
let int    = Int.fromDatabaseValue(dbValue)    // nil
let date   = Date.fromDatabaseValue(dbValue)   // nil

Row 采用标准 RandomAccessCollection 协议，可以将其视为 DatabaseValue 的字典

// All the (columnName, dbValue) tuples, from left to right:
for (columnName, dbValue) in row {
    ...
}

你可以从字典构建行（标准的 Swift 字典和 NSDictionary）。 更多支持的类型请参见 值。

let row: Row = ["name": "foo", "date": nil]
let row = Row(["name": "foo", "date": nil])
let row = Row(/* [AnyHashable: Any] */) // nil if invalid dictionary

然而，行并不是真正的字典：它们可能包含重复的列。

let row = try Row.fetchOne(db, sql: "SELECT 1 AS foo, 2 AS foo")!
row.columnNames    // ["foo", "foo"]
row.databaseValues // [1, 2]
row["foo"]         // 1 (leftmost matching column)
for (columnName, dbValue) in row { ... } // ("foo", 1), ("foo", 2)

当你从行构建字典时，你必须消除重复列的歧义，并选择如何表示数据库值。 例如：

• 一个 [String: DatabaseValue] 字典，如果存在重复的列名，则保留最左边的值。

  let dict = Dictionary(row, uniquingKeysWith: { (left, _) in left })

• 一个 [String: AnyObject] 字典，如果存在重复的列名，则保留最右边的值。 这个字典与 FMDB 中 FMResultSet 的 resultDictionary 相同。它包含空列的 NSNull 值，并且可以与 Objective-C 共享。

  let dict = Dictionary(
      row.map { (column, dbValue) in
          (column, dbValue.storage.value as AnyObject)
      },
      uniquingKeysWith: { (_, right) in right })

• 一个 [String: Any] 字典，例如，可以用来给 JSONSerialization 提供数据。

  let dict = Dictionary(
      row.map { (column, dbValue) in
          (column, dbValue.storage.value)
      },
      uniquingKeysWith: { (left, _) in left })

有关更多信息，请参见 Dictionary.init(_:uniquingKeysWith:) 的文档。

📖 DatabaseValueConvertible

你可以直接获取值，而不是获取行。 有许多支持的 值类型 (Bool, Int, String, Date, Swift 枚举等)。

与行一样，将值作为游标、数组、集合或单个值获取 (请参见 获取方法)。 值是从 SQL 查询的最左侧列中提取的。

try dbQueue.read { db in
    try Int.fetchCursor(db, sql: "SELECT ...", arguments: ...) // A Cursor of Int
    try Int.fetchAll(db, sql: "SELECT ...", arguments: ...)    // [Int]
    try Int.fetchSet(db, sql: "SELECT ...", arguments: ...)    // Set<Int>
    try Int.fetchOne(db, sql: "SELECT ...", arguments: ...)    // Int?
    
    let maxScore = try Int.fetchOne(db, sql: "SELECT MAX(score) FROM player") // Int?
    let names = try String.fetchAll(db, sql: "SELECT name FROM player")       // [String]
}

Int.fetchOne 在两种情况下返回 nil：要么 SELECT 语句没有产生任何行，要么产生了一行但包含一个 NULL 值。

// No row:
try Int.fetchOne(db, sql: "SELECT 42 WHERE FALSE") // nil

// One row with a NULL value:
try Int.fetchOne(db, sql: "SELECT NULL")           // nil

// One row with a non-NULL value:
try Int.fetchOne(db, sql: "SELECT 42")             // 42

对于可能包含 NULL 的请求，获取可选类型。

try dbQueue.read { db in
    try Optional<Int>.fetchCursor(db, sql: "SELECT ...", arguments: ...) // A Cursor of Int?
    try Optional<Int>.fetchAll(db, sql: "SELECT ...", arguments: ...)    // [Int?]
    try Optional<Int>.fetchSet(db, sql: "SELECT ...", arguments: ...)    // Set<Int?>
}

💡 提示：当获取单个值时，一个高级用例是区分语句未产生任何行或产生一行但包含 NULL 值的情况。为此，请使用 Optional<Int>.fetchOne，它返回一个双重可选类型 Int??。

// No row:
try Optional<Int>.fetchOne(db, sql: "SELECT 42 WHERE FALSE") // .none
// One row with a NULL value:
try Optional<Int>.fetchOne(db, sql: "SELECT NULL")           // .some(.none)
// One row with a non-NULL value:
try Optional<Int>.fetchOne(db, sql: "SELECT 42")             // .some(.some(42))

有许多支持的值类型 (Bool, Int, String, Date, Swift 枚举等)。 更多信息请参见 值。

GRDB 附带对以下值类型的内置支持：

• Swift 标准库：Bool, Double, Float, 所有有符号和无符号整数类型, String, Swift 枚举。

• Foundation: Data, Date, DateComponents, Decimal, NSNull, NSNumber, NSString, URL, UUID。

• CoreGraphics: CGFloat.

• DatabaseValue, 该类型提供有关存储在数据库中的原始值的信息。

• 全文模式：FTS3Pattern 和 FTS5Pattern。

• 一般来说，所有采用 DatabaseValueConvertible 协议的类型都支持。

值可以用作 语句参数。

let url: URL = ...
let verified: Bool = ...
try db.execute(
    sql: "INSERT INTO link (url, verified) VALUES (?, ?)",
    arguments: [url, verified])

值可以从 行中提取。

let rows = try Row.fetchCursor(db, sql: "SELECT * FROM link")
while let row = try rows.next() {
    let url: URL = row["url"]
    let verified: Bool = row["verified"]
}

值可以被 直接获取。

let urls = try URL.fetchAll(db, sql: "SELECT url FROM link")  // [URL]

在 Records 中使用值。

struct Link: FetchableRecord {
    var url: URL
    var isVerified: Bool
    
    init(row: Row) {
        url = row["url"]
        isVerified = row["verified"]
    }
}

在 查询接口 中使用值。

let url: URL = ...
let link = try Link.filter(Column("url") == url).fetchOne(db)

Data 适用于 BLOB SQLite 列。 它可以像其他 值 一样存储和从数据库中获取。

let rows = try Row.fetchCursor(db, sql: "SELECT data, ...")
while let row = try rows.next() {
    let data: Data = row["data"]
}

在请求迭代的每个步骤中，row[] 下标都会创建数据库字节的 *两个副本*：一个由 SQLite 获取，另一个存储在 Swift Data 值中。

你可以通过不复制 SQLite 获取的数据来节省内存。

while let row = try rows.next() {
    try row.withUnsafeData(name: "data") { (data: Data?) in
        ...
    }
}

非复制数据的生命周期不会超过迭代步骤：请确保你在此点之后不使用它。

Date 和 DateComponents 可以存储和从数据库中获取。

以下是 GRDB 如何支持 SQLite 支持的各种 日期格式。

¹ 缺失的组件假定为零。 日期以 UTC 时区存储和读取，除非格式后跟时区指示符 ⁽²⁾。

² 此格式可以选择后跟 [+-]HH:MM 或仅 Z 形式的时区指示符。

³ GRDB 2+ 将数值解释为驱动 Date(timeIntervalSince1970:) 的时间戳。 之前的 GRDB 版本过去将数字解释为 儒略日。 儒略日仍然支持，通过 Date(julianDay:) 初始化器。

警告：SQLite 日期格式中有效年份的范围是 0000-9999。 当你的应用程序需要处理此范围之外的年份时，你需要选择另一种日期格式。 请参见以下章节。

Date 可以像其他 值 一样存储和从数据库中获取。

try db.execute(
    sql: "INSERT INTO player (creationDate, ...) VALUES (?, ...)",
    arguments: [Date(), ...])

let row = try Row.fetchOne(db, ...)!
let creationDate: Date = row["creationDate"]

日期使用 "YYYY-MM-DD HH:MM:SS.SSS" 格式以 UTC 时区存储。 它精确到毫秒。

注意：选择此格式是因为它是唯一一个：

• 可比较的 (ORDER BY date 工作)
• 与 SQLite 关键字 CURRENT_TIMESTAMP 可比较 (WHERE date > CURRENT_TIMESTAMP 工作)
• 能够给 SQLite 日期和时间函数 提供数据
• 足够精确

警告：SQLite 日期格式中有效年份的范围是 0000-9999。 你会遇到超出此范围的年份的问题，例如解码错误，或使用 SQLite 日期和时间函数 进行的无效日期计算。

某些应用程序可能更喜欢另一种日期格式。

• 有些人可能更喜欢带有 T 分隔符的 ISO-8601。
• 有些人可能更喜欢带有时区的 ISO-8601。
• 有些人可能需要存储超出 0000-9999 范围的年份。
• 有些人可能需要亚毫秒级的精度。
• 有些人可能需要精确的 Date 往返。
• 等等。

在选择不同的日期格式之前，你应该三思。

• ISO-8601 是关于 *交换和通信* 的，而 SQLite 是关于 *存储和数据操作* 的。 在你的数据库和 JSON 文件中使用相同的表示形式只会提供表面的便利，并且应该是你最不优先考虑的事情。 如果不了解你会失去什么，请不要将日期存储为 ISO-8601。 例如，ISO-8601 时区禁止数据库级别的日期比较。
• 亚毫秒级的精度和精确的 Date 往返并不像乍看起来那样明显。 日期通常在离开你的应用程序后就不能精确往返，因为你的应用程序与之通信的其他系统使用它们自己的日期表示形式（你的应用程序的 Android 版本，你的应用程序与之通信的服务器等）。 最重要的是，Date 比较至少与 浮点数比较 一样困难和令人讨厌。

日期格式的自定义是明确的。 例如：

let date = Date()
let timeInterval = date.timeIntervalSinceReferenceDate
try db.execute(
    sql: "INSERT INTO player (creationDate, ...) VALUES (?, ...)",
    arguments: [timeInterval, ...])

if let row = try Row.fetchOne(db, ...) {
    let timeInterval: TimeInterval = row["creationDate"]
    let creationDate = Date(timeIntervalSinceReferenceDate: timeInterval)
}

另请参见 Codable Records 以获取更多日期自定义选项，如果你想定义一个带有自定义数据库表示的 Date 包装类型，请参见 DatabaseValueConvertible。

DateComponents 通过 DatabaseDateComponents 辅助类型间接支持。

DatabaseDateComponents 从所有 SQLite 支持的日期格式 中读取日期组件，并将它们存储在你选择的格式中，从 HH:MM 到 YYYY-MM-DD HH:MM:SS.SSS。

警告：有效年份的范围是 0000-9999。 你会遇到超出此范围的年份的问题，例如解码错误，或使用 SQLite 日期和时间函数 进行的无效日期计算。 更多信息请参见 Date。

DatabaseDateComponents 可以像其他 值 一样存储和从数据库中获取。

let components = DateComponents()
components.year = 1973
components.month = 9
components.day = 18

// Store "1973-09-18"
let dbComponents = DatabaseDateComponents(components, format: .YMD)
try db.execute(
    sql: "INSERT INTO player (birthDate, ...) VALUES (?, ...)",
    arguments: [dbComponents, ...])

// Read "1973-09-18"
let row = try Row.fetchOne(db, sql: "SELECT birthDate ...")!
let dbComponents: DatabaseDateComponents = row["birthDate"]
dbComponents.format         // .YMD (the actual format found in the database)
dbComponents.dateComponents // DateComponents

NSNumber 和 Decimal 可以像其他 值 一样存储和从数据库中获取。

以下是 GRDB 如何支持 SQLite 支持的各种数据类型。

• 所有这三种类型都可以解码数据库整数和双精度浮点数。

  let number = try NSNumber.fetchOne(db, sql: "SELECT 10")            // NSNumber
  let number = try NSDecimalNumber.fetchOne(db, sql: "SELECT 1.23")   // NSDecimalNumber
  let number = try Decimal.fetchOne(db, sql: "SELECT -100")           // Decimal

• 所有这三种类型都将数据库字符串解码为十进制数字。

  let number = try NSNumber.fetchOne(db, sql: "SELECT '10'")          // NSDecimalNumber (sic)
  let number = try NSDecimalNumber.fetchOne(db, sql: "SELECT '1.23'") // NSDecimalNumber
  let number = try Decimal.fetchOne(db, sql: "SELECT '-100'")         // Decimal

• NSNumber 和 NSDecimalNumber 在数据库中发送 64 位有符号整数和双精度浮点数。

  // INSERT INTO transfer VALUES (10)
  try db.execute(sql: "INSERT INTO transfer VALUES (?)", arguments: [NSNumber(value: 10)])
  
  // INSERT INTO transfer VALUES (10.0)
  try db.execute(sql: "INSERT INTO transfer VALUES (?)", arguments: [NSNumber(value: 10.0)])
  
  // INSERT INTO transfer VALUES (10)
  try db.execute(sql: "INSERT INTO transfer VALUES (?)", arguments: [NSDecimalNumber(string: "10.0")])
  
  // INSERT INTO transfer VALUES (10.5)
  try db.execute(sql: "INSERT INTO transfer VALUES (?)", arguments: [NSDecimalNumber(string: "10.5")])

  警告：由于 SQLite 不支持十进制数字，因此发送非整数 NSDecimalNumber 可能会导致在转换为双精度浮点数时精度损失。

  与其将非整数 NSDecimalNumber 发送到数据库，你可能更喜欢：

  • 发送 Decimal 代替（这些将十进制字符串存储在数据库中）。
  • 发送整数代替（例如，存储美分金额而不是欧元金额）。

• Decimal 在数据库中发送十进制字符串。

  // INSERT INTO transfer VALUES ('10')
  try db.execute(sql: "INSERT INTO transfer VALUES (?)", arguments: [Decimal(10)])
  
  // INSERT INTO transfer VALUES ('10.5')
  try db.execute(sql: "INSERT INTO transfer VALUES (?)", arguments: [Decimal(string: "10.5")!])

UUID 可以像其他 值 一样存储和从数据库中获取。

GRDB 将 uuid 存储为 16 字节的数据 blob，并从 16 字节的数据 blob 和字符串（例如 "E621E1F8-C36C-495A-93FC-0C247A3E6E5F"）中解码它们。

Swift 枚举 以及通常所有采用 RawRepresentable 协议的类型，都可以像它们的原始 值 一样存储和从数据库中获取。

enum Color : Int {
    case red, white, rose
}

enum Grape : String {
    case chardonnay, merlot, riesling
}

// Declare empty DatabaseValueConvertible adoption
extension Color : DatabaseValueConvertible { }
extension Grape : DatabaseValueConvertible { }

// Store
try db.execute(
    sql: "INSERT INTO wine (grape, color) VALUES (?, ?)",
    arguments: [Grape.merlot, Color.red])

// Read
let rows = try Row.fetchCursor(db, sql: "SELECT * FROM wine")
while let row = try rows.next() {
    let grape: Grape = row["grape"]
    let color: Color = row["color"]
}

当数据库值与任何枚举情况都不匹配时，你会得到一个致命错误。 可以使用 DatabaseValue 类型避免此致命错误。

let row = try Row.fetchOne(db, sql: "SELECT 'syrah'")!

row[0] as String  // "syrah"
row[0] as Grape?  // fatal error: could not convert "syrah" to Grape.
row[0] as Grape   // fatal error: could not convert "syrah" to Grape.

let dbValue: DatabaseValue = row[0]
if dbValue.isNull {
    // Handle NULL
} else if let grape = Grape.fromDatabaseValue(dbValue) {
    // Handle valid grape
} else {
    // Handle unknown grape
}

SQLite 允许你定义 SQL 函数和聚合。

自定义 SQL 函数或聚合扩展了 SQLite

SELECT reverse(name) FROM player;   -- custom function
SELECT maxLength(name) FROM player; -- custom aggregate

• 自定义 SQL 函数
• 自定义聚合

📖 DatabaseFunction

函数 参数接受一个 DatabaseValue 数组，并返回任何有效的 值 (Bool, Int, String, Date, Swift 枚举等)。 数据库值的数量保证是 argumentCount。

当函数是“纯函数”时，SQLite 有机会执行额外的优化，这意味着它们的结果仅取决于它们的参数。 因此，请尽可能将 pure 参数设置为 true。

let reverse = DatabaseFunction("reverse", argumentCount: 1, pure: true) { (values: [DatabaseValue]) in
    // Extract string value, if any...
    guard let string = String.fromDatabaseValue(values[0]) else {
        return nil
    }
    // ... and return reversed string:
    return String(string.reversed())
}

你通过数据库连接的配置使函数可用。

var config = Configuration()
config.prepareDatabase { db in
    db.add(function: reverse)
}
let dbQueue = try DatabaseQueue(path: dbPath, configuration: config)

try dbQueue.read { db in
    // "oof"
    try String.fetchOne(db, sql: "SELECT reverse('foo')")!
}

函数可以接受可变数量的参数。

当你未提供任何显式 argumentCount 时，该函数可以接受任意数量的参数。

let averageOf = DatabaseFunction("averageOf", pure: true) { (values: [DatabaseValue]) in
    let doubles = values.compactMap { Double.fromDatabaseValue($0) }
    return doubles.reduce(0, +) / Double(doubles.count)
}
db.add(function: averageOf)

// 2.0
try Double.fetchOne(db, sql: "SELECT averageOf(1, 2, 3)")!

函数可以抛出错误。

let sqrt = DatabaseFunction("sqrt", argumentCount: 1, pure: true) { (values: [DatabaseValue]) in
    guard let double = Double.fromDatabaseValue(values[0]) else {
        return nil
    }
    guard double >= 0 else {
        throw DatabaseError(message: "invalid negative number")
    }
    return sqrt(double)
}
db.add(function: sqrt)

// SQLite error 1 with statement `SELECT sqrt(-1)`: invalid negative number
try Double.fetchOne(db, sql: "SELECT sqrt(-1)")!

在 查询界面 中使用自定义函数。

// SELECT reverseString("name") FROM player
Player.select(reverseString(nameColumn))

GRDB 附带内置的 SQL 函数，这些函数执行 Unicode 感知的字符串转换。 请参见 Unicode。

📖 DatabaseFunction, DatabaseAggregate

在注册自定义聚合函数之前，你需要定义一个遵循 DatabaseAggregate 协议的类型。

protocol DatabaseAggregate {
    // Initializes an aggregate
    init()
    
    // Called at each step of the aggregation
    mutating func step(_ dbValues: [DatabaseValue]) throws
    
    // Returns the final result
    func finalize() throws -> DatabaseValueConvertible?
}

例如

struct MaxLength : DatabaseAggregate {
    var maxLength: Int = 0
    
    mutating func step(_ dbValues: [DatabaseValue]) {
        // At each step, extract string value, if any...
        guard let string = String.fromDatabaseValue(dbValues[0]) else {
            return
        }
        // ... and update the result
        let length = string.count
        if length > maxLength {
            maxLength = length
        }
    }
    
    func finalize() -> DatabaseValueConvertible? {
        maxLength
    }
}

let maxLength = DatabaseFunction(
    "maxLength",
    argumentCount: 1,
    pure: true,
    aggregate: MaxLength.self)

和 自定义 SQL 函数 一样，你可以通过数据库连接的配置，使聚合函数对数据库连接可用。

var config = Configuration()
config.prepareDatabase { db in
    db.add(function: maxLength)
}
let dbQueue = try DatabaseQueue(path: dbPath, configuration: config)

try dbQueue.read { db in
    // Some Int
    try Int.fetchOne(db, sql: "SELECT maxLength(name) FROM player")!
}

聚合函数的 step 方法接受一个 DatabaseValue 数组。这个数组包含与 *argumentCount* 参数一样多的值（或者当 *argumentCount* 参数被省略时，包含任意数量的值）。

聚合函数的 finalize 方法返回最终的聚合 值 (Bool, Int, String, Date, Swift 枚举等等)。

当聚合函数是“纯粹的”时，SQLite 有机会执行额外的优化，这意味着它们的结果只取决于它们的输入。因此，如果可能，请确保将 *pure* 参数设置为 true。

在 查询接口 中使用自定义聚合函数。

// SELECT maxLength("name") FROM player
let request = Player.select(maxLength.apply(nameColumn))
try Int.fetchOne(db, request) // Int?

如果并非所有的 SQLite API 都暴露在 GRDB 中，你仍然可以使用 SQLite C 接口 并调用 SQLite C 函数。

要从 SQLCipher 或系统 SQLite 访问 C SQLite 函数，你需要执行额外的导入。

import SQLite3   // System SQLite
import SQLCipher // SQLCipher

let sqliteVersion = String(cString: sqlite3_libversion())

可以通过 Database.sqliteConnection 和 Statement.sqliteStatement 属性访问数据库连接和语句的原始指针。

try dbQueue.read { db in
    // The raw pointer to a database connection:
    let sqliteConnection = db.sqliteConnection

    // The raw pointer to a statement:
    let statement = try db.makeStatement(sql: "SELECT ...")
    let sqliteStatement = statement.sqliteStatement
}

注意

• 这些指针由 GRDB 拥有：不要关闭 GRDB 创建的连接或结束语句。
• GRDB 在“多线程模式”下打开 SQLite 连接，这（奇怪地）意味着**它们不是线程安全的**。请确保在它们专用的调度队列中操作原始数据库和语句。
• 使用原始 SQLite C 接口的风险自负。GRDB 不会阻止你搬起石头砸自己的脚。

**除了 SQLite API 之外，GRDB 还提供了协议**，这些协议有助于将数据库行作为名为“记录”的常规对象进行操作。

try dbQueue.write { db in
    if var place = try Place.fetchOne(db, id: 1) {
        place.isFavorite = true
        try place.update(db)
    }
}

当然，你需要先打开一个 数据库连接，并 创建数据库表。

要定义记录类型，请定义一个类型并使用附带重点功能集的协议对其进行扩展。

例如

struct Player {
    var id: Int64
    var name: String
    var score: Int
}

// Players can be fetched from the database.
extension Player: FetchableRecord { ... }

// Players can be saved into the database.
extension Player: PersistableRecord { ... }

查看一些 记录定义示例。

注意：如果你熟悉 Core Data 的 NSManagedObject 或 Realm 的 Object，你可能会感到文化冲击：GRDB 记录不是唯一的，不会自动更新，也不会延迟加载。这既是目的，也是面向协议编程的结果。

提示：设计记录类型的推荐做法 指南提供了通用指导。

提示：查看 Demo Applications 获取使用记录的示例应用程序。

概述

• 插入记录
• 获取记录
• 更新记录
• 删除记录
• 计数记录

协议和 Record 类

• 记录协议概述
• FetchableRecord 协议
• TableRecord 协议
• PersistableRecord 协议
  • 持久化方法
  • 持久化方法和 RETURNING 子句
  • 持久化回调
• 可识别的记录
• Codable 记录
• 记录比较
• 记录自定义选项
• 记录时间戳和事务日期

要在数据库中插入记录，请调用 insert 方法。

let player = Player(name: "Arthur", email: "arthur@example.com")
try player.insert(db)

👉 insert 方法适用于遵循 PersistableRecord 协议的类型。

要从数据库中获取记录，请调用一个 获取方法。

let arthur = try Player.fetchOne(db,            // Player?
    sql: "SELECT * FROM players WHERE name = ?",
    arguments: ["Arthur"])

let bestPlayers = try Player                    // [Player]
    .order(Column("score").desc)
    .limit(10)
    .fetchAll(db)
    
let spain = try Country.fetchOne(db, id: "ES")  // Country?
let italy = try Country.find(db, id: "IT")      // Country

👉 对于遵循 FetchableRecord 协议的类型，可以使用原始 SQL 进行获取。

👉 对于同时遵循 FetchableRecord 和 TableRecord 协议的类型，可以使用 查询接口 进行无 SQL 获取。

要在数据库中更新记录，请调用 update 方法。

var player: Player = ...
player.score = 1000
try player.update(db)

可以 避免无用的更新。

// does not hit the database if score has not changed
try player.updateChanges(db) {
    $0.score = 1000
}

有关批量更新，请参见 查询接口。

try Player
    .filter(Column("team") == "red")
    .updateAll(db, Column("score") += 1)

👉 update 方法适用于遵循 PersistableRecord 协议的类型。批量更新适用于 TableRecord 协议。

要在数据库中删除记录，请调用 delete 方法。

let player: Player = ...
try player.delete(db)

你还可以通过主键、唯一键删除，或执行批量删除（参见 删除请求）。

try Player.deleteOne(db, id: 1)
try Player.deleteOne(db, key: ["email": "arthur@example.com"])
try Country.deleteAll(db, ids: ["FR", "US"])
try Player
    .filter(Column("email") == nil)
    .deleteAll(db)

👉 delete 方法适用于遵循 PersistableRecord 协议的类型。批量删除适用于 TableRecord 协议。

要计数记录，请调用 fetchCount 方法。

let playerCount: Int = try Player.fetchCount(db)

let playerWithEmailCount: Int = try Player
    .filter(Column("email") == nil)
    .fetchCount(db)

👉 fetchCount 方法适用于遵循 TableRecord 协议的类型。

详细信息如下

• 记录协议概述
• FetchableRecord 协议
• TableRecord 协议
• PersistableRecord 协议
• 可识别的记录
• Codable 记录
• 记录比较
• 记录自定义选项
• 记录定义示例

**GRDB 附带了三个记录协议**。根据你希望扩展类型的功能，你自己的类型将采用其中一个或多个协议。

• FetchableRecord 能够**解码数据库行**。

  struct Place: FetchableRecord { ... }
  
  let places = try dbQueue.read { db in
      try Place.fetchAll(db, sql: "SELECT * FROM place")
  }

  💡 **提示**：FetchableRecord 可以从标准 Decodable 协议派生其实现。有关更多信息，请参见 Codable 记录。

  FetchableRecord 可以解码数据库行，但它无法为你构建 SQL 请求。为此，你还需要 TableRecord。

• TableRecord 能够**生成 SQL 查询**。

  struct Place: TableRecord { ... }
  
  let placeCount = try dbQueue.read { db in
      // Generates and runs `SELECT COUNT(*) FROM place`
      try Place.fetchCount(db)
  }

  当一个类型同时遵循 TableRecord 和 FetchableRecord 时，它可以从这些请求中加载数据。

  struct Place: TableRecord, FetchableRecord { ... }
  
  try dbQueue.read { db in
      let places = try Place.order(Column("title")).fetchAll(db)
      let paris = try Place.fetchOne(id: 1)
  }

• PersistableRecord 能够**写入**：它可以在数据库中创建、更新和删除行。

  struct Place : PersistableRecord { ... }
  
  try dbQueue.write { db in
      try Place.delete(db, id: 1)
      try Place(...).insert(db)
  }

  一个可持久化的记录还可以针对其他记录进行比较，并避免无用的数据库更新。

  💡 **提示**：PersistableRecord 可以从标准 Encodable 协议派生其实现。有关更多信息，请参见 Codable 记录。

📖 FetchableRecord

**FetchableRecord 协议向任何可以从数据库行构建的类型授予获取方法**。

protocol FetchableRecord {
    /// Row initializer
    init(row: Row) throws
}

例如

struct Place {
    var id: Int64?
    var title: String
    var coordinate: CLLocationCoordinate2D
}

extension Place : FetchableRecord {
    init(row: Row) {
        id = row["id"]
        title = row["title"]
        coordinate = CLLocationCoordinate2D(
            latitude: row["latitude"],
            longitude: row["longitude"])
    }
}

行也接受列枚举。

extension Place : FetchableRecord {
    enum Columns: String, ColumnExpression {
        case id, title, latitude, longitude
    }
    
    init(row: Row) {
        id = row[Columns.id]
        title = row[Columns.title]
        coordinate = CLLocationCoordinate2D(
            latitude: row[Columns.latitude],
            longitude: row[Columns.longitude])
    }
}

有关 row[] 下标的更多信息，请参见 列值。

当你的记录类型遵循标准 Decodable 协议时，你不必为 init(row:) 提供实现。有关更多信息，请参见 Codable 记录。

// That's all
struct Player: Decodable, FetchableRecord {
    var id: Int64
    var name: String
    var score: Int
}

FetchableRecord 允许采用类型从 SQL 查询中获取。

try Place.fetchCursor(db, sql: "SELECT ...", arguments:...) // A Cursor of Place
try Place.fetchAll(db, sql: "SELECT ...", arguments:...)    // [Place]
try Place.fetchSet(db, sql: "SELECT ...", arguments:...)    // Set<Place>
try Place.fetchOne(db, sql: "SELECT ...", arguments:...)    // Place?

有关 fetchCursor、fetchAll、fetchSet 和 fetchOne 方法的信息，请参见 获取方法。有关查询参数的更多信息，请参见 StatementArguments。

**注意**：出于性能原因，在 fetch 查询的迭代过程中，传递给 init(row:) 的相同 row 参数会被重用。 如果你想保留该行以供以后使用，请确保存储一个副本：self.row = row.copy()。

**注意**：FetchableRecord.init(row:) 初始化器满足了大多数应用程序的需求。但是，有些应用程序的需求更高。当 FetchableRecord 不能完全提供你需要的支持时，请查看 超越 FetchableRecord 章节。

📖 TableRecord

**TableRecord 协议**为你生成 SQL。

protocol TableRecord {
    static var databaseTableName: String { get }
    static var databaseSelection: [any SQLSelectable] { get }
}

databaseSelection 类型属性是可选的，并在 请求选择的列 章节中进行了文档说明。

databaseTableName 类型属性是一个数据库表的名称。 默认情况下，它派生自类型名称。

struct Place: TableRecord { }

print(Place.databaseTableName) // prints "place"

例如

• Place: place
• Country: country
• PostalAddress: postalAddress
• HTTPRequest: httpRequest
• TOEFL: toefl

你仍然可以提供自定义表名。

struct Place: TableRecord {
    static let databaseTableName = "location"
}

print(Place.databaseTableName) // prints "location"

当一个类型同时采用 TableRecord 和 FetchableRecord 时，可以使用 查询接口 获取它。

// SELECT * FROM place WHERE name = 'Paris'
let paris = try Place.filter(nameColumn == "Paris").fetchOne(db)

TableRecord 还可以处理主键和唯一键：参见 按键获取 和 测试记录是否存在。

📖 EncodableRecord, MutablePersistableRecord, PersistableRecord

GRDB 记录类型可以在数据库中创建、更新和删除行。

这些能力由三个协议授予。

// Defines how a record encodes itself into the database
protocol EncodableRecord {
    /// Defines the values persisted in the database
    func encode(to container: inout PersistenceContainer) throws
}

// Adds persistence methods
protocol MutablePersistableRecord: TableRecord, EncodableRecord {
    /// Optional method that lets your adopting type store its rowID upon
    /// successful insertion. Don't call it directly: it is called for you.
    mutating func didInsert(_ inserted: InsertionSuccess)
}

// Adds immutability
protocol PersistableRecord: MutablePersistableRecord {
    /// Non-mutating version of the optional didInsert(_:)
    func didInsert(_ inserted: InsertionSuccess)
}

是的，三个协议而不是一个。 这是你如何选择其中一个或另一个。

• **如果你的类型是一个类**，请选择 PersistableRecord。 最重要的是，如果数据库表具有自动递增的主键，请实现 didInsert(_:)。

• **如果你的类型是一个结构体，并且数据库表具有自动递增的主键**，请选择 MutablePersistableRecord，并实现 didInsert(_:)。

• **否则**，选择 PersistableRecord，并忽略 didInsert(_:)。

encode(to:) 方法定义了哪些 值（Bool，Int，String，Date，Swift 枚举等等）被分配给数据库列。

可选的 didInsert 方法允许采用类型在成功插入后存储其 rowID，并且仅对具有自动递增主键的表有用。 它从受保护的调度队列调用，并与所有数据库更新序列化。

例如

extension Place : MutablePersistableRecord {
    /// The values persisted in the database
    func encode(to container: inout PersistenceContainer) {
        container["id"] = id
        container["title"] = title
        container["latitude"] = coordinate.latitude
        container["longitude"] = coordinate.longitude
    }
    
    // Update auto-incremented id upon successful insertion
    mutating func didInsert(_ inserted: InsertionSuccess) {
        id = inserted.rowID
    }
}

var paris = Place(
    id: nil,
    title: "Paris",
    coordinate: CLLocationCoordinate2D(latitude: 48.8534100, longitude: 2.3488000))

try paris.insert(db)
paris.id   // some value

持久化容器也接受列枚举。

extension Place : MutablePersistableRecord {
    enum Columns: String, ColumnExpression {
        case id, title, latitude, longitude
    }
    
    func encode(to container: inout PersistenceContainer) {
        container[Columns.id] = id
        container[Columns.title] = title
        container[Columns.latitude] = coordinate.latitude
        container[Columns.longitude] = coordinate.longitude
    }
}

当你的记录类型遵循标准 Encodable 协议时，你不必为 encode(to:) 提供实现。有关更多信息，请参见 Codable 记录。

// That's all
struct Player: Encodable, MutablePersistableRecord {
    var id: Int64?
    var name: String
    var score: Int
    
    // Update auto-incremented id upon successful insertion
    mutating func didInsert(_ inserted: InsertionSuccess) {
        id = inserted.rowID
    }
}

遵循 PersistableRecord 协议的类型具有插入、更新和删除的方法。

// INSERT
try place.insert(db)
let insertedPlace = try place.inserted(db) // non-mutating

// UPDATE
try place.update(db)
try place.update(db, columns: ["title"])

// Maybe UPDATE
try place.updateChanges(db, from: otherPlace)
try place.updateChanges(db) { $0.isFavorite = true }

// INSERT or UPDATE
try place.save(db)
let savedPlace = place.saved(db) // non-mutating

// UPSERT
try place.upsert(db)
let insertedPlace = place.upsertAndFetch(db)

// DELETE
try place.delete(db)

// EXISTENCE CHECK
let exists = try place.exists(db)

有关 upsert 的更多信息，请参见下面的 Upsert。

TableRecord 协议附带批量操作。:

// UPDATE
try Place.updateAll(db, ...)

// DELETE
try Place.deleteAll(db)
try Place.deleteAll(db, ids:...)
try Place.deleteAll(db, keys:...)
try Place.deleteOne(db, id:...)
try Place.deleteOne(db, key:...)

有关批量更新的更多信息，请参见 更新请求。

• 所有持久化方法都可以抛出 DatabaseError。

• 如果数据库不包含该记录的主键的任何行，则 update 和 updateChanges 会抛出 RecordError。

• save 确保你的值被存储到数据库中。如果记录具有非空的 primary key（主键），它会执行 UPDATE 操作；如果没有任何行被修改，则执行 INSERT 操作。如果记录没有 primary key，或者 primary key 为空，它会直接执行 INSERT 操作。

• delete 和 deleteOne 返回一个数据库行是否被删除。deleteAll 返回被删除的行数。updateAll 返回被更新的行数。updateChanges 返回一个数据库行是否被更新。

支持所有主键，包括跨越多个列的复合主键，以及隐藏的 rowid 列。

要自定义持久化方法，你可以提供持久化回调，如下所述。不要尝试覆盖现成的持久化方法。

UPSERT 是 SQLite 的一项功能，如果 INSERT 操作违反了唯一性约束（primary key 或唯一索引），则使 INSERT 操作表现为 UPDATE 操作或无操作。

注意：Upsert API 在 SQLite 3.35.0+ 版本中可用：iOS 15.0+、macOS 12.0+、tvOS 15.0+、watchOS 8.0+，或者通过自定义 SQLite 构建或SQLCipher。

注意：关于持久化回调，upsert 的行为与 insert 完全相同。特别是：aroundInsert(_:) 和 didInsert(_:) 回调报告了插入或更新行的 rowid；willUpdate、aroundUdate、didUdate 不会被调用。

PersistableRecord 提供了三种 upsert 方法

• upsert(_:)

  插入或更新记录。

  如果表上的任何唯一性约束（primary key 或唯一索引）被违反，则会触发 upsert 行为。如果发生冲突，除 primary key 外的所有列都会被插入的值覆盖

  struct Player: Encodable, PersistableRecord {
      var id: Int64
      var name: String
      var score: Int
  }
  
  // INSERT INTO player (id, name, score)
  // VALUES (1, 'Arthur', 1000)
  // ON CONFLICT DO UPDATE SET
  //   name = excluded.name,
  //   score = excluded.score
  let player = Player(id: 1, name: "Arthur", score: 1000)
  try player.upsert(db)

• upsertAndFetch(_:onConflict:doUpdate:)（需要符合 FetchableRecord 协议）

  插入或更新记录，并返回 upsert 后的记录。

  onConflict 和 doUpdate 参数允许你进一步控制 upsert 行为。请务必查看 SQLite UPSERT 文档以获取详细信息。

  • onConflict： “冲突目标”是唯一性约束（primary key 或唯一索引）中触发 upsert 的列的数组。

    如果为空（默认值），则考虑所有唯一性约束。

  • doUpdate：一个闭包，返回在发生冲突时要执行的列赋值。其他列会被插入的值覆盖。

    默认情况下，所有插入的列，除了 primary key 和冲突目标外，都会被覆盖。

  在下面的例子中，我们 upsert 新的词汇单词 "jovial"。如果该单词尚未在词典中，则插入它。否则，count 会递增，isTainted 不会被覆盖，kind 会被覆盖

  // CREATE TABLE vocabulary(
  //   word TEXT NOT NULL PRIMARY KEY,
  //   kind TEXT NOT NULL,
  //   isTainted BOOLEAN DEFAULT 0,
  //   count INT DEFAULT 1))
  struct Vocabulary: Encodable, PersistableRecord {
      var word: String
      var kind: String
      var isTainted: Bool
  }
  
  // INSERT INTO vocabulary(word, kind, isTainted)
  // VALUES('jovial', 'adjective', 0)
  // ON CONFLICT(word) DO UPDATE SET \
  //   count = count + 1,   -- on conflict, count is incremented
  //   kind = excluded.kind -- on conflict, kind is overwritten
  // RETURNING *
  let vocabulary = Vocabulary(word: "jovial", kind: "adjective", isTainted: false)
  let upserted = try vocabulary.upsertAndFetch(
      db, onConflict: ["word"],
      doUpdate: { _ in
          [Column("count") += 1,            // on conflict, count is incremented
           Column("isTainted").noOverwrite] // on conflict, isTainted is NOT overwritten
      })

  doUpdate 闭包接受一个 excluded TableAlias 参数，该参数引用触发冲突的插入值。你可以使用它来指定显式覆盖，或执行计算。在下一个示例中，如果发生冲突，upsert 会保留最大日期

  // INSERT INTO message(id, text, date)
  // VALUES(...)
  // ON CONFLICT DO UPDATE SET \
  //   text = excluded.text,
  //   date = MAX(date, excluded.date)
  // RETURNING *
  let upserted = try message.upsertAndFetch(doUpdate: { excluded in
      // keep the maximum date in case of conflict
      [Column("date").set(to: max(Column("date"), excluded["date"]))]
  })

• upsertAndFetch(_:as:onConflict:doUpdate:)（不需要符合 FetchableRecord 协议）

  此方法与上面描述的 upsertAndFetch(_:onConflict:doUpdate:) 相同，但是你可以提供不同的 FetchableRecord 记录类型作为结果，以便指定返回的列。

SQLite 能够使用 RETURNING 子句从插入、更新或删除的行中返回值。

注意：对 RETURNING 子句的支持在 SQLite 3.35.0+ 版本中可用：iOS 15.0+、macOS 12.0+、tvOS 15.0+、watchOS 8.0+，或者通过自定义 SQLite 构建或SQLCipher。

RETURNING 子句有助于处理数据库功能，例如自增 id、默认值和生成的列。例如，你可以插入一些列，并在一个步骤中获取默认列或生成的列。

GRDB 在所有名称中包含 AndFetch 的持久化方法中使用 RETURNING 子句。

例如，给定一个具有自增 primary key 和默认分数的数据库表

try dbQueue.write { db in
    try db.execute(sql: """
        CREATE TABLE player(
          id INTEGER PRIMARY KEY AUTOINCREMENT,
          name TEXT NOT NULL,
          score INTEGER NOT NULL DEFAULT 1000)
        """)
}

你可以定义一个包含完整数据库信息的记录类型，以及另一个处理列子集的局部记录类型

// A player with full database information
struct Player: Codable, PersistableRecord, FetchableRecord {
    var id: Int64
    var name: String
    var score: Int
}

// A partial player
struct PartialPlayer: Encodable, PersistableRecord {
    static let databaseTableName = "player"
    var name: String
}

现在你可以通过插入一个局部 player 来获得一个完整的 player

try dbQueue.write { db in
    let partialPlayer = PartialPlayer(name: "Alice")
    
    // INSERT INTO player (name) VALUES ('Alice') RETURNING *
    let player = try partialPlayer.insertAndFetch(db, as: Player.self)
    print(player.id)    // The inserted id
    print(player.name)  // The inserted name
    print(player.score) // The default score
}

为了获得更高的精度，你可以只选择你需要的列，并从提供的预编译的 Statement 中获取所需的值

try dbQueue.write { db in
    let partialPlayer = PartialPlayer(name: "Alice")
    
    // INSERT INTO player (name) VALUES ('Alice') RETURNING score
    let score = try partialPlayer.insertAndFetch(db, selection: [Column("score")]) { statement in
        try Int.fetchOne(statement)
    }
    print(score) // Prints 1000, the default score
}

还有其他类似的持久化方法，例如 upsertAndFetch、saveAndFetch、updateAndFetch、updateChangesAndFetch 等。它们的行为都类似于 upsert、save、update、updateChanges，只不过它们返回保存的值。例如

// Save and return the saved player
let savedPlayer = try player.saveAndFetch(db)

有关更多信息，请参见持久化方法、Upsert 和 updateChanges 方法。

批量操作可以返回更新或删除的值

警告：请务必查看 RETURNING 子句的文档，其中描述了批量操作的重要限制和注意事项。

let request = Player.filter(...)...

// Fetch all deleted players
// DELETE FROM player RETURNING *
let deletedPlayers = try request.deleteAndFetchAll(db) // [Player]

// Fetch a selection of columns from the deleted rows
// DELETE FROM player RETURNING name
let statement = try request.deleteAndFetchStatement(db, selection: [Column("name")])
let deletedNames = try String.fetchSet(statement)

// Fetch all updated players
// UPDATE player SET score = score + 10 RETURNING *
let updatedPlayers = try request.updateAndFetchAll(db, [Column("score") += 10]) // [Player]

// Fetch a selection of columns from the updated rows
// UPDATE player SET score = score + 10 RETURNING score
let statement = try request.updateAndFetchStatement(
    db, [Column("score") += 10],
    select: [Column("score")])
let updatedScores = try Int.fetchAll(statement)

当调用持久化方法时，你的自定义类型可能想要执行额外的工作。

为此，你的记录类型可以实现持久化回调。回调是在记录生命周期的特定时刻被调用的方法。通过回调，可以编写在插入、更新或删除记录时运行的代码。

为了使用回调方法，你需要提供它的实现。例如，一个经常使用的回调是 didInsert，在自增数据库 id 的情况下

struct Player: MutablePersistableRecord {
    var id: Int64?
    
    // Update auto-incremented id upon successful insertion
    mutating func didInsert(_ inserted: InsertionSuccess) {
        id = inserted.rowID
    }
}

try dbQueue.write { db in
    var player = Player(id: nil, ...)
    try player.insert(db)
    print(player.id) // didInsert was called: prints some non-nil id
}

回调还可以帮助实现记录验证

struct Link: PersistableRecord {
    var url: URL
    
    func willSave(_ db: Database) throws {
        if url.host == nil {
            throw ValidationError("url must be absolute.")
        }
    }
}

try link.insert(db) // Calls the willSave callback
try link.update(db) // Calls the willSave callback
try link.save(db)   // Calls the willSave callback
try link.upsert(db) // Calls the willSave callback

以下是所有可用的持久化回调的列表，按照它们在各自操作期间被调用的顺序排列

• 插入记录（所有 record.insert 和 record.upsert 方法）

  • willSave
  • aroundSave
  • willInsert
  • aroundInsert
  • didInsert
  • didSave

• 更新记录（所有 record.update 方法）

  • willSave
  • aroundSave
  • willUpdate
  • aroundUpdate
  • didUpdate
  • didSave

• 删除记录（仅 record.delete(_:) 方法）

  • willDelete
  • aroundDelete
  • didDelete

有关每个回调的详细信息，请查看参考文档。

在 MutablePersistableRecord 协议中，willInsert 和 didInsert 是 mutating 方法。在 PersistableRecord 中，它们不是 mutating 方法。

注意：如果记录具有非空的 primary key，则 record.save(_:) 方法会执行 UPDATE 操作；如果没有任何行被修改，则执行 INSERT 操作。如果记录没有 primary key，或者 primary key 为空，它会直接执行 INSERT 操作。它会相应地触发 update 和/或 insert 回调。

警告：回调仅从对记录实例调用的持久化方法中调用。当你调用类型方法、执行批量操作或执行原始 SQL 时，不会调用回调。

警告：当调用 did*** 回调时，不要假设更改实际上已持久化到磁盘，因为数据库可能仍在未提交的事务中。当你需要处理事务完成时，请使用afterNextTransaction(onCommit:onRollback:)。例如

struct PictureFile: PersistableRecord {
    var path: String
    
    func willDelete(_ db: Database) {
        db.afterNextTransaction { _ in
            try? deleteFileOnDisk()
        }
    }
}

当记录类型映射一个具有单列 primary key 的表时，建议使其采用标准的 Identifiable 协议。

struct Player: Identifiable, FetchableRecord, PersistableRecord {
    var id: Int64 // fulfills the Identifiable requirement
    var name: String
    var score: Int
}

当 id 具有数据库兼容的类型（Int64、Int、String、UUID 等）时，符合 Identifiable 协议会解锁类型安全的记录和请求方法

let player = try Player.find(db, id: 1)               // Player
let player = try Player.fetchOne(db, id: 1)           // Player?
let players = try Player.fetchAll(db, ids: [1, 2, 3]) // [Player]
let players = try Player.fetchSet(db, ids: [1, 2, 3]) // Set<Player>

let request = Player.filter(id: 1)
let request = Player.filter(ids: [1, 2, 3])

try Player.deleteOne(db, id: 1)
try Player.deleteAll(db, ids: [1, 2, 3])

注意：并非所有记录类型都可以设置为 Identifiable，并且并非所有表都具有单列 primary key。GRDB 提供了其他处理 primary key 和唯一键的方法，但它们不会检查其参数的类型

// Available on non-Identifiable types
try Player.fetchOne(db, key: 1)
try Player.fetchOne(db, key: ["email": "arthur@example.com"])
try Country.fetchAll(db, keys: ["FR", "US"])
try Citizenship.fetchOne(db, key: ["citizenId": 1, "countryCode": "FR"])

let request = Player.filter(key: 1)
let request = Player.filter(keys: [1, 2, 3])

try Player.deleteOne(db, key: 1)
try Player.deleteAll(db, keys: [1, 2, 3])

注意：不建议在使用自增 primary key 的记录类型上使用 Identifiable

// AVOID declaring Identifiable conformance when key is auto-incremented
struct Player {
    var id: Int64? // Not an id suitable for Identifiable
    var name: String
    var score: Int
}

extension Player: FetchableRecord, MutablePersistableRecord {
    // Update auto-incremented id upon successful insertion
    mutating func didInsert(_ inserted: InsertionSuccess) {
        id = inserted.rowID
    }
}

有关详细的基本原理，请参阅issue #1435。

某些数据库表具有一个名为 "id" 的单列 primary key

try db.create(table: "country") { t in
    t.primaryKey("isoCode", .text)
    t.column("name", .text).notNull()
    t.column("population", .integer).notNull()
}

在这种情况下，例如，可以通过从 id 属性返回 primary key 列来实现 Identifiable 协议

struct Country: Identifiable, FetchableRecord, PersistableRecord {
    var isoCode: String
    var name: String
    var population: Int
    
    // Fulfill the Identifiable requirement
    var id: String { isoCode }
}

let france = try dbQueue.read { db in
    try Country.fetchOne(db, id: "FR")
}

采用存档协议（Codable、Encodable 或 Decodable）的记录类型只需声明符合所需的记录协议即可获得免费的数据库支持

// Declare a record...
struct Player: Codable, FetchableRecord, PersistableRecord {
    var name: String
    var score: Int
}

// ...and there you go:
try dbQueue.write { db in
    try Player(name: "Arthur", score: 100).insert(db)
    let players = try Player.fetchAll(db)
}