@an5/adapters 0.2.10 → 0.2.13

package/swift/Sources/An5Adapters/SQLBuilder.swift

@@ -0,0 +1,359 @@
+import Foundation
+
+/// The database dialects AN5 speaks, and everything that differs between them.
+///
+/// The differences are not cosmetic: quoting, pagination and the `WITH (NOLOCK)` hint each
+/// have to be produced per dialect, and getting one wrong yields SQL the target engine
+/// cannot parse.
+public enum Dialect: String, CaseIterable, Sendable {
+    case mssql
+    case postgres
+    case sqlite
+
+    /// The dialect a connection string points at.
+    ///
+    /// Lower-cased first: a URI scheme is case-insensitive, so `MySQL://` and `mysql://` are
+    /// the same connection.
+    public static func detect(_ connectionString: String) -> Dialect {
+        let value = connectionString.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        if value.hasPrefix("postgres://") || value.hasPrefix("postgresql://") {
+            return .postgres
+        }
+        if value.hasPrefix("sqlite://")
+            || value.hasPrefix("sqlite:")
+            || value.hasPrefix("file:")
+            || value.hasSuffix(".db")
+            || value.hasSuffix(".sqlite")
+            || value.hasSuffix(".sqlite3")
+            || value == ":memory:" {
+            return .sqlite
+        }
+        return .mssql
+    }
+
+    /// The bind placeholder.
+    ///
+    /// Every driver AN5 speaks binds positionally, so this is `?` throughout; it exists so
+    /// the SQL builder never hardcodes a placeholder and a new driver has one place to differ.
+    public var placeholder: String { "?" }
+
+    /// Quotes a bare column or identifier name for this dialect.
+    public func quote(_ name: String) -> String {
+        let unwrapped = Dialect.strip(name, left: "[", right: "]")
+        switch self {
+        case .mssql:
+            return "[" + unwrapped.replacingOccurrences(of: "]", with: "]]") + "]"
+        case .postgres, .sqlite:
+            let bare = Dialect.strip(unwrapped, left: "\"", right: "\"")
+            return "\"" + bare.replacingOccurrences(of: "\"", with: "\"\"") + "\""
+        }
+    }
+
+    /// `WITH (NOLOCK)` is an MSSQL table hint; no other dialect has an equivalent.
+    public var supportsNoLock: Bool { self == .mssql }
+
+    /// The trailing limit clause.
+    ///
+    /// SQLite has `LIMIT ... OFFSET` like PostgreSQL. Emitting the MSSQL
+    /// `OFFSET ... FETCH NEXT` form against SQLite produces SQL it cannot parse.
+    public func pagination(take: Int?, skip: Int, orderBy: String) -> String {
+        guard let take else { return "" }
+        if self == .mssql {
+            let prefix = orderBy.isEmpty ? " ORDER BY (SELECT NULL)" : ""
+            return "\(prefix) OFFSET \(max(0, skip)) ROWS FETCH NEXT \(take) ROWS ONLY"
+        }
+        return " LIMIT \(take) OFFSET \(max(0, skip))"
+    }
+
+    static func strip(_ value: String, left: String, right: String) -> String {
+        guard value.count >= left.count + right.count,
+              value.hasPrefix(left),
+              value.hasSuffix(right) else { return value }
+        return String(value.dropFirst(left.count).dropLast(right.count))
+    }
+}
+
+/// The `WHERE` clause for a filter tree, with the values it binds in order.
+public struct WhereClause {
+    public let sql: String
+    public let parameters: [SQLValue]
+
+    public var isEmpty: Bool { sql.isEmpty }
+
+    public init(sql: String = "", parameters: [SQLValue] = []) {
+        self.sql = sql
+        self.parameters = parameters
+    }
+}
+
+/// Turns a filter tree into SQL and the bind values that go with it.
+public enum SQLBuilder {
+
+    /// The operator keys that make a map a filter rather than a nested condition.
+    static let operatorKeys: Set<String> = [
+        "equals", "in", "notIn", "contains", "startsWith", "endsWith", "not", "gte", "lte", "gt", "lt",
+    ]
+
+    /// Builds the `WHERE` clause and the parameters it binds, in order.
+    ///
+    /// Every value reaches the database as a bind parameter; none is ever formatted into the
+    /// SQL. `AND`/`OR`/`NOT` groups are supported, and an empty `in: []` becomes `1=0` rather
+    /// than the invalid `IN ()`.
+    public static func whereClause(_ filter: Where?, dialect: Dialect, prefix: String = "") -> WhereClause {
+        guard let filter, !filter.isEmpty else { return WhereClause() }
+
+        // A key with an underscore whose value is a map of plain columns is a flattened
+        // relation filter; hoisting it puts those conditions alongside the rest instead of
+        // quoting the whole thing as one column name.
+        var flattened: [String: Any?] = [:]
+        for (key, value) in filter {
+            if key.contains("_"), let nested = value as? Where, !isOperatorValue(nested) {
+                for (nestedKey, nestedValue) in nested { flattened[nestedKey] = nestedValue }
+            } else {
+                flattened[key] = value
+            }
+        }
+
+        var conditions: [String] = []
+        var parameters: [SQLValue] = []
+        for (key, value) in flattened {
+            switch key {
+            case "OR":
+                guard let branches = value as? [Where] else { continue }
+                var sub: [String] = []
+                for (index, branch) in branches.enumerated() {
+                    let clause = self.whereClause(branch, dialect: dialect, prefix: "\(prefix)or\(index)_")
+                    sub.append(clause.isEmpty ? "1=1" : clause.sql)
+                    parameters.append(contentsOf: clause.parameters)
+                }
+                conditions.append(sub.isEmpty ? "1=0" : "(\(sub.joined(separator: " OR ")))")
+            case "AND":
+                let items = value as? [Where] ?? [value as? Where ?? [:]]
+                var sub: [String] = []
+                for (index, item) in items.enumerated() {
+                    let clause = self.whereClause(item, dialect: dialect, prefix: "\(prefix)and\(index)_")
+                    parameters.append(contentsOf: clause.parameters)
+                    if !clause.isEmpty { sub.append(clause.sql) }
+                }
+                if !sub.isEmpty { conditions.append("(\(sub.joined(separator: " AND ")))") }
+            case "NOT":
+                let items = value as? [Where] ?? [value as? Where ?? [:]]
+                var sub: [String] = []
+                for (index, item) in items.enumerated() {
+                    let clause = self.whereClause(item, dialect: dialect, prefix: "\(prefix)not\(index)_")
+                    sub.append(clause.isEmpty ? "1=1" : clause.sql)
+                    parameters.append(contentsOf: clause.parameters)
+                }
+                if !sub.isEmpty { conditions.append("NOT (\(sub.joined(separator: " OR ")))") }
+            default:
+                conditions.append(
+                    condition(key: key, value: value, dialect: dialect, prefix: prefix, parameters: &parameters)
+                )
+            }
+        }
+        return WhereClause(sql: conditions.filter { !$0.isEmpty }.joined(separator: " AND "), parameters: parameters)
+    }
+
+    private static func condition(
+        key: String,
+        value: Any?,
+        dialect: Dialect,
+        prefix: String,
+        parameters: inout [SQLValue]
+    ) -> String {
+        let column = dialect.quote(key)
+        let placeholder = dialect.placeholder
+
+        if value == nil || value is NSNull {
+            return "\(column) IS NULL"
+        }
+        guard let operators = value as? Where else {
+            parameters.append(SQLValue.encode(value) ?? .null)
+            return "\(column) = \(placeholder)"
+        }
+
+        var conditions: [String] = []
+        if let inner = operators["not"] {
+            if inner == nil || inner is NSNull {
+                conditions.append("\(column) IS NOT NULL")
+            } else if let nested = inner as? Where {
+                let clause = self.whereClause([key: nested], dialect: dialect, prefix: prefix + key + "_not_")
+                parameters.append(contentsOf: clause.parameters)
+                if !clause.isEmpty { conditions.append("NOT (\(clause.sql))") }
+            } else {
+                parameters.append(SQLValue.encode(inner) ?? .null)
+                conditions.append("\(column) <> \(placeholder)")
+            }
+        }
+        if operators.keys.contains("equals") {
+            // Flattened: a lookup on a `[String: Any?]` yields `Any??`, and letting the
+            // compiler coerce it is how a `NULL` operand stops reading as "is null".
+            let equals = operators["equals"] ?? nil
+            if equals == nil || equals is NSNull {
+                conditions.append("\(column) IS NULL")
+            } else {
+                parameters.append(SQLValue.encode(equals) ?? .null)
+                conditions.append("\(column) = \(placeholder)")
+            }
+        }
+        for (op, template) in [("contains", "%@%"), ("startsWith", "@%"), ("endsWith", "%@")] {
+            guard let operand = operators[op] else { continue }
+            // Rendered through `encode` rather than interpolated directly: a filter built
+            // from a `[String: Any?]` dictionary hands the operand over wrapped in an
+            // `Optional`, and interpolating that would search for the text "Optional(da)".
+            parameters.append(.text(template.replacingOccurrences(of: "@", with: literal(operand))))
+            conditions.append("\(column) LIKE \(placeholder)")
+        }
+        for (op, sql) in [("gte", ">="), ("lte", "<="), ("gt", ">"), ("lt", "<")] {
+            guard let operand = operators[op] else { continue }
+            parameters.append(SQLValue.encode(operand) ?? .null)
+            conditions.append("\(column) \(sql) \(placeholder)")
+        }
+        for (op, sql, emptyResult) in [("in", " IN (", "1=0"), ("notIn", " NOT IN (", "1=1")] {
+            guard let raw = operators[op] else { continue }
+            // Accepts an untyped list whatever element type it was built with: a caller that
+            // wrote `["Ada", "Grace"]` produced a `[String]`, and a cast straight to
+            // `[Any?]` does not always see through that, which would silently turn an
+            // `in` filter into "match nothing".
+            let values: [Any?]
+            if let typed = raw as? [Any?] {
+                values = typed
+            } else if let list = raw as? [Any] {
+                values = list.map { $0 }
+            } else {
+                values = []
+            }
+            if values.isEmpty {
+                // `IN ()` is a syntax error in every dialect. An empty set can match nothing,
+                // so it becomes 1=0; the negated form is true of every row, so 1=1.
+                conditions.append(emptyResult)
+                continue
+            }
+            conditions.append(column + sql + values.map { _ in placeholder }.joined(separator: ", ") + ")")
+            parameters.append(contentsOf: values.map { SQLValue.encode($0) ?? .null })
+        }
+        return conditions.joined(separator: " AND ")
+    }
+
+    /// A bind value as the text a `LIKE` operand needs.
+    private static func literal(_ value: Any?) -> String {
+        switch SQLValue.encode(value) {
+        case .some(.text(let text)): return text
+        case .some(.integer(let number)): return String(number)
+        case .some(.real(let number)): return String(number)
+        case .some(.uuid(let uuid)): return uuid.uuidString
+        default: return ""
+        }
+    }
+
+    /// Builds the `ORDER BY` clause.
+    ///
+    /// Accepts every shape the other clients use for ordering — a single column, a
+    /// column/direction pair, a dictionary, or a list of dictionaries — because a generated
+    /// client may hand over whichever form its own language finds natural.
+    public static func orderBy(_ orderBy: Any?, dialect: Dialect) -> String {
+        var parts: [String] = []
+        for entry in orderEntries(orderBy) {
+            for (column, direction) in entry {
+                parts.append("\(dialect.quote(column)) \(direction.lowercased() == "desc" ? "DESC" : "ASC")")
+            }
+        }
+        return parts.isEmpty ? "" : "ORDER BY \(parts.joined(separator: ", "))"
+    }
+
+    /// Normalises any accepted ordering shape into column/direction entries.
+    static func orderEntries(_ orderBy: Any?) -> [[String: String]] {
+        if let list = orderBy as? [[String: String]] { return list }
+        if let list = orderBy as? [[String: Any?]] {
+            return list.map { $0.mapValues { ($0 as? String) ?? "asc" } }
+        }
+        if let single = orderBy as? [String: String] { return [single] }
+        if let single = orderBy as? [String: Any?] {
+            return [single.mapValues { ($0 as? String) ?? "asc" }]
+        }
+        if let pair = orderBy as? (String, String) { return [[pair.0: pair.1]] }
+        return []
+    }
+
+    /// Appends one `SET` assignment, expanding the arithmetic update operators.
+    public static func appendUpdateSet(
+        _ setParts: inout [String],
+        _ values: inout [SQLValue],
+        column: String,
+        value: Any?,
+        dialect: Dialect
+    ) {
+        let quoted = dialect.quote(column)
+        let placeholder = dialect.placeholder
+        if let operations = value as? [String: Any?] {
+            for (operation, symbol) in [("increment", "+"), ("decrement", "-"), ("multiply", "*"), ("divide", "/")] {
+                if let operand = operations[operation] {
+                    setParts.append("\(quoted) = \(quoted) \(symbol) \(placeholder)")
+                    values.append(SQLValue.encode(operand) ?? .null)
+                    return
+                }
+            }
+            if let replacement = operations["set"] {
+                setParts.append("\(quoted) = \(placeholder)")
+                values.append(SQLValue.encode(replacement) ?? .null)
+                return
+            }
+        }
+        setParts.append("\(quoted) = \(placeholder)")
+        values.append(SQLValue.encode(value) ?? .null)
+    }
+
+    /// Quotes a possibly schema-qualified table name.
+    ///
+    /// An already-bracketed name is never returned as-is: that quoting is only correct on
+    /// MSSQL, so the brackets are stripped and re-applied for the target dialect instead of
+    /// letting one dialect's quoting follow the name into another.
+    public static func quoteTable(_ table: String, dialect: Dialect) -> String {
+        var parts = splitQualified(table)
+        if dialect == .sqlite, parts.count == 2, unquote(parts[0]).lowercased() == "dbo" {
+            parts = Array(parts.dropFirst())
+        }
+        if parts.isEmpty { parts = [table] }
+        return parts.map { dialect.quote($0) }.joined(separator: ".")
+    }
+
+    /// Splits `schema.table` without cutting a dot inside brackets or quotes.
+    ///
+    /// A plain split on `.` turns `[dbo].[users]` into two bracketed parts, which is right for
+    /// MSSQL but leaves the other dialects quoting a name that already carries brackets.
+    private static func splitQualified(_ table: String) -> [String] {
+        var parts: [String] = []
+        var buffer = ""
+        var closing: Character?
+        for character in table {
+            if let close = closing {
+                buffer.append(character)
+                if character == close { closing = nil }
+                continue
+            }
+            switch character {
+            case "[": closing = "]"; buffer.append(character)
+            case "\"": closing = "\""; buffer.append(character)
+            case ".": parts.append(buffer); buffer = ""
+            default: buffer.append(character)
+            }
+        }
+        parts.append(buffer)
+        return parts.filter { !$0.isEmpty }
+    }
+
+    private static func unquote(_ name: String) -> String {
+        Dialect.strip(Dialect.strip(name, left: "[", right: "]"), left: "\"", right: "\"")
+    }
+
+    /// A bind parameter name that is a legal identifier in every dialect.
+    public static func sanitizeParameterName(_ name: String) -> String {
+        var cleaned = String(name.map { $0.isLetter || $0.isNumber || $0 == "_" ? $0 : "_" })
+        if cleaned.isEmpty || !cleaned.first!.isLetter { cleaned = "p_" + cleaned }
+        return cleaned
+    }
+
+    private static func isOperatorValue(_ value: Where) -> Bool {
+        value.keys.contains { operatorKeys.contains($0) }
+    }
+}

