Doc updates

Author: jberkel

CHANGELOG.md

@@ -1,5 +1,6 @@
 0.14.0 (tbd), [diff][diff-0.14.0]
 ========================================
+For breaking changes, see [Upgrading.md](Documentation/Upgrading.md).
 
 * Support more complex schema changes and queries ([#1073][], [#1146][] [#1148][])
 * Support `ATTACH`/`DETACH` ([#30][], [#1142][])

Documentation/Index.md

@@ -41,14 +41,19 @@
   - [Updating Rows](#updating-rows)
   - [Deleting Rows](#deleting-rows)
   - [Transactions and Savepoints](#transactions-and-savepoints)
+  - [Querying the Schema](#querying-the-schema)
   - [Altering the Schema](#altering-the-schema)
     - [Renaming Tables](#renaming-tables)
+    - [Dropping Tables](#dropping-tables)
     - [Adding Columns](#adding-columns)
       - [Added Column Constraints](#added-column-constraints)
+    - [Schema Changer](#schemachanger)
+      - [Renaming Columns](#renaming-columns)
+      - [Dropping Columns](#dropping-columns)
+      - [Renaming/dropping tables](#renamingdropping-tables)
     - [Indexes](#indexes)
       - [Creating Indexes](#creating-indexes)
       - [Dropping Indexes](#dropping-indexes)
-    - [Dropping Tables](#dropping-tables)
     - [Migrations and Schema Versioning](#migrations-and-schema-versioning)
   - [Custom Types](#custom-types)
     - [Date-Time Values](#date-time-values)
@@ -1409,7 +1414,6 @@ for column in columns {
 SQLite.swift comes with several functions (in addition to `Table.create`) for
 altering a database schema in a type-safe manner.
 
-
 ### Renaming Tables
 
 We can build an `ALTER TABLE … RENAME TO` statement by calling the `rename`
@@ -1420,6 +1424,24 @@ try db.run(users.rename(Table("users_old")))
 // ALTER TABLE "users" RENAME TO "users_old"
 ```
 
+### Dropping Tables
+
+We can build
+[`DROP TABLE` statements](https://www.sqlite.org/lang_droptable.html)
+by calling the `dropTable` function on a `SchemaType`.
+
+```swift
+try db.run(users.drop())
+// DROP TABLE "users"
+```
+
+The `drop` function has one additional parameter, `ifExists`, which (when
+`true`) adds an `IF EXISTS` clause to the statement.
+
+```swift
+try db.run(users.drop(ifExists: true))
+// DROP TABLE IF EXISTS "users"
+```
 
 ### Adding Columns
 
@@ -1484,57 +1506,54 @@ tables](#creating-a-table).
     // ALTER TABLE "posts" ADD COLUMN "user_id" INTEGER REFERENCES "users" ("id")
     ```
 
-### Renaming Columns
+### SchemaChanger
 
-We can rename columns with the help of the `SchemaChanger` class:
+Version 0.14.0 introduces `SchemaChanger`, an alternative API to perform more complex
+migrations such as renaming columns. These operations work with all versions of
+SQLite but use SQL statements such as `ALTER TABLE RENAME COLUMN` when available.
+
+#### Adding 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.rename(column: "old_name", to: "new_name")
+    table.add(newColumn)
 }
 ```
 
-### Dropping Columns
+#### Renaming Columns
 
 ```swift
 let schemaChanger = SchemaChanger(connection: db)
 try schemaChanger.alter(table: "users") { table in
-    table.drop(column: "email")
+    table.rename(column: "old_name", to: "new_name")
 }
 ```
 
-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:
+#### Dropping 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)
+    table.drop(column: "email")
 }
 ```
 
-### Renaming/dropping Tables (SchemaChanger)
-
-The `SchemaChanger` provides an alternative API to rename and drop tables:
+#### Renaming/dropping Tables
 
 ```swift
 let schemaChanger = SchemaChanger(connection: db)
 
 try schemaChanger.rename(table: "users", to: "users_new")
-try schemaChanger.drop(table: "emails")
+try schemaChanger.drop(table: "emails", ifExists: false)
 ```
 
 ### Indexes
@@ -1592,25 +1611,6 @@ try db.run(users.dropIndex(email, ifExists: true))
 // DROP INDEX IF EXISTS "index_users_on_email"
 ```
 
-### Dropping Tables
-
-We can build
-[`DROP TABLE` statements](https://www.sqlite.org/lang_droptable.html)
-by calling the `dropTable` function on a `SchemaType`.
-
-```swift
-try db.run(users.drop())
-// DROP TABLE "users"
-```
-
-The `drop` function has one additional parameter, `ifExists`, which (when
-`true`) adds an `IF EXISTS` clause to the statement.
-
-```swift
-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

Documentation/Release.md

@@ -3,6 +3,7 @@
 * [ ] Make sure current master branch has a green build
 * [ ] Make sure `SQLite.playground` runs without errors
 * [ ] Make sure `CHANGELOG.md` is up-to-date
+* [ ] Add content to `Documentation/Upgrading.md` if needed
 * [ ] Update the version number in `SQLite.swift.podspec`
 * [ ] Run `pod lib lint` locally
 * [ ] Update the version numbers mentioned in `README.md`, `Documentation/Index.md`

Documentation/Upgrading.md

@@ -0,0 +1,11 @@
+# Upgrading
+
+## 0.13 → 0.14
+
+- `Expression.asSQL()` is no longer available. Expressions now implement `CustomStringConvertible`,
+  where `description` returns the SQL.
+- `Statement.prepareRowIterator()` is now longer available. Instead, use the methods
+  of the same name on `Connection`.
+- `Blob` no longer wraps byte arrays and now uses `NSData`, which enables memory and
+ performance improvements.
+- `Connection.registerTokenizer` is no longer available to register custom FTS4 tokenizers.

SQLite.playground/Contents.swift

@@ -52,6 +52,7 @@ for user in try Array(rowIterator) {
 
 /// also with `map()`
 let mapRowIterator = try db.prepareRowIterator(users)
+
 let userIds = try mapRowIterator.map { $0[id] }
 
 /// using `failableNext()` on `RowIterator`

Sources/SQLite/Schema/SchemaChanger.swift

@@ -141,8 +141,8 @@ public class SchemaChanger: CustomStringConvertible {
         }
     }
 
-    public func drop(table: String) throws {
-        try dropTable(table)
+    public func drop(table: String, ifExists: Bool = true) throws {
+        try dropTable(table, ifExists: ifExists)
     }
 
     // Beginning with release 3.25.0 (2018-09-15), references to the table within trigger bodies and
@@ -192,7 +192,7 @@ public class SchemaChanger: CustomStringConvertible {
 
     private func moveTable(from: String, to: String, options: Options = .default, operation: Operation? = nil) throws {
         try copyTable(from: from, to: to, options: options, operation: operation)
-        try dropTable(from)
+        try dropTable(from, ifExists: true)
     }
 
     private func copyTable(from: String, to: String, options: Options = .default, operation: Operation?) throws {
@@ -225,8 +225,8 @@ public class SchemaChanger: CustomStringConvertible {
         }
     }
 
-    private func dropTable(_ table: String) throws {
-        try connection.run("DROP TABLE IF EXISTS \(table.quote())")
+    private func dropTable(_ table: String, ifExists: Bool) throws {
+        try connection.run("DROP TABLE \(ifExists ? "IF EXISTS" : "") \(table.quote())")
     }
 
     private func copyTableContents(from: TableDefinition, to: TableDefinition) throws {

Tests/SQLiteTests/Schema/SchemaChangerTests.swift

@@ -135,6 +135,20 @@ class SchemaChangerTests: SQLiteTestCase {
         }
     }
 
+    func test_drop_table_if_exists_true() throws {
+        try schemaChanger.drop(table: "xxx", ifExists: true)
+    }
+
+    func test_drop_table_if_exists_false() throws {
+        XCTAssertThrowsError(try schemaChanger.drop(table: "xxx", ifExists: false)) { error in
+            if case Result.error(let message, _, _) =  error {
+                XCTAssertEqual(message, "no such table: xxx")
+            } else {
+                XCTFail("unexpected error \(error)")
+            }
+        }
+    }
+
     func test_rename_table() throws {
         try schemaChanger.rename(table: "users", to: "users_new")
         let users_new = Table("users_new")