Adding public method to reset a prepared statement

[adamwulf]

For context, the sqlite docs: https://www.sqlite.org/lang_transaction.html#implicit_versus_explicit_transactions

An implicit transaction (a transaction that is started automatically, not a transaction started by BEGIN) is committed automatically when the last active statement finishes. A statement finishes when its last cursor closes, which is guaranteed to happen when the prepared statement is reset or finalized. Some statements might "finish" for the purpose of transaction control prior to being reset or finalized, but there is no guarantee of this. The only way to ensure that a statement has "finished" is to invoke sqlite3_reset() or sqlite3_finalize() on that statement.

For clients that keep and reuse prepared statements, that statement prevents transactions from fully closing (even after a COMMIT). This, in turn, prevents a wal checkpoint (both explicitly requested checkpoint and auto checkpoints) from succeeding. Since reset is only currently called when starting a new query or in deinit, this means for any long-lived prepared statement will prevent a wal checkpoint, causing the wal file to grow unbounded.

Instead, allowing clients to explicitly reset their prepared statements allows them to control when the transaction closes, which allows wal checkpoints to succeed.

[nathanfallet]

LGTM. Can you add one line somewhere in documentation to mention the existence of this method?

[jberkel]

unnecessary test

[jberkel]

it's better to create new and unique temporary file instead: see temporaryFile() in Fixtures

[jberkel]

you don't need to remove these files since they are created each time

[adamwulf]

Just pushed up changes to the test, as well as a documentation mention and context for its use.

[jberkel]

XCTAssertThrowsError

[jberkel]

probably not relevant to the test

[adamwulf]

ok - new changes pushed up with the test cleanup

[jberkel]

the test also passes with just

let db = try Connection(.inMemory)

looks like the exclusive lock is obtained even when WAL mode is not active

[adamwulf]

ah interesting, i wouldn't have expected a wal_checkpoint to affect a non-wal mode db. i'll remove that line then

[jberkel]

After looking at this a bit more, I would change the test to not depend on any WAL specifics at all. Another way the db can end up in a locked state is when you have an open reader and then try to drop the table from the same connection:

let statement = try db.prepare("SELECT email FROM users")
_ = try statement.step()

// verify that the transaction is not closed, which prevents schema changes
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, allowing the implicit transaction to close
statement.reset()

// DROP table succeeds now
try db.run("DROP TABLE users")

The db should be opened in-memory. Additionally, can you simplify the db schema? Most of the fields defined are not relevant.

[adamwulf]

good idea to use the drop table - i've just pushed up a commit that uses the .inMemory db and users table from the setup() method, and swaps to that drop table query