wip

mbrandonw · mbrandonw · commit 0c6c9ef5d35c · 2025-04-21T20:05:46.000-07:00
diff --git a/Sources/SharingGRDBCore/Documentation.docc/Articles/ComparisonWithSwiftData.md b/Sources/SharingGRDBCore/Documentation.docc/Articles/ComparisonWithSwiftData.md
@@ -10,7 +10,7 @@ SwiftUI views (including UIKit, `@Observable` models, _etc._). This article desc
 approaches compare in a variety of situations, such as setting up the data store, fetching data,
 associations, and more.
 
-  * [Designing your schema](#Designing-your-schema)
+  * [Defining your schema](#Defining-your-schema)
   * [Setting up external storage](#Setting-up-external-storage)
   * [Fetching data for a view](#Fetching-data-for-a-view)
   * [Fetching data for an @Observable model](#Fetching-data-for-an-Observable-model)
@@ -22,7 +22,7 @@ associations, and more.
     * [Manual migrations](#Manual-migrations)
   * [Supported Apple platforms](#Supported-Apple-platforms)
 
-### Designing your schema
+### Defining your schema
 
 Both SharingGRDB and SwiftData come with tools to expose your data types' fields to the compiler
 so that type-safe and schema-safe queries can be written. SharingGRDB uses another library of ours
@@ -73,6 +73,11 @@ Some key differences:
   * The `@Model` version of `Item` does not need an `id` field because SwiftData provides a
     `persistentIdentifier` to each model.
 
+See the [documentation][sq-defining-schema] from StructuredQueries for more information on how
+to define your schema.
+
+[sq-defining-schema]: https://swiftpackageindex.com/pointfreeco/swift-structured-queries/main/documentation/structuredqueriescore/definingyourschema
+
 ### Setting up external storage
 
 Both SharingGRDB and SwiftData require some work to be done at the entry point of the app in order
diff --git a/Sources/SharingGRDBCore/Documentation.docc/Articles/MigrationGuides/MigratingTo0.2.md b/Sources/SharingGRDBCore/Documentation.docc/Articles/MigrationGuides/MigratingTo0.2.md
@@ -9,13 +9,62 @@ simplify the library, and make it more powerful. As such, we often need to depre
 in favor of newer ones. We recommend people update their code as quickly as possible to the newest
 APIs, and these guides contain tips to do so.
 
-> Important: Before following any particular migration guide be sure you have followed all the 
-> preceding migration guides.
-
-* [FetchAll, FetchOne, Fetch](#)
+* [@FetchAll, @FetchOne, @Fetch](#)
 * [fetchAll, fetchOne, fetch: soft-deprecated](#)
 * [Avoiding the cost of macros](#)
 
-<!--
-todo: finish
--->
+## @FetchAll, @FetchOne, @Fetch
+
+SharingGRDB 0.2.0 comes with 3 brand new property wrappers that largely replace the need for 
+SwiftData and its `@Query` macro. In 0.1.0, one would perform queries as either a hard coded SQL
+string:
+
+```swift
+@SharedReader(.fetchAll("SELECT * FROM reminders WHERE isCompleted ORDER BY title"))
+var completedReminders: [Reminder]
+```
+
+Or by defining a ``FetchKeyRequest`` conformance to perform a query using GRDB's query builder:
+
+```swift
+struct CompletedReminders: FetchKeyRequest {
+  func fetch(_ db: Database) throws -> [Reminder] {
+    Reminder.all()
+      .where(Column("isCompleted"))
+      .order(Column("title"))
+  }
+}
+
+@SharedReader(.fetch(CompletedReminders()))
+var completedReminders
+```
+
+Each of these are cumbersome, and version 0.2.0 of SharingGRDB fixes it thanks to our newly 
+released [StructuredQueries][] library. You can now describe the query for your data in a type-safe
+manner, and directly inline:
+
+```swift
+@FetchAll(Reminde.where(\.isCompleted).order(by: \.title))
+var completedReminders: [Reminder]
+```
+
+Read <doc:Fetching> for more information on how to use these new property wrappers.
+
+[StructuredQueries]: http://github.com/pointfreeco/swift-structured-queries
+
+## fetchAll, fetchOne, fetch: soft-deprecated
+
+The [`.fetchAll`](<doc:Sharing/SharedReaderKey/fetchAll(sql:arguments:database:)>),
+[`.fetchOne`](<doc:Sharing/SharedReaderKey/fetchOne(sql:arguments:database:)>),
+and [`.fetch`](<doc:Sharing/SharedReaderKey/fetch(_:database:)>) APIs have been soft-deprecated
+in favor of the more modern tools described above and in <doc:Fetching>. They will be hard 
+deprecated in a future release of SharingGRDB, and removed in 1.0.
+
+## Avoiding the cost of macros
+
+SharingGRDB introduces a macro in version 0.2.0 (in particular, the `@Table` macro), and 
+unfortunately macros currently come with an unfortunate cost in that you have to compile SwiftSyntax
+from scratch, which can take time. If the cost of macros is too high for you, then you can depend 
+on the SharingGRDBCore module instead of the full SharingGRDB module. This will give you access to 
+only a subset of tools provided by SharingGRDB, but you will have access to all tools that were
+available in version 0.1.0 of the library.
diff --git a/Sources/SharingGRDBCore/Documentation.docc/SharingGRDBCore.md b/Sources/SharingGRDBCore/Documentation.docc/SharingGRDBCore.md
@@ -105,7 +105,7 @@ in SwiftData:
 > Note: For more information on preparing a SQLite database, see <doc:PreparingDatabase>.
 
 This `defaultDatabase` connection is used implicitly by SharingGRDB's strategies, like 
-[`@FetchAll`](<doc:SharingGRDBCore/FetchAll):
+[`@FetchAll`](<doc:SharingGRDBCore/FetchAll>):
 
 ```swift
 @FetchAll var items: [Item]
diff --git a/Sources/SharingGRDBCore/FetchKey.swift b/Sources/SharingGRDBCore/FetchKey.swift
@@ -43,7 +43,7 @@ extension SharedReaderKey {
   /// - Parameters:
   ///   - request: A request describing the data to fetch.
   ///   - database: The database to read from. A value of `nil` will use
-  ///     `@Dependency(\.defaultDatabase)``.
+  ///     `@Dependency(\.defaultDatabase)`.
   /// - Returns: A key that can be passed to the `@SharedReader` property wrapper.
   @available(iOS, deprecated: 9999, message: "Use the '@Fetch' property wrapper, instead")
   @available(macOS, deprecated: 9999, message: "Use the '@Fetch' property wrapper, instead")
@@ -70,7 +70,7 @@ extension SharedReaderKey {
   /// - Parameters:
   ///   - request: A request describing the data to fetch.
   ///   - database: The database to read from. A value of `nil` will use
-  ///     `@Dependency(\.defaultDatabase)``.
+  ///     `@Dependency(\.defaultDatabase)`.
   /// - Returns: A key that can be passed to the `@SharedReader` property wrapper.
   @available(iOS, deprecated: 9999, message: "Use the '@Fetch' property wrapper, instead")
   @available(macOS, deprecated: 9999, message: "Use the '@Fetch' property wrapper, instead")
@@ -99,7 +99,7 @@ extension SharedReaderKey {
   ///   - sql: A raw SQL string describing the data to fetch.
   ///   - arguments: Arguments to bind to the SQL statement.
   ///   - database: The database to read from. A value of `nil` will use
-  ///     `@Dependency(\.defaultDatabase)``.
+  ///     `@Dependency(\.defaultDatabase)`.
   /// - Returns: A key that can be passed to the `@SharedReader` property wrapper.
   @available(iOS, deprecated: 9999, message: "Use '@FetchAll' and '#sql', instead")
   @available(macOS, deprecated: 9999, message: "Use '@FetchAll' and '#sql', instead")
@@ -132,7 +132,7 @@ extension SharedReaderKey {
   ///   - sql: A raw SQL string describing the data to fetch.
   ///   - arguments: Arguments to bind to the SQL statement.
   ///   - database: The database to read from. A value of `nil` will use
-  ///     `@Dependency(\.defaultDatabase)``.
+  ///     `@Dependency(\.defaultDatabase)`.
   /// - Returns: A key that can be passed to the `@SharedReader` property wrapper.
   @available(iOS, deprecated: 9999, message: "Use '@FetchOne' and '#sql', instead")
   @available(macOS, deprecated: 9999, message: "Use '@FetchOne' and '#sql', instead")
@@ -158,7 +158,7 @@ extension SharedReaderKey {
   /// - Parameters:
   ///   - request: A request describing the data to fetch.
   ///   - database: The database to read from. A value of `nil` will use
-  ///     `@Dependency(\.defaultDatabase)``.
+  ///     `@Dependency(\.defaultDatabase)`.
   ///   - scheduler: The scheduler to observe from. By default, database observation is performed
   ///     asynchronously on the main queue.
   /// - Returns: A key that can be passed to the `@SharedReader` property wrapper.
@@ -184,7 +184,7 @@ extension SharedReaderKey {
   /// - Parameters:
   ///   - request: A request describing the data to fetch.
   ///   - database: The database to read from. A value of `nil` will use
-  ///     `@Dependency(\.defaultDatabase)``.
+  ///     `@Dependency(\.defaultDatabase)`.
   ///   - scheduler: The scheduler to observe from. By default, database observation is performed
   ///     asynchronously on the main queue.
   /// - Returns: A key that can be passed to the `@SharedReader` property wrapper.
@@ -211,7 +211,7 @@ extension SharedReaderKey {
   ///   - sql: A raw SQL string describing the data to fetch.
   ///   - arguments: Arguments to bind to the SQL statement.
   ///   - database: The database to read from. A value of `nil` will use
-  ///     `@Dependency(\.defaultDatabase)``.
+  ///     `@Dependency(\.defaultDatabase)`.
   ///   - scheduler: The scheduler to observe from. By default, database observation is performed
   ///     asynchronously on the main queue.
   /// - Returns: A key that can be passed to the `@SharedReader` property wrapper.
@@ -244,7 +244,7 @@ extension SharedReaderKey {
   ///   - sql: A raw SQL string describing the data to fetch.
   ///   - arguments: Arguments to bind to the SQL statement.
   ///   - database: The database to read from. A value of `nil` will use
-  ///     `@Dependency(\.defaultDatabase)``.
+  ///     `@Dependency(\.defaultDatabase)`.
   ///   - scheduler: The scheduler to observe from. By default, database observation is performed
   ///     asynchronously on the main queue.
   /// - Returns: A key that can be passed to the `@SharedReader` property wrapper.