package/swift/Sources/An5Adapters/SQLiteDriver.swift

@@ -0,0 +1,301 @@
+import Foundation
+import CSQLite
+
+/// Tells SQLite to copy a bound value rather than keep the pointer.
+///
+/// `SQLITE_TRANSIENT` is a C macro, and Swift cannot import those, so the same value is
+/// spelled out here: `((sqlite3_destructor_type)-1)`. Without it SQLite would read freed
+/// memory the moment the Swift value went out of scope.
+private let SQLITE_TRANSIENT = unsafeBitCast(-1, to: sqlite3_destructor_type.self)
+
+/// What a registered distance function needs to remember about itself.
+private final class MetricContext {
+    let metric: DistanceMetric
+
+    init(metric: DistanceMetric) {
+        self.metric = metric
+    }
+}
+
+/// The SQL surface the AN5 runtime needs, so the runtime is not welded to one driver.
+///
+/// A protocol rather than a direct call into SQLite so an app can put its own database
+/// layer underneath — GRDB, SQLite.swift, or a connection it already owns — without the
+/// generated models or the query builder changing.
+public protocol SQLDriver: AnyObject {
+    /// Runs a query and returns its rows keyed by column name.
+    func query(_ sql: String, _ parameters: [SQLValue]) throws -> [Row]
+
+    /// Runs a statement that returns no rows and gives back the affected row count.
+    @discardableResult
+    func execute(_ sql: String, _ parameters: [SQLValue]) throws -> Int
+
+    func beginTransaction() throws
+    func commit() throws
+    func rollback() throws
+}
+
+/// SQLite, through the system library.
+///
+/// The database every mobile platform already has: no bundled engine, no extra binary, and
+/// the same file on device and in a simulator. One connection is held for the driver's
+/// lifetime rather than opened per statement, because an in-memory database disappears when
+/// its last connection closes and because per-statement connections are the wrong shape for
+/// a device.
+///
+/// Not thread-safe: SQLite connections are not, and serialising every call would hide that
+/// rather than fix it. Use one driver per thread, or an actor around one.
+public final class SQLiteDriver: SQLDriver {
+
+    private var handle: OpaquePointer?
+    private let path: String
+
+    /// Opens a database, creating the file if it does not exist.
+    ///
+    /// - Parameter path: a file path, `:memory:` for an in-memory database, or a `file:`
+    ///   URI.
+    public init(path: String) throws {
+        self.path = path
+        var handle: OpaquePointer?
+        let flags = SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE | SQLITE_OPEN_FULLMUTEX
+        let status = sqlite3_open_v2(path, &handle, flags, nil)
+        guard status == SQLITE_OK, let handle else {
+            let message = handle.map { String(cString: sqlite3_errmsg($0)) } ?? "status \(status)"
+            sqlite3_close_v2(handle)
+            throw An5Error.driver("cannot open \(path): \(message)")
+        }
+        self.handle = handle
+        // Foreign keys are off by default in SQLite, unlike every other dialect, so a schema
+        // that relies on them would silently accept rows nothing points at.
+        _ = try? execute("PRAGMA foreign_keys = ON", [])
+        // `sqlite3_enable_load_extension` is unavailable on Apple mobile platforms, where an
+        // application links SQLite statically and supplies its own extension instead.
+        #if os(Linux) || os(macOS) || os(Windows)
+        if let path = Self.sqliteVecPath {
+            // An extension is optional: without it the search still ranks, through the
+            // distance functions registered below or `json_each`.
+            _ = sqlite3_enable_load_extension(handle, 1)
+            _ = sqlite3_load_extension(handle, path, nil, nil)
+            _ = sqlite3_enable_load_extension(handle, 0)
+        }
+        #endif
+        registerVectorFunctions()
+    }
+
+    /// Where to load sqlite-vec from, set before the first driver is opened.
+    ///
+    /// A process-wide setting on purpose: the extension belongs to the SQLite build rather
+    /// than to one connection, and every AN5 connection wants the same one.
+    public static var sqliteVecPath: String?
+
+    /// Registers `an5_vec_cosine` / `an5_vec_l2` / `an5_vec_ip` so SQLite can rank a
+    /// `VECTOR(n)` column without the client loading it.
+    ///
+    /// This runs per connection because a user function only exists for the connection that
+    /// declared it.
+    private func registerVectorFunctions() {
+        // AN5's native extension or sqlite-vec already provide these names. Registering a
+        // Swift callback over them would silently replace native code with a slower path.
+        if (try? query("SELECT an5_vector_version()", [])) != nil { return }
+        for (metric, name) in SqliteVectors.an5Functions {
+            guard let resolved = DistanceMetric(rawValue: metric) else { continue }
+            registerVectorFunction(name, metric: resolved)
+        }
+    }
+
+    /// Registers one distance function.
+    ///
+    /// The metric travels in the function's user-data pointer rather than the callback
+    /// context: a C function pointer cannot capture anything, so the callback reads what it
+    /// needs back out of SQLite.
+    private func registerVectorFunction(_ name: String, metric: DistanceMetric) {
+        let userData = Unmanaged.passRetained(MetricContext(metric: metric)).toOpaque()
+        sqlite3_create_function_v2(
+            handle,
+            name,
+            2,
+            SQLITE_UTF8 | SQLITE_DETERMINISTIC,
+            userData,
+            SQLiteDriver.vectorCallback,
+            nil, nil,
+            SQLiteDriver.vectorDestructor
+        )
+    }
+
+    /// The distance callback, at file scope for the C ABI.
+    ///
+    /// A `@convention(c)` function pointer cannot capture anything, not even `Self`, so
+    /// this is a free function rather than a method. Everything it needs arrives through
+    /// SQLite: the metric in the user-data pointer, the arguments in `values`.
+    private static let vectorCallback: @convention(c) (
+        OpaquePointer?, Int32, UnsafeMutablePointer<OpaquePointer?>?
+    ) -> Void = { context, count, values in
+        // A vector that cannot be scored leaves the result NULL, which the ranking query
+        // filters out rather than handing to the caller.
+        guard let context, count == 2, let values else { return }
+        guard let raw = sqlite3_user_data(context) else { return }
+        let metric = Unmanaged<MetricContext>.fromOpaque(raw).takeUnretainedValue().metric
+        guard let left = SQLiteDriver.sqliteVectorArgument(values[0]),
+              let right = SQLiteDriver.sqliteVectorArgument(values[1]),
+              left.count == right.count, !left.isEmpty else { return }
+        sqlite3_result_double(context, DistanceMetric.distance(metric, left, right))
+    }
+
+    /// Releases the metric box allocated for one registered function.
+    private static let vectorDestructor: @convention(c) (UnsafeMutableRawPointer?) -> Void = { pointer in
+        if let pointer { Unmanaged<MetricContext>.fromOpaque(pointer).release() }
+    }
+
+    /// Reads one bound argument: a BLOB of float32 or a legacy JSON text column.
+    ///
+    /// Static because the C callback above cannot capture `self`.
+    ///
+    /// `sqlite3_value` is an incomplete C type, so Swift imports it as
+    /// `OpaquePointer`.
+    private static func sqliteVectorArgument(_ value: OpaquePointer?) -> [Double]? {
+        guard let value else { return nil }
+        switch sqlite3_value_type(value) {
+        case SQLITE_BLOB:
+            let count = Int(sqlite3_value_bytes(value))
+            guard count > 0, let bytes = sqlite3_value_blob(value) else { return nil }
+            return SqliteVectors.decodeBlob(Data(bytes: bytes, count: count))
+        case SQLITE_TEXT:
+            guard let text = sqlite3_value_text(value) else { return nil }
+            return SqliteVectors.decode(String(cString: text))
+        default:
+            return nil
+        }
+    }
+
+    deinit {
+        sqlite3_close_v2(handle)
+    }
+
+    /// The file this driver opened, for logging and diagnostics.
+    public var databasePath: String { path }
+
+    public func query(_ sql: String, _ parameters: [SQLValue]) throws -> [Row] {
+        let statement = try prepare(sql, parameters)
+        defer { sqlite3_finalize(statement) }
+
+        var rows: [Row] = []
+        while true {
+            let status = sqlite3_step(statement)
+            if status == SQLITE_ROW {
+                rows.append(readRow(statement))
+            } else if status == SQLITE_DONE {
+                return rows
+            } else {
+                throw error(status, sql)
+            }
+        }
+    }
+
+    @discardableResult
+    public func execute(_ sql: String, _ parameters: [SQLValue]) throws -> Int {
+        let statement = try prepare(sql, parameters)
+        defer { sqlite3_finalize(statement) }
+
+        while true {
+            let status = sqlite3_step(statement)
+            if status == SQLITE_ROW || status == SQLITE_DONE {
+                return Int(sqlite3_changes(handle))
+            }
+            throw error(status, sql)
+        }
+    }
+
+    public func beginTransaction() throws {
+        try execute("BEGIN", [])
+    }
+
+    public func commit() throws {
+        try execute("COMMIT", [])
+    }
+
+    public func rollback() throws {
+        try execute("ROLLBACK", [])
+    }
+
+    // ─── Binding ───────────────────────────────────────────────────────────────
+
+    private func prepare(_ sql: String, _ parameters: [SQLValue]) throws -> OpaquePointer? {
+        var statement: OpaquePointer?
+        guard sqlite3_prepare_v2(handle, sql, -1, &statement, nil) == SQLITE_OK, let statement else {
+            throw error(sqlite3_errcode(handle), sql)
+        }
+        for (index, value) in parameters.enumerated() {
+            try bind(value, to: statement, at: Int32(index + 1))
+        }
+        return statement
+    }
+
+    private func bind(_ value: SQLValue, to statement: OpaquePointer?, at index: Int32) throws {
+        let status: Int32
+        switch value {
+        case .null:
+            status = sqlite3_bind_null(statement, index)
+        case .bool(let flag):
+            status = sqlite3_bind_int64(statement, index, flag ? 1 : 0)
+        case .integer(let number):
+            status = sqlite3_bind_int64(statement, index, number)
+        case .real(let number):
+            status = sqlite3_bind_double(statement, index, number)
+        case .text(let text):
+            status = sqlite3_bind_text(statement, index, text, -1, SQLITE_TRANSIENT)
+        case .blob(let data):
+            // A zero-length blob still has to be bound with its length: passing 0 would bind
+            // a NULL instead, because SQLite reads -1 as "use strlen" and 0 as "no bytes
+            // and no length".
+            status = data.isEmpty
+                ? sqlite3_bind_zeroblob(statement, index, 0)
+                : data.withUnsafeBytes { buffer in
+                    sqlite3_bind_blob(statement, index, buffer.baseAddress, Int32(buffer.count), SQLITE_TRANSIENT)
+                }
+        case .date(let date):
+            status = sqlite3_bind_double(statement, index, date.timeIntervalSince1970)
+        case .uuid(let uuid):
+            status = sqlite3_bind_text(statement, index, uuid.uuidString, -1, SQLITE_TRANSIENT)
+        }
+        guard status == SQLITE_OK else {
+            throw error(status, "binding parameter \(index)")
+        }
+    }
+
+    private func readRow(_ statement: OpaquePointer?) -> Row {
+        var row: Row = [:]
+        let columns = sqlite3_column_count(statement)
+        for index in 0..<columns {
+            guard let rawName = sqlite3_column_name(statement, index) else { continue }
+            let name = String(cString: rawName)
+            switch sqlite3_column_type(statement, index) {
+            case SQLITE_INTEGER:
+                row[name] = sqlite3_column_int64(statement, index)
+            case SQLITE_FLOAT:
+                row[name] = sqlite3_column_double(statement, index)
+            case SQLITE_TEXT:
+                if let text = sqlite3_column_text(statement, index) {
+                    row[name] = String(cString: text)
+                } else {
+                    row[name] = nil
+                }
+            case SQLITE_BLOB:
+                if let bytes = sqlite3_column_blob(statement, index) {
+                    row[name] = Foundation.Data(bytes: bytes, count: Int(sqlite3_column_bytes(statement, index)))
+                } else {
+                    row[name] = nil
+                }
+            default:
+                // SQLITE_NULL, and anything a newer SQLite adds: absent rather than a
+                // fabricated zero, so "no value" never reads as "the value 0".
+                row[name] = nil
+            }
+        }
+        return row
+    }
+
+    private func error(_ status: Int32, _ context: String) -> An5Error {
+        let message = handle.map { String(cString: sqlite3_errmsg($0)) } ?? "unknown"
+        return .driver("\(message) — while running: \(context)")
+    }
+}