Merge pull request #1145 from museapphq/feature/reset-statement

Adding public method to reset a prepared statement

Author: jberkel

Documentation/Index.md

@@ -828,7 +828,7 @@ let query = try db.prepare(users)
 for user in query {
     // 💥 can throw an error here
 }
-````
+```
 
 #### Failable iteration
 
@@ -1872,6 +1872,14 @@ let stmt = try db.prepare("SELECT * FROM attachments WHERE typeConformsTo(UTI, ?
 for row in stmt.bind(kUTTypeImage) { /* ... */ }
 ```
 
+> _Note:_ Prepared queries can be reused, and long lived prepared queries should be `reset()` after each use. Otherwise, the transaction (either [implicit or explicit](https://www.sqlite.org/lang_transaction.html#implicit_versus_explicit_transactions)) will be held open until the query is reset or finalized. This can affect performance. Statements are reset automatically during `deinit`.
+> 
+> ```swift
+> someObj.statement = try db.prepare("SELECT * FROM attachments WHERE typeConformsTo(UTI, ?)")
+> for row in someObj.statement.bind(kUTTypeImage) { /* ... */ }
+> someObj.statement.reset()
+> ```
+
 [UTTypeConformsTo]: https://developer.apple.com/documentation/coreservices/1444079-uttypeconformsto
 
 ## Custom Aggregations

Sources/SQLite/Core/Statement.swift

@@ -185,7 +185,11 @@ public final class Statement {
         try connection.sync { try connection.check(sqlite3_step(handle)) == SQLITE_ROW }
     }
 
-    fileprivate func reset(clearBindings shouldClear: Bool = true) {
+    public func reset() {
+        reset(clearBindings: true)
+    }
+
+    fileprivate func reset(clearBindings shouldClear: Bool) {
         sqlite3_reset(handle)
         if shouldClear { sqlite3_clear_bindings(handle) }
     }

Tests/SQLiteTests/StatementTests.swift

@@ -1,6 +1,16 @@
 import XCTest
 import SQLite
 
+#if SQLITE_SWIFT_STANDALONE
+import sqlite3
+#elseif SQLITE_SWIFT_SQLCIPHER
+import SQLCipher
+#elseif os(Linux)
+import CSQLite
+#else
+import SQLite3
+#endif
+
 class StatementTests: SQLiteTestCase {
     override func setUpWithError() throws {
         try super.setUpWithError()
@@ -34,4 +44,32 @@ class StatementTests: SQLiteTestCase {
 
         XCTAssertEqual(names.map({ "\($0)@example.com" }), emails.sorted())
     }
+
+    /// Check that a statement reset will close the implicit transaction, allowing wal file to checkpoint
+    func test_reset_statement() throws {
+        // insert single row
+        try insertUsers("bob")
+
+        // prepare a statement and read a single row. This will increment the cursor which
+        // prevents the implicit transaction from closing.
+        // https://www.sqlite.org/lang_transaction.html#implicit_versus_explicit_transactions
+        let statement = try db.prepare("SELECT email FROM users")
+        _ = try statement.step()
+
+        // verify implicit transaction is not closed, and the users table is still locked
+        XCTAssertThrowsError(try db.run("DROP TABLE users")) { error in
+            if case let Result.error(_, code, _) = error {
+                XCTAssertEqual(code, SQLITE_LOCKED)
+            } else {
+                XCTFail("unexpected error")
+            }
+        }
+
+        // reset the prepared statement, unlocking the table and allowing the implicit transaction to close
+        statement.reset()
+
+        // truncate succeeds
+        try db.run("DROP TABLE users")
+    }
+
 }