Rename SQLRaw to SQLUnsafeRaw and SQLRawBuilder to SQLUnsafeRawBuilder

README.md

@@ -258,10 +258,10 @@ The delete builder is also an `SQLPredicateBuilder`.
 
 ## Raw
 
-The `raw(_:)` method allows passing custom SQL query strings, with support for parameterized bindings and correctly-quoted identifiers:
+The `unsafeRaw(_:)` method allows passing custom SQL query strings, with support for parameterized bindings and correctly-quoted identifiers:
 
 ```swift
-let planets = try await db.raw("SELECT \(SQLLiteral.all) FROM \(ident: table) WHERE \(ident: name) = \(bind: "planet")")
+let planets = try await db.unsafeRaw("SELECT \(SQLLiteral.all) FROM \(ident: table) WHERE \(ident: name) = \(bind: "planet")")
     .all()
 ```
 

Sources/SQLKit/Builders/Implementations/SQLRawBuilder.swift

@@ -1,5 +1,5 @@
 /// Builds raw SQL queries.
-public final class SQLRawBuilder: SQLQueryBuilder, SQLQueryFetcher {
+public final class SQLUnsafeRawBuilder: SQLQueryBuilder, SQLQueryFetcher {
     /// Raw query being built.
     @usableFromInline
     var sql: SQLQueryString
@@ -13,7 +13,7 @@ public final class SQLRawBuilder: SQLQueryBuilder, SQLQueryFetcher {
         self.sql
     }
 
-    /// Create a new ``SQLRawBuilder``.
+    /// Create a new ``SQLUnsafeRawBuilder``.
     @inlinable
     public init(_ sql: SQLQueryString, on database: any SQLDatabase) {
         self.database = database
@@ -22,9 +22,9 @@ public final class SQLRawBuilder: SQLQueryBuilder, SQLQueryFetcher {
 }
 
 extension SQLDatabase {
-    /// Create a new ``SQLRawBuilder``.
+    /// Create a new ``SQLUnsafeRawBuilder``.
     @inlinable
-    public func raw(_ sql: SQLQueryString) -> SQLRawBuilder {
+    public func unsafeRaw(_ sql: SQLQueryString) -> SQLUnsafeRawBuilder {
         .init(sql, on: self)
     }
 }

Sources/SQLKit/Builders/Prototypes/SQLJoinBuilder.swift

@@ -82,8 +82,8 @@ extension SQLJoinBuilder {
     public func join(_ table: any SQLExpression, method: any SQLExpression = SQLJoinMethod.inner, using columns: any SQLExpression) -> Self {
         // TODO: Make ``SQLJoin`` aware of the `USING` syntax; this method is hacky and somewhat driver-specific.
         self.joins.append(SQLList([
-            method, SQLRaw("JOIN"), table, SQLRaw("USING"), SQLGroupExpression(columns)
-        ], separator: SQLRaw(" ")))
+            method, SQLUnsafeRaw("JOIN"), table, SQLUnsafeRaw("USING"), SQLGroupExpression(columns)
+        ], separator: SQLUnsafeRaw(" ")))
         return self
     }
 }

Sources/SQLKit/Database/SQLDialect.swift

@@ -18,15 +18,15 @@ public protocol SQLDialect: Sendable {
     /// No default is provided.
     var name: String { get }
 
-    /// An expression (usually an ``SQLRaw``) giving the character(s) used to quote SQL
+    /// An expression (usually an ``SQLUnsafeRaw``) giving the character(s) used to quote SQL
     /// identifiers, such as table and column names.
     ///
     /// The identifier quote is placed immediately preceding and following each identifier.
     ///
     /// No default is provided.
     var identifierQuote: any SQLExpression { get }
 
-    /// An expression (usually an ``SQLRaw``) giving the character(s) used to quote literal
+    /// An expression (usually an ``SQLUnsafeRaw``) giving the character(s) used to quote literal
     /// string values which appear in a query, such as enumerator names.
     ///
     /// The literal quote is placed immediately preceding and following each string literal.
@@ -82,21 +82,21 @@ public protocol SQLDialect: Sendable {
     ///   the first parameter has position `1`. This value is guaranteed to be greater than zero.
     func bindPlaceholder(at position: Int) -> any SQLExpression
 
-    /// A function which returns an SQL expression (usually an ``SQLRaw``) representing the given
+    /// A function which returns an SQL expression (usually an ``SQLUnsafeRaw``) representing the given
     /// literal boolean value.
     /// 
     /// No default is provided.
     ///
     /// - Parameter value: The boolean value to represent.
     func literalBoolean(_ value: Bool) -> any SQLExpression
 
-    /// An expression (usually an ``SQLRaw``) giving the syntax used to express both "use this as
+    /// An expression (usually an ``SQLUnsafeRaw``) giving the syntax used to express both "use this as
     /// the default value" in a column definition and "use the default value for this column" in
     /// a value list.
     ///
     /// ``SQLLiteral/default`` always serializes to this expression.
     ///
-    /// Defaults to `SQLRaw("DEFAULT")`.
+    /// Defaults to `SQLUnsafeRaw("DEFAULT")`.
     var literalDefault: any SQLExpression { get }
 
     /// `true` if the dialect supports the `IF EXISTS` modifier for all types of `DROP` queries
@@ -483,7 +483,7 @@ extension SQLDialect {
     /// Default implementation of ``literalStringQuote-3ur0m``.
     @inlinable
     public var literalStringQuote: any SQLExpression {
-        SQLRaw("'")
+        SQLUnsafeRaw("'")
     }
 
     /// Default implementation of ``autoIncrementFunction-1ktxy``.
@@ -495,7 +495,7 @@ extension SQLDialect {
     /// Default implementation of ``literalDefault-7nz7t``.
     @inlinable
     public var literalDefault: any SQLExpression {
-        SQLRaw("DEFAULT")
+        SQLUnsafeRaw("DEFAULT")
     }
 
     /// Default implementation of ``supportsIfExists-5dxcu``.

Sources/SQLKit/Deprecated/SQLDatabase+Deprecated.swift

@@ -38,3 +38,11 @@ extension SQLDatabaseReportedVersion {
         (otherVersion as? Self).map { !self.isOlder(than: $0) } ?? false
     }
 }
+
+extension SQLDatabase {
+    @available(*, deprecated, renamed: "unsafeRaw(_:)", message: "SQLDatabase.unsafeRaw(_:) has been renamed to SQLDatabase.unsafeRaw(_:).")
+    @inlinable
+    public func raw(_ sql: SQLQueryString) -> SQLRawBuilder {
+        self.unsafeRaw(sql)
+    }
+}

Sources/SQLKit/Deprecated/SQLExpressions+Deprecated.swift

@@ -72,8 +72,11 @@ extension SQLQueryString {
     }
 }
 
-extension SQLRaw {
-    @available(*, deprecated, message: "Binds set in an `SQLRaw` are ignored. Use `SQLBind`instead.")
+@available(*, deprecated, renamed: "SQLUnsafeRaw", message: "SQLRaw has been renamed to SQLUnsafeRaw.")
+public typealias SQLRaw = SQLUnsafeRaw
+
+extension SQLUnsafeRaw {
+    @available(*, deprecated, message: "Binds set in an `SQLUnsafeRaw` are ignored. Use `SQLBind`instead.")
     @inlinable
     public init(_ sql: String, _ binds: [any Encodable & Sendable]) {
         self.sql = sql

Sources/SQLKit/Deprecated/SQLQueryBuilders+Deprecated.swift

@@ -31,15 +31,15 @@ extension SQLCreateTriggerBuilder {
     @inlinable
     @discardableResult
     public func condition(_ value: String) -> Self {
-        self.condition(SQLRaw(value))
+        self.condition(SQLUnsafeRaw(value))
     }
 
     /// Specify a body for the trigger.
-    @available(*, deprecated, message: "Specifying SQL statements as raw strings is unsafe. Use `SQLQueryString` or `SQLRaw` explicitly.")
+    @available(*, deprecated, message: "Specifying SQL statements as raw strings is unsafe. Use `SQLQueryString` or `SQLUnsafeRaw` explicitly.")
     @inlinable
     @discardableResult
     public func body(_ statements: [String]) -> Self {
-        self.body(statements.map { SQLRaw($0) })
+        self.body(statements.map { SQLUnsafeRaw($0) })
     }
 }
 
@@ -55,6 +55,9 @@ extension SQLJoinBuilder {
     @inlinable
     @discardableResult
     public func join(_ table: String, method: SQLJoinMethod = .inner, on expression: String) -> Self {
-         self.join(SQLIdentifier(table), method: method, on: SQLRaw(expression))
+         self.join(SQLIdentifier(table), method: method, on: SQLUnsafeRaw(expression))
     }
 }
+
+@available(*, deprecated, renamed: "SQLUnsafeRawBuilder", message: "SQLRawBuilder has been renamed to SQLUnsafeRawBuilder.")
+public typealias SQLRawBuilder = SQLUnsafeRawBuilder

Sources/SQLKit/Docs.docc/BasicUsage.md

@@ -273,10 +273,10 @@ The delete builder also conforms to ``SQLPredicateBuilder``.
 
 ### Raw
 
-The ``SQLDatabase/raw(_:)`` method allows passing custom SQL query strings, with support for parameterized bindings and correctly-quoted identifiers:
+The ``SQLDatabase/unsafeRaw(_:)`` method allows passing custom SQL query strings, with support for parameterized bindings and correctly-quoted identifiers:
 
 ```swift
-let planets = try await db.raw("SELECT \(SQLLiteral.all) FROM \(ident: table) WHERE \(ident: name) = \(bind: "planet")")
+let planets = try await db.unsafeRaw("SELECT \(SQLLiteral.all) FROM \(ident: table) WHERE \(ident: name) = \(bind: "planet")")
     .all()
 ```
 

Sources/SQLKit/Docs.docc/SQLKit.md

@@ -69,12 +69,12 @@ SQLKit does _not_ provide facilities for creating or managing database connectio
 - ``SQLDropTriggerBuilder``
 - ``SQLInsertBuilder``
 - ``SQLPredicateGroupBuilder``
-- ``SQLRawBuilder``
 - ``SQLReturningResultBuilder``
 - ``SQLSecondaryPredicateGroupBuilder``
 - ``SQLSelectBuilder``
 - ``SQLSubqueryBuilder``
 - ``SQLUnionBuilder``
+- ``SQLUnsafeRawBuilder``
 - ``SQLUpdateBuilder``
 
 ### Syntactic Expressions
@@ -87,7 +87,7 @@ SQLKit does _not_ provide facilities for creating or managing database connectio
 - ``SQLIdentifier``
 - ``SQLList``
 - ``SQLLiteral``
-- ``SQLRaw``
+- ``SQLUnsafeRaw``
 
 ### Basic Expressions
 

Sources/SQLKit/Expressions/Basics/SQLDataType.swift

@@ -32,7 +32,7 @@ public enum SQLDataType: SQLExpression {
     /// > Note: Implemented as a static var rather than a new case for now because adding new cases to a public enum
     /// > is a source-breaking change.
     public static var timestamp: Self {
-        .custom(SQLRaw("TIMESTAMP"))
+        .custom(SQLUnsafeRaw("TIMESTAMP"))
     }
 
     /// Translates to the serialization of the given expression, unless overridden by dialect.
@@ -48,17 +48,17 @@ public enum SQLDataType: SQLExpression {
         } else {
             switch self {
             case .smallint:
-                sql = SQLRaw("SMALLINT")
+                sql = SQLUnsafeRaw("SMALLINT")
             case .int:
-                sql = SQLRaw("INTEGER")
+                sql = SQLUnsafeRaw("INTEGER")
             case .bigint:
-                sql = SQLRaw("BIGINT")
+                sql = SQLUnsafeRaw("BIGINT")
             case .text:
-                sql = SQLRaw("TEXT")
+                sql = SQLUnsafeRaw("TEXT")
             case .real:
-                sql = SQLRaw("REAL")
+                sql = SQLUnsafeRaw("REAL")
             case .blob:
-                sql = SQLRaw("BLOB")
+                sql = SQLUnsafeRaw("BLOB")
             case .custom(let exp):
                 sql = exp
             }

Sources/SQLKit/Expressions/Basics/SQLQueryString.swift

@@ -1,6 +1,6 @@
 /// An expression consisting of an array of constituent subexpressions generated by custom string interpolations.
 ///
-/// Query strings are primarily intended for use with ``SQLRawBuilder``, providing for the inclusion of bound
+/// Query strings are primarily intended for use with ``SQLUnsafeRawBuilder``, providing for the inclusion of bound
 /// parameters in otherwise "raw" queries. The API also supports some of the more commonly used quoting functionality.
 /// Query strings are also ``SQLExpression``s, allowing them to be used almost anywhere in SQLKit.
 ///
@@ -12,7 +12,7 @@
 ///
 /// ```swift
 /// // As an entire query:
-/// try await database.raw("""
+/// try await database.unsafeRaw("""
 ///     UPDATE \(ident: "foo")
 ///         SET \(ident: "bar")=\(bind: value)
 ///         WHERE \(ident: "baz")=\(literal: "bop")
@@ -31,7 +31,7 @@
 ///
 /// ```swift
 /// let messyIdentifer = someCondition ? "abcd{}efgh" : "marmalade!!" // invalid identifiers if not escaped
-/// try await database.raw("""
+/// try await database.unsafeRaw("""
 ///     SELECT \(ident: messyIdentifier) FROM \(ident: "whatever") WHERE \(ident: "x")=\(bind: "foo")
 ///     """).all()
 /// // This query renders differently in various dialect:
@@ -62,7 +62,7 @@ public struct SQLQueryString: SQLExpression, ExpressibleByStringInterpolation, S
     /// Create a query string from a plain string containing raw SQL.
     @inlinable
     public init(_ string: String) {
-        self.fragments = [SQLRaw(string)]
+        self.fragments = [SQLUnsafeRaw(string)]
     }
 
     // See `SQLExpression.serialize(to:)`.
@@ -98,7 +98,7 @@ extension SQLQueryString {
     // See `StringInterpolationProtocol.appendLiteral(_:)`.
     @inlinable
     public mutating func appendLiteral(_ literal: String) {
-        self.fragments.append(SQLRaw(literal))
+        self.fragments.append(SQLUnsafeRaw(literal))
     }
 }
 
@@ -111,7 +111,7 @@ extension SQLQueryString {
     /// > a purpose-specific expression instead whenever possible.
     @inlinable
     public mutating func appendInterpolation(unsafeRaw value: String) {
-        self.fragments.append(SQLRaw(value))
+        self.fragments.append(SQLUnsafeRaw(value))
     }
 
     /// Embed an `Encodable` value as a binding in the SQL query.
@@ -167,7 +167,7 @@ extension SQLQueryString {
     /// Embed an array of `String`s as a list of literal values, placing the `joiner` between each pair of values.
     ///
     /// This is equivalent to adding an ``SQLList`` whose subexpressions are all ``SQLLiteral/string(_:)``s and whose
-    /// separator is the `joiner` wrapped by ``SQLRaw``.
+    /// separator is the `joiner` wrapped by ``SQLUnsafeRaw``.
     ///
     /// Example:
     ///
@@ -180,7 +180,7 @@ extension SQLQueryString {
     /// ```
     @inlinable
     public mutating func appendInterpolation(literals: [String], joinedBy joiner: String) {
-        self.fragments.append(SQLList(literals.map { SQLLiteral.string($0) }, separator: SQLRaw(joiner)))
+        self.fragments.append(SQLList(literals.map { SQLLiteral.string($0) }, separator: SQLUnsafeRaw(joiner)))
     }
 
     /// Embed a `String` as an identifier, as if via ``SQLIdentifier``.
@@ -210,7 +210,7 @@ extension SQLQueryString {
     /// ```
     @inlinable
     public mutating func appendInterpolation(idents: [String], joinedBy joiner: String) {
-        self.fragments.append(SQLList(idents.map { SQLIdentifier($0) }, separator: SQLRaw(joiner)))
+        self.fragments.append(SQLList(idents.map { SQLIdentifier($0) }, separator: SQLUnsafeRaw(joiner)))
     }
 
     /// Embed an arbitary ``SQLExpression`` in the string.
@@ -245,7 +245,7 @@ extension Sequence<SQLQueryString> {
     /// - Returns: A single, concatenated string.
     @inlinable
     public func joined(separator: String = "") -> SQLQueryString {
-        self.joined(separator: SQLRaw(separator))
+        self.joined(separator: SQLUnsafeRaw(separator))
     }
 
     /// Returns a new ``SQLQueryString`` formed by concatenating the elements of the sequence, adding the given

Sources/SQLKit/Expressions/Clauses/SQLColumnDefinition.swift

@@ -53,7 +53,7 @@ public struct SQLColumnDefinition: SQLExpression {
         serializer.statement {
             $0.append(self.column, self.dataType)
             if !self.constraints.isEmpty {
-                $0.append(SQLList(self.constraints, separator: SQLRaw(" ")))
+                $0.append(SQLList(self.constraints, separator: SQLUnsafeRaw(" ")))
             }
         }
     }

Sources/SQLKit/Expressions/Clauses/SQLJoinMethod.swift

@@ -18,7 +18,7 @@ public enum SQLJoinMethod: SQLExpression {
     /// An outer join not otherwise specified.
     ///
     /// Although this expression does generate `OUTER JOIN` for this case, this is not a valid join in most dialects.
-    /// It is therefore deprecated and should not be used. Users who need it can use `SQLRaw("OUTER JOIN")` instead.
+    /// It is therefore deprecated and should not be used. Users who need it can use `SQLUnsafeRaw("OUTER JOIN")` instead.
     ///
     /// > Note: Presumably, the original intention of this case was to allow expressing a `FULL JOIN` or
     /// > `FULL OUTER JOIN`, which is simply a combination of the effects of a left and right join.

Sources/SQLKit/Expressions/Queries/SQLAlterTable.swift

@@ -60,9 +60,9 @@ public struct SQLAlterTable: SQLExpression {
             // Emit the query anyway so the error will propagate when the database rejects it.
         }
 
-        let additions = (self.addColumns  + self.addTableConstraints).map  { (verb: SQLRaw("ADD"),  definition: $0) }
-        let removals  = (self.dropColumns + self.dropTableConstraints).map { (verb: SQLRaw("DROP"), definition: $0) }
-        let modifications = self.modifyColumns.map { (verb: syntax.alterColumnDefinitionClause ?? SQLRaw("__INVALID__"), definition: $0) }
+        let additions = (self.addColumns  + self.addTableConstraints).map  { (verb: SQLUnsafeRaw("ADD"),  definition: $0) }
+        let removals  = (self.dropColumns + self.dropTableConstraints).map { (verb: SQLUnsafeRaw("DROP"), definition: $0) }
+        let modifications = self.modifyColumns.map { (verb: syntax.alterColumnDefinitionClause ?? SQLUnsafeRaw("__INVALID__"), definition: $0) }
         let alterations = additions + removals + modifications
 
         serializer.statement {

Sources/SQLKit/Expressions/Queries/SQLCreateTrigger.swift

@@ -196,7 +196,7 @@ public struct SQLCreateTrigger: SQLExpression {
             }
 
             if syntax.contains(.supportsBody), let body = self.body {
-                $0.append("BEGIN", SQLList(body, separator: SQLRaw(" ")), "END;")
+                $0.append("BEGIN", SQLList(body, separator: SQLUnsafeRaw(" ")), "END;")
             } else if let procedure = self.procedure {
                 $0.append("EXECUTE PROCEDURE", procedure)
             }

Sources/SQLKit/Expressions/Queries/SQLSelect.swift

@@ -112,7 +112,7 @@ public struct SQLSelect: SQLExpression {
                 $0.append("FROM", SQLList(self.tables))
             }
             if !self.joins.isEmpty {
-                $0.append(SQLList(self.joins, separator: SQLRaw(" ")))
+                $0.append(SQLList(self.joins, separator: SQLUnsafeRaw(" ")))
             }
             if self.predicate != nil {
                 $0.append("WHERE", self.predicate)

Sources/SQLKit/Expressions/SQLExpression.swift

@@ -3,7 +3,7 @@
 /// ``SQLExpression``s are not well-enough organized in practice to be considered a proper Abstract Syntax Tree
 /// representation, but they nonetheless conceptually act as AST nodes. As such, _anything_ which is executed as
 /// SQL by an ``SQLDatabase`` is represented by a value conforming to ``SQLExpression`` - even if that value is an
-/// instance of ``SQLRaw`` containing arbitrary SQL text.
+/// instance of ``SQLUnsafeRaw`` containing arbitrary SQL text.
 ///
 /// The single requirement of ``SQLExpression`` is the ``SQLExpression/serialize(to:)`` method, which must output
 /// the appropriate raw text, bindings, and/or subexpressions to the provided ``SQLSerializer`` when invoked. Most