Merge remote-tracking branch 'origin/main' into default-date-uuid-representations

Author: stephencelis

Sources/StructuredQueries/Macros.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/StructuredQueriesCore/Documentation.docc/Articles/QueryCookbook.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
 

Sources/StructuredQueriesCore/Documentation.docc/Articles/SafeSQLStrings.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/QueryFragment.swift

@@ -262,6 +262,10 @@ extension QueryFragment: ExpressibleByStringInterpolation {
     ///
     /// - Parameter table: A table.
     public mutating func appendInterpolation<T: Table>(_ table: T.Type) {
+      if let schemaName = table.schemaName {
+        appendInterpolation(quote: schemaName)
+        appendLiteral(".")
+      }
       appendInterpolation(quote: table.tableAlias ?? table.tableName)
     }
 

Sources/StructuredQueriesCore/Statements/CommonTableExpression.swift

@@ -39,10 +39,10 @@ public struct With<QueryValue>: Statement {
 
 public struct CommonTableExpressionClause: QueryExpression {
   public typealias QueryValue = ()
-  let tableName: String
+  let tableName: QueryFragment
   let select: QueryFragment
   public var queryFragment: QueryFragment {
-    "\(quote: tableName) AS (\(.newline)\(select.indented())\(.newline))"
+    "\(tableName) AS (\(.newline)\(select.indented())\(.newline))"
   }
 }
 
@@ -55,7 +55,7 @@ public enum CommonTableExpressionBuilder {
   public static func buildExpression<CTETable: Table>(
     _ expression: some PartialSelectStatement<CTETable>
   ) -> CommonTableExpressionClause {
-    CommonTableExpressionClause(tableName: CTETable.tableName, select: expression.query)
+    CommonTableExpressionClause(tableName: "\(CTETable.self)", select: expression.query)
   }
 
   public static func buildBlock(

Sources/StructuredQueriesCore/Statements/Delete.swift

@@ -135,7 +135,11 @@ extension Delete: Statement {
   public typealias QueryValue = Returning
 
   public var query: QueryFragment {
-    var query: QueryFragment = "DELETE FROM \(quote: From.tableName)"
+    var query: QueryFragment = "DELETE FROM "
+    if let schemaName = From.schemaName {
+      query.append("\(quote: schemaName).")
+    }
+    query.append("\(quote: From.tableName)")
     if let tableAlias = From.tableAlias {
       query.append(" AS \(quote: tableAlias)")
     }

Sources/StructuredQueriesCore/Statements/Insert.swift

@@ -403,7 +403,11 @@ extension Insert: Statement {
     if let conflictResolution {
       query.append(" OR \(conflictResolution)")
     }
-    query.append(" INTO \(quote: Into.tableName)")
+    query.append(" INTO ")
+    if let schemaName = Into.schemaName {
+      query.append("\(quote: schemaName).")
+    }
+    query.append("\(quote: Into.tableName)")
     if let tableAlias = Into.tableAlias {
       query.append(" AS \(quote: tableAlias)")
     }

Sources/StructuredQueriesCore/Statements/Select.swift

@@ -1410,7 +1410,11 @@ extension Select: SelectStatement {
       query.append(" DISTINCT")
     }
     query.append(" \(columns.joined(separator: ", "))")
-    query.append("\(.newlineOrSpace)FROM \(quote: From.tableName)")
+    query.append("\(.newlineOrSpace)FROM ")
+    if let schemaName = From.schemaName {
+      query.append("\(quote: schemaName).")
+    }
+    query.append("\(quote: From.tableName)")
     if let tableAlias = From.tableAlias {
       query.append(" AS \(quote: tableAlias)")
     }

Sources/StructuredQueriesCore/Statements/Update.swift

@@ -196,11 +196,14 @@ extension Update: Statement {
     guard !updates.isEmpty
     else { return "" }
 
-    var query: QueryFragment = "UPDATE"
+    var query: QueryFragment = "UPDATE "
     if let conflictResolution {
-      query.append(" OR \(conflictResolution)")
+      query.append("OR \(conflictResolution) ")
     }
-    query.append(" \(quote: From.tableName)")
+    if let schemaName = From.schemaName {
+      query.append("\(quote: schemaName).")
+    }
+    query.append("\(quote: From.tableName)")
     if let tableAlias = From.tableAlias {
       query.append(" AS \(quote: tableAlias)")
     }

Sources/StructuredQueriesCore/Table.swift

@@ -21,6 +21,9 @@ public protocol Table: QueryRepresentable where TableColumns.QueryValue == Self
   /// This property should always return `nil` unless called on a ``TableAlias``.
   static var tableAlias: String? { get }
 
+  /// The table schema's name.
+  static var schemaName: String? { get }
+
   /// A select statement for this table.
   ///
   /// The default implementation of this property returns a fully unscoped query for the table
@@ -90,6 +93,10 @@ extension Table {
     nil
   }
 
+  public static var schemaName: String? {
+    nil
+  }
+
   /// Returns a table column to the resulting value of a given key path.
   ///
   /// Allows, _e.g._ `Reminder.columns.id` to be abbreviated `Reminder.id`, which is useful when