Add documentation

Author: jberkel

Documentation/Index.md

@@ -1371,6 +1371,37 @@ try db.transaction {
 
 > _Note:_ Transactions run in a serial queue.
 
+## Querying the Schema
+
+We can obtain generic information about objects in the current schema with a `SchemaReader`:
+
+```swift
+let schema = db.schema
+```
+
+To query the data:
+
+```swift
+let indexes = try schema.objectDefinitions(type: .index)
+let tables = try schema.objectDefinitions(type: .table)
+let triggers = try schema.objectDefinitions(type: .trigger)
+```
+
+### Indexes and Columns
+
+Specialized methods are available to get more detailed information:
+
+```swift
+let indexes = try schema.indexDefinitions("users")
+let columns = try schema.columnDefinitions("users")
+
+for index in indexes {
+    print("\(index.name) columns:\(index.columns))")
+}
+for column in columns {
+    print("\(column.name) pk:\(column.primaryKey) nullable: \(column.nullable)")
+}
+```
 
 ## Altering the Schema
 
@@ -1454,11 +1485,56 @@ tables](#creating-a-table).
 
 ### Renaming Columns
 
-Added in SQLite 3.25.0, not exposed yet. [#1073](https://github.com/stephencelis/SQLite.swift/issues/1073)
+We can rename columns with the help of the `SchemaChanger` class:
+
+```swift
+let schemaChanger = SchemaChanger(connection: db)
+try schemaChanger.alter(table: "users") { table in
+    table.rename("old_name", to: "new_name")
+}
+```
 
 ### Dropping Columns
 
-Added in SQLite 3.35.0, not exposed yet. [#1073](https://github.com/stephencelis/SQLite.swift/issues/1073)
+```swift
+let schemaChanger = SchemaChanger(connection: db)
+try schemaChanger.alter(table: "users") { table in
+    table.drop("column")
+}
+```
+
+These operations will work with all versions of SQLite and use modern SQL
+operations such as `DROP COLUMN` when available.
+
+### Adding Columns (SchemaChanger)
+
+The `SchemaChanger` provides an alternative API to add new columns:
+
+```swift
+let newColumn = ColumnDefinition(
+    name: "new_text_column",
+    type: .TEXT,
+    nullable: true, 
+    defaultValue: .stringLiteral("foo")
+)
+
+let schemaChanger = SchemaChanger(connection: db)
+
+try schemaChanger.alter(table: "users") { table in
+    table.add(newColumn)
+}
+```
+
+### Renaming/dropping Tables (SchemaChanger)
+
+The `SchemaChanger` provides an alternative API to rename and drop tables:
+
+```swift
+let schemaChanger = SchemaChanger(connection: db)
+
+try schemaChanger.rename(table: "users", to: "users_new")
+try schemaChanger.drop(table: "emails")
+```
 
 ### Indexes
 
@@ -1515,7 +1591,6 @@ try db.run(users.dropIndex(email, ifExists: true))
 // DROP INDEX IF EXISTS "index_users_on_email"
 ```
 
-
 ### Dropping Tables
 
 We can build
@@ -1535,7 +1610,6 @@ try db.run(users.drop(ifExists: true))
 // DROP TABLE IF EXISTS "users"
 ```
 
-
 ### Migrations and Schema Versioning
 
 You can use the convenience property on `Connection` to query and set the

Sources/SQLite/Schema/SchemaChanger.swift

@@ -99,7 +99,7 @@ public class SchemaChanger: CustomStringConvertible {
             operations.append(.addColumn(column))
         }
 
-        public func remove(_ column: String) {
+        public func drop(_ column: String) {
             operations.append(.dropColumn(column))
         }
 

Sources/SQLite/Schema/SchemaDefinitions.swift

@@ -31,6 +31,10 @@ public struct ObjectDefinition: Equatable {
 
     // SQL text that describes the object (NULL for the internal indexes)
     public let sql: String?
+
+    public var isInternal: Bool {
+        name.starts(with: "sqlite_") || sql == nil
+    }
 }
 
 // https://sqlite.org/syntax/column-def.html

Sources/SQLite/Schema/SchemaReader.swift

@@ -52,7 +52,7 @@ public class SchemaReader {
             return ObjectDefinition(
                 type: type,
                 name: row[SchemaTable.nameColumn],
-                tableName: row[SchemaTable.nameColumn],
+                tableName: row[SchemaTable.tableNameColumn],
                 rootpage: row[SchemaTable.rootPageColumn] ?? 0,
                 sql: row[SchemaTable.sqlColumn]
             )

Tests/SQLiteTests/Schema/SchemaChangerTests.swift

@@ -3,41 +3,41 @@ import XCTest
 
 class SchemaChangerTests: SQLiteTestCase {
     var schemaChanger: SchemaChanger!
-    var schemaReader: SchemaReader!
+    var schema: SchemaReader!
 
     override func setUpWithError() throws {
         try super.setUpWithError()
         try createUsersTable()
 
         try insertUsers("bob")
 
-        schemaReader = SchemaReader(connection: db)
+        schema = SchemaReader(connection: db)
         schemaChanger = SchemaChanger(connection: db)
     }
 
     func test_empty_migration_does_not_change_column_definitions() throws {
-        let previous = try schemaReader.columnDefinitions(table: "users")
+        let previous = try schema.columnDefinitions(table: "users")
         try schemaChanger.alter(table: "users") { _ in
         }
-        let current = try schemaReader.columnDefinitions(table: "users")
+        let current = try schema.columnDefinitions(table: "users")
 
         XCTAssertEqual(previous, current)
     }
 
     func test_empty_migration_does_not_change_index_definitions() throws {
-        let previous = try schemaReader.indexDefinitions(table: "users")
+        let previous = try schema.indexDefinitions(table: "users")
         try schemaChanger.alter(table: "users") { _ in
         }
-        let current = try schemaReader.indexDefinitions(table: "users")
+        let current = try schema.indexDefinitions(table: "users")
 
         XCTAssertEqual(previous, current)
     }
 
     func test_empty_migration_does_not_change_foreign_key_definitions() throws {
-        let previous = try schemaReader.foreignKeys(table: "users")
+        let previous = try schema.foreignKeys(table: "users")
         try schemaChanger.alter(table: "users") { _ in
         }
-        let current = try schemaReader.foreignKeys(table: "users")
+        let current = try schema.foreignKeys(table: "users")
 
         XCTAssertEqual(previous, current)
     }
@@ -51,21 +51,21 @@ class SchemaChangerTests: SQLiteTestCase {
         XCTAssertEqual(previous, current)
     }
 
-    func test_remove_column() throws {
+    func test_drop_column() throws {
         try schemaChanger.alter(table: "users") { table in
-            table.remove("age")
+            table.drop("age")
         }
-        let columns = try schemaReader.columnDefinitions(table: "users").map(\.name)
+        let columns = try schema.columnDefinitions(table: "users").map(\.name)
         XCTAssertFalse(columns.contains("age"))
     }
 
-    func test_remove_column_legacy() throws {
+    func test_drop_column_legacy() throws {
         schemaChanger = .init(connection: db, version: .init(major: 3, minor: 24)) // DROP COLUMN introduced in 3.35.0
 
         try schemaChanger.alter(table: "users") { table in
-            table.remove("age")
+            table.drop("age")
         }
-        let columns = try schemaReader.columnDefinitions(table: "users").map(\.name)
+        let columns = try schema.columnDefinitions(table: "users").map(\.name)
         XCTAssertFalse(columns.contains("age"))
     }
 
@@ -74,7 +74,7 @@ class SchemaChangerTests: SQLiteTestCase {
             table.rename("age", to: "age2")
         }
 
-        let columns = try schemaReader.columnDefinitions(table: "users").map(\.name)
+        let columns = try schema.columnDefinitions(table: "users").map(\.name)
         XCTAssertFalse(columns.contains("age"))
         XCTAssertTrue(columns.contains("age2"))
     }
@@ -86,7 +86,7 @@ class SchemaChangerTests: SQLiteTestCase {
             table.rename("age", to: "age2")
         }
 
-        let columns = try schemaReader.columnDefinitions(table: "users").map(\.name)
+        let columns = try schema.columnDefinitions(table: "users").map(\.name)
         XCTAssertFalse(columns.contains("age"))
         XCTAssertTrue(columns.contains("age2"))
     }
@@ -102,7 +102,7 @@ class SchemaChangerTests: SQLiteTestCase {
             table.add(newColumn)
         }
 
-        let columns = try schemaReader.columnDefinitions(table: "users")
+        let columns = try schema.columnDefinitions(table: "users")
         XCTAssertTrue(columns.contains(newColumn))
 
         XCTAssertEqual(try db.pluck(users.select(column))?[column], "foo")

Tests/SQLiteTests/Schema/SchemaReaderTests.swift

@@ -146,7 +146,7 @@ class SchemaReaderTests: SQLiteTestCase {
 
         XCTAssertEqual(tables.map { table in [table.name, table.tableName, table.type.rawValue]}, [
             ["users", "users", "table"],
-            ["sqlite_autoindex_users_1", "sqlite_autoindex_users_1", "index"]
+            ["sqlite_autoindex_users_1", "users", "index"]
         ])
     }
 
@@ -162,6 +162,38 @@ class SchemaReaderTests: SQLiteTestCase {
         ])
     }
 
+    func test_objectDefinitions_indexes() throws {
+        let emailIndex = users.createIndex(Expression<String>("email"), unique: false, ifNotExists: true)
+        try db.run(emailIndex)
+
+        let indexes = try schemaReader.objectDefinitions(type: .index)
+            .filter { !$0.isInternal }
+
+        XCTAssertEqual(indexes.map { index in [index.name, index.tableName, index.type.rawValue, index.sql]}, [
+            ["index_users_on_email",
+             "users",
+             "index",
+             "CREATE INDEX \"index_users_on_email\" ON \"users\" (\"email\")"]
+        ])
+    }
+
+    func test_objectDefinitions_triggers() throws {
+        let trigger = """
+        CREATE TRIGGER test_trigger
+            AFTER INSERT ON users BEGIN
+                UPDATE USERS SET name = "update" WHERE id = NEW.rowid;
+            END;
+        """
+
+        try db.run(trigger)
+
+        let triggers = try schemaReader.objectDefinitions(type: .trigger)
+
+        XCTAssertEqual(triggers.map { trigger in [trigger.name, trigger.tableName, trigger.type.rawValue]}, [
+            ["test_trigger", "users", "trigger"]
+        ])
+    }
+
     func test_objectDefinitionsFilterByType() throws {
         let tables = try schemaReader.objectDefinitions(type: .table)