updates to SQLite (#156)

motivation: expand the API of SQLite to allow more sophisticated use cases

changes:
* provide initiallizers for in-memory and temp file modes
* move timeout to configuration for future extensibility
* make Row value accesssors public
* add tests
* refactor testing util mktmpdir to throw instead of use XCFail which more correctly report errors, and adjust call sites

Author: tomerd

Sources/TSCTestSupport/misc.swift

@@ -25,27 +25,21 @@ public enum Configuration {
 }
 
 /// Test helper utility for executing a block with a temporary directory.
-public func mktmpdir(
+public func testWithTemporaryDirectory(
     function: StaticString = #function,
-    file: StaticString = #file,
-    line: UInt = #line,
     body: (AbsolutePath) throws -> Void
-) {
-    do {
-        let cleanedFunction = function.description
-            .replacingOccurrences(of: "(", with: "")
-            .replacingOccurrences(of: ")", with: "")
-            .replacingOccurrences(of: ".", with: "")
-        try withTemporaryDirectory(prefix: "spm-tests-\(cleanedFunction)") { tmpDirPath in
-            defer {
-                // Unblock and remove the tmp dir on deinit.
-                try? localFileSystem.chmod(.userWritable, path: tmpDirPath, options: [.recursive])
-                try? localFileSystem.removeFileTree(tmpDirPath)
-            }
-            try body(tmpDirPath)
+) throws {
+    let cleanedFunction = function.description
+        .replacingOccurrences(of: "(", with: "")
+        .replacingOccurrences(of: ")", with: "")
+        .replacingOccurrences(of: ".", with: "")
+    try withTemporaryDirectory(prefix: "spm-tests-\(cleanedFunction)") { tmpDirPath in
+        defer {
+            // Unblock and remove the tmp dir on deinit.
+            try? localFileSystem.chmod(.userWritable, path: tmpDirPath, options: [.recursive])
+            try? localFileSystem.removeFileTree(tmpDirPath)
         }
-    } catch {
-        XCTFail("\(error)", file: file, line: line)
+        try body(tmpDirPath)
     }
 }
 

Sources/TSCUtility/PersistenceCache.swift

@@ -41,7 +41,7 @@ public final class SQLiteBackedPersistentCache: PersistentCacheProtocol {
     }
 
     public convenience init(cacheFilePath: AbsolutePath) throws {
-        let db = try SQLite(dbPath: cacheFilePath)
+        let db = try SQLite(location: .path(cacheFilePath))
         try self.init(db: db)
     }
 

Sources/TSCUtility/SQLite.swift

@@ -6,7 +6,7 @@
 
  See http://swift.org/LICENSE.txt for license information
  See http://swift.org/CONTRIBUTORS.txt for Swift project authors
-*/
+ */
 
 import Foundation
 import TSCBasic
@@ -15,6 +15,104 @@ import TSCBasic
 
 /// A minimal SQLite wrapper.
 public struct SQLite {
+    /// The location of the database.
+    public let location: Location
+
+    /// The configuration for the database.
+    public let configuration: Configuration
+
+    /// Pointer to the database.
+    let db: OpaquePointer
+
+    /// Create or open the database at the given path.
+    ///
+    /// The database is opened in serialized mode.
+    public init(location: Location, configuration: Configuration = Configuration()) throws {
+        self.location = location
+        self.configuration = configuration
+
+        var handle: OpaquePointer?
+        try Self.checkError("Unable to open database at \(self.location)") {
+            sqlite3_open_v2(
+                location.pathString,
+                &handle,
+                SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE | SQLITE_OPEN_FULLMUTEX,
+                nil
+            )
+        }
+
+        guard let db = handle else {
+            throw StringError("Unable to open database at \(self.location)")
+        }
+        self.db = db
+        try Self.checkError("Unable to configure database") { sqlite3_extended_result_codes(db, 1) }
+        try Self.checkError("Unable to configure database") { sqlite3_busy_timeout(db, self.configuration.busyTimeoutSeconds) }
+    }
+
+    @available(*, deprecated, message: "use init(location:configuration) instead")
+    public init(dbPath: AbsolutePath) throws {
+        try self.init(location: .path(dbPath))
+    }
+
+    /// Prepare the given query.
+    public func prepare(query: String) throws -> PreparedStatement {
+        try PreparedStatement(db: self.db, query: query)
+    }
+
+    /// Directly execute the given query.
+    ///
+    /// Note: Use withCString for string arguments.
+    public func exec(query queryString: String, args: [CVarArg] = [], _ callback: SQLiteExecCallback? = nil) throws {
+        let query = withVaList(args) { ptr in
+            sqlite3_vmprintf(queryString, ptr)
+        }
+
+        let wcb = callback.map { CallbackWrapper($0) }
+        let callbackCtx = wcb.map { Unmanaged.passUnretained($0).toOpaque() }
+
+        var err: UnsafeMutablePointer<Int8>?
+        try Self.checkError { sqlite3_exec(db, query, sqlite_callback, callbackCtx, &err) }
+
+        sqlite3_free(query)
+
+        if let err = err {
+            let errorString = String(cString: err)
+            sqlite3_free(err)
+            throw StringError(errorString)
+        }
+    }
+
+    public func close() throws {
+        try Self.checkError { sqlite3_close(db) }
+    }
+
+    public typealias SQLiteExecCallback = ([Column]) -> Void
+
+    public struct Configuration {
+        public var busyTimeoutSeconds: Int32
+
+        public init() {
+            self.busyTimeoutSeconds = 5
+        }
+    }
+
+    public enum Location {
+        case path(AbsolutePath)
+        case memory
+        case temporary
+
+        var pathString: String {
+            switch self {
+            case .path(let path):
+                return path.pathString
+            case .memory:
+                return ":memory:"
+            case .temporary:
+                return ""
+            }
+        }
+    }
+
     /// Represents an sqlite value.
     public enum SQLiteValue {
         case null
@@ -29,23 +127,28 @@ public struct SQLite {
         let stmt: OpaquePointer
 
         /// Get integer at the given column index.
-        func int(at index: Int32) -> Int {
-            Int(sqlite3_column_int64(stmt, index))
+        public func int(at index: Int32) -> Int {
+            Int(sqlite3_column_int64(self.stmt, index))
         }
 
         /// Get blob data at the given column index.
-        func blob(at index: Int32) -> Data {
+        public func blob(at index: Int32) -> Data {
             let bytes = sqlite3_column_blob(stmt, index)!
             let count = sqlite3_column_bytes(stmt, index)
             return Data(bytes: bytes, count: Int(count))
         }
 
         /// Get string at the given column index.
-        func string(at index: Int32) -> String {
-            return String(cString: sqlite3_column_text(stmt, index))
+        public func string(at index: Int32) -> String {
+            return String(cString: sqlite3_column_text(self.stmt, index))
         }
     }
 
+    public struct Column {
+        public var name: String
+        public var value: String
+    }
+
     /// Represents a prepared statement.
     public struct PreparedStatement {
         typealias sqlite3_destructor_type = (@convention(c) (UnsafeMutableRawPointer?) -> Void)
@@ -57,7 +160,7 @@ public struct SQLite {
 
         public init(db: OpaquePointer, query: String) throws {
             var stmt: OpaquePointer?
-            try sqlite { sqlite3_prepare_v2(db, query, -1, &stmt, nil) }
+            try checkError { sqlite3_prepare_v2(db, query, -1, &stmt, nil) }
             self.stmt = stmt!
         }
 
@@ -70,7 +173,7 @@ public struct SQLite {
             case SQLITE_DONE:
                 return nil
             case SQLITE_ROW:
-                return Row(stmt: stmt)
+                return Row(stmt: self.stmt)
             default:
                 throw StringError(String(cString: sqlite3_errstr(result)))
             }
@@ -82,13 +185,13 @@ public struct SQLite {
                 let idx = Int32(idx) + 1
                 switch argument {
                 case .null:
-                    try sqlite { sqlite3_bind_null(stmt, idx) }
+                    try checkError { sqlite3_bind_null(stmt, idx) }
                 case .int(let int):
-                    try sqlite { sqlite3_bind_int64(stmt, idx, Int64(int)) }
+                    try checkError { sqlite3_bind_int64(stmt, idx, Int64(int)) }
                 case .string(let str):
-                    try sqlite { sqlite3_bind_text(stmt, idx, str, -1, Self.SQLITE_TRANSIENT) }
+                    try checkError { sqlite3_bind_text(stmt, idx, str, -1, Self.SQLITE_TRANSIENT) }
                 case .blob(let blob):
-                    try sqlite {
+                    try checkError {
                         blob.withUnsafeBytes { ptr in
                             sqlite3_bind_blob(
                                 stmt,
@@ -105,91 +208,37 @@ public struct SQLite {
 
         /// Reset the prepared statement.
         public func reset() throws {
-            try sqlite { sqlite3_reset(stmt) }
+            try checkError { sqlite3_reset(stmt) }
         }
 
         /// Clear bindings from the prepared statment.
         public func clearBindings() throws {
-            try sqlite { sqlite3_clear_bindings(stmt) }
+            try checkError { sqlite3_clear_bindings(stmt) }
         }
 
         /// Finalize the statement and free up resources.
         public func finalize() throws {
-            try sqlite { sqlite3_finalize(stmt) }
+            try checkError { sqlite3_finalize(stmt) }
         }
     }
 
-    /// The path to the database file.
-    public let dbPath: AbsolutePath
-
-    /// Pointer to the database.
-    let db: OpaquePointer
-
-    /// Create or open the database at the given path.
-    ///
-    /// The database is opened in serialized mode.
-    public init(dbPath: AbsolutePath) throws {
-        self.dbPath = dbPath
-
-        var db: OpaquePointer? = nil
-        try sqlite("unable to open database at \(dbPath)") {
-            sqlite3_open_v2(
-                dbPath.pathString,
-                &db,
-                SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE | SQLITE_OPEN_FULLMUTEX,
-                nil
-            )
+    fileprivate class CallbackWrapper {
+        var callback: SQLiteExecCallback
+        init(_ callback: @escaping SQLiteExecCallback) {
+            self.callback = callback
         }
-
-        self.db = db!
-        try sqlite { sqlite3_extended_result_codes(db, 1) }
-        try sqlite { sqlite3_busy_timeout(db, 5 * 1000 /* 5s */) }
-    }
-
-    /// Prepare the given query.
-    public func prepare(query: String) throws -> PreparedStatement {
-        try PreparedStatement(db: db, query: query)
     }
 
-    /// Directly execute the given query.
-    ///
-    /// Note: Use withCString for string arguments.
-    public func exec(query: String, args: [CVarArg] = [], _ callback: SQLiteExecCallback? = nil) throws {
-        let query = withVaList(args) { ptr in
-            sqlite3_vmprintf(query, ptr)
-        }
-
-        let wcb = callback.map { CallbackWrapper($0) }
-        let callbackCtx = wcb.map { Unmanaged.passUnretained($0).toOpaque() }
-
-        var err: UnsafeMutablePointer<Int8>? = nil
-        try sqlite { sqlite3_exec(db, query, sqlite_callback, callbackCtx, &err) }
-
-        if let err = err {
-            let errorString = String(cString: err)
-            sqlite3_free(err)
-            throw StringError(errorString)
+    private static func checkError(_ errorPrefix: String? = nil, _ fn: () -> Int32) throws {
+        let result = fn()
+        if result != SQLITE_OK {
+            var error = ""
+            if let errorPrefix = errorPrefix {
+                error += errorPrefix + ": "
+            }
+            error += String(cString: sqlite3_errstr(result))
+            throw StringError(error)
         }
-
-        sqlite3_free(query)
-    }
-
-    public func close() throws {
-        try sqlite { sqlite3_close(db) }
-    }
-
-    public struct Column {
-        public var name: String
-        public var value: String
-    }
-
-    public typealias SQLiteExecCallback = ([Column]) -> Void
-}
-
-private class CallbackWrapper {
-    var callback: SQLite.SQLiteExecCallback
-    init(_ callback: @escaping SQLite.SQLiteExecCallback) {
-        self.callback = callback
     }
 }
 
@@ -204,7 +253,7 @@ private func sqlite_callback(
     let numColumns = Int(numColumns)
     var result: [SQLite.Column] = []
 
-    for idx in 0..<numColumns {
+    for idx in 0 ..< numColumns {
         var name = ""
         if let ptr = columnNames.advanced(by: idx).pointee {
             name = String(cString: ptr)
@@ -216,20 +265,8 @@ private func sqlite_callback(
         result.append(SQLite.Column(name: name, value: value))
     }
 
-    let wcb = Unmanaged<CallbackWrapper>.fromOpaque(ctx).takeUnretainedValue()
+    let wcb = Unmanaged<SQLite.CallbackWrapper>.fromOpaque(ctx).takeUnretainedValue()
     wcb.callback(result)
 
     return 0
 }
-
-private func sqlite(_ errorPrefix: String? = nil, _ fn: () -> Int32) throws {
-    let result = fn()
-    if result != SQLITE_OK {
-        var error = ""
-        if let errorPrefix = errorPrefix {
-            error += errorPrefix + ": "
-        }
-        error += String(cString: sqlite3_errstr(result))
-        throw StringError(error)
-    }
-}