Merge remote-tracking branch 'origin/main' into tagged-trait

Author: stephencelis

.github/workflows/ci.yml

@@ -27,7 +27,7 @@ jobs:
       - name: Run tests
         run: swift test
       - name: Build release
-        run: swift build -c release
+        run: swift build -c release --build-tests
 
   linux:
     name: Linux

Package.resolved

@@ -43,7 +43,7 @@ let package = Package(
     .package(url: "https://github.com/pointfreeco/swift-snapshot-testing", from: "1.18.1"),
     .package(url: "https://github.com/pointfreeco/swift-tagged", from: "0.10.0"),
     .package(url: "https://github.com/pointfreeco/xctest-dynamic-overlay", from: "1.5.2"),
-    .package(url: "https://github.com/swiftlang/swift-syntax", "600.0.0"..<"601.0.0"),
+    .package(url: "https://github.com/swiftlang/swift-syntax", "600.0.0"..<"602.0.0"),
   ],
   targets: [
     .target(

Package.swift

@@ -16,12 +16,16 @@ import StructuredQueriesCore
   named(init(_:)),
   named(init(decoder:)),
   named(QueryValue),
+  named(schemaName),
   named(tableName)
 )
 @attached(
   memberAttribute
 )
-public macro Table(_ name: String? = nil) =
+public macro Table(
+  _ name: String? = nil,
+  schema schemaName: String? = nil
+) =
   #externalMacro(
     module: "StructuredQueriesMacros",
     type: "TableMacro"

Sources/StructuredQueries/Macros.swift

@@ -143,14 +143,19 @@ generated when writing queries will correctly use `"is_completed"`.
 
 ### Custom data types
 
-There are many data types that do not have native support in SQLite. For these data types you must
-define a conformance to ``QueryBindable`` in order to translate values to a format that SQLite does
-understand. The library comes with conformances to aid in representing dates, UUIDs, and JSON, and
-you can define your own conformances for your own custom data types.
+StructuredQueries provides support for many basic Swift data types out of the box, like strings,
+integers, doubles, bytes, and booleans, but you may want to represent custom, domain specific types
+with your table's columns, instead. For these data types you must either define a conformance to
+``QueryBindable`` to translate values to a format that the library does understand, or provide a
+``QueryRepresentable`` type that wraps your domain type.
+
+The library comes with several `QueryRepresentable` conformances to aid in representing dates,
+UUIDs, and JSON, and you can define your own conformances for your own custom data types.
 
 #### Dates
 
-SQLite does not have a native date type, and instead has 3 different ways to represent dates:
+While some relational databases, like MySQL and Postgres, have native support for dates, SQLite
+does _not_. Instead, it has 3 different ways to represent dates:
 
   * Text column interpreted as ISO-8601-formatted string.
   * Int column interpreted as number of seconds since Unix epoch.
@@ -203,6 +208,14 @@ And StructuredQueries will take care of formatting the value for the database:
   }
 }
 
+When querying against a date column with a Swift date, you will need to explicitly bundle up the
+Swift date into the appropriate representation to use various query helpers. This can be done using
+the `#bind` macro:
+
+```swift
+Reminder.where { $0.created > #bind(startDate) }
+```
+
 #### UUID
 
 SQLite also does not have native support for UUIDs. If you try to use a UUID in your tables you
@@ -238,6 +251,14 @@ translate the UUID to text:
 }
 ```
 
+When querying against a UUID column with a Swift UUID, you will need to explicitly bundle up the
+Swift UUID into the appropriate representation to use various query helpers. This can be done using
+the `#bind` macro:
+
+```swift
+Reminder.where { $0.id != #bind(reminder.id) }
+```
+
 #### RawRepresentable
 
 Simple data types, in particular ones conforming to `RawRepresentable` whose `RawValue` is a string
@@ -295,14 +316,15 @@ example, suppose the `Reminder` table had an array of notes:
 
 This does not work because the `@Table` macro does not know how to encode and decode an array
 of strings into a value that SQLite understands. If you annotate this field with
-``JSONRepresentation``, then the library can encode the array of strings to a JSON string when
-storing data in the table, and decode the JSON array into a Swift array when decoding a row:
+``Swift/Decodable/JSONRepresentation``, then the library can encode the array of strings to a JSON
+string when storing data in the table, and decode the JSON array into a Swift array when decoding a
+row:
 
 ```swift
 @Table struct Reminder {
   let id: Int
   var title = ""
-  @Column(as: JSONRepresentation<[String]>.self)
+  @Column(as: [String].JSONRepresentation.self)
   var notes: [String]
 }
 ```

Sources/StructuredQueriesCore/Documentation.docc/Articles/DefiningYourSchema.md

@@ -217,7 +217,7 @@ draft has an ID or inserting a new row if the ID is `nil`:
 @Row {
   @Column {
     ```swift
-    let reminder = Reminder(
+    let reminder = Reminder.Draft(
       id: 1,
       title: "Get groceries",
       isCompleted: false
@@ -231,7 +231,7 @@ draft has an ID or inserting a new row if the ID is `nil`:
     ("id", "isCompleted", "title")
     VALUES
     (1, 0, 'Get groceries')
-    ON CONFLICT DO UPDATE SET
+    ON CONFLICT ("id") DO UPDATE SET
       "isCompleted" =
         "excluded"."isCompleted",
       "title" = "excluded"."title"

Sources/StructuredQueriesCore/Documentation.docc/Articles/PrimaryKeyedTables.md

@@ -12,7 +12,7 @@ large and complex queries.
 * [Reusable column queries](#Reusable-column-queries)
 * [Default scopes](#Default-scopes)
 * [Custom selections](#Custom-selections)
-* [Pre-loading associations with JSON](#Pre-loading-associations-with-json)
+* [Pre-loading associations with JSON](#Pre-loading-associations-with-JSON)
 
 ### Reusable table queries
 
@@ -396,19 +396,20 @@ suspiciously like a join constraint, which should give us a hint that what we ar
 quite right.
 
 Another way to do this is to use the `@Selection` macro described above
-(<doc:QueryCookbook#Custom-selections>), along with a ``JSONRepresentation`` of the collection
-of reminders you want to load for each list:
+(<doc:QueryCookbook#Custom-selections>), along with a ``Swift/Decodable/JSONRepresentation`` of the
+collection of reminders you want to load for each list:
 
 ```struct
 @Selection
 struct Row {
   let remindersList: RemindersList
-  @Column(as: JSONRepresentation<[Reminder]>.self)
+  @Column(as: [Reminder].JSONRepresentation.self)
   let reminders: [Reminder]
 }
 ```
 
-> Note: `Reminder` must conform to `Codable` to be able to use ``JSONRepresentation``.
+> Note: `Reminder` must conform to `Codable` to be able to use
+> ``Swift/Decodable/JSONRepresentation``.
 
 This allows the query to serialize the associated rows into JSON, which are then deserialized into
 a `Row` type. To construct such a query you can use the

Sources/StructuredQueriesCore/Documentation.docc/Articles/QueryCookbook.md

@@ -108,6 +108,27 @@ could be written as a single invocation of the macro:
 All of the columns provided to trailing closures in the query builder are available statically on
 each table type, so you can freely interpolate this schema information into the SQL string.
 
+> Important: _Always_ interpolate as much static schema information as possible into the SQL string
+> to better ensure that queries are correct and will successfully decode.
+>
+> For example:
+>
+> ```diff
+> -SELECT * FROM reminders
+> +SELECT \(Reminder.columns) FROM \(Reminder.self)
+> ```
+>
+>   * Selecting "`*`" requires that the column order in the database matches the field order in the
+>     Swift data type. Because StructuredQueries decodes columns in positional order, a query using
+>     "`*`" will fail to decode unless the field order matches exactly. Instead of leaving this to
+>     chance, prefer interpolating `Table.columns`, which will generate an explicit SQL column
+>     selection that matches the order of fields in the Swift data type.
+>   * Spelling out table and column names directly inside the query (_e.g._ "`reminders`") can lead
+>     to runtime errors due to typos or stale queries that refer to schema columns that have been
+>     renamed or removed. Instead, prefer interpolating `Table.columnName` to refer to a particular
+>     column (_e.g._, `Reminder.isCompleted`), and `Table.self` to refer to a table (_e.g._,
+>     `Reminder.self`).
+
 Note that the query's represented type cannot be inferred here, and so the `as` parameter is used
 to let Swift know that we expect to decode the `Reminder` type when we execute the query.
 
@@ -131,11 +152,12 @@ Values can be interpolated into `#sql` strings to produce dynamic queries:
   @Column {
     ```swift
     let isCompleted = true
+
     #sql(
       """
       SELECT count(*)
-      FROM reminders
-      WHERE isCompleted = \(isCompleted)
+      FROM \(Reminder.self)
+      WHERE \(Reminder.isCompleted) = \(isCompleted)
       """,
       as: Reminder.self
     )
@@ -144,22 +166,22 @@ Values can be interpolated into `#sql` strings to produce dynamic queries:
   @Column {
     ```sql
     SELECT count(*)
-    FROM reminders
-    WHERE isCompleted = ?
+    FROM "reminders"
+    WHERE "reminders"."isCompleted" = ?
     -- [1]
     ```
   }
 }
 
-Note that although it seems the literal value is being interpolated directly into the string, that
+Note that although it seems that `isCompleted` is being interpolated directly into the string, that
 is not what is happening. The interpolated value is captured as a separate statement binding in
 order to protect against SQL injection.
 
-String bindings are handled in a special fashion to make it clear what the intended usage is. If
-you interpolate a string into a `#sql` string, you will get a deprecation warning:
+String bindings are handled in a special fashion to make it clear what the intended usage is. If you
+interpolate a string into a `#sql` string, you will get a deprecation warning:
 
 ```swift
-let searchText = "get"
+let searchText = "%get%"
 #sql(
   """
   SELECT \(Reminder.columns)
@@ -178,7 +200,7 @@ If you mean to bind the string as a value, you can update the interpolation to u
 @Row {
   @Column {
     ```swift
-    let searchText = "get"
+    let searchText = "%get%"
     #sql(
       """
       SELECT \(Reminder.columns)
@@ -205,12 +227,12 @@ If you mean to interpolate the string directly into the SQL you can use
 @Row {
   @Column {
     ```swift
-    let searchText = "get"
+    let searchText = "%get%"
     #sql(
       """
       SELECT \(Reminder.columns)
       FROM \(Reminder.self)
-      WHERE \(Reminder.title) COLLATE NOCASE LIKE '%\(raw: searchText)%'
+      WHERE \(Reminder.title) COLLATE NOCASE LIKE '\(raw: searchText)'
       """,
       as: Reminder.self
     )

Sources/StructuredQueriesCore/Documentation.docc/Articles/SafeSQLStrings.md

@@ -721,7 +721,8 @@ The `limit(_:offset:)` function is used to change a query's `LIMIT` and `OFFSET`
   }
 }
 
-Multiple chained calls to `limit` will override the limit and offset to the last call:
+Multiple chained calls to `limit` will override the limit and offset to the last call, using the
+existing offset if none is provided:
 
 @Row {
   @Column {
@@ -755,6 +756,22 @@ Multiple chained calls to `limit` will override the limit and offset to the last
   }
 }
 
+@Row {
+  @Column {
+    ```swift
+    Reminder
+      .limit(10, offset: 10)
+      .limit(20, offset: 20)
+    ```
+  }
+  @Column {
+    ```sql
+    SELECT … FROM "reminders"
+    LIMIT 20 OFFSET 20
+    ```
+  }
+}
+
 ### Compound selects
 
 It is possible to combine multiple selects together using the `union`, `intersect`, and `except`

Sources/StructuredQueriesCore/Documentation.docc/Articles/SelectStatements.md

@@ -16,4 +16,4 @@
 - ``Foundation/UUID/BytesRepresentation``
 - ``Foundation/UUID/LowercasedRepresentation``
 - ``Foundation/UUID/UppercasedRepresentation``
-- ``JSONRepresentation``
+- ``Swift/Decodable/JSONRepresentation``