Update documentation

- Closes stephencelis#1076
- Clarify BusyHandler usage (Closes stephencelis#786)
- Integrate playground into project

Author: jberkel

CHANGELOG.md

@@ -3,6 +3,8 @@
 
 * Support for database backup ([#919][])
 * Support for custom SQL aggregates ([#881][])
+* Restore previous iteration behavior ([#1075][])
+* Fix compilation on Linux ([#1077][])
 
 0.13.0 (22-08-2021), [diff][diff-0.13.0]
 ========================================
@@ -124,3 +126,5 @@
 [#866]: https://github.com/stephencelis/SQLite.swift/pull/866
 [#881]: https://github.com/stephencelis/SQLite.swift/pull/881
 [#919]: https://github.com/stephencelis/SQLite.swift/pull/919
+[#1075]: https://github.com/stephencelis/SQLite.swift/pull/1075
+[#1077]: https://github.com/stephencelis/SQLite.swift/issues/1077

Documentation/Index.md

@@ -77,9 +77,6 @@ The [Swift Package Manager][] is a tool for managing the distribution of
 Swift code. It’s integrated with the Swift build system to automate the
 process of downloading, compiling, and linking dependencies.
 
-It is the recommended approach for using SQLite.swift in OSX CLI
-applications.
-
  1. Add the following to your `Package.swift` file:
 
   ```swift
@@ -342,16 +339,15 @@ execution and can be safely accessed across threads. Threads that open
 transactions and savepoints will block other threads from executing
 statements while the transaction is open.
 
-If you maintain multiple connections for a single database, consider setting a timeout (in seconds) and/or a busy handler:
+If you maintain multiple connections for a single database, consider setting a timeout
+(in seconds) *or* a busy handler. There can only be one active at a time, so setting a busy
+handler will effectively override `busyTimeout`.
 
 ```swift
-db.busyTimeout = 5
+db.busyTimeout = 5 // error after 5 seconds (does multiple retries)
 
 db.busyHandler({ tries in
-    if tries >= 3 {
-        return false
-    }
-    return true
+    tries < 3  // error after 3 tries
 })
 ```
 
@@ -656,12 +652,13 @@ do {
 }
 ```
 
-Multiple rows can be inserted at once by similarily calling `insertMany` with an array of per-row [setters](#setters).
+Multiple rows can be inserted at once by similarily calling `insertMany` with an array of
+per-row [setters](#setters).
 
 ```swift
 do {
-    let rowid = try db.run(users.insertMany([mail <- "[email protected]"], [email <- "[email protected]"]))
-    print("inserted id: \(rowid)")
+    let lastRowid = try db.run(users.insertMany([mail <- "[email protected]"], [email <- "[email protected]"]))
+    print("last inserted id: \(lastRowid)")
 } catch {
     print("insertion failed: \(error)")
 }
@@ -799,6 +796,33 @@ for user in try db.prepare(users) {
 }
 ```
 
+Note that the iterator can throw *undeclared* database errors at any point during
+iteration:
+
+```swift
+let query = try db.prepare(users)
+for user in query {
+    // 💥 can throw an error here
+}
+````
+
+#### Failable iteration
+
+It is therefore recommended using the `RowIterator` API instead,
+which has explicit error handling:
+
+```swift
+let rowIterator = try db.prepareRowIterator(users)
+for user in try Array(rowIterator) {
+    print("id: \(user[id]), email: \(user[email])")
+}
+
+/// or using `map()`
+let mapRowIterator = try db.prepareRowIterator(users)
+let userIds = try mapRowIterator.map { $0[id] }
+
+```
+
 ### Plucking Rows
 
 We can pluck the first row by passing a query to the `pluck` function on a
@@ -1285,7 +1309,6 @@ try db.run(users.addColumn(suffix))
 // ALTER TABLE "users" ADD COLUMN "suffix" TEXT
 ```
 
-
 #### Added Column Constraints
 
 The `addColumn` function shares several of the same [`column` function
@@ -1337,6 +1360,13 @@ tables](#creating-a-table).
     // ALTER TABLE "posts" ADD COLUMN "user_id" INTEGER REFERENCES "users" ("id")
     ```
 
+### Renaming Columns
+
+Added in SQLite 3.25.0, not exposed yet. [#1073](https://github.com/stephencelis/SQLite.swift/issues/1073)
+
+### Dropping Columns
+
+Added in SQLite 3.35.0, not exposed yet. [#1073](https://github.com/stephencelis/SQLite.swift/issues/1073)
 
 ### Indexes
 
@@ -1762,6 +1792,19 @@ for row in stmt.bind(kUTTypeImage) { /* ... */ }
 
 [UTTypeConformsTo]: https://developer.apple.com/documentation/coreservices/1444079-uttypeconformsto
 
+## Custom Aggregations
+
+We can create custom aggregation functions by calling `createAggregation`:
+
+```swift
+let reduce: (String, [Binding?]) -> String = { (last, bindings) in
+    last + " " + (bindings.first as? String ?? "")
+}
+
+db.createAggregation("customConcat", initialValue: "", reduce: reduce, result: { $0 })
+let result = db.prepare("SELECT customConcat(email) FROM users").scalar() as! String
+```
+
 ## Custom Collations
 
 We can create custom collating sequences by calling `createCollation` on a
@@ -1944,6 +1987,19 @@ using the following functions.
     let count = try stmt.scalar() as! Int64
     ```
 
+## Online Database Backup
+
+To copy a database to another using the
+[SQLite Online Backup API](https://sqlite.org/backup.html):
+
+```swift
+// creates an in-memory copy of db.sqlite
+let db = try Connection("db.sqlite")
+let target = try Connection(.inMemory)
+
+let backup = try db.backup(usingConnection: target)
+try backup.step()
+```
 
 ## Logging
 
@@ -1955,6 +2011,14 @@ We can log SQL using the database’s `trace` function.
 #endif
 ```
 
+## Vacuum
+
+To run the [vacuum](https://www.sqlite.org/lang_vacuum.html) command:
+
+```swift
+try db.vacuum()
+```
+
 
 [ROWID]: https://sqlite.org/lang_createtable.html#rowid
 [SQLiteMigrationManager.swift]: https://github.com/garriguv/SQLiteMigrationManager.swift

Documentation/Planning.md

@@ -6,7 +6,7 @@ additions and Pull Requests, as well as to keep the Issues list clear of
 enhancement requests so that bugs are more visible.
 
 > ⚠ This document is currently not actively maintained. See
-> the [0.13.0 milestone](https://github.com/stephencelis/SQLite.swift/issues?q=is%3Aopen+is%3Aissue+milestone%3A0.13.0)
+> the [0.13.1 milestone](https://github.com/stephencelis/SQLite.swift/issues?q=is%3Aopen+is%3Aissue+milestone%3A0.13.1)
 > on Github for additional information about planned features for the next release.
 
 ## Roadmap

Documentation/Release.md

@@ -1,6 +1,7 @@
 # SQLite.swift Release checklist
 
 * [ ] Make sure current master branch has a green build
+* [ ] Make sure `SQLite.playground` runs without errors
 * [ ] Make sure `CHANGELOG.md` is up-to-date
 * [ ] Update the version number in `SQLite.swift.podspec`
 * [ ] Run `pod lib lint` locally

README.md

@@ -146,6 +146,8 @@ Swift code.
   $ swift build
   ```
 
+See the [Tests/SPM](https://github.com/stephencelis/SQLite.swift/tree/master/Tests/SPM) folder for a small demo project which uses SPM.
+
 [Swift Package Manager]: https://swift.org/package-manager
 
 ### Carthage
@@ -175,8 +177,7 @@ install SQLite.swift with Carthage:
 [CocoaPods][] is a dependency manager for Cocoa projects. To install
 SQLite.swift with CocoaPods:
 
- 1. Make sure CocoaPods is [installed][CocoaPods Installation]. (SQLite.swift
-    requires version 1.6.1 or greater.)
+ 1. Make sure CocoaPods is [installed][CocoaPods Installation].
 
     ```sh
     # Using the default Ruby install will require you to use sudo when
@@ -266,7 +267,8 @@ These projects enhance or use SQLite.swift:
 
  - [SQLiteMigrationManager.swift][] (inspired by
    [FMDBMigrationManager][])
- - [Delta: Math helper](https://apps.apple.com/app/delta-math-helper/id1436506800) (see [Delta/Utils/Database.swift](https://github.com/GroupeMINASTE/Delta-iOS/blob/master/Delta/Utils/Database.swift) for production implementation example)
+ - [Delta: Math helper](https://apps.apple.com/app/delta-math-helper/id1436506800)
+   (see [Delta/Utils/Database.swift](https://github.com/GroupeMINASTE/Delta-iOS/blob/master/Delta/Utils/Database.swift) for production implementation example)
 
 
 ## Alternatives
@@ -278,7 +280,6 @@ Looking for something else? Try another Swift wrapper (or [FMDB][]):
  - [SQLiteDB](https://github.com/FahimF/SQLiteDB)
  - [Squeal](https://github.com/nerdyc/Squeal)
  - [SwiftData](https://github.com/ryanfowler/SwiftData)
- - [SwiftSQLite](https://github.com/chrismsimpson/SwiftSQLite)
 
 [Swift]: https://swift.org/
 [SQLite3]: https://www.sqlite.org

SQLite.playground/Contents.swift

@@ -1,43 +1,93 @@
 import SQLite
 
-let db = try! Connection()
+/// Create an in-memory database
+let db = try Connection(.inMemory)
 
+/// enable statement logging
 db.trace { print($0) }
 
+/// define a "users" table with some fields
 let users = Table("users")
 
 let id = Expression<Int64>("id")
-let email = Expression<String>("email")
-let name = Expression<String?>("name")
+let email = Expression<String>("email") // non-null
+let name = Expression<String?>("name")  // nullable
 
-try! db.run(users.create { t in
+/// prepare the query
+let statement = users.create { t in
     t.column(id, primaryKey: true)
     t.column(email, unique: true, check: email.like("%@%"))
     t.column(name)
-})
+}
+
+/// …and run it
+try db.run(statement)
+
+/// insert "alice"
+let rowid = try db.run(users.insert(email <- "[email protected]"))
+
+/// insert multiple rows using `insertMany`
+let lastRowid = try db.run(users.insertMany([
+  [email <- "[email protected]"],
+  [email <- "[email protected]"]
+]))
+
+
+let query = try db.prepare(users)
+for user in query {
+    print("id: \(user[id]), email: \(user[email])")
+}
 
-let rowid = try! db.run(users.insert(email <- "[email protected]"))
-let alice = users.filter(id == rowid)
+// re-requery just rowid of Alice
+let alice = try db.prepare(users.filter(id == rowid))
+for user in alice {
+    print("id: \(user[id]), email: \(user[email])")
+}
 
-for user in try! db.prepare(users) {
+/// using the `RowIterator` API
+let rowIterator = try db.prepareRowIterator(users)
+for user in try Array(rowIterator) {
     print("id: \(user[id]), email: \(user[email])")
 }
 
+/// also with `map()`
+let mapRowIterator = try db.prepareRowIterator(users)
+let userIds = try mapRowIterator.map { $0[id] }
+
+/// define a virtual tabe for the FTS index
 let emails = VirtualTable("emails")
 
-let subject = Expression<String?>("subject")
+let subject = Expression<String>("subject")
 let body = Expression<String?>("body")
 
-try! db.run(emails.create(.FTS4(subject, body)))
+/// create the index
+try db.run(emails.create(.FTS5(
+    FTS5Config()
+      .column(subject)
+      .column(body)
+)))
 
-try! db.run(emails.insert(
+/// populate with data
+try db.run(emails.insert(
     subject <- "Hello, world!",
     body <- "This is a hello world message."
 ))
 
-let row = try! db.pluck(emails.match("hello"))
+/// run a query
+let ftsQuery = try db.prepare(emails.match("hello"))
 
-let query = try! db.prepare(emails.match("hello"))
-for row in query {
+for row in ftsQuery {
     print(row[subject])
 }
+
+/// custom aggregations
+let reduce: (String, [Binding?]) -> String = { (last, bindings) in
+    last + " " + (bindings.first as? String ?? "")
+}
+
+db.createAggregation("customConcat",
+                     initialValue: "users:",
+                     reduce: reduce,
+                     result: { $0 })
+let result = db.prepare("SELECT customConcat(email) FROM users").scalar() as! String
+print(result)

SQLite.playground/contents.xcplayground

@@ -1,4 +1,4 @@
 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
-<playground version='5.0' target-platform='osx' display-mode='raw'>
+<playground version='5.0' target-platform='macos' display-mode='rendered' buildActiveScheme='true' importAppTypes='true'>
     <timeline fileName='timeline.xctimeline'/>
 </playground>

SQLite.playground/playground.xcworkspace/contents.xcworkspacedata

@@ -256,6 +256,7 @@
 		19A17E723300E5ED3771DCB5 /* Result.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = Result.swift; sourceTree = "<group>"; };
 		19A17EA3A313F129011B3FA0 /* Release.md */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = net.daringfireball.markdown; path = Release.md; sourceTree = "<group>"; };
 		3717F907221F5D7C00B9BD3D /* CustomAggregationTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = CustomAggregationTests.swift; sourceTree = "<group>"; };
+		3D3C3CCB26E5568800759140 /* SQLite.playground */ = {isa = PBXFileReference; lastKnownFileType = file.playground; path = SQLite.playground; sourceTree = "<group>"; xcLanguageSpecificationIdentifier = xcode.lang.swift; };
 		3D67B3E51DB2469200A4F4C6 /* libsqlite3.tbd */ = {isa = PBXFileReference; lastKnownFileType = "sourcecode.text-based-dylib-definition"; name = libsqlite3.tbd; path = Platforms/WatchOS.platform/Developer/SDKs/WatchOS3.0.sdk/usr/lib/libsqlite3.tbd; sourceTree = DEVELOPER_DIR; };
 		3DDC112E26CDBA0200CE369F /* SQLiteObjc.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; name = SQLiteObjc.h; path = ../SQLiteObjc/include/SQLiteObjc.h; sourceTree = "<group>"; };
 		49EB68C31F7B3CB400D89D40 /* Coding.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = Coding.swift; sourceTree = "<group>"; };
@@ -386,6 +387,7 @@
 			children = (
 				EE247AD51C3F04ED00AE3E12 /* SQLite */,
 				EE247AE11C3F04ED00AE3E12 /* SQLiteTests */,
+				3D3C3CCB26E5568800759140 /* SQLite.playground */,
 				EE247B8A1C3F81D000AE3E12 /* Metadata */,
 				EE247AD41C3F04ED00AE3E12 /* Products */,
 				3D67B3E41DB2469200A4F4C6 /* Frameworks */,

SQLite.xcodeproj/project.pbxproj

@@ -90,7 +90,7 @@ extension Connection {
         register(functionName, argc: argc, value: box)
     }
 
-    func createAggregation<T: AnyObject>(
+    public func createAggregation<T: AnyObject>(
             _ aggregate: String,
             argumentCount: UInt? = nil,
             deterministic: Bool = false,
@@ -122,7 +122,7 @@ extension Connection {
         createAggregation(aggregate, step: step, final: final, state: state)
     }
 
-    func createAggregation<T>(
+    public func createAggregation<T>(
             _ aggregate: String,
             argumentCount: UInt? = nil,
             deterministic: Bool = false,