Adds SchemaChanger to perform database schema changes

Author: jberkel

SQLite.xcodeproj/project.pbxproj

@@ -0,0 +1,145 @@
+import Foundation
+
+extension Connection {
+    // Changing the foreign_keys setting affects the execution of all statements prepared using the database
+    // connection, including those prepared before the setting was changed.
+    //
+    // https://sqlite.org/pragma.html#pragma_foreign_keys
+    var foreignKeys: Bool {
+        get { getBoolPragma("foreign_keys") }
+        set { setBoolPragma("foreign_keys", newValue) }
+    }
+
+    var deferForeignKeys: Bool {
+        get { getBoolPragma("defer_foreign_keys") }
+        set { setBoolPragma("defer_foreign_keys", newValue) }
+    }
+
+    // https://sqlite.org/pragma.html#pragma_foreign_key_check
+
+    // There are four columns in each result row.
+    // The first column is the name of the table that
+    // contains the REFERENCES clause.
+    // The second column is the rowid of the row that contains the
+    // invalid REFERENCES clause, or NULL if the child table is a WITHOUT ROWID table.
+    // The third column is the name of the table that is referred to.
+    // The fourth column is the index of the specific foreign key constraint that failed.
+    func foreignKeyCheck() throws -> [ForeignKeyError] {
+        try run("PRAGMA foreign_key_check").compactMap { row -> ForeignKeyError? in
+            guard let table = row[0] as? String,
+                  let rowId = row[1] as? Int64,
+                  let target = row[2] as? String else { return nil }
+
+            return ForeignKeyError(from: table, rowId: rowId, to: target)
+        }
+    }
+
+    // https://sqlite.org/pragma.html#pragma_table_info
+    //
+    // This pragma returns one row for each column in the named table. Columns in the result set include the
+    // column name, data type, whether or not the column can be NULL, and the default value for the column. The
+    // "pk" column in the result set is zero for columns that are not part of the primary key, and is the
+    // index of the column in the primary key for columns that are part of the primary key.
+    func columnInfo(table: String) throws  -> [ColumnDefinition] {
+        func parsePrimaryKey(column: String) throws -> ColumnDefinition.PrimaryKey? {
+            try createTableSQL(name: table).flatMap { .init(sql: $0) }
+        }
+
+        let foreignKeys: [String: [ForeignKeyDefinition]] =
+            Dictionary(grouping: try foreignKeyInfo(table: table), by: { $0.column })
+
+        return try run("PRAGMA table_info(\(table.quote()))").compactMap { row -> ColumnDefinition? in
+            guard let name = row[1] as? String,
+                  let type = row[2] as? String,
+                  let notNull = row[3] as? Int64,
+                  let defaultValue = row[4] as? String?,
+                  let primaryKey = row[5] as? Int64 else { return nil }
+            return ColumnDefinition(name: name,
+                                    primaryKey: primaryKey == 1 ? try parsePrimaryKey(column: name) : nil,
+                                    type: ColumnDefinition.Affinity.from(type),
+                                    null: notNull == 0,
+                                    defaultValue: LiteralValue.from(defaultValue),
+                                    references: foreignKeys[name]?.first)
+        }
+    }
+
+    func indexInfo(table: String) throws -> [IndexDefinition] {
+        func indexSQL(name: String) throws  -> String? {
+            try run("""
+                    SELECT sql FROM sqlite_master WHERE name=? AND type='index'
+                      UNION ALL
+                    SELECT sql FROM sqlite_temp_master WHERE name=? AND type='index'
+                    """, name, name)
+                    .compactMap { row in row[0] as? String }
+                    .first
+        }
+
+        func columns(name: String) throws -> [String] {
+            try run("PRAGMA index_info(\(name.quote()))").compactMap { row in
+                row[2] as? String
+            }
+        }
+
+        return try run("PRAGMA index_list(\(table.quote()))").compactMap { row -> IndexDefinition? in
+            guard let name = row[1] as? String,
+                  let unique = row[2] as? Int64,
+                    // Indexes SQLite creates implicitly for internal use start with "sqlite_".
+                    // See https://www.sqlite.org/fileformat2.html#intschema
+                  !name.starts(with: "sqlite_") else {
+                return nil
+            }
+            return .init(table: table,
+                         name: name,
+                         unique: unique == 1,
+                         columns: try columns(name: name),
+                         indexSQL: try indexSQL(name: name))
+        }
+    }
+
+    func tableInfo() throws -> [String] {
+        try run("SELECT tbl_name FROM sqlite_master WHERE type = 'table'").compactMap { row in
+            if let name = row[0] as? String, !name.starts(with: "sqlite_") {
+                return name
+            } else {
+                return nil
+            }
+        }
+    }
+
+    func foreignKeyInfo(table: String) throws -> [ForeignKeyDefinition] {
+        try run("PRAGMA foreign_key_list(\(table.quote()))").compactMap { row in
+            if let table = row[2] as? String,      // table
+               let column = row[3] as? String,     // from
+               let primaryKey = row[4] as? String, // to
+               let onUpdate = row[5] as? String,
+               let onDelete = row[6] as? String {
+                return ForeignKeyDefinition(table: table, column: column, primaryKey: primaryKey,
+                                            onUpdate: onUpdate == TableBuilder.Dependency.noAction.rawValue ? nil : onUpdate,
+                                            onDelete: onDelete == TableBuilder.Dependency.noAction.rawValue ? nil : onDelete
+                )
+            } else {
+                return nil
+            }
+        }
+    }
+
+    private func createTableSQL(name: String) throws  -> String? {
+        try run("""
+                SELECT sql FROM sqlite_master WHERE name=? AND type='table'
+                  UNION ALL
+                SELECT sql FROM sqlite_temp_master WHERE name=? AND type='table'
+        """, name, name)
+            .compactMap { row in row[0] as? String }
+            .first
+    }
+
+    private func getBoolPragma(_ key: String) -> Bool {
+        guard let binding = try? scalar("PRAGMA \(key)"),
+              let intBinding = binding as? Int64 else { return false }
+        return intBinding == 1
+    }
+
+    private func setBoolPragma(_ key: String, _ newValue: Bool) {
+        _ = try? run("PRAGMA \(key) = \(newValue ? "1" : "0")")
+    }
+}

Sources/SQLite/Schema/Connection+Schema.swift

@@ -0,0 +1,231 @@
+import Foundation
+
+/*
+    https://www.sqlite.org/lang_altertable.html
+
+   The only schema altering commands directly supported by SQLite are the "rename table" and "add column"
+   commands shown above.
+
+    (SQLite 3.25.0: RENAME COLUMN)
+    (SQLite 3.35.0: DROP COLUMN)
+
+   However, applications can make other arbitrary changes to the format of a table using a
+   simple sequence of operations. The steps to make arbitrary changes to the schema design of some table X are as follows:
+
+        1. If foreign key constraints are enabled, disable them using PRAGMA foreign_keys=OFF.
+        2. Start a transaction.
+        3. Remember the format of all indexes and triggers associated with table X
+           (SELECT sql FROM sqlite_master WHERE tbl_name='X' AND type='index')
+        4. Use CREATE TABLE to construct a new table "new_X" that is in the desired revised format of table X.
+        5. Transfer content from X into new_X using a statement like: INSERT INTO new_X SELECT ... FROM X.
+        6. Drop the old table X: DROP TABLE X.
+        7. Change the name of new_X to X using: ALTER TABLE new_X RENAME TO X.
+        8. Use CREATE INDEX and CREATE TRIGGER to reconstruct indexes and triggers associated with table X.
+        9. If any views refer to table X in a way that is affected by the schema change, then drop those views using DROP VIEW
+       10. If foreign key constraints were originally enabled then run PRAGMA foreign_key_check
+       11. Commit the transaction started in step 2.
+       12. If foreign keys constraints were originally enabled, reenable them now.
+*/
+public class SchemaChanger: CustomStringConvertible {
+    enum SchemaChangeError: LocalizedError {
+        case foreignKeyError([ForeignKeyError])
+
+        var errorDescription: String? {
+            switch self {
+            case .foreignKeyError(let errors):
+                return "Foreign key errors: \(errors)"
+            }
+        }
+    }
+
+    public enum Operation {
+        case none
+        case add(ColumnDefinition)
+        case remove(String)
+        case renameColumn(String, String)
+        case renameTable(String)
+
+        /// Returns non-nil if the operation can be executed with a simple SQL statement
+        func toSQL(_ table: String) -> String? {
+            switch self {
+            case .add(let definition): return "ALTER TABLE \(table.quote()) ADD COLUMN \(definition.toSQL())"
+            default: return nil
+            }
+        }
+    }
+
+    public class AlterTableDefinition {
+        fileprivate var operations: [Operation] = []
+
+        let name: String
+
+        init(name: String) {
+            self.name = name
+        }
+
+        public func add(_ column: ColumnDefinition) {
+            operations.append(.add(column))
+        }
+
+        public func remove(_ column: String) {
+            operations.append(.remove(column))
+        }
+
+        public func rename(_ column: String, to: String) {
+            operations.append(.renameColumn(column, to))
+        }
+    }
+
+    private let connection: Connection
+    static let tempPrefix = "tmp_"
+    typealias Block = () throws -> Void
+    public typealias AlterTableDefinitionBlock = (AlterTableDefinition) -> Void
+
+    struct Options: OptionSet {
+        let rawValue: Int
+        static let `default`: Options = []
+        static let temp = Options(rawValue: 1)
+    }
+
+    public init(connection: Connection) {
+        self.connection = connection
+    }
+
+    public func alter(table: String, block: AlterTableDefinitionBlock) throws {
+        let alterTableDefinition = AlterTableDefinition(name: table)
+        block(alterTableDefinition)
+
+        for operation in alterTableDefinition.operations {
+            try run(table: table, operation: operation)
+        }
+    }
+
+    public func drop(table: String) throws {
+        try dropTable(table)
+    }
+
+    private func run(table: String, operation: Operation) throws {
+        if let sql = operation.toSQL(table) {
+            try connection.run(sql)
+        } else {
+            try doTheTableDance(table: table, operation: operation)
+        }
+    }
+
+    private func doTheTableDance(table: String, operation: Operation) throws {
+        try connection.transaction {
+            try disableRefIntegrity {
+                let tempTable = "\(SchemaChanger.tempPrefix)\(table)"
+                try moveTable(from: table, to: tempTable, options: [.temp], operation: operation)
+                try moveTable(from: tempTable, to: table)
+                let foreignKeyErrors = try connection.foreignKeyCheck()
+                if foreignKeyErrors.count > 0 {
+                    throw SchemaChangeError.foreignKeyError(foreignKeyErrors)
+                }
+            }
+        }
+    }
+
+    private func disableRefIntegrity(block: Block) throws {
+        let oldForeignKeys = connection.foreignKeys
+        let oldDeferForeignKeys = connection.deferForeignKeys
+
+        connection.deferForeignKeys = true
+        connection.foreignKeys = false
+
+        defer {
+            connection.deferForeignKeys = oldDeferForeignKeys
+            connection.foreignKeys = oldForeignKeys
+        }
+
+        try block()
+    }
+
+    private func moveTable(from: String, to: String, options: Options = .default, operation: Operation = .none) throws {
+        try copyTable(from: from, to: to, options: options, operation: operation)
+        try dropTable(from)
+    }
+
+    private func copyTable(from: String, to: String, options: Options = .default, operation: Operation) throws {
+        let fromDefinition = TableDefinition(
+            name: from,
+            columns: try connection.columnInfo(table: from),
+            indexes: try connection.indexInfo(table: from)
+        )
+        let toDefinition   = fromDefinition.apply(.renameTable(to)).apply(operation)
+
+        try createTable(definition: toDefinition, options: options)
+        try createTableIndexes(definition: toDefinition)
+        if case .remove = operation {
+            try copyTableContents(from: fromDefinition.apply(operation), to: toDefinition)
+        } else {
+            try copyTableContents(from: fromDefinition, to: toDefinition)
+        }
+    }
+
+    private func createTable(definition: TableDefinition, options: Options) throws {
+        try connection.run(definition.toSQL(temporary: options.contains(.temp)))
+    }
+
+    private func createTableIndexes(definition: TableDefinition) throws {
+        for index in definition.indexes {
+            try index.validate()
+            try connection.run(index.toSQL())
+        }
+    }
+
+    private func dropTable(_ table: String) throws {
+        try connection.run("DROP TABLE IF EXISTS \(table.quote())")
+    }
+
+    private func copyTableContents(from: TableDefinition, to: TableDefinition) throws {
+        try connection.run(from.copySQL(to: to))
+    }
+
+    public var description: String {
+        "SQLiteSchemaChanger: \(connection.description)"
+    }
+}
+
+extension IndexDefinition {
+    func renameTable(to: String) -> IndexDefinition {
+        func indexName() -> String {
+            if to.starts(with: SchemaChanger.tempPrefix) {
+                return "\(SchemaChanger.tempPrefix)\(name)"
+            } else if table.starts(with: SchemaChanger.tempPrefix) {
+                return name.replacingOccurrences(of: SchemaChanger.tempPrefix, with: "")
+            } else {
+                return name
+            }
+        }
+        return IndexDefinition(table: to, name: indexName(), unique: unique, columns: columns, where: `where`, orders: orders)
+    }
+
+    func renameColumn(from: String, to: String) -> IndexDefinition {
+        IndexDefinition(table: table, name: name, unique: unique, columns: columns.map {
+            $0 == from ? to : $0
+        }, where: `where`, orders: orders)
+    }
+}
+
+extension TableDefinition {
+    func apply(_ operation: SchemaChanger.Operation) -> TableDefinition {
+        switch operation {
+        case .none: return self
+        case .add: fatalError("Use 'ALTER TABLE ADD COLUMN (...)'")
+        case .remove(let column):
+            return TableDefinition(name: name,
+                columns: columns.filter { $0.name != column },
+                indexes: indexes.filter { !$0.columns.contains(column) }
+            )
+        case .renameColumn(let from, let to):
+            return TableDefinition(
+                name: name,
+                columns: columns.map { $0.rename(from: from, to: to) },
+                indexes: indexes.map { $0.renameColumn(from: from, to: to) }
+        )
+        case .renameTable(let to):
+            return TableDefinition(name: to, columns: columns, indexes: indexes.map { $0.renameTable(to: to) })
+        }
+    }
+}