diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index eab1679cb..708ea423b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -28,7 +28,7 @@ How you can Contribute - `GRDB`: GRDB sources - `Tests`: GRDB tests - `GRDBCustom.xcodeproj`: the project which builds GRDB with a custom SQLite build. - - `GRDBProfiling.xcodeproj`: a project which helps profiling GRDB with Instruments. No code here is really precious. + - `GRDBProfiling.xcodeproj`: a project which helps profile GRDB with Instruments. No code here is really precious. - `GRDBDemoiOS.xcodeproj`, `GRDBCombineDemo.xcodeproj`, `GRDBAsyncDemo.xcodeproj`: the demo apps. To work with `GRDBCustom.xcodeproj`: @@ -71,11 +71,11 @@ How you can Contribute Please keep the reference and the guides up-to-date. To control the quality of your DocC reference documentation, close the workspace, open `Package.swift` in Xcode, and use Product > Build Documentation. - GRDB is "documentation-driven", which means that nothing ships until it is supported by documentation that makes sense. Documentation makes sense when someone who is not you is able to figure out what is the purpose of your contribution, how to use it, and what are its eventual caveats and corner cases. When the documentation is hard to write, or reveals too many caveats, it is the sign that the api needs to be fixed. + GRDB is "documentation-driven", which means that nothing ships until it is supported by documentation that makes sense. Documentation makes sense when someone who is not you is able to figure out what the purpose of your contribution is, how to use it, and what its caveats and corner cases are. When the documentation is hard to write, or reveals too many caveats, it is a sign that the api needs to be fixed. 8. **Open a pull request with your changes (targeting the `development` branch)!** -9. **If you are granted a push access to the repository**, check [ReleaseProcess.md](Documentation/ReleaseProcess.md) in order to publish a new GRDB version. +9. **If you are granted push access to the repository**, check [ReleaseProcess.md](Documentation/ReleaseProcess.md) in order to publish a new GRDB version. ## Answer issues and contribute to discussions @@ -85,7 +85,7 @@ Answering [issues](https://github.com/groue/GRDB.swift/issues), participating in ## Financial support and sponsoring -GRDB is free, and openly developed by its contributors, on their free time, according to their will, needs, and availability. It is not controlled by any company. +GRDB is free, and openly developed by its contributors, in their free time, according to their will, needs, and availability. It is not controlled by any company. Support is free as well, as long as it happens publicly, and is available to everyone as well as internet search engines. This excludes the private channels of social networks, closed environments such as Slack, etc. diff --git a/Documentation/AssociationsBasics.md b/Documentation/AssociationsBasics.md index 9b73837a0..e8199fca3 100644 --- a/Documentation/AssociationsBasics.md +++ b/Documentation/AssociationsBasics.md @@ -141,7 +141,7 @@ let request = Book.including(optional: Book.author) let bookInfos = BookInfo.fetchAll(db, request) ``` -Before we dive in, please remember that associations can not generate all possible SQL queries that involve several tables. You may also *prefer* writing SQL, and this is just OK, because your SQL skills are welcome. The [`splittingRowAdapters(columnCounts:)`](https://swiftpackageindex.com/groue/GRDB.swift/documentation/grdb/splittingrowadapters(columncounts:)) method can help you consume the rows fetched from joined queries, as in `SELECT book.*, author.* FROM ...`. +Before we dive in, please remember that associations cannot generate all possible SQL queries that involve several tables. You may also *prefer* writing SQL, and this is just fine, because your SQL skills are welcome. The [`splittingRowAdapters(columnCounts:)`](https://swiftpackageindex.com/groue/GRDB.swift/documentation/grdb/splittingrowadapters(columncounts:)) method can help you consume the rows fetched from joined queries, as in `SELECT book.*, author.* FROM ...`. ## Required Protocols @@ -211,7 +211,7 @@ GRDB handles several types of associations: - **HasOneThrough** - **Associations to common table expressions** -An association generally declares a link from a record type to another, as in "one book **belongs to** its author". It instructs GRDB to use the foreign keys declared in the database as support for Swift methods. +An association generally declares a link from one record type to another, as in "one book **belongs to** its author". It instructs GRDB to use the foreign keys declared in the database as support for Swift methods. Each one of these associations is appropriate for a particular database situation. @@ -243,7 +243,7 @@ struct Author: TableRecord { } ``` -The **BelongsTo** association between a book and its author needs that the database table for books has a column that points to the table for authors: +The **BelongsTo** association between a book and its author requires that the database table for books has a column that points to the table for authors: ![BelongsToSchema](https://cdn.rawgit.com/groue/GRDB.swift/master/Documentation/Images/Associations2/BelongsToSchema.svg) @@ -266,7 +266,7 @@ struct Book: TableRecord { } ``` -The **HasMany** association between an author and its books needs that the database table for books has a column that points to the table for authors: +The **HasMany** association between an author and its books requires that the database table for books has a column that points to the table for authors: ![HasManySchema](https://cdn.rawgit.com/groue/GRDB.swift/master/Documentation/Images/Associations2/HasManySchema.svg) @@ -290,7 +290,7 @@ struct Demographics: TableRecord { } ``` -The **HasOne** association between a country and its demographics needs that the database table for demographics has a column that points to the table for countries: +The **HasOne** association between a country and its demographics requires that the database table for demographics has a column that points to the table for countries: ![HasOneSchema](https://cdn.rawgit.com/groue/GRDB.swift/master/Documentation/Images/Associations2/HasOneSchema.svg) @@ -468,7 +468,7 @@ Associations and the Database Schema **Associations are grounded in the database schema, the way database tables are defined.** -For example, a **[BelongsTo]** association between a book and its author needs that the database table for books has a column that points to the table for authors. +For example, a **[BelongsTo]** association between a book and its author requires that the database table for books has a column that points to the table for authors. GRDB also comes with several *conventions* for defining your database schema. @@ -507,7 +507,7 @@ GRDB will automatically **pluralize** or **singularize** names in order to help For example, the Book and Author records will automatically feed properties named `books`, `author`, or `bookCount` in your decoded records, without any explicit configuration, as long as the names of the backing database tables are "book" and "author". -The GRDB pluralization mechanisms are very powerful, being capable of pluralizing and singularizing both regular and irregular words (it's directly inspired from the battle-tested [Ruby on Rails inflections](https://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-pluralize)). +The GRDB pluralization mechanisms are very powerful, being capable of pluralizing and singularizing both regular and irregular words (it's directly inspired by the battle-tested [Ruby on Rails inflections](https://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-pluralize)). When using class names composed of two or more words, the table name should use the camelCase singular form: @@ -711,9 +711,9 @@ struct Author: TableRecord { > **Note**: Generally speaking, all foreign keys are supported, including composite keys that span several columns. > -> **Warning**: SQLite voids foreign key constraints when one or more of a foreign key column is NULL (see [SQLite Foreign Key Support](https://www.sqlite.org/foreignkeys.html)). GRDB does not match foreign keys that involve a NULL value either. +> **Warning**: SQLite voids foreign key constraints when one or more foreign key columns are NULL (see [SQLite Foreign Key Support](https://www.sqlite.org/foreignkeys.html)). GRDB does not match foreign keys that involve a NULL value either. -Sometimes the database schema does not define any foreign key. And sometimes, there are *several* foreign keys from a table to another. +Sometimes the database schema does not define any foreign key. And sometimes, there are *several* foreign keys from one table to another. ![AmbiguousForeignKeys](https://cdn.rawgit.com/groue/GRDB.swift/master/Documentation/Images/Associations2/AmbiguousForeignKeys.svg) @@ -1207,14 +1207,14 @@ let request = Book.joining(optional: Book.author) This method accepts any association. It has the base record "joined" with one associated record, which is not included in the fetched results. The associated record can be missing: it is "optional". -This method has no observable effect unless the associated record is used in a way or another. We'll see examples later in this documentation. +This method has no observable effect unless the associated record is used in one way or another. We'll see examples later in this documentation. ### Choosing a Joining Method Given the Shape of the Decoded Type In the description of the [joining methods] above, we have seen that you need to define dedicated record types in order to prefetch associated records. Each joining method needs a dedicated record type that has a specific shape. -In this chapter, we take the reversed perspective. We list various shapes of decoded record types. When you find the type you want, you'll know the joining method you need. +In this chapter, we take the reverse perspective. We list various shapes of decoded record types. When you find the type you want, you'll know the joining method you need. > **Note**: If you don't find the type you want, chances are that you are fighting the framework, and should reconsider your position. Your escape hatch is the low-level APIs described in [Decoding a Joined Request with FetchableRecord]. @@ -1383,7 +1383,7 @@ let bookInfos: [BookInfo] = try BookInfo.fetchAll(db, request) The request above fetches all books, along with their author and optional translator. -You can chain associations in order to jump from a record to another: +You can chain associations in order to jump from one record to another: ```swift // SELECT book.*, person.*, country.* @@ -1441,7 +1441,7 @@ struct BookInfo: FetchableRecord, Decodable { let bookInfos: [BookInfo] = try BookInfo.fetchAll(db, request) ``` -> **Warning**: you can not currently chain a required association behind an optional association: +> **Warning**: you cannot currently chain a required association behind an optional association: > > ```swift > // Not implemented @@ -1496,7 +1496,7 @@ let authorInfos: [AuthorInfo] = try AuthorInfo.fetchAll(db, request) **There are more filtering options:** - Filtering on conditions that involve several tables. -- Filtering in the WHERE clause instead of the ON clause (can be useful when you are skilled enough in SQL to make the difference). +- Filtering in the WHERE clause instead of the ON clause (can be useful when you are skilled enough in SQL to tell the difference). Those extra filtering options require **[Table Aliases]**, introduced below. @@ -1779,7 +1779,7 @@ let request = Book When executed, we'll get a DatabaseError of code 1, "no such column: book.deathDate". -That is because the "deathDate" column has been used for filtering books, when it is defined on the person database table. +That is because the "deathDate" column has been used for filtering books, whereas it is defined on the person database table. To fix this error, we need a **table alias**: @@ -2124,7 +2124,7 @@ let request = Book .including(optional: Person.country)) ``` -This requests for all books, with their cover images, and their authors and translators. Those people are themselves decorated with their respective nationalities. +This requests all books, with their cover images, and their authors and translators. Those people are themselves decorated with their respective nationalities. We plan to decode this request into the following nested record: @@ -2143,7 +2143,7 @@ struct BookInfo: FetchableRecord, Decodable { This request needs a little preparation: we need **association keys** that match the **coding keys** for the authorInfo and translatorInfo properties. -And who is the most able to know those coding keys? BookInfo itself, thanks to its `CodingKeys` enum that was automatically generated by the Swift compiler. We thus define the `BookInfo.all()` method that builds our request: +And who is best able to know those coding keys? BookInfo itself, thanks to its `CodingKeys` enum that was automatically generated by the Swift compiler. We thus define the `BookInfo.all()` method that builds our request: ```swift extension BookInfo { @@ -2168,7 +2168,7 @@ let bookInfos = try BookInfo.all().fetchAll(db, request) // [BookInfo] ## Decoding a Joined Request with FetchableRecord -When [Decodable](#decoding-a-joined-request-with-a-decodable-record) records provide convenient decoding of joined rows, you may want a little more control over row decoding. +While [Decodable](#decoding-a-joined-request-with-a-decodable-record) records provide convenient decoding of joined rows, you may want a little more control over row decoding. The `init(row:)` initializer of the [FetchableRecord] protocol is what you look for: @@ -2250,7 +2250,7 @@ print(rows[0].debugDescription) // + prizes: 3 rows ``` -Watch in the row debugging description: +In the row debugging description, watch for: - the **association keys**: "author", "country", "coverImage" and "prizes" in our example - associated rows that contain only null values ("coverImage", above). diff --git a/Documentation/Combine.md b/Documentation/Combine.md index af1f70bee..4f2496a5f 100644 --- a/Documentation/Combine.md +++ b/Documentation/Combine.md @@ -188,7 +188,7 @@ let newPlayerCount = dbQueue.writePublisher { db -> Int in } ``` -The difference is that the last fetches are performed in the `thenRead` function. This function accepts two arguments: a readonly database connection, and the result of the `updates` function. This allows you to pass information from a function to the other (it is ignored in the sample code above). +The difference is that the last fetches are performed in the `thenRead` function. This function accepts two arguments: a readonly database connection, and the result of the `updates` function. This allows you to pass information from one function to the other (it is ignored in the sample code above). When you use a [database pool], this method applies a scheduling optimization: the `thenRead` function sees the database in the state left by the `updates` function, and yet does not block any concurrent writes. This can reduce database write contention. diff --git a/Documentation/CommonTableExpressions.md b/Documentation/CommonTableExpressions.md index a5c3030bf..72dedb2e9 100644 --- a/Documentation/CommonTableExpressions.md +++ b/Documentation/CommonTableExpressions.md @@ -128,7 +128,7 @@ let request = Player > **Note**: the `with(_:)` method can be called as many times as there are common table expressions in your request. > -> **Note**: the `with(_:)` method can be called at any time, as all request methods: `Player.with(...).filter(...).with(...)`. +> **Note**: the `with(_:)` method can be called at any time, like all request methods: `Player.with(...).filter(...).with(...)`. > > **Note**: the `with(_:)` method replaces any previously embedded CTE that has the same table name. This allows you to embed the same CTE several times if you feel like it. > @@ -270,7 +270,7 @@ LeftRecord ### CTE Association Example: a Chat App -As an example, let's build the classical main screen of a chat application: a list of all latest messages from all conversations. +As an example, let's build the classic main screen of a chat application: a list of all latest messages from all conversations. The database schema of the chat app contains a `chat` and a `message` table. The application defines the following records: diff --git a/Documentation/CustomSQLiteBuilds.md b/Documentation/CustomSQLiteBuilds.md index 5ffc98047..8e838851d 100644 --- a/Documentation/CustomSQLiteBuilds.md +++ b/Documentation/CustomSQLiteBuilds.md @@ -109,7 +109,7 @@ GRDB builds SQLite with [swiftlyfalling/SQLiteLib](https://github.com/swiftlyfal echo "Finished syncing" ``` - Modify the top of `GRDBCustomSQLite-INSTALL.sh` file so that it contains correct paths. + Modify the top of the `GRDBCustomSQLite-INSTALL.sh` file so that it contains correct paths. 5. Embed the `GRDBCustom.xcodeproj` project in your own project. diff --git a/Documentation/FTS5Tokenizers.md b/Documentation/FTS5Tokenizers.md index cd7fa9e7d..0906ab626 100644 --- a/Documentation/FTS5Tokenizers.md +++ b/Documentation/FTS5Tokenizers.md @@ -175,14 +175,14 @@ This method's arguments are: - `iStart`: Byte offset of token within input text - `iEnd`: Byte offset of end of token within input text -Since tokenization is hard, and pointers to byte buffers uneasy to deal with, you may enjoy the [FTS5WrapperTokenizer](#fts5wrappertokenizer) protocol. +Since tokenization is hard, and pointers to byte buffers difficult to deal with, you may enjoy the [FTS5WrapperTokenizer](#fts5wrappertokenizer) protocol. ## FTS5WrapperTokenizer **FTS5WrapperTokenizer** is the high-level protocol for your custom tokenizers. It provides a default implementation for the low-level `tokenize(context:tokenization:pText:nText:tokenCallback:)` method, so that the adopting type does not have to deal with raw byte buffers of the raw [FTS5 C API](https://www.sqlite.org/fts5.html#custom_tokenizers). -An FTS5WrapperTokenizer lets the hard tokenization job to another tokenizer, the "wrapped tokenizer", and post-processes the tokens produced by this wrapped tokenizer. +An FTS5WrapperTokenizer leaves the hard tokenization job to another tokenizer, the "wrapped tokenizer", and post-processes the tokens produced by this wrapped tokenizer. ```swift protocol FTS5WrapperTokenizer : FTS5CustomTokenizer { @@ -195,7 +195,7 @@ protocol FTS5WrapperTokenizer : FTS5CustomTokenizer { } ``` -As all custom tokenizers, wrapper tokenizers must have a name: +Like all custom tokenizers, wrapper tokenizers must have a name: ```swift final class MyTokenizer : FTS5WrapperTokenizer { @@ -236,7 +236,7 @@ final class MyTokenizer : FTS5WrapperTokenizer { The token argument is a token produced by the wrapped tokenizer, ready to be ignored, modified, or multiplied into several [synonyms](#example-synonyms). -The tokenization parameter tells the reason why tokens are produced, if FTS5 is tokenizing a document, or a search pattern. Some tokenizers may produce different tokens depending on this parameter. +The tokenization parameter tells the reason why tokens are produced: whether FTS5 is tokenizing a document, or a search pattern. Some tokenizers may produce different tokens depending on this parameter. Finally, the tokenCallback is a function you call to output a custom token. @@ -300,9 +300,9 @@ try db.create(virtualTable: "documents", using: FTS5()) { t in The topic of synonyms is documented at https://www.sqlite.org/fts5.html#synonym_support, which describes several methods. You should carefully read this documentation, and pick the method you prefer. -In the example below, we'll pick method (3), and implement a tokenizer that adds multiple synonyms for a single term to the FTS index. Using this method, when tokenizing document text, the tokenizer provides multiple synonyms for each token. So that when a document such as "I won first place" is tokenized, entries are added to the FTS index for "i", "won", "first", "1st" and "place". +In the example below, we'll pick method (3), and implement a tokenizer that adds multiple synonyms for a single term to the FTS index. Using this method, when tokenizing document text, the tokenizer provides multiple synonyms for each token. So when a document such as "I won first place" is tokenized, entries are added to the FTS index for "i", "won", "first", "1st" and "place". -We'll also take care of the SQLite advice: +We'll also follow the SQLite advice: > When using methods (2) or (3), it is important that the tokenizer only provide synonyms when tokenizing document text or query text, not both. Doing so will not cause any errors, but is inefficient. @@ -350,11 +350,11 @@ Languages that use the [latin script](https://en.wikipedia.org/wiki/Latin_script Full-text search in such a corpus often needs input tolerance, so that "encyclopaedia" can match "Encyclopædia", "Grossmann", "Großmann", and "Jerome", "Jérôme". -German has something specific in that both "Mueller" and "Muller" should match "Müller", when "Bauer" should not match "Baur" (only "ü" accepts both "u" and "ue"). A pull request that adds a chapter about German will be welcome. +German has something specific in that both "Mueller" and "Muller" should match "Müller", while "Bauer" should not match "Baur" (only "ü" accepts both "u" and "ue"). A pull request that adds a chapter about German will be welcome. A custom FTS5 tokenizer lets you provide fuzzy latin matching: after "Grossmann", "Großmann", and "GROSSMANN" have all been turned into "grossmann", they will all match together. -We'll wrap the built-in [unicode61](https://www.sqlite.org/fts5.html#unicode61_tokenizer) tokenizer (the one that knows how to split text on spaces and punctuations), and transform its tokens into their bare lowercase ascii form. +We'll wrap the built-in [unicode61](https://www.sqlite.org/fts5.html#unicode61_tokenizer) tokenizer (the one that knows how to split text on spaces and punctuation), and transform its tokens into their bare lowercase ascii form. The tokenizer wrapping is provided by the [FTS5WrapperTokenizer](#fts5wrappertokenizer) protocol. The string transformation is provided by the [String.applyingTransform](https://developer.apple.com/reference/swift/string/1643133-applyingtransform) method: diff --git a/Documentation/FullTextSearch.md b/Documentation/FullTextSearch.md index 96cb169d7..f2532ee4d 100644 --- a/Documentation/FullTextSearch.md +++ b/Documentation/FullTextSearch.md @@ -78,7 +78,7 @@ Generally speaking, FTS5 is better than FTS4 which improves on FTS3. But this do For a full feature list, read the SQLite documentation. Some missing features can be achieved with extra application code. -- **The speed versus disk space constraints.** Roughly speaking, FTS4 and FTS5 are faster than FTS3, but use more space. FTS4 only supports content compression. +- **The speed versus disk space constraints.** Roughly speaking, FTS4 and FTS5 are faster than FTS3, but use more space. Only FTS4 supports content compression. - **The location of the indexed text in your database schema.** Only FTS4 and FTS5 support "contentless" and "external content" tables. @@ -592,7 +592,7 @@ GRDB does not provide any ranking for FTS3 and FTS4. See SQLite's [Search Applic **An external content table does not store the indexed text.** Instead, it indexes the text stored in another table. -This is very handy when you want to index a table that can not be declared as a full-text table (because it contains non-textual values, for example). You just have to define an external content full-text table that refers to the regular table. +This is very handy when you want to index a table that cannot be declared as a full-text table (because it contains non-textual values, for example). You just have to define an external content full-text table that refers to the regular table. The two tables must be kept up-to-date, so that the full-text index matches the content of the regular table. This synchronization happens automatically if you use the `synchronize(withTable:)` method in your full-text table definition: diff --git a/Documentation/GRDB5MigrationGuide.md b/Documentation/GRDB5MigrationGuide.md index e40b7a826..59c7ea6f2 100644 --- a/Documentation/GRDB5MigrationGuide.md +++ b/Documentation/GRDB5MigrationGuide.md @@ -63,9 +63,9 @@ let dbQueue = try DatabaseQueue(dbPath, configuration: config) ## ValueObservation -[ValueObservation] is the database observation tool that tracks changes in database values. It has quite changed in GRDB 5. +[ValueObservation] is the database observation tool that tracks changes in database values. It has changed quite a bit in GRDB 5. -Those changes have the vanilla GRDB, its [Combine publishers], and [RxGRDB] offer a common API, and a common behavior. This greatly helps choose or switch your preferred database observation technique. In previous versions of GRDB, the three companion libraries used to have subtle differences that were just opportunities for bugs. +Those changes make the vanilla GRDB, its [Combine publishers], and [RxGRDB] offer a common API, and a common behavior. This greatly helps choose or switch your preferred database observation technique. In previous versions of GRDB, the three companion libraries used to have subtle differences that were just opportunities for bugs. In the end, this migration step might require some work. But it's for the benefit of all! @@ -111,7 +111,7 @@ let observation = ValueObservation.tracking(someFetchFunction) let observation = ValueObservation.tracking { db in ... } ``` -Finally, ValueObservation used to let application define custom "reducers" based on a protocol named ValueReducer, which was removed in GRDB 5. See the [#731](https://github.com/groue/GRDB.swift/pull/731) conversation for a solution towards a replacement. +Finally, ValueObservation used to let applications define custom "reducers" based on a protocol named ValueReducer, which was removed in GRDB 5. See the [#731](https://github.com/groue/GRDB.swift/pull/731) conversation for a solution towards a replacement.
RxGRDB impact @@ -181,13 +181,13 @@ let cancellable = observation.start( **The behavior of ValueObservation has changed**. -The changes can quite impact your application. We'll describe them below, as well as the strategies to restore the previous behavior when needed. +The changes can have quite an impact on your application. We'll describe them below, as well as the strategies to restore the previous behavior when needed. 1. ValueObservation used to notify its initial value *immediately* when the observation starts. Now, it notifies fresh values on the main thread, *asynchronously*, by default. This means that the parts of your application that rely on this immediate value to, say, set up their user interface, have to be modified. Otherwise, they may suffer from a brief flash of missing data, during the short amount of time between the beginning of the observation, and the asynchronous delivery of the initial value. - To be granted with an immediate, synchronous, delivery of the initial value, insert a `scheduling: .immediate` argument in the `start` method: + To get an immediate, synchronous, delivery of the initial value, insert a `scheduling: .immediate` argument in the `start` method: ```swift let observation = ValueObservation.tracking(Player.fetchAll) @@ -319,7 +319,7 @@ The changes can quite impact your application. We'll describe them below, as wel } ``` - As in previous versions of GRDB, do not use the `combineLatest` operators of Combine or RxSwift in order to combine several ValueObservation. You would lose all guarantees of [data consistency](https://en.wikipedia.org/wiki/Consistency_(database_systems)). + As in previous versions of GRDB, do not use the `combineLatest` operators of Combine or RxSwift in order to combine several ValueObservation instances. You would lose all guarantees of [data consistency](https://en.wikipedia.org/wiki/Consistency_(database_systems)). ## Combine Integration @@ -372,7 +372,7 @@ let publisher = observation > :question: This change avoids conflicts with other libraries that define the same operator. -3. [SQL Interpolation] does no longer wrap subqueries in parentheses: +3. [SQL Interpolation] no longer wraps subqueries in parentheses: ```swift // BEFORE: GRDB 4 @@ -387,7 +387,7 @@ let publisher = observation > :question: This change makes it possible to concatenate subqueries with the UNION operator. -4. In order to extract raw SQL string from an [SQL literal], you now need a database connection: +4. In order to extract the raw SQL string from an [SQL literal], you now need a database connection: ```swift // BEFORE: GRDB 4 @@ -404,7 +404,7 @@ let publisher = observation print(arguments) // prints ["O'Brien", 42] ``` -5. In order to extract raw SQL string from a request ([SQLRequest] or [QueryInterfaceRequest]), you now need to call the `makePreparedRequest()` method: +5. In order to extract the raw SQL string from a request ([SQLRequest] or [QueryInterfaceRequest]), you now need to call the `makePreparedRequest()` method: ```swift // BEFORE: GRDB 4 @@ -460,7 +460,7 @@ let publisher = observation import GRDB ``` -10. Importing the `GRDB` module grants access to the [SQLite C interface](https://www.sqlite.org/c3ref/intro.html). You don't need any longer to import the underlying SQLite library: +10. Importing the `GRDB` module grants access to the [SQLite C interface](https://www.sqlite.org/c3ref/intro.html). You no longer need to import the underlying SQLite library: ```swift // BEFORE: GRDB 4 diff --git a/Documentation/GRDB6MigrationGuide.md b/Documentation/GRDB6MigrationGuide.md index 98769550f..eea4b8ad0 100644 --- a/Documentation/GRDB6MigrationGuide.md +++ b/Documentation/GRDB6MigrationGuide.md @@ -154,7 +154,7 @@ The record protocols have been refactored. We tried to keep the amount of modifi } ``` - If you subclass the `Record` class, you have to call `super` at some point of your implementation: + If you subclass the `Record` class, you have to call `super` at some point in your implementation: ```diff class Player: Record { @@ -242,7 +242,7 @@ The record protocols have been refactored. We tried to keep the amount of modifi try link.upsert(db) // Calls the willSave callback ``` - If you subclass the `Record` class, you have to call `super` at some point of your implementation: + If you subclass the `Record` class, you have to call `super` at some point in your implementation: ```swift // GRDB 6 diff --git a/Documentation/GRDB7MigrationGuide.md b/Documentation/GRDB7MigrationGuide.md index c01f5465a..664d94b02 100644 --- a/Documentation/GRDB7MigrationGuide.md +++ b/Documentation/GRDB7MigrationGuide.md @@ -160,9 +160,9 @@ You can still specify a transaction kind explicitly when necessary. See [Transac ## ValueObservation and the Main Actor -In GRDB 7, `ValueObservation` fosters the main actor, because it is frequently used to automatically update database values on screen. +In GRDB 7, `ValueObservation` favors the main actor, because it is frequently used to automatically update database values on screen. -By default, its [`start`](https://swiftpackageindex.com/groue/GRDB.swift/documentation/grdb/valueobservation/start(in:scheduling:onerror:onchange:)) method must be started on the main actor, and its notification callbacks run on the main actor as well. +By default, its [`start`](https://swiftpackageindex.com/groue/GRDB.swift/documentation/grdb/valueobservation/start(in:scheduling:onerror:onchange:)) method must be called on the main actor, and its notification callbacks run on the main actor as well. It is not necessary to call `MainActor.assumeIsolated` in `ValueObservation` callbacks: diff --git a/Documentation/QueryInterfaceOrganization.md b/Documentation/QueryInterfaceOrganization.md index 41d41cc68..01b20bb10 100644 --- a/Documentation/QueryInterfaceOrganization.md +++ b/Documentation/QueryInterfaceOrganization.md @@ -3,7 +3,7 @@ Query Interface Organization **The [query interface] is a Swift API that approximates the [SQLite SELECT query grammar](https://sqlite.org/lang_select.html) through a hierarchy of values and protocols.** -This document exposes its inner organization, so that you can leverage the most of those types and protocols when you want it. +This document describes its inner organization, so that you can make the most of those types and protocols when you want it. In the diagram below, protocols are pale blue and have rounded corners, and standard types are grey rectangles. Solid arrows read "inherits from", and dashed arrows read "produces". Generic types are marked as such, as well as "PATs" (protocols with associated types). diff --git a/Documentation/SQLInterpolation.md b/Documentation/SQLInterpolation.md index b38e47352..fcf242333 100644 --- a/Documentation/SQLInterpolation.md +++ b/Documentation/SQLInterpolation.md @@ -84,7 +84,7 @@ try dbQueue.write { db in } ``` -**`SQL` is not a Swift String.** You can not use the `execute(literal:)` method with a String argument: +**`SQL` is not a Swift String.** You cannot use the `execute(literal:)` method with a String argument: ```swift try dbQueue.write { db in @@ -131,7 +131,7 @@ let query = SQL( arguments: [name, id]) ``` -`SQL` can embed any [value], as we have seen above, but not only. Please keep on reading the next chapter, or jump directly to the [SQL Interpolation Reference]. +`SQL` can embed any [value], as we have seen above, and more. Please keep on reading the next chapter, or jump directly to the [SQL Interpolation Reference]. ## SQL Interpolation and the Query Interface @@ -357,7 +357,7 @@ Let's extend Player with database methods. } ``` - This last request shows how to build an SQLRequest from an [SQL Literal]. You will need `SQL` when the request can not be written in a single stroke. + This last request shows how to build an SQLRequest from an [SQL Literal]. You will need `SQL` when the request cannot be written in a single stroke. diff --git a/Documentation/WhyAdoptGRDB.md b/Documentation/WhyAdoptGRDB.md index 9d2a961f9..6098839a6 100644 --- a/Documentation/WhyAdoptGRDB.md +++ b/Documentation/WhyAdoptGRDB.md @@ -1,9 +1,9 @@ Why Adopt GRDB? =============== -This document aims at exposing why GRDB could become your favorite database library. +This document aims at explaining why GRDB could become your favorite database library. -We'll start with a few [core principles](#core-principles), so that you see where this library aims at. Then we'll see how GRDB [solves problems](#solving-problems) that developers often face when they use database libraries such as FMDB, FCModel, SQLite.swift, Core Data, or Realm. +We'll start with a few [core principles](#core-principles), so that you see what this library aims at. Then we'll see how GRDB [solves problems](#solving-problems) that developers often face when they use database libraries such as FMDB, FCModel, SQLite.swift, Core Data, or Realm. ## Core Principles @@ -24,7 +24,7 @@ Complex database queries sometimes need to be prototyped and debugged in an SQL ### The database file is the single source of truth. -Each Core Data's managed object context has its own version of the database. This can be useful when developing a macOS application full of inspector panels and nested undo stacks. But that's about it. +Each Core Data managed object context has its own version of the database. This can be useful when developing a macOS application full of inspector panels and nested undo stacks. But that's about it. In the same vein, each application thread has its own version of a Realm database, with non trivial synchronization points. @@ -39,9 +39,9 @@ This means that dealing with servers, MySQL, or PostgreSQL is out of scope. GRDB Focusing on SQLite and applications has allowed GRDB to build features usually only found in company-sponsored libraries: migrations, record comparison, database observation, multi-threading safety, table view animations, support for reactive streams... -The bet of GRDB is that developers can take great profit from a library that provides efficient and community-tested solutions to existing problems. For example, one can not address the multithreading difficulties of Core Data or Realm without looking at database concurrency and records straight in the face. +The bet of GRDB is that developers can greatly benefit from a library that provides efficient and community-tested solutions to existing problems. For example, one cannot address the multithreading difficulties of Core Data or Realm without looking at database concurrency and records straight in the face. -Since you don't have to take my words for granted, we'll now see how GRDB actually solves common problems that developers face with other database libraries. +Since you don't have to take my word for it, we'll now see how GRDB actually solves common problems that developers face with other database libraries. ## Solving Problems @@ -88,14 +88,14 @@ try place.delete(db) For your convenience, those record protocols can be derived from the [Decodable and Encodable](https://developer.apple.com/documentation/foundation/archives_and_serialization/encoding_and_decoding_custom_types) protocols of the standard library. [Codable records] are even given free support for JSON columns and other niceties. -Being a protocol-oriented library that welcomes immutable types, GRDB records are unlike records in other ORM libraries. Particularly, records do not auto-update, and records are not uniqued. We'll see below that the lack of those features can be replaced with **database change notifications**, with many advantages. +Being a protocol-oriented library that welcomes immutable types, GRDB records are unlike records in other ORM libraries. In particular, records do not auto-update, and records are not uniqued. We'll see below that the lack of those features can be replaced with **database change notifications**, with many advantages. See [Recommended Practices for Designing Record Types](https://swiftpackageindex.com/groue/GRDB.swift/documentation/grdb/recordrecommendedpractices) for some practical advice. ### Allow database records to cross threads -As soon as records are immutable values, they can safely be used from different threads. You no longer have to pass object ids or references between threads, as in Core Data or Realm: +Since records are immutable values, they can safely be used from different threads. You no longer have to pass object ids or references between threads, as in Core Data or Realm: ```swift if let player = try Player.fetchOne(db, key: 1) { @@ -184,7 +184,7 @@ The more threats are handled by the application, the more skilled and careful a I had to omit [Realm] and [FCModel] from the list, because I don't know them well enough. Yet I'd bet that Realm shares some behaviors with Core Data, and FCModel shares some behaviors with FMDatabaseQueue. -We can see that the threat of conflicts is *always* left to the application. Core Data provides conflict policies, but no one can pretend that they are easy to plan, use, or test. This is an argument for leaving the application 100% responsible for conflict handling, in hope that simple ones can be handled in a simple way. +We can see that the threat of conflicts is *always* left to the application. Core Data provides conflict policies, but no one can claim that they are easy to plan, use, or test. This is an argument for leaving the application 100% responsible for conflict handling, in the hope that simple ones can be handled in a simple way. Finally, raw FMDatabase, SQLite.swift, and Core Data are the hardest tools, and you'd better be a very skilled developer in order to use them properly. @@ -254,7 +254,7 @@ extension Player { let player = try Player.filter(name: "Arthur O'Brien").fetchOne(db) ``` -Custom SQL requests as the one above are welcome in database observation tools like the built-in [ValueObservation] and its [Combine](Combine.md) and [RxSwift](https://github.com/RxSwiftCommunity/RxGRDB) flavors: +Custom SQL requests such as the one above are welcome in database observation tools like the built-in [ValueObservation] and its [Combine](Combine.md) and [RxSwift](https://github.com/RxSwiftCommunity/RxGRDB) flavors: ```swift let playerObservation = ValueObservation.tracking { db in diff --git a/GRDB/Core/Configuration.swift b/GRDB/Core/Configuration.swift index cc05616f9..fe55d75c1 100644 --- a/GRDB/Core/Configuration.swift +++ b/GRDB/Core/Configuration.swift @@ -245,7 +245,7 @@ public struct Configuration: Sendable { // MARK: - Transactions /// A boolean value indicating whether it is valid to leave a transaction - /// opened at the end of a database access method. + /// open at the end of a database access method. /// /// The default value is false: not completing a transaction is a /// programmer error: @@ -277,7 +277,7 @@ public struct Configuration: Sendable { /// ``` /// /// This configuration flag has no effect on ``DatabasePool`` reader - /// connections: those never allow leaving a transaction opened at the end + /// connections: those never allow leaving a transaction open at the end /// of a read access. public var allowsUnsafeTransactions = false @@ -336,7 +336,7 @@ public struct Configuration: Sendable { /// The maximum number of concurrent reader connections. /// - /// This configuration has effect on ``DatabasePool`` and + /// This configuration has an effect on ``DatabasePool`` and /// ``DatabaseSnapshotPool`` only. The default value is 5. /// /// You can query this value at runtime in order to get the actual capacity @@ -416,7 +416,7 @@ public struct Configuration: Sendable { /// default value is false. /// /// When the flag is false, a `DatabasePool` closes read-only - /// connections when requested to dispose non-essential memory with + /// connections when requested to dispose of non-essential memory with /// ``DatabasePool/releaseMemory()``. When true, those connections are /// kept open. /// diff --git a/GRDB/Core/Cursor.swift b/GRDB/Core/Cursor.swift index 91fddc5b6..427afd2f8 100644 --- a/GRDB/Core/Cursor.swift +++ b/GRDB/Core/Cursor.swift @@ -41,7 +41,7 @@ extension RangeReplaceableCollection { /// Adds the elements of a cursor to the end of this collection. /// - /// In case of error, an unspecified amount of elements have been added to + /// In case of error, an unspecified number of elements have been added to /// the collection. /// /// - parameter newElements: The elements to append to the collection. @@ -279,7 +279,7 @@ extension Sequence { /// /// - Cursor types are classes, and have a lifetime. /// - Cursor iteration may throw errors. -/// - A cursor can not be repeated. +/// - A cursor cannot be repeated. /// /// The protocol comes with default implementations for many operations similar /// to those defined by Swift's Sequence protocol: `contains`, `dropFirst`, diff --git a/GRDB/Core/Database+SQLCipher.swift b/GRDB/Core/Database+SQLCipher.swift index c528020b3..d2d047138 100644 --- a/GRDB/Core/Database+SQLCipher.swift +++ b/GRDB/Core/Database+SQLCipher.swift @@ -87,7 +87,7 @@ extension Database { get throws { try String.fetchOne(self, sql: "PRAGMA cipher_provider_version") } } - /// Sets the passphrase used to crypt and decrypt an SQLCipher database. + /// Sets the passphrase used to encrypt and decrypt an SQLCipher database. /// /// Call this method from `Configuration.prepareDatabase`, /// as in the example below: @@ -106,7 +106,7 @@ extension Database { try usePassphrase(data) } - /// Sets the passphrase used to crypt and decrypt an SQLCipher database. + /// Sets the passphrase used to encrypt and decrypt an SQLCipher database. /// /// Call this method from `Configuration.prepareDatabase`, /// as in the example below: @@ -181,7 +181,7 @@ extension Database { /// Instructs SQLCipher to log internal debugging and operational information. /// - /// The supplied `logLevel` determines the granularity of the logs output. + /// The supplied `logLevel` determines the granularity of the log output. /// /// See /// - Parameter logLevel: The granularity to use for the logging system - defaults to `DEBUG`. diff --git a/GRDB/Core/Database+Schema.swift b/GRDB/Core/Database+Schema.swift index 54d632a42..1c59abece 100644 --- a/GRDB/Core/Database+Schema.swift +++ b/GRDB/Core/Database+Schema.swift @@ -531,7 +531,7 @@ extension Database { /// Nil is returned if the view does not exist, or if `columns` is empty. /// /// - precondition: If the view exists, columns must exist, must - /// identify a unique row, and must be not null. + /// identify a unique row, and must not be null. func fetchPrimitivePrimaryKey( forView view: DatabaseObjectID, columns: [String] @@ -1028,7 +1028,7 @@ extension Database { /// Fetches the columns in the database table identified by `table`, or /// returns nil if the database schema does not contain that table. /// - /// This method relies entirely on SQLite schema introspection. Starting + /// This method relies entirely on SQLite schema introspection. Starting with /// SQLite 3.26.0, it returns all columns, including /// [generated columns](https://www.sqlite.org/gencol.html) and /// [hidden columns](https://www.sqlite.org/vtab.html#hiddencol). @@ -1098,7 +1098,7 @@ extension Database { /// the case of input columns. /// /// This method accepts both tables and views. For views, the primary - /// key returned by the schemaSource is considered as a unique key. + /// key returned by the schemaSource is considered a unique key. func columnsForUniqueKey( _ columns: some Collection, in tableName: String @@ -1332,7 +1332,7 @@ public struct ColumnInfo: FetchableRecord, Sendable { /// When nil, the column has no default value. /// /// When not nil, it contains an SQL string that defines an expression. That - /// expression may be a literal, as `1`, or `'foo'`. It may also contain a + /// expression may be a literal, such as `1`, or `'foo'`. It may also contain a /// non-constant expression such as `CURRENT_TIMESTAMP`. /// /// Related SQLite documentation: . diff --git a/GRDB/Core/Database+Statements.swift b/GRDB/Core/Database+Statements.swift index ba34ed7c7..508a6f280 100644 --- a/GRDB/Core/Database+Statements.swift +++ b/GRDB/Core/Database+Statements.swift @@ -51,8 +51,8 @@ extension Database { /// try statement.execute(arguments: ["Barbara"]) /// ``` /// - /// In the provided literal, no argument must be set, or all arguments must - /// be set. An error is raised otherwise. For example: + /// In the provided literal, either no argument is set, or all arguments + /// are set. An error is raised otherwise. For example: /// /// ```swift /// // OK @@ -166,8 +166,8 @@ extension Database { /// try statement.execute(arguments: ["Barbara"]) /// ``` /// - /// In the provided literal, no argument must be set, or all arguments must - /// be set. An error is raised otherwise. For example: + /// In the provided literal, either no argument is set, or all arguments + /// are set. An error is raised otherwise. For example: /// /// ```swift /// // OK @@ -267,8 +267,8 @@ extension Database { /// } /// ``` /// - /// In the provided literal, no argument must be set, or all arguments must - /// be set. The returned cursor will throw an error otherwise. For example: + /// In the provided literal, either no argument is set, or all arguments + /// are set. The returned cursor will throw an error otherwise. For example: /// /// ```swift /// // OK @@ -472,7 +472,7 @@ extension Database { /// Always throws an error @usableFromInline func statementDidFail(_ statement: Statement, withResultCode resultCode: CInt) throws -> Never { - // Failed statements can not be reused, because `sqlite3_reset` won't + // Failed statements cannot be reused, because `sqlite3_reset` won't // be able to restore the statement to its initial state: // https://www.sqlite.org/c3ref/reset.html // diff --git a/GRDB/Core/Database.swift b/GRDB/Core/Database.swift index f2de73697..ceb3247fb 100644 --- a/GRDB/Core/Database.swift +++ b/GRDB/Core/Database.swift @@ -399,7 +399,7 @@ public final class Database: CustomStringConvertible, CustomDebugStringConvertib var autocommitState = AutocommitState.on /// The date of the current transaction, wrapped in a result that is an - /// error if there was an error grabbing this date when the transaction has + /// error if there was an error grabbing this date when the transaction /// started. /// /// Invariant: `transactionDateResult` is nil iff connection is not @@ -1499,7 +1499,7 @@ public final class Database: CustomStringConvertible, CustomDebugStringConvertib /// /// Related SQLite documentation: /// - /// - warning: This method is not reentrant: you can not nest transactions. + /// - warning: This method is not reentrant: you cannot nest transactions. /// Use ``inSavepoint(_:)`` instead. /// /// - parameters: @@ -1726,11 +1726,11 @@ public final class Database: CustomStringConvertible, CustomDebugStringConvertib public func beginTransaction(_ kind: TransactionKind? = nil) throws { // SQLite throws an error for non-deferred transactions when read-only. // We prefer immediate transactions for writes, so that write - // transactions can not overlap. This reduces the opportunity for + // transactions cannot overlap. This reduces the opportunity for // SQLITE_BUSY, which is immediately thrown whenever a transaction // is upgraded after an initial read and a concurrent processes // has acquired the write lock beforehand. This SQLITE_BUSY error - // can not be avoided with a busy timeout. + // cannot be avoided with a busy timeout. // // See . let kind = kind ?? (isReadOnly ? .deferred : .immediate) diff --git a/GRDB/Core/DatabaseBackupProgress.swift b/GRDB/Core/DatabaseBackupProgress.swift index d7c06a21e..9e8161d58 100644 --- a/GRDB/Core/DatabaseBackupProgress.swift +++ b/GRDB/Core/DatabaseBackupProgress.swift @@ -1,4 +1,4 @@ -/// Describe the progress of a database backup. +/// Describes the progress of a database backup. /// /// Related SQLite documentation: public struct DatabaseBackupProgress: Sendable { diff --git a/GRDB/Core/DatabasePool.swift b/GRDB/Core/DatabasePool.swift index 1b0c50f28..6e4924959 100644 --- a/GRDB/Core/DatabasePool.swift +++ b/GRDB/Core/DatabasePool.swift @@ -149,7 +149,7 @@ extension DatabasePool { // MARK: - Memory management - /// Frees as much memory as possible, by disposing non-essential memory. + /// Frees as much memory as possible, by disposing of non-essential memory. /// /// This method is synchronous, and blocks the current thread until all /// database accesses are completed. @@ -185,7 +185,7 @@ extension DatabasePool { } } - /// Eventually frees as much memory as possible, by disposing + /// Eventually frees as much memory as possible, by disposing of /// non-essential memory. /// /// This method eventually closes all read-only connections, unless the @@ -898,11 +898,11 @@ extension DatabasePool { // MARK: - Snapshots - /// Creates a database snapshot that serializes accesses to an unchanging + /// Creates a database snapshot that serializes accesses to unchanging /// database content, as it exists at the moment the snapshot is created. /// /// It is a programmer error to create a snapshot from the writer dispatch - /// queue when a transaction is opened: + /// queue when a transaction is open: /// /// ```swift /// try dbPool.write { db in @@ -951,7 +951,7 @@ extension DatabasePool { } #if SQLITE_ENABLE_SNAPSHOT && !SQLITE_DISABLE_SNAPSHOT - /// Creates a database snapshot that allows concurrent accesses to an + /// Creates a database snapshot that allows concurrent accesses to /// unchanging database content, as it exists at the moment the snapshot /// is created. /// diff --git a/GRDB/Core/DatabaseReader.swift b/GRDB/Core/DatabaseReader.swift index 7461790a9..ca19e42cd 100644 --- a/GRDB/Core/DatabaseReader.swift +++ b/GRDB/Core/DatabaseReader.swift @@ -79,7 +79,7 @@ public protocol DatabaseReader: AnyObject, Sendable { /// throws a ``DatabaseError`` of code `SQLITE_BUSY`. /// See for more information. /// - /// After an error has been thrown, the database may still be opened, and + /// After an error has been thrown, the database may still be open, and /// you can keep on accessing it. It may also remain in a "zombie" state, /// in which case it will throw `SQLITE_MISUSE` for all future /// database accesses. @@ -696,7 +696,7 @@ extension AnyDatabaseReader: DatabaseReader { } } -/// A type that sees an unchanging database content. +/// A type that sees unchanging database content. /// /// Do not declare new conformances to `DatabaseSnapshotReader`. Only the /// built-in conforming types are valid. diff --git a/GRDB/Core/DatabaseSchemaSource.swift b/GRDB/Core/DatabaseSchemaSource.swift index 15df0f551..f3586286f 100644 --- a/GRDB/Core/DatabaseSchemaSource.swift +++ b/GRDB/Core/DatabaseSchemaSource.swift @@ -43,7 +43,7 @@ /// } /// ``` /// -/// Take care that **a good migration is a migration that is never +/// Keep in mind that **a good migration is a migration that is never /// modified once it has shipped**: check /// . /// @@ -72,7 +72,7 @@ public protocol DatabaseSchemaSource: Sendable { /// each individual row in the view. /// - No column contains NULL values. /// - /// It is a programmer error with undefined consequences to miss + /// It is a programmer error with undefined consequences to violate /// those requirements. /// /// For example: @@ -91,7 +91,7 @@ public protocol DatabaseSchemaSource: Sendable { /// config.schemaSource = MySchemaSource() /// let dbQueue = try DatabaseQueue(path: "/path/to/db.sqlite", configuration: config) /// - /// // A record type that feeds from a view. + /// // A record type that is decoded from a view. /// struct Player: Decodable, Identifiable, FetchableRecord { /// static let databaseTableName = "playerView" /// var id: String diff --git a/GRDB/Core/DatabaseSnapshot.swift b/GRDB/Core/DatabaseSnapshot.swift index 14429b544..9c2c91874 100644 --- a/GRDB/Core/DatabaseSnapshot.swift +++ b/GRDB/Core/DatabaseSnapshot.swift @@ -1,11 +1,11 @@ import Dispatch -/// A database connection that serializes accesses to an unchanging +/// A database connection that serializes accesses to unchanging /// database content, as it existed at the moment the snapshot was created. /// /// ## Overview /// -/// A `DatabaseSnapshot` never sees any database modification during all its +/// A `DatabaseSnapshot` never sees any database modification during its whole /// lifetime. All database accesses performed from a snapshot always see the /// same identical database content. /// diff --git a/GRDB/Core/DatabaseSnapshotPool.swift b/GRDB/Core/DatabaseSnapshotPool.swift index 17e7a6aec..6d7c8eabc 100644 --- a/GRDB/Core/DatabaseSnapshotPool.swift +++ b/GRDB/Core/DatabaseSnapshotPool.swift @@ -11,14 +11,14 @@ import SQLCipher import GRDBSQLite #endif -/// A database connection that allows concurrent accesses to an unchanging +/// A database connection that allows concurrent accesses to unchanging /// database content, as it existed at the moment the snapshot was created. /// /// ## Overview /// /// - note: [**🔥 EXPERIMENTAL**](https://github.com/groue/GRDB.swift/blob/master/README.md#what-are-experimental-features) /// -/// A `DatabaseSnapshotPool` never sees any database modification during all its +/// A `DatabaseSnapshotPool` never sees any database modification during its whole /// lifetime. All database accesses performed from a snapshot always see the /// same identical database content. /// diff --git a/GRDB/Core/DatabaseValue.swift b/GRDB/Core/DatabaseValue.swift index 14d3b072c..b28f8fced 100644 --- a/GRDB/Core/DatabaseValue.swift +++ b/GRDB/Core/DatabaseValue.swift @@ -261,7 +261,7 @@ extension DatabaseValue.Storage: Equatable { } extension DatabaseValue: Equatable { - /// Returns whether two ``DatabaseValue`` are equal. + /// Returns whether two ``DatabaseValue`` instances are equal. /// /// For example: /// diff --git a/GRDB/Core/DatabaseValueConvertible.swift b/GRDB/Core/DatabaseValueConvertible.swift index abab6fc10..4e4c09a09 100644 --- a/GRDB/Core/DatabaseValueConvertible.swift +++ b/GRDB/Core/DatabaseValueConvertible.swift @@ -64,13 +64,13 @@ public protocol DatabaseValueConvertible: SQLExpressible, StatementBinding { /// Returns the `JSONDecoder` that decodes the value. /// - /// This method is dedicated to ``DatabaseValueConvertible`` types that + /// This method is intended for ``DatabaseValueConvertible`` types that /// also conform to the standard `Decodable` protocol. static func databaseJSONDecoder() -> JSONDecoder /// Returns the `JSONEncoder` that encodes the value. /// - /// This method is dedicated to ``DatabaseValueConvertible`` types that + /// This method is intended for ``DatabaseValueConvertible`` types that /// also conform to the standard `Encodable` protocol. static func databaseJSONEncoder() -> JSONEncoder } diff --git a/GRDB/Core/DatabaseWriter.swift b/GRDB/Core/DatabaseWriter.swift index 26c99e6db..3b2bcbdba 100644 --- a/GRDB/Core/DatabaseWriter.swift +++ b/GRDB/Core/DatabaseWriter.swift @@ -394,7 +394,7 @@ extension DatabaseWriter { /// Database operations are wrapped in a transaction. If they throw an /// error, the transaction is rolled back and the error is rethrown. /// - /// Concurrent database accesses can not see partial database updates (even + /// Concurrent database accesses cannot see partial database updates (even /// when performed by other processes). /// /// Database operations run in the writer dispatch queue, serialized @@ -449,7 +449,7 @@ extension DatabaseWriter { /// the result of the transaction. This result is a failure if the /// transaction could not be committed or if `updates` has thrown an error. /// - /// Concurrent database accesses can not see partial database updates + /// Concurrent database accesses cannot see partial database updates /// performed by `updates` (even when performed by other processes). /// /// Database operations run in the writer dispatch queue, serialized @@ -626,7 +626,7 @@ extension DatabaseWriter { /// Database operations are wrapped in a transaction. If they throw an /// error, the transaction is rolled back and the error is rethrown. /// - /// Concurrent database accesses can not see partial database updates (even + /// Concurrent database accesses cannot see partial database updates (even /// when performed by other processes). /// /// Database operations run in the writer dispatch queue, serialized @@ -719,7 +719,7 @@ extension DatabaseWriter { /// error, the transaction is rolled back and the error completes /// the publisher. /// - /// Concurrent database accesses can not see partial database updates (even + /// Concurrent database accesses cannot see partial database updates (even /// when performed by other processes). /// /// Database operations are asynchronously dispatched in the writer dispatch @@ -777,7 +777,7 @@ extension DatabaseWriter { /// The difference is that the last fetches are performed in the `thenRead` /// closure. This closure accepts two arguments: a read-only database /// connection, and the result of the `updates` function. This allows you to - /// pass information from a function to the other (it is ignored in the + /// pass information from one function to the other (it is ignored in the /// sample code above). /// /// When you use a ``DatabasePool``, this method applies a scheduling diff --git a/GRDB/Core/FetchRequest.swift b/GRDB/Core/FetchRequest.swift index c64406e09..afacd85af 100644 --- a/GRDB/Core/FetchRequest.swift +++ b/GRDB/Core/FetchRequest.swift @@ -97,7 +97,7 @@ public protocol FetchRequest: SQLSubqueryable, DatabaseRegionConvert } extension FetchRequest { - /// Returns the database region that the request feeds from. + /// Returns the database region that the request looks into. /// /// - parameter db: A database connection. public func databaseRegion(_ db: Database) throws -> DatabaseRegion { diff --git a/GRDB/Core/Row.swift b/GRDB/Core/Row.swift index 9b03aca52..483b3d2ee 100644 --- a/GRDB/Core/Row.swift +++ b/GRDB/Core/Row.swift @@ -627,7 +627,7 @@ extension Row { /// the same name, the leftmost column is considered. /// /// If the row does not contain any column with that name, or if the SQLite - /// value is `NULL`, the data is nil. If the SQLite value can not be + /// value is `NULL`, the data is nil. If the SQLite value cannot be /// converted to `Data`, an error is thrown. /// /// - warning: The `Data` argument to the body must not be stored or used @@ -645,7 +645,7 @@ extension Row { /// the same name, the leftmost column is considered. /// /// If the row does not contain any column with that name, or if the SQLite - /// value is `NULL`, the data is nil. If the SQLite value can not be + /// value is `NULL`, the data is nil. If the SQLite value cannot be /// converted to `Data`, an error is thrown. /// /// - warning: The `Data` argument to the body must not be stored or used @@ -675,7 +675,7 @@ extension Row { /// the same name, the leftmost column is considered. /// /// If the column is missing or if the SQLite value is NULL, the result is - /// nil. If the SQLite value can not be converted to Data, a fatal error + /// nil. If the SQLite value cannot be converted to Data, a fatal error /// is raised. /// /// The returned data does not own its bytes: it must not be used longer @@ -694,7 +694,7 @@ extension Row { /// the same name, the leftmost column is considered. /// /// If the column is missing or if the SQLite value is NULL, the result is - /// nil. If the SQLite value can not be converted to Data, a fatal error + /// nil. If the SQLite value cannot be converted to Data, a fatal error /// is raised. /// /// The returned data does not own its bytes: it must not be used longer @@ -769,7 +769,7 @@ extension Row { // MARK: - Extracting Records - /// Returns the record associated to the given key. + /// Returns the record associated with the given key. /// /// The key is a row scope that was either defined manually, with /// ``ScopeAdapter``, or with the ``JoinableRequest/including(required:)`` @@ -815,7 +815,7 @@ extension Row { try! decode(Record.self, forKey: scope) } - /// Returns the record associated to the given key, if any. + /// Returns the record associated with the given key, if any. /// /// The key is a row scope that was either defined manually, with /// ``ScopeAdapter``, or with the ``JoinableRequest/including(required:)`` @@ -861,7 +861,7 @@ extension Row { try! decodeIfPresent(Record.self, forKey: scope) } - /// Returns a collection of prefetched records associated to the given + /// Returns a collection of prefetched records associated with the given /// association key. /// /// Prefetched rows are defined by the ``JoinableRequest/including(all:)`` @@ -895,7 +895,7 @@ extension Row { try! decode(Records.self, forKey: key) } - /// Returns the set of prefetched records associated to the given + /// Returns the set of prefetched records associated with the given /// association key. /// /// Prefetched rows are defined by the ``JoinableRequest/including(all:)`` @@ -931,7 +931,7 @@ extension Row { /// A view on the scopes defined by row adapters. /// - /// The returned object provides an access to all available scopes in + /// The returned object provides access to all available scopes in /// the row. /// /// Row scopes can be defined manually, with ``ScopeAdapter``. @@ -978,7 +978,7 @@ extension Row { /// A view on the scopes tree defined by row adapters. /// - /// The returned object provides an access to all available scopes in + /// The returned object provides access to all available scopes in /// the row, recursively. For any given scope identifier, a breadth-first /// search is performed. /// @@ -1393,7 +1393,7 @@ extension Row { // MARK: - Throwing Record Decoding Methods extension Row { - /// Returns the record associated to the given key, if any. + /// Returns the record associated with the given key, if any. /// /// The key is a row scope that was either defined manually, with /// ``ScopeAdapter``, or with the ``JoinableRequest/including(required:)`` @@ -1448,7 +1448,7 @@ extension Row { return try Record(row: scopedRow) } - /// Returns the record associated to the given key. + /// Returns the record associated with the given key. /// /// The key is a row scope that was either defined manually, with /// ``ScopeAdapter``, or with the ``JoinableRequest/including(required:)`` @@ -1531,7 +1531,7 @@ extension Row { // MARK: - Throwing Record RangeReplaceableCollection and Set Methods extension Row { - /// Returns a collection of prefetched records associated to the given + /// Returns a collection of prefetched records associated with the given /// association key. /// /// Prefetched rows are defined by the ``JoinableRequest/including(all:)`` @@ -1597,7 +1597,7 @@ extension Row { return collection } - /// Returns the set of prefetched records associated to the given + /// Returns the set of prefetched records associated with the given /// association key. /// /// Prefetched rows are defined by the ``JoinableRequest/including(all:)`` diff --git a/GRDB/Core/SQLRequest.swift b/GRDB/Core/SQLRequest.swift index 6ec272c57..26d734e2e 100644 --- a/GRDB/Core/SQLRequest.swift +++ b/GRDB/Core/SQLRequest.swift @@ -48,7 +48,7 @@ public struct SQLRequest { /// There are two statement caches: one "public" for statements generated by /// the user, and one "internal" for the statements generated by GRDB. Those /// are separated so that GRDB has no opportunity to inadvertently modify - /// the arguments of user's cached statements. + /// the arguments of the user's cached statements. enum Cache { /// The public cache, for library user case `public` diff --git a/GRDB/Core/Statement.swift b/GRDB/Core/Statement.swift index d0df60e3d..cc56556fc 100644 --- a/GRDB/Core/Statement.swift +++ b/GRDB/Core/Statement.swift @@ -24,7 +24,7 @@ extension String { /// SQL statements with `String.trimmedSQLStatement`. private static let sqlStatementSeparators = CharacterSet(charactersIn: ";").union(.whitespacesAndNewlines) - /// Returns a string trimmed from SQL statement separators. + /// Returns a string trimmed of SQL statement separators. /// /// For example: /// @@ -476,7 +476,7 @@ public final class Statement { } /// Convenience method that resets, sets arguments if needed, and checks - /// arguments validity. + /// argument validity. /// /// - parameter newArguments: if not nil, this method sets arguments. func prepareExecution(withArguments newArguments: StatementArguments? = nil) throws { @@ -551,7 +551,7 @@ public final class Statement { /// `arguments` parameter, it is assumed that the statement won't be /// reused with the same arguments. When the number of arguments is /// small, execution is performed with temporary SQLite bindings that - /// avoid copying strings and blobs arguments. + /// avoid copying string and blob arguments. /// /// For more information, see [`SQLITE_STATIC` and `SQLITE_TRANSIENT`](https://www.sqlite.org/c3ref/c_static.html). /// Compare: @@ -931,7 +931,7 @@ func withBindings( /// /// ## Positional Arguments /// -/// To fill question marks placeholders, feed `StatementArguments` with an array: +/// To fill question mark placeholders, feed `StatementArguments` with an array: /// /// ```swift /// try db.execute( @@ -983,7 +983,7 @@ func withBindings( /// arguments += ["name": "Barbara"] /// ``` /// -/// On the other side, `&+` and ``StatementArguments/append(contentsOf:)`` +/// On the other hand, `&+` and ``StatementArguments/append(contentsOf:)`` /// allow overriding named arguments: /// /// ```swift @@ -1008,7 +1008,7 @@ func withBindings( /// print(row) /// ``` /// -/// Mixed arguments exist as a support for requests like the following: +/// Mixed arguments exist to support requests like the following: /// /// ```swift /// let players = try Player diff --git a/GRDB/Core/TransactionObserver.swift b/GRDB/Core/TransactionObserver.swift index f9efb4a6b..9372a04f7 100644 --- a/GRDB/Core/TransactionObserver.swift +++ b/GRDB/Core/TransactionObserver.swift @@ -174,7 +174,7 @@ extension Database { /// func databaseDidRollback(_ db: Database) /// } /// -/// First observer is added, and a transaction is started. At this point, +/// First, an observer is added, and a transaction is started. At this point, /// there's not much to say: /// /// let observer = MyObserver() @@ -187,7 +187,7 @@ extension Database { /// try db.execute(sql: "INSERT INTO document ...") /// /// The observation process starts when the statement is *compiled*: -/// sqlite3_set_authorizer tells that the statement performs insertion into the +/// sqlite3_set_authorizer reports that the statement performs insertion into the /// `document` table. Generally speaking, statements may have many effects, by /// means of foreign key actions and SQL triggers. SQLite takes care of /// exposing all those effects to sqlite3_set_authorizer. @@ -196,7 +196,7 @@ extension Database { /// observer.observes(eventsOfKind:) method. If it returns true, the observer is /// *activated*. /// -/// During the statement *execution*, SQLite tells that a row has been inserted +/// During the statement *execution*, SQLite reports that a row has been inserted /// through sqlite3_update_hook: the broker calls the observer.databaseDidChange(with:) /// method, if and only if the observer has been activated at the previous step. /// @@ -204,7 +204,7 @@ extension Database { /// /// try db.execute(sql: "SAVEPOINT foo") /// -/// Statement compilation has sqlite3_set_authorizer tell that this statement +/// Statement compilation has sqlite3_set_authorizer report that this statement /// begins a "foo" savepoint. /// /// After the statement *has been executed*, the broker knows that the SQLite @@ -215,7 +215,7 @@ extension Database { /// /// try db.execute(sql: "INSERT INTO document ...") /// -/// This time, when the statement is *executed* and SQLite tells that a row has +/// This time, when the statement is *executed* and SQLite reports that a row has /// been inserted, the broker buffers the change event instead of immediately /// notifying the activated observers. That is because the savepoint can be /// rolled back, and GRDB guarantees observers that they are only notified of @@ -225,12 +225,12 @@ extension Database { /// /// try db.execute(sql: "RELEASE SAVEPOINT foo") /// -/// Statement compilation has sqlite3_set_authorizer tell that this statement +/// Statement compilation has sqlite3_set_authorizer report that this statement /// releases the "foo" savepoint. /// /// After the statement *has been executed*, the broker knows that the SQLite /// [savepoint stack](https://www.sqlite.org/lang_savepoint.html) is now empty, -/// and notifies the buffered changes to activated observers. +/// and notifies activated observers of the buffered changes. /// /// Finally the transaction is committed: /// @@ -329,7 +329,7 @@ class DatabaseObservationBroker { func statementWillExecute(_ statement: Statement) { if !database.isReadOnly && !transactionObservations.isEmpty { // As statement executes, it may trigger database changes that will - // be notified to transaction observers. As a consequence, observers + // be reported to transaction observers. As a consequence, observers // may disable themselves with stopObservingDatabaseChangesUntilNextTransaction() // // This method takes no argument, and requires access to the "current @@ -739,13 +739,13 @@ class DatabaseObservationBroker { /// Transaction state is unchanged. case none - /// Transaction turns committed. + /// Transaction is committed. case commit - /// Transaction turns rolled back. + /// Transaction is rolled back. case rollback - /// Transaction turns rolled back because a transaction observer has + /// Transaction is rolled back because a transaction observer has /// cancelled a commit by throwing an error. case cancelledCommit(Error) } @@ -753,7 +753,7 @@ class DatabaseObservationBroker { // MARK: - DatabaseEventObservationStrategy -/// Controls which database changes are notified to a `TransactionObserver`. +/// Controls which database changes are reported to a `TransactionObserver`. public struct DatabaseEventObservationStrategy: Sendable { /// A boolean value indicating whether a ``TransactionObserver`` focuses /// on database changes filtered by its @@ -784,7 +784,7 @@ public struct DatabaseEventObservationStrategy: Sendable { public protocol TransactionObserver: AnyObject { - /// Controls which database changes should be notified to the observer. + /// Controls which database changes should be reported to the observer. /// /// The default value is ``DatabaseEventObservationStrategy/default``, /// which only detects changes performed by `DELETE`, `INSERT` and @@ -1053,7 +1053,7 @@ final class TransactionObservation { case 1: // We'll execute a simple statement without any side effect. // All database events will thus have the same kind. All - // database events can be notified to interested observations. + // database events can be reported to interested observations. // // For example, if one observes all deletions in the table T, then // all individual deletions of DELETE FROM T are notified: diff --git a/GRDB/Documentation.docc/Concurrency.md b/GRDB/Documentation.docc/Concurrency.md index 3021c0794..90a8c970e 100644 --- a/GRDB/Documentation.docc/Concurrency.md +++ b/GRDB/Documentation.docc/Concurrency.md @@ -31,7 +31,7 @@ Open one single ``DatabaseQueue`` or ``DatabasePool`` per database file, for the Database operations that are grouped in a transaction are guaranteed to be either fully saved on disk, or not at all. Read-only transactions guarantee a stable and immutable view of the database, and do not see changes performed by concurrent writes. -In other words, transactions are the one and single tool that helps you enforce and rely on the invariants of your database (such as "all authors must have at least one book"). +In other words, transactions are the one and only tool that helps you enforce and rely on the invariants of your database (such as "all authors must have at least one book"). **You are responsible**, in your Swift code, for delimiting transactions. You do so by grouping database accesses inside a pair of `{ db in ... }` brackets: @@ -47,7 +47,7 @@ try dbQueue.read { db in Alternatively, you can open an explicit transaction or savepoint: see . -- *Why does this rule exist?* - Because GRDB and SQLite can not guess where to insert the transaction boundaries that protect the invariants of your database. This is your task. Transactions also avoid concurrency problems, as described in the section below. +- *Why does this rule exist?* - Because GRDB and SQLite cannot guess where to insert the transaction boundaries that protect the invariants of your database. This is your task. Transactions also avoid concurrency problems, as described in the section below. - *Practical advice* - Take the time to identify the invariants of your database. Some of them can be enforced in the database schema itself, such as "all books must have a non-empty title", or "all books must have an author" (see ). Some invariants can only be enforced by transactions, such as "all account credits must have a matching debit", or "all authors must have at least one book". @@ -162,7 +162,7 @@ This guarantee prevents [`SQLITE_BUSY`] errors during concurrent writes. **All writes are wrapped in a transaction.** -Concurrent reads can not see partial database updates (even reads performed by other processes). +Concurrent reads cannot see partial database updates (even reads performed by other processes). #### Isolated Reads @@ -228,7 +228,7 @@ Despite the common guarantees and rules shared by database queues and pools, tho ![DatabasePool Scheduling](DatabasePoolScheduling.png) -See how, with database pools, two reads can see different database states at the same time. This may look scary! Please see the next chapter below for a relief. +See how, with database pools, two reads can see different database states at the same time. This may look scary! Please see the next chapter below for some relief. ## Concurrent Thinking @@ -265,7 +265,7 @@ All you need is a little "concurrent thinking", based on those two basic facts: ## Advanced DatabasePool -``DatabasePool`` is very concurrent, since all reads can run in parallel, and can even run during write operations. But writes are still serialized: at any given point in time, there is no more than a single thread that is writing into the database. +``DatabasePool`` is highly concurrent, since all reads can run in parallel, and can even run during write operations. But writes are still serialized: at any given point in time, there is no more than a single thread that is writing into the database. When your application modifies the database, and then reads some value that depends on those modifications, you may want to avoid blocking concurrent writes longer than necessary - especially when the read is slow: @@ -302,7 +302,7 @@ try dbPool.writeWithoutTransaction { db in } ``` -The ``DatabasePool/asyncConcurrentRead(_:)`` method blocks until it can guarantee its closure argument an isolated access to the database, in the exact state left by the last transaction. It then asynchronously executes the closure. +The ``DatabasePool/asyncConcurrentRead(_:)`` method blocks until it can guarantee its closure argument isolated access to the database, in the exact state left by the last transaction. It then asynchronously executes the closure. In the illustration below, the striped band shows the delay needed for the reading thread to acquire isolation. Until then, no other thread can write: diff --git a/GRDB/Documentation.docc/DatabaseConnections.md b/GRDB/Documentation.docc/DatabaseConnections.md index 588a40fa5..ff210cc39 100644 --- a/GRDB/Documentation.docc/DatabaseConnections.md +++ b/GRDB/Documentation.docc/DatabaseConnections.md @@ -37,17 +37,17 @@ let dbPath = Bundle.main.path(forResource: "db", ofType: "sqlite") if let dbPath { // If the resource exists, open a read-only connection. - // Writes are disallowed because resources can not be modified. + // Writes are disallowed because resources cannot be modified. var config = Configuration() config.readonly = true let dbQueue = try DatabaseQueue(path: dbPath, configuration: config) } else { - // The database resource can not be found. + // The database resource cannot be found. // Fix your setup, or report the problem to the user. } ``` -**If the application creates or writes in the database**, then first choose a proper location for the database file. Document-based applications will let the user pick a location. Apps that use the database as a global storage will prefer the Application Support directory. +**If the application creates or writes in the database**, then first choose a proper location for the database file. Document-based applications will let the user pick a location. Apps that use the database as global storage will prefer the Application Support directory. > Tip: Regardless of the database location, it is recommended that you wrap the database file inside a dedicated directory. This directory will bundle the main database file and its related [SQLite temporary files](https://www.sqlite.org/tempfiles.html) together. > diff --git a/GRDB/Documentation.docc/DatabaseSchemaRecommendations.md b/GRDB/Documentation.docc/DatabaseSchemaRecommendations.md index 5b4aabe2c..5b2fc7461 100644 --- a/GRDB/Documentation.docc/DatabaseSchemaRecommendations.md +++ b/GRDB/Documentation.docc/DatabaseSchemaRecommendations.md @@ -6,7 +6,7 @@ Recommendations for an ideal integration of the database schema with GRDB Even though all schemas are supported, some features of the library and of the Swift language are easier to use when the schema follows a few conventions described below. -When those conventions are not applied, or not applicable, you will have to perform extra configurations. +When those conventions are not applied, or not applicable, you will have to perform extra configuration. For recommendations specific to JSON columns, see . @@ -235,10 +235,10 @@ try db.create( > Tip: SQLite does not support deferred unique indexes, and this creates undesired churn when you need to temporarily break them. This may happen, for example, when you want to reorder player positions in our above example. > -> There exist several workarounds; one of them involves dropping and recreating the unique index after the temporary violations have been fixed. If you plan to use this technique, take care that only actual indexes can be dropped. Unique constraints created inside the table body can not: +> There exist several workarounds; one of them involves dropping and recreating the unique index after the temporary violations have been fixed. If you plan to use this technique, be aware that only actual indexes can be dropped. Unique constraints created inside the table body cannot: > > ```swift -> // Unique constraint on player(name) can not be dropped. +> // Unique constraint on player(name) cannot be dropped. > try db.create(table: "player") { t in > t.column("name", .text).unique() > } @@ -252,7 +252,7 @@ try db.create( > > If you want to turn an undroppable constraint into a droppable index, you'll need to recreate the database table. See for the detailed procedure. -☝️ **If a table misses unique indexes**, some record methods such as ``FetchableRecord/fetchOne(_:key:)-92b9m`` and ``TableRecord/deleteOne(_:key:)-5pdh5`` will raise a fatal error: +☝️ **If a table lacks unique indexes**, some record methods such as ``FetchableRecord/fetchOne(_:key:)-92b9m`` and ``TableRecord/deleteOne(_:key:)-5pdh5`` will raise a fatal error: ```swift try dbQueue.write { db in diff --git a/GRDB/Documentation.docc/DatabaseSharing.md b/GRDB/Documentation.docc/DatabaseSharing.md index 0ae4da462..70b40387d 100644 --- a/GRDB/Documentation.docc/DatabaseSharing.md +++ b/GRDB/Documentation.docc/DatabaseSharing.md @@ -141,7 +141,7 @@ Since several processes may open the database at the same time, protect the crea Read-only connections will fail unless two extra files ending in `-shm` and `-wal` are present next to the database file ([source](https://www.sqlite.org/walformat.html#operations_that_require_locks_and_which_locks_those_operations_use)). Those files are regular companions of databases in the [WAL mode]. But they are deleted, under regular operations, when database connections are closed. Precisely speaking, they *may* be deleted: it depends on the SQLite and the operating system versions ([source](https://github.com/groue/GRDB.swift/issues/739#issuecomment-604363998)). And when they are deleted, read-only connections fail. -The solution is to enable the "persistent WAL mode", as shown in the sample code above, by setting the [SQLITE_FCNTL_PERSIST_WAL](https://www.sqlite.org/c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlpersistwal) flag. This mode makes sure the `-shm` and `-wal` files are never deleted, and guarantees a database access to read-only connections. +The solution is to enable the "persistent WAL mode", as shown in the sample code above, by setting the [SQLITE_FCNTL_PERSIST_WAL](https://www.sqlite.org/c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlpersistwal) flag. This mode makes sure the `-shm` and `-wal` files are never deleted, and guarantees database access to read-only connections. ## How to limit the SQLITE_BUSY error @@ -224,7 +224,7 @@ do { Post ``Database/resumeNotification`` in order to resume suspended databases. You can safely post this notification when the app comes back to foreground. -In applications that use the background modes supported by iOS, post `resumeNotification` from each and every background mode callback that may use the database, and don't forget to post `suspendNotification` again before the app turns suspended. +In applications that use the background modes supported by iOS, post `resumeNotification` from each and every background mode callback that may use the database, and don't forget to post `suspendNotification` again before the app is suspended. ## How to perform cross-process database observation diff --git a/GRDB/Documentation.docc/Extension/DatabaseRegionObservation.md b/GRDB/Documentation.docc/Extension/DatabaseRegionObservation.md index 12f79271b..51da47c63 100644 --- a/GRDB/Documentation.docc/Extension/DatabaseRegionObservation.md +++ b/GRDB/Documentation.docc/Extension/DatabaseRegionObservation.md @@ -29,7 +29,7 @@ let cancellable = observation.start(in: dbQueue) { error in } ``` -Enjoy the changes notifications: +Enjoy the change notifications: ```swift try dbQueue.write { db in diff --git a/GRDB/Documentation.docc/Extension/DatabaseValueConvertible.md b/GRDB/Documentation.docc/Extension/DatabaseValueConvertible.md index 51aa384a6..8c48c04d4 100644 --- a/GRDB/Documentation.docc/Extension/DatabaseValueConvertible.md +++ b/GRDB/Documentation.docc/Extension/DatabaseValueConvertible.md @@ -14,7 +14,7 @@ A `DatabaseValueConvertible` type supports conversion to and from database value To conform to `DatabaseValueConvertible`, implement the two requirements ``fromDatabaseValue(_:)-21zzv`` and ``databaseValue-1ob9k``. Do not customize the ``fromMissingColumn()-7iamp`` requirement. If your type `MyValue` conforms, then the conformance of the optional type `MyValue?` is automatic. -The implementation of `fromDatabaseValue` must return nil if the type can not be decoded from the raw database value. This nil value will have GRDB throw a decoding error accordingly. +The implementation of `fromDatabaseValue` must return nil if the type cannot be decoded from the raw database value. This nil value will have GRDB throw a decoding error accordingly. For example: @@ -59,7 +59,7 @@ extension Grape: DatabaseValueConvertible { } ### Built-in Codable support -`DatabaseValueConvertible` is also ready-made for `Codable` types, which are automatically coded and decoded from JSON arrays and objects: +`DatabaseValueConvertible` is also ready-made for `Codable` types, which are automatically encoded and decoded from JSON arrays and objects: ```swift struct Color: Codable { @@ -91,7 +91,7 @@ protocol DatabaseValueConvertible { import Tagged struct Player: Identifiable { - // Thanks to Tagged, Player.ID can not be confused with Team.ID or + // Thanks to Tagged, Player.ID cannot be confused with Team.ID or // Award.ID, even though they all wrap strings. typealias ID = Tagged var id: ID diff --git a/GRDB/Documentation.docc/Extension/Statement.md b/GRDB/Documentation.docc/Extension/Statement.md index 7c09cf5cc..6e3e6b70f 100644 --- a/GRDB/Documentation.docc/Extension/Statement.md +++ b/GRDB/Documentation.docc/Extension/Statement.md @@ -66,9 +66,9 @@ try insertStatement.execute(arguments: ["name": "Arthur", "score": 1000]) let player = try Player.fetchOne(selectStatement, arguments: ["Arthur"]) ``` -> Note: A prepared statement that has failed with an error can not be recovered. Create a new instance, or use a cached statement as described below. +> Note: A prepared statement that has failed with an error cannot be recovered. Create a new instance, or use a cached statement as described below. -> Tip: When you look for the best performance, take care about a difference between setting the arguments before execution, and setting the arguments at the moment of execution: +> Tip: When you look for the best performance, be aware of a difference between setting the arguments before execution, and setting the arguments at the moment of execution: > > ```swift > // First option @@ -81,8 +81,8 @@ let player = try Player.fetchOne(selectStatement, arguments: ["Arthur"]) > > Both perform exactly the same action, and most applications should not care about the difference. Yet: > -> - ``setArguments(_:)`` performs a copy of string and blob arguments. It uses the low-level [`SQLITE_TRANSIENT`](https://www.sqlite.org/c3ref/c_static.html) option, and fits well the reuse of a given statement with the same arguments. -> - ``execute(arguments:)`` avoids a temporary allocation for string and blob arguments if the number of arguments is small. Instead of `SQLITE_TRANSIENT`, it uses the low-level [`SQLITE_STATIC`](https://www.sqlite.org/c3ref/c_static.html) option. This fits well the reuse of a given statement with various arguments. +> - ``setArguments(_:)`` performs a copy of string and blob arguments. It uses the low-level [`SQLITE_TRANSIENT`](https://www.sqlite.org/c3ref/c_static.html) option, and is well suited to the reuse of a given statement with the same arguments. +> - ``execute(arguments:)`` avoids a temporary allocation for string and blob arguments if the number of arguments is small. Instead of `SQLITE_TRANSIENT`, it uses the low-level [`SQLITE_STATIC`](https://www.sqlite.org/c3ref/c_static.html) option. This is well suited to the reuse of a given statement with various arguments. > > Don't make a blind choice, and monitor your app performance if it really matters! diff --git a/GRDB/Documentation.docc/Extension/TransactionObserver.md b/GRDB/Documentation.docc/Extension/TransactionObserver.md index cab43973d..ccfccaebd 100644 --- a/GRDB/Documentation.docc/Extension/TransactionObserver.md +++ b/GRDB/Documentation.docc/Extension/TransactionObserver.md @@ -21,13 +21,13 @@ By default, the database holds weak references to its transaction observers: the ## Database Changes And Transactions -Database changes are notified to the ``databaseDidChange(with:)`` callback. This includes indirect changes triggered by `ON DELETE` and `ON UPDATE` actions associated to [foreign keys](https://www.sqlite.org/foreignkeys.html#fk_actions), and [SQL triggers](https://www.sqlite.org/lang_createtrigger.html). +Database changes are reported to the ``databaseDidChange(with:)`` callback. This includes indirect changes triggered by `ON DELETE` and `ON UPDATE` actions associated with [foreign keys](https://www.sqlite.org/foreignkeys.html#fk_actions), and [SQL triggers](https://www.sqlite.org/lang_createtrigger.html). -Transaction completions are notified to the ``databaseWillCommit()-7mksu``, ``databaseDidCommit(_:)`` and ``databaseDidRollback(_:)`` callbacks. +Transaction completions are reported to the ``databaseWillCommit()-7mksu``, ``databaseDidCommit(_:)`` and ``databaseDidRollback(_:)`` callbacks. > Important: Some changes and transactions are not automatically notified. See below. -Notified changes are not actually written to disk until the transaction commits, and the `databaseDidCommit` callback is called. On the other side, `databaseDidRollback` confirms their invalidation: +Notified changes are not actually written to disk until the transaction commits, and the `databaseDidCommit` callback is called. On the other hand, `databaseDidRollback` confirms their invalidation: ```swift try dbQueue.write { db in @@ -97,7 +97,7 @@ do { **Transaction observers can choose the database changes they are interested in.** -By default, the ``observes(eventsOfKind:)`` method filters events that are notified to ``databaseDidChange(with:)``. It is the most efficient and recommended change filtering technique, because it is only called once before a database query is executed, and can completely disable change tracking: +By default, the ``observes(eventsOfKind:)`` method filters events that are reported to ``databaseDidChange(with:)``. It is the most efficient and recommended change filtering technique, because it is only called once before a database query is executed, and can completely disable change tracking: ```swift // Calls `observes(eventsOfKind:)` once. @@ -230,7 +230,7 @@ This extra API can be activated in two ways: ## Dealing with Undetected Changes -The changes and transactions that are not automatically notified to transaction observers are: +The changes and transactions that are not automatically reported to transaction observers are: - Read-only transactions. - Changes and transactions performed by external database connections. diff --git a/GRDB/Documentation.docc/Extension/ValueObservation.md b/GRDB/Documentation.docc/Extension/ValueObservation.md index c995bb767..e50fcc5e9 100644 --- a/GRDB/Documentation.docc/Extension/ValueObservation.md +++ b/GRDB/Documentation.docc/Extension/ValueObservation.md @@ -10,7 +10,7 @@ See below for the li ## ValueObservation Usage -1. Make sure that a unique database connection, ``DatabaseQueue`` or ``DatabasePool``, is kept open during the whole duration of the observation. +1. Make sure that a single database connection, ``DatabaseQueue`` or ``DatabasePool``, is kept open during the whole duration of the observation. 2. Create a `ValueObservation` with a closure that fetches the observed value: @@ -90,7 +90,7 @@ Starting an observation retains the database connection, until it is stopped. As The database observation stops when the cancellable returned by the `start` method is cancelled or deallocated, or if an error occurs. -> Important: Take care that there are use cases that `ValueObservation` is unfit for. +> Important: Be aware that there are use cases that `ValueObservation` is unfit for. > > For example, an application may need to process absolutely all changes, and avoid any coalescing. An application may also need to process changes before any further modifications could be performed in the database file. In those cases, the application needs to track *individual transactions*, not values: use ``DatabaseRegionObservation``. > @@ -114,7 +114,7 @@ You can change this behavior by adding a `scheduling` argument to the `start()` For example, the ``ValueObservationMainActorScheduler/immediate`` scheduler notifies all values on the main actor, and notifies the first one immediately when the observation starts. -It is very useful in graphic applications, because you can configure views right away, without waiting for the initial value to be fetched eventually. You don't have to implement any empty or loading screen, or to prevent some undesired initial animation. Take care that the user interface is not responsive during the fetch of the first value, so only use the `immediate` scheduling for very fast database requests! +It is very useful in graphical applications, because you can configure views right away, without waiting for the initial value to be fetched eventually. You don't have to implement any empty or loading screen, or to prevent some undesired initial animation. Be aware that the user interface is not responsive during the fetch of the first value, so only use the `immediate` scheduling for very fast database requests! ```swift // Immediate scheduling notifies @@ -168,7 +168,7 @@ do { ``` -As described above, the `scheduling` argument controls the execution of the change and error callbacks. You also have some control on the execution of the database fetch: +As described above, the `scheduling` argument controls the execution of the change and error callbacks. You also have some control over the execution of the database fetch: - With the `.immediate` scheduling, the initial fetch is always performed synchronously, on the main actor, when the observation starts, so that the initial value can be notified immediately. @@ -183,7 +183,7 @@ As described above, the `scheduling` argument controls the execution of the chan ## ValueObservation Sharing -Sharing a `ValueObservation` spares database resources. When a database change happens, a fresh value is fetched only once, and then notified to all clients of the shared observation. +Sharing a `ValueObservation` saves database resources. When a database change happens, a fresh value is fetched only once, and then delivered to all clients of the shared observation. You build a shared observation with ``shared(in:scheduling:extent:)``: @@ -265,17 +265,17 @@ When needed, you can help GRDB optimize observations and reduce database content > Important: **Keep your number of observations bounded.** > -> In particular, do not observe independently all elements in a list. Instead, observe the whole list in a single observation. +> In particular, do not independently observe all elements in a list. Instead, observe the whole list in a single observation. > Tip: Stop observations when possible. > > For example, if a `UIViewController` needs to display database values, it can start the observation in `viewWillAppear`, and stop it in `viewWillDisappear`. > -> In a SwiftUI application, you can profit from the [GRDBQuery](https://github.com/groue/GRDBQuery) companion library, and its [`View.queryObservation(_:)`](https://swiftpackageindex.com/groue/grdbquery/documentation/grdbquery/queryobservation) method. +> In a SwiftUI application, you can benefit from the [GRDBQuery](https://github.com/groue/GRDBQuery) companion library, and its [`View.queryObservation(_:)`](https://swiftpackageindex.com/groue/grdbquery/documentation/grdbquery/queryobservation) method. > Tip: Share observations when possible. > -> Each call to `ValueObservation.start` method triggers independent values refreshes. When several components of your app are interested in the same value, consider sharing the observation with ``shared(in:scheduling:extent:)``. +> Each call to the `ValueObservation.start` method triggers independent value refreshes. When several components of your app are interested in the same value, consider sharing the observation with ``shared(in:scheduling:extent:)``. > Tip: When the observation processes some raw fetched values, use the ``map(_:)`` operator: > @@ -296,7 +296,7 @@ When needed, you can help GRDB optimize observations and reduce database content > Tip: When the observation tracks a constant database region, create an optimized observation with the ``tracking(regions:fetch:)`` or ``trackingConstantRegion(_:)`` methods. Make sure you read the documentation of those methods, or you might write an observation that misses some database changes. -**Truncating WAL checkpoints impact ValueObservation.** Such checkpoints are performed with ``Database/checkpoint(_:on:)`` or [`PRAGMA wal_checkpoint`](https://www.sqlite.org/pragma.html#pragma_wal_checkpoint). When an observation is started on a ``DatabasePool``, from a database that has a missing or empty [wal file](https://www.sqlite.org/tempfiles.html#write_ahead_log_wal_files), the observation will always notify two values when it starts, even if the database content is not changed. This is a consequence of the impossibility to create the [wal snapshot](https://www.sqlite.org/c3ref/snapshot_get.html) needed for detecting that no changes were performed during the observation startup. If your application performs truncating checkpoints, you will avoid this behavior if you recreate a non-empty wal file before starting observations. To do so, perform any kind of no-op transaction (such as creating and dropping a dummy table). +**Truncating WAL checkpoints impact ValueObservation.** Such checkpoints are performed with ``Database/checkpoint(_:on:)`` or [`PRAGMA wal_checkpoint`](https://www.sqlite.org/pragma.html#pragma_wal_checkpoint). When an observation is started on a ``DatabasePool``, from a database that has a missing or empty [wal file](https://www.sqlite.org/tempfiles.html#write_ahead_log_wal_files), the observation will always notify two values when it starts, even if the database content is not changed. This is a consequence of the impossibility of creating the [wal snapshot](https://www.sqlite.org/c3ref/snapshot_get.html) needed for detecting that no changes were performed during the observation startup. If your application performs truncating checkpoints, you will avoid this behavior if you recreate a non-empty wal file before starting observations. To do so, perform any kind of no-op transaction (such as creating and dropping a dummy table). ## Topics diff --git a/GRDB/Documentation.docc/GRDB.md b/GRDB/Documentation.docc/GRDB.md index e76f56dc1..4cd686869 100644 --- a/GRDB/Documentation.docc/GRDB.md +++ b/GRDB/Documentation.docc/GRDB.md @@ -28,7 +28,7 @@ Use this library to save your application’s permanent data into SQLite databas - **Leverage your SQLite skills** - Not all developers need advanced SQLite features. But when you do, GRDB is as sharp as you want it to be. Come with your SQL and SQLite skills, or learn new ones as you go! + Not all developers need advanced SQLite features. But when you do, GRDB is as sharp as you want it to be. Bring your SQL and SQLite skills, or learn new ones as you go! ## Usage diff --git a/GRDB/Documentation.docc/JSON.md b/GRDB/Documentation.docc/JSON.md index 9b11e9873..9871aa128 100644 --- a/GRDB/Documentation.docc/JSON.md +++ b/GRDB/Documentation.docc/JSON.md @@ -4,7 +4,7 @@ Store and use JSON values in SQLite databases. ## Overview -SQLite and GRDB can store and fetch JSON values in database columns. Starting iOS 16+, macOS 10.15+, tvOS 17+, and watchOS 9+, JSON values can be manipulated at the database level. +SQLite and GRDB can store and fetch JSON values in database columns. Starting with iOS 16, macOS 10.15, tvOS 17, and watchOS 9, JSON values can be manipulated at the database level. ## Store and fetch JSON values @@ -123,11 +123,11 @@ extension Team: FetchableRecord, PersistableRecord { > .fetchAll(db) > ``` > -> Take care that SQLite will compare strings, not JSON objects: white-space and key ordering matter. For this comparison to succeed, make sure that the database contains values that are formatted exactly like a serialized `Address`. +> Be aware that SQLite will compare strings, not JSON objects: white-space and key ordering matter. For this comparison to succeed, make sure that the database contains values that are formatted exactly like a serialized `Address`. ## Manipulate JSON values at the database level -[SQLite JSON functions and operators](https://www.sqlite.org/json1.html) are available starting iOS 16+, macOS 10.15+, tvOS 17+, and watchOS 9+. +[SQLite JSON functions and operators](https://www.sqlite.org/json1.html) are available starting with iOS 16, macOS 10.15, tvOS 17, and watchOS 9. Functions such as `JSON`, `JSON_EXTRACT`, `JSON_PATCH` and others are available as static methods on `Database`: ``Database/json(_:)``, ``Database/jsonExtract(_:atPath:)``, ``Database/jsonPatch(_:with:)``, etc. diff --git a/GRDB/Documentation.docc/Migrations.md b/GRDB/Documentation.docc/Migrations.md index 16dd7b0b9..c32283fc4 100644 --- a/GRDB/Documentation.docc/Migrations.md +++ b/GRDB/Documentation.docc/Migrations.md @@ -78,7 +78,7 @@ try dbQueue.read { db in **Migrations run with deferred foreign key checks.** This means that foreign key violations are only checked at the end of the migration (and they make the migration fail). See below for more information. -**The memory of applied migrations is stored in the database itself** (in a reserved table). +**The record of applied migrations is stored in the database itself** (in a reserved table). ## Defining the Database Schema from a Migration @@ -110,7 +110,7 @@ migrator.registerMigration("Guilds", foreignKeyChecks: .immediate) { db in } ``` -Note: migrations that run with `.immediate` foreign key checks can not be used to recreate database tables, as described below. When needed, define two migrations instead of one. +Note: migrations that run with `.immediate` foreign key checks cannot be used to recreate database tables, as described below. When needed, define two migrations instead of one. #### How to Recreate a Database Table diff --git a/GRDB/Documentation.docc/RecordRecommendedPractices.md b/GRDB/Documentation.docc/RecordRecommendedPractices.md index 71c5f6cb0..154545caa 100644 --- a/GRDB/Documentation.docc/RecordRecommendedPractices.md +++ b/GRDB/Documentation.docc/RecordRecommendedPractices.md @@ -51,7 +51,7 @@ Thanks to this database schema, the application will always process *consistent > Tip: **A local SQLite database is not a JSON payload loaded from a remote server.** > -> The JSON format and content can not be controlled, and an application must defend itself against wacky servers. But a local database is under your full control. It is trustable. A relational database such as SQLite guarantees the quality of users' data, as long as enough energy is put in the proper definition of the database schema. +> The JSON format and content cannot be controlled, and an application must defend itself against wacky servers. But a local database is under your full control. It is trustworthy. A relational database such as SQLite guarantees the quality of users' data, as long as enough energy is put in the proper definition of the database schema. > Tip: **Plan early for future versions of your application**: use . @@ -120,7 +120,7 @@ let books = try dbQueue.read { db in } ``` -> Tip: When a column of a database table can't be NULL, define a non-optional property in the record type. On the other side, when the database may contain NULL, define an optional property. Compare: +> Tip: When a column of a database table can't be NULL, define a non-optional property in the record type. On the other hand, when the database may contain NULL, define an optional property. Compare: > > ```swift > try db.create(table: "author") { t in @@ -138,7 +138,7 @@ let books = try dbQueue.read { db in > > There are exceptions to this rule. > -> For example, the `id` column is never NULL in the database. And yet, `Author` has an optional `id` property. That is because we want to create instances of `Author` before they could be inserted in the database, and be assigned an auto-incremented id. If the `id` property was not optional, the `Author` type could not profit from auto-incremented ids! +> For example, the `id` column is never NULL in the database. And yet, `Author` has an optional `id` property. That is because we want to create instances of `Author` before they could be inserted in the database, and be assigned an auto-incremented id. If the `id` property was not optional, the `Author` type could not benefit from auto-incremented ids! > > Another exception to this rule is described in , where the creation date of a record is never NULL in the database, but optional in the Swift type. @@ -151,7 +151,7 @@ let books = try dbQueue.read { db in > } > ``` > -> Take care that **`Identifiable` is not a good fit for optional ids**. You will frequently meet optional ids for records with auto-incremented ids: +> Be aware that **`Identifiable` is not a good fit for optional ids**. You will frequently meet optional ids for records with auto-incremented ids: > > ```swift > struct Player: Codable { @@ -174,7 +174,7 @@ let books = try dbQueue.read { db in In the previous code samples, the `Book` and `Author` structs have one property per database column, and their types are natively supported by SQLite (`String`, `Int`, etc.) -But it happens that raw database column names, or raw column types, are not a very good fit for the application. +But sometimes raw database column names, or raw column types, are not a very good fit for the application. When this happens, it's time to **distinguish the Swift and database representations**. Record types are the dedicated place where raw database values can be transformed into Swift types that are well-suited for the rest of the application. @@ -256,11 +256,11 @@ Generally speaking, private properties make it possible to hide raw columns from #### Third Example: Money Amounts -Before storing money amounts in an SQLite database, take care that [floating-point numbers are never a good fit](https://stackoverflow.com/questions/3730019/why-not-use-double-or-float-to-represent-currency). +Before storing money amounts in an SQLite database, be aware that [floating-point numbers are never a good fit](https://stackoverflow.com/questions/3730019/why-not-use-double-or-float-to-represent-currency). SQLite only supports two kinds of numbers: integers and doubles, so we'll store amounts as integers. $12.00 will be represented by 1200, a quantity of cents. This allows SQLite to compute exact sums of price, for example. -On the other side, an amount of cents is not very practical for the rest of the Swift application. The [`Decimal`] type looks like a better fit. +On the other hand, an amount of cents is not very practical for the rest of the Swift application. The [`Decimal`] type looks like a better fit. That's why the `Product` record type has a `price: Decimal` property, backed by a `priceCents` integer column: @@ -389,7 +389,7 @@ try dbQueue.read { db in } ``` -Extensions to the `DerivableRequest` protocol can not change the type of requests. They remain requests of the base record. To define requests of another type, use an extension to ``QueryInterfaceRequest``, as in the example below: +Extensions to the `DerivableRequest` protocol cannot change the type of requests. They remain requests of the base record. To define requests of another type, use an extension to ``QueryInterfaceRequest``, as in the example below: ```swift extension QueryInterfaceRequest { @@ -517,7 +517,7 @@ let authorships: [Authorship] = try dbQueue.read { db in In the above code samples, requests that fetch values from several tables are decoded into additional record types: `AuthorInfo`, `LiteraryCareer`, and `Authorship`. -Those record types conform to both [`Decodable`] and ``FetchableRecord``, so that they can feed from database rows. They do not provide any persistence methods, though. **All database writes are performed from persistable record instances** (of type `Author` or `Book`). +Those record types conform to both [`Decodable`] and ``FetchableRecord``, so that they can be decoded from database rows. They do not provide any persistence methods, though. **All database writes are performed from persistable record instances** (of type `Author` or `Book`). For more information about associations, see the [Associations] guide. @@ -536,7 +536,7 @@ author.books.each do |book| # Lazily fetch books on demand end ``` -**GRDB does not perform lazy loading.** In a GUI application, lazy loading can not be achieved without record management (as in [Core Data]), which in turn comes with non-trivial pain points for developers regarding concurrency. Instead of lazy loading, the library provides the tooling needed to fetch data, even complex graphs, in an [isolated] fashion, so that fetched values accurately represent the database content, and all database invariants are preserved. See the guide for more information. +**GRDB does not perform lazy loading.** In a GUI application, lazy loading cannot be achieved without record management (as in [Core Data]), which in turn comes with non-trivial pain points for developers regarding concurrency. Instead of lazy loading, the library provides the tooling needed to fetch data, even complex graphs, in an [isolated] fashion, so that fetched values accurately represent the database content, and all database invariants are preserved. See the guide for more information. Vapor [Fluent] uses **eager loading**, which means that relationships are only fetched if explicitly requested: diff --git a/GRDB/Documentation.docc/RecordTimestamps.md b/GRDB/Documentation.docc/RecordTimestamps.md index 30a19df65..a1947f5fe 100644 --- a/GRDB/Documentation.docc/RecordTimestamps.md +++ b/GRDB/Documentation.docc/RecordTimestamps.md @@ -10,7 +10,7 @@ Some applications want to record creation and modification dates of database rec > > This is not advice against triggers, and you won't feel hindered in any way if you prefer to use triggers. Still, consider: > -> - A trigger does not suffer any exception, when some applications eventually want to fine-tune timestamps, or to perform migrations without touching timestamps. +> - A trigger does not allow any exception, when some applications eventually want to fine-tune timestamps, or to perform migrations without touching timestamps. > - The current time, according to SQLite, is not guaranteed to be constant in a given transaction. This may create undesired timestamp variations. We'll see below how GRDB provides a date that is constant at any point during a transaction. > - The current time, according to SQLite, can't be controlled in tests and previews. @@ -132,11 +132,11 @@ try dbQueue.write { db in Again, we use ``Database/transactionDate``, so that all modified players get the same timestamp within a given write transaction. -> Note: The insertion case could profit from automatic initialization of the creation date with the ``MutablePersistableRecord/willInsert(_:)-1xfwo`` persistence callback, but the modification date is not handled with ``MutablePersistableRecord/willUpdate(_:columns:)-3oko4``. Instead, the above sample code explicitly modifies the modification date. +> Note: The insertion case could benefit from automatic initialization of the creation date with the ``MutablePersistableRecord/willInsert(_:)-1xfwo`` persistence callback, but the modification date is not handled with ``MutablePersistableRecord/willUpdate(_:columns:)-3oko4``. Instead, the above sample code explicitly modifies the modification date. > > This may look like an inconvenience, but there are several reasons for this: > -> 1. The persistence methods that update are not mutating methods. `willUpdate` can not modify the modification date. +> 1. The persistence methods that update are not mutating methods. `willUpdate` cannot modify the modification date. > > 2. Automatic changes to the modification date from the general `update` method create problems. > @@ -144,7 +144,7 @@ Again, we use ``Database/transactionDate``, so that all modified players get the > > This need is well acknowledged by existing database libraries: to disable automatic timestamp updates, [ActiveRecord](https://stackoverflow.com/questions/861448/is-there-a-way-to-avoid-automatically-updating-rails-timestamp-fields) uses globals (not thread-safe in a Swift application), [Django ORM](https://stackoverflow.com/questions/7499767/temporarily-disable-auto-now-auto-now-add) does not make it easy, and [Fluent](https://github.com/vapor/fluent-kit/issues/355) simply does not allow it. > -> None of those solutions or lack thereof are seducing. +> None of those solutions or lack thereof are appealing. > > 3. Not all applications need one modification timestamp. For example, some need one timestamp per property, or per group of properties. > diff --git a/GRDB/Documentation.docc/SQLSupport.md b/GRDB/Documentation.docc/SQLSupport.md index 36cda8d4d..91eb59d39 100644 --- a/GRDB/Documentation.docc/SQLSupport.md +++ b/GRDB/Documentation.docc/SQLSupport.md @@ -10,7 +10,7 @@ If SQL is not your cup of tea, jump to 🙂 ## SQL Support -GRDB has a wide support for SQL. +GRDB has wide support for SQL. Once connected with one of the , you can execute raw SQL statements: diff --git a/GRDB/Documentation.docc/SingleRowTables.md b/GRDB/Documentation.docc/SingleRowTables.md index 5afdc440e..b8bbb4c51 100644 --- a/GRDB/Documentation.docc/SingleRowTables.md +++ b/GRDB/Documentation.docc/SingleRowTables.md @@ -95,7 +95,7 @@ extension AppConfiguration { } ``` -This ceremony is not needed when the column can not be null: +This ceremony is not needed when the column cannot be null: ```swift // The simplified setup for non-nullable columns @@ -109,7 +109,7 @@ struct AppConfiguration: Codable { } ``` -In case the database table would be empty, we need a default configuration: +In case the database table is empty, we need a default configuration: ```swift extension AppConfiguration { diff --git a/GRDB/Documentation.docc/SwiftConcurrency.md b/GRDB/Documentation.docc/SwiftConcurrency.md index f4126beb6..bfe0cb3de 100644 --- a/GRDB/Documentation.docc/SwiftConcurrency.md +++ b/GRDB/Documentation.docc/SwiftConcurrency.md @@ -33,7 +33,7 @@ for try await players in observation.values(in: writer) { } ``` -`DatabaseQueue` serializes all database accesses, when `DatabasePool` allows parallel reads and writes. The common ``DatabaseWriter`` protocol provides the [SQLite isolation guarantees](https://www.sqlite.org/isolation.html) that abstract away the differences between the two connection types, without sacrificing data integrity. See the guide for more information. +`DatabaseQueue` serializes all database accesses, whereas `DatabasePool` allows parallel reads and writes. The common ``DatabaseWriter`` protocol provides the [SQLite isolation guarantees](https://www.sqlite.org/isolation.html) that abstract away the differences between the two connection types, without sacrificing data integrity. See the guide for more information. All safety guarantees of Swift 6 are enforced during database accesses. They are controlled by the language mode and level of concurrency checking used by your application, as described in [Migrating to Swift 6] on swift.org. @@ -168,7 +168,7 @@ You do not need to perform this refactoring right away: you can compile your app - **Question: My record types are subclasses of the built-in GRDB `Record` class.** - Consider refactoring them as structs. The ``Record`` class was present in GRDB 1.0, in 2017. It has served its purpose. It is not `Sendable`, and its use is actively discouraged since GRDB 7. + Consider refactoring them as structs. The ``Record`` class was present in GRDB 1.0, in 2017. It has served its purpose. It is not `Sendable`, and its use has been actively discouraged since GRDB 7. - **Question: I need a hierarchy of record classes because I use inheritance.** @@ -186,7 +186,7 @@ You do not need to perform this refactoring right away: you can compile your app - **Question: Can I mark my record classes as `@unchecked Sendable`?** - Take care that all humans and machines who will read your code will think that the class is thread-safe, so make sure it really is. See the following questions. + Be aware that all humans and machines who will read your code will think that the class is thread-safe, so make sure it really is. See the following questions. - **Question: I can use locks to make my class safely Sendable.** @@ -194,7 +194,7 @@ You do not need to perform this refactoring right away: you can compile your app - **Question: Can I make my record classes immutable?** - Yes. Classes that can not be modified, made of constant `let` properties, are Sendable. Those immutable classes will not make it easy to modify the database, though. + Yes. Classes that cannot be modified, made of constant `let` properties, are Sendable. Those immutable classes will not make it easy to modify the database, though. ### Choosing between Synchronous and Asynchronous Database Accesses @@ -212,7 +212,7 @@ Synchronous database accesses are handy. They avoid undesired delays, flashes of Performing synchronous accesses from Swift Concurrency tasks is not incorrect. -Some people recommend avoiding long blocking jobs on the cooperative thread pool, so you might want to follow this advice, and prefer to always `await` for the database in Swift tasks. In many occasions, the compiler will help you. For example, in the sample code below, the compiler requires the `await` keyword: +Some people recommend avoiding long blocking jobs on the cooperative thread pool, so you might want to follow this advice, and prefer to always `await` for the database in Swift tasks. On many occasions, the compiler will help you. For example, in the sample code below, the compiler requires the `await` keyword: ```swift func fetchPlayers() async throws -> [Player] { diff --git a/GRDB/Documentation.docc/Transactions.md b/GRDB/Documentation.docc/Transactions.md index 279030b53..000be400a 100644 --- a/GRDB/Documentation.docc/Transactions.md +++ b/GRDB/Documentation.docc/Transactions.md @@ -6,7 +6,7 @@ Precise transaction handling. **A transaction is a fundamental tool of SQLite** that guarantees [data consistency](https://www.sqlite.org/transactional.html) as well as [proper isolation](https://sqlite.org/isolation.html) between application threads and database connections. It is at the core of GRDB guarantees. -To profit from database transactions, all you have to do is group related database statements in a single database access method such as ``DatabaseWriter/write(_:)-76inz`` or ``DatabaseReader/read(_:)-3806d``: +To benefit from database transactions, all you have to do is group related database statements in a single database access method such as ``DatabaseWriter/write(_:)-76inz`` or ``DatabaseReader/read(_:)-3806d``: ```swift // BEGIN TRANSACTION @@ -157,7 +157,7 @@ In particular, since commits may throw an error, make sure you perform a rollbac This restriction can be lifted with the ``Configuration/allowsUnsafeTransactions`` configuration flag. -It is possible to ask if a transaction is currently opened: +It is possible to ask if a transaction is currently open: ```swift func myCriticalMethod(_ db: Database) throws { @@ -212,7 +212,7 @@ try dbQueue.writeWithoutTransaction { db in } ``` -SQLite savepoints are more than nested transactions, though. For advanced uses, use [SQLite savepoint documentation](https://www.sqlite.org/lang_savepoint.html). +SQLite savepoints are more than nested transactions, though. For advanced uses, see the [SQLite savepoint documentation](https://www.sqlite.org/lang_savepoint.html). ## Transaction Kinds diff --git a/GRDB/Documentation.docc/ViewRecords.md b/GRDB/Documentation.docc/ViewRecords.md index 147118ee4..a0bee3582 100644 --- a/GRDB/Documentation.docc/ViewRecords.md +++ b/GRDB/Documentation.docc/ViewRecords.md @@ -28,7 +28,7 @@ This article explains how to solve those errors: > important: GRDB is impacted by some SQLite limitations regarding INSTEAD OF triggers: > -> - **Auto-incremented primary keys are not supported.** To be precise, SQLite won't expose the rowid of rows inserted via an INSTEAD OF trigger, so GRDB won't know the id of newly inserted rows. This has various nefarious consequences—see for example the important notice in the ``MutablePersistableRecord/didInsert(_:)`` callback. For more information, check this [SQLite forum thread](https://sqlite.org/forum/forumpost/707e7ed932). +> - **Auto-incremented primary keys are not supported.** To be precise, SQLite won't expose the rowid of rows inserted via an INSTEAD OF trigger, so GRDB won't know the id of newly inserted rows. This has various harmful consequences—see for example the important notice in the ``MutablePersistableRecord/didInsert(_:)`` callback. For more information, check this [SQLite forum thread](https://sqlite.org/forum/forumpost/707e7ed932). > - **INSTEAD OF triggers and the RETURNING clause do not play well together.** Those are SQLite bugs. All GRDB record methods with `andFetch` in their name may return unexpected or wrong results, depending on the SQLite version. For example, the SQLite version that ships with iOS 18 has bugs, and even more in iOS 17. If you intend to use the `RETURNING` clause, it is recommended that you write tests and run them in various target operating systems. ## Preliminary Setup @@ -119,7 +119,7 @@ try dbQueue.write { db in SQLite views do not have any primary key, so GRDB cannot introspect the database schema and automatically find the primary key, if any. -To instruct GRDB about the primary key, define a **schema source**, a type that conforms to ``DatabaseSchemaSource``. In this sample code, the schema only contains the "captain" view, so our schema source does not need to be very complicated. Check the documentation of the protocol for more detailed instructions: +To tell GRDB about the primary key, define a **schema source**, a type that conforms to ``DatabaseSchemaSource``. In this sample code, the schema only contains the "captain" view, so our schema source does not need to be very complicated. Check the documentation of the protocol for more detailed instructions: ```swift struct GameSchemaSource: DatabaseSchemaSource { diff --git a/GRDB/Dump/Database+Dump.swift b/GRDB/Dump/Database+Dump.swift index e4a8afdc7..6df9eb623 100644 --- a/GRDB/Dump/Database+Dump.swift +++ b/GRDB/Dump/Database+Dump.swift @@ -131,7 +131,7 @@ extension Database { /// > (those with a name that starts with "sqlite_" or "grdb_"). /// > /// > [Shadow tables](https://www.sqlite.org/vtab.html#xshadowname) are - /// > not recorded, starting SQLite 3.37+. + /// > not recorded, starting with SQLite 3.37. /// /// - Parameters: /// - format: The output format. @@ -167,7 +167,7 @@ extension Database { /// > (those with a name that starts with "sqlite_" or "grdb_"). /// > /// > [Shadow tables](https://www.sqlite.org/vtab.html#xshadowname) are - /// > not recorded, starting SQLite 3.37+. + /// > not recorded, starting with SQLite 3.37. /// /// - Parameters: /// - stream: A stream for text output, which directs output to the diff --git a/GRDB/Dump/DatabaseReader+dump.swift b/GRDB/Dump/DatabaseReader+dump.swift index 73fb10d2f..fc23e0fa9 100644 --- a/GRDB/Dump/DatabaseReader+dump.swift +++ b/GRDB/Dump/DatabaseReader+dump.swift @@ -122,7 +122,7 @@ extension DatabaseReader { /// > (those with a name that starts with "sqlite_" or "grdb_"). /// > /// > [Shadow tables](https://www.sqlite.org/vtab.html#xshadowname) are - /// > not recorded, starting SQLite 3.37+. + /// > not recorded, starting with SQLite 3.37. /// /// - Parameters: /// - format: The output format. @@ -157,7 +157,7 @@ extension DatabaseReader { /// > (those with a name that starts with "sqlite_" or "grdb_"). /// > /// > [Shadow tables](https://www.sqlite.org/vtab.html#xshadowname) are - /// > not recorded, starting SQLite 3.37+. + /// > not recorded, starting with SQLite 3.37. /// /// - Parameters: /// - stream: A stream for text output, which directs output to the diff --git a/GRDB/Dump/DumpFormat.swift b/GRDB/Dump/DumpFormat.swift index 8157fc0ca..8a36fa9f3 100644 --- a/GRDB/Dump/DumpFormat.swift +++ b/GRDB/Dump/DumpFormat.swift @@ -4,7 +4,7 @@ /// ``DatabaseReader/dumpContent(format:to:)`` and /// ``Database/dumpSQL(_:format:to:)``. /// -/// Most built-in formats are inspired from the +/// Most built-in formats are inspired by the /// [output formats of the SQLite command line tool](https://sqlite.org/cli.html#changing_output_formats). /// /// ## Topics diff --git a/GRDB/FTS/FTS5Tokenizer.swift b/GRDB/FTS/FTS5Tokenizer.swift index cfbac2b58..96c03d210 100644 --- a/GRDB/FTS/FTS5Tokenizer.swift +++ b/GRDB/FTS/FTS5Tokenizer.swift @@ -73,7 +73,7 @@ public struct FTS5Tokenization: OptionSet, Sendable { /// - ``FTS5TokenCallback`` public protocol FTS5Tokenizer: AnyObject { /// Tokenizes the text described by `pText` and `nText`, and - /// notifies found tokens to the `tokenCallback` function. + /// passes found tokens to the `tokenCallback` function. /// /// It matches the `xTokenize` function documented at /// diff --git a/GRDB/FTS/FTS5WrapperTokenizer.swift b/GRDB/FTS/FTS5WrapperTokenizer.swift index 6768bde9b..cdef73850 100644 --- a/GRDB/FTS/FTS5WrapperTokenizer.swift +++ b/GRDB/FTS/FTS5WrapperTokenizer.swift @@ -48,7 +48,7 @@ public protocol FTS5WrapperTokenizer: FTS5CustomTokenizer { /// The wrapped tokenizer var wrappedTokenizer: any FTS5Tokenizer { get } - /// Given a token produced by the wrapped tokenizer, notifies customized + /// Given a token produced by the wrapped tokenizer, passes customized /// tokens to the `tokenCallback` function. /// /// For example: diff --git a/GRDB/JSON/JSONColumn.swift b/GRDB/JSON/JSONColumn.swift index 759cc0691..1c947b717 100644 --- a/GRDB/JSON/JSONColumn.swift +++ b/GRDB/JSON/JSONColumn.swift @@ -49,7 +49,7 @@ /// } /// ``` /// -/// > Tip: When you can not create a `JSONColumn`, you'll get the same +/// > Tip: When you cannot create a `JSONColumn`, you'll get the same /// > convenient access to JSON subcomponents /// > with ``SQLSpecificExpressible/asJSON``. /// > diff --git a/GRDB/JSON/SQLJSONFunctions.swift b/GRDB/JSON/SQLJSONFunctions.swift index acf3c2dcf..c5f043a01 100644 --- a/GRDB/JSON/SQLJSONFunctions.swift +++ b/GRDB/JSON/SQLJSONFunctions.swift @@ -172,7 +172,7 @@ extension Database { /// Database.jsonReplace(#"{"a":2,"c":4}"#, ["$.a": 99]) /// ``` /// - /// Related SQLite documentation: + /// Related SQLite documentation: /// /// - Parameters: /// - value: A JSON value. @@ -196,7 +196,7 @@ extension Database { /// Database.jsonSet(#"{"a":2,"c":4}"#, ["$.a": 99]) /// ``` /// - /// Related SQLite documentation: + /// Related SQLite documentation: /// /// - Parameters: /// - value: A JSON value. @@ -437,7 +437,7 @@ extension Database { /// } /// ``` /// - /// Related SQLite documentation: + /// Related SQLite documentation: public static func jsonGroupObject( key: some SQLExpressible, value: some SQLExpressible, @@ -475,7 +475,7 @@ extension Database { /// Database.jsonb(#" { "a": [ "test" ] } "#) /// ``` /// - /// Related SQLite documentation: + /// Related SQLite documentation: public static func jsonb(_ value: some SQLExpressible) -> SQLExpression { .function("JSONB", [value.sqlExpression]) } @@ -489,7 +489,7 @@ extension Database { /// Database.jsonbArray(1...4) /// ``` /// - /// Related SQLite documentation: + /// Related SQLite documentation: public static func jsonbArray( _ values: some Collection ) -> SQLExpression { @@ -505,7 +505,7 @@ extension Database { /// Database.jsonbArray([1, 2, "3", 4]) /// ``` /// - /// Related SQLite documentation: + /// Related SQLite documentation: public static func jsonbArray( _ values: some Collection ) -> SQLExpression { @@ -521,7 +521,7 @@ extension Database { /// Database.jsonbExtract(#"{"a":123}"#, atPath: "$.a") /// ``` /// - /// Related SQLite documentation: + /// Related SQLite documentation: /// /// - Parameters: /// - value: A JSON value. @@ -539,7 +539,7 @@ extension Database { /// Database.jsonbExtract(#"{"a":2,"c":[4,5]}"#, atPaths: ["$.c", "$.a"]) /// ``` /// - /// Related SQLite documentation: + /// Related SQLite documentation: /// /// - Parameters: /// - value: A JSON value. @@ -584,7 +584,7 @@ extension Database { /// Database.jsonbReplace(#"{"a":2,"c":4}"#, ["$.a": 99]) /// ``` /// - /// Related SQLite documentation: + /// Related SQLite documentation: /// /// - Parameters: /// - value: A JSON value. @@ -608,7 +608,7 @@ extension Database { /// Database.jsonbSet(#"{"a":2,"c":4}"#, ["$.a": 99]) /// ``` /// - /// Related SQLite documentation: + /// Related SQLite documentation: /// /// - Parameters: /// - value: A JSON value. @@ -645,7 +645,7 @@ extension Database { /// ]) /// ``` /// - /// Related SQLite documentation: + /// Related SQLite documentation: public static func jsonbObject( _ elements: some Collection<(key: String, value: any SQLExpressible)> ) -> SQLExpression { @@ -663,7 +663,7 @@ extension Database { /// Database.jsonbPatch(#"{"a":1,"b":2}"#, #"{"c":3,"d":4}"#) /// ``` /// - /// Related SQLite documentation: + /// Related SQLite documentation: public static func jsonbPatch( _ value: some SQLExpressible, with patch: some SQLExpressible) @@ -681,7 +681,7 @@ extension Database { /// Database.jsonbRemove("[0,1,2,3,4]", atPath: "$[2]") /// ``` /// - /// Related SQLite documentation: + /// Related SQLite documentation: /// /// - Parameters: /// - value: A JSON value. @@ -699,7 +699,7 @@ extension Database { /// Database.jsonbRemove("[0,1,2,3,4]", atPaths: ["$[2]", "$[0]"]) /// ``` /// - /// Related SQLite documentation: + /// Related SQLite documentation: /// /// - Parameters: /// - value: A JSON value. @@ -733,7 +733,7 @@ extension Database { /// Player.select { Database.jsonbGroupArray($0.name, orderBy: $0.name) } /// ``` /// - /// Related SQLite documentation: + /// Related SQLite documentation: public static func jsonbGroupArray( _ value: some SQLExpressible, orderBy ordering: (any SQLOrderingTerm)? = nil, @@ -775,7 +775,7 @@ extension Database { /// } /// ``` /// - /// Related SQLite documentation: + /// Related SQLite documentation: public static func jsonbGroupObject( key: some SQLExpressible, value: some SQLExpressible, @@ -956,7 +956,7 @@ extension Database { /// Database.jsonReplace(#"{"a":2,"c":4}"#, ["$.a": 99]) /// ``` /// - /// Related SQLite documentation: + /// Related SQLite documentation: /// /// - Parameters: /// - value: A JSON value. @@ -981,7 +981,7 @@ extension Database { /// Database.jsonSet(#"{"a":2,"c":4}"#, ["$.a": 99]) /// ``` /// - /// Related SQLite documentation: + /// Related SQLite documentation: /// /// - Parameters: /// - value: A JSON value. @@ -1216,7 +1216,7 @@ extension Database { /// } /// ``` /// - /// Related SQLite documentation: + /// Related SQLite documentation: @available(iOS 16, tvOS 17, watchOS 9, *) // SQLite 3.38+ with exceptions for macOS public static func jsonGroupObject( key: some SQLExpressible, diff --git a/GRDB/Migration/DatabaseMigrator.swift b/GRDB/Migration/DatabaseMigrator.swift index ed6f88659..b11b33237 100644 --- a/GRDB/Migration/DatabaseMigrator.swift +++ b/GRDB/Migration/DatabaseMigrator.swift @@ -262,12 +262,12 @@ public struct DatabaseMigrator: Sendable { /// } /// ``` /// - /// In the above sample code, the merged migration is named like the + /// In the above sample code, the merged migration is named after the /// last one of the merged set. You can also give it a brand new name, /// as in the alternative below. Notice the different logic in the /// migration code. /// - /// **In all cases avoid naming the merged migration like the first + /// **In all cases avoid naming the merged migration after the first /// elements in the merged set** (`v1` or `v2` in our example). /// /// ```swift diff --git a/GRDB/QueryInterface/ForeignKey.swift b/GRDB/QueryInterface/ForeignKey.swift index 84367b882..1f6a2d7ef 100644 --- a/GRDB/QueryInterface/ForeignKey.swift +++ b/GRDB/QueryInterface/ForeignKey.swift @@ -5,7 +5,7 @@ /// tables that are not unambiguously related with a single SQLite foreign key. /// /// Sometimes the database schema does not define any foreign key between two -/// tables. And sometimes, there are several foreign keys from a table +/// tables. And sometimes, there are several foreign keys from one table /// to another: /// /// | Table book | | Table person | @@ -20,7 +20,7 @@ /// foreign key from book to person", or "Could not infer foreign key from book /// to person". /// -/// Your help is needed. You have to instruct which foreign key to use. +/// Your help is needed. You have to specify which foreign key to use. /// For example: /// /// ```swift diff --git a/GRDB/QueryInterface/Request/Association/AssociationAggregate.swift b/GRDB/QueryInterface/Request/Association/AssociationAggregate.swift index 68925f57a..3a43ae6ac 100644 --- a/GRDB/QueryInterface/Request/Association/AssociationAggregate.swift +++ b/GRDB/QueryInterface/Request/Association/AssociationAggregate.swift @@ -706,7 +706,7 @@ extension AssociationAggregate: Refinable { } } - /// Returns an aggregate that is selected in a column named like the given + /// Returns an aggregate that is selected in a column named after the given /// coding key. /// /// See ``forKey(_:)-1rvux``. diff --git a/GRDB/QueryInterface/Request/Association/HasManyThroughAssociation.swift b/GRDB/QueryInterface/Request/Association/HasManyThroughAssociation.swift index d0ecb09f7..d8b99bf23 100644 --- a/GRDB/QueryInterface/Request/Association/HasManyThroughAssociation.swift +++ b/GRDB/QueryInterface/Request/Association/HasManyThroughAssociation.swift @@ -3,7 +3,7 @@ /// declaring record can be matched with zero or more instances of another /// record by proceeding through a third record. /// -/// For example, consider the practice of passport delivery. One country +/// For example, consider the practice of passport issuance. One country /// "has many" citizens "through" its passports: /// /// ```swift diff --git a/GRDB/QueryInterface/Request/RequestProtocols.swift b/GRDB/QueryInterface/Request/RequestProtocols.swift index 77f6769e0..7950e6f2d 100644 --- a/GRDB/QueryInterface/Request/RequestProtocols.swift +++ b/GRDB/QueryInterface/Request/RequestProtocols.swift @@ -471,7 +471,7 @@ extension FilteredRequest where Self: TypedRequest, Self.RowDecoder: TableRecord // MARK: - TableRequest -/// A request that feeds from a database table +/// A request that fetches from a database table /// /// ## Topics /// @@ -1344,7 +1344,7 @@ public protocol OrderedRequest { /// Returns a request with a stable order. /// - /// The returned request lifts ordering ambiguities and always returns + /// The returned request resolves ordering ambiguities and always returns /// its results in the same order. /// /// The purpose of this method is to make requests testable. diff --git a/GRDB/QueryInterface/SQL/SQLAssociation.swift b/GRDB/QueryInterface/SQL/SQLAssociation.swift index 0d62e528a..ecbbef3f2 100644 --- a/GRDB/QueryInterface/SQL/SQLAssociation.swift +++ b/GRDB/QueryInterface/SQL/SQLAssociation.swift @@ -230,7 +230,7 @@ enum SQLAssociationKey: Refinable { case inflected(String) /// A key that is inflected in plural contexts, but strictly honors - /// user-provided name in singular contexts. + /// the user-provided name in singular contexts. /// /// For example: /// @@ -244,7 +244,7 @@ enum SQLAssociationKey: Refinable { case fixedSingular(String) /// A key that is inflected in singular contexts, but strictly honors - /// user-provided name in plural contexts. + /// the user-provided name in plural contexts. /// See .inflected and .fixedSingular for some context. case fixedPlural(String) diff --git a/GRDB/QueryInterface/SQL/SQLExpression.swift b/GRDB/QueryInterface/SQL/SQLExpression.swift index 42efb2a7c..e699e5714 100644 --- a/GRDB/QueryInterface/SQL/SQLExpression.swift +++ b/GRDB/QueryInterface/SQL/SQLExpression.swift @@ -905,7 +905,7 @@ extension SQLExpression { // sqlite> SELECT ('a' COLLATE NOCASE) IN ('A'); // 1 // - // Conclusion: "x IN (y,z, ...) COLLATE nocase" can not match the + // Conclusion: "x IN (y,z, ...) COLLATE nocase" cannot match the // user intent. We could fatal error. Or warn. Or just make it work: // // Prefer: (expression COLLATE collation) IN (...) @@ -2191,7 +2191,7 @@ extension SQLExpressible where Self == Column { /// For example, ``Column`` is a type that only exists to help you build /// requests, and it adopts `SQLSpecificExpressible`. /// -/// On the other side, `Int` adopts ``SQLExpressible``. +/// On the other hand, `Int` adopts ``SQLExpressible``. /// /// ## Topics /// diff --git a/GRDB/QueryInterface/SQL/SQLForeignKeyRequest.swift b/GRDB/QueryInterface/SQL/SQLForeignKeyRequest.swift index 1cb5c9d52..8d4be402a 100644 --- a/GRDB/QueryInterface/SQL/SQLForeignKeyRequest.swift +++ b/GRDB/QueryInterface/SQL/SQLForeignKeyRequest.swift @@ -1,10 +1,10 @@ -/// SQLForeignKeyRequest looks for the foreign keys associations need to +/// SQLForeignKeyRequest looks for the foreign keys that associations need to /// join tables. /// /// Column mappings come from foreign keys, when they exist in the /// database schema. /// -/// When the schema does not define any foreign key, we can still infer complete +/// When the schema does not define any foreign key, we can still infer a complete /// mapping from partial information and primary keys. struct SQLForeignKeyRequest { let originTable: String diff --git a/GRDB/QueryInterface/SQL/SQLFunctions.swift b/GRDB/QueryInterface/SQL/SQLFunctions.swift index 893b107d9..6867218ff 100644 --- a/GRDB/QueryInterface/SQL/SQLFunctions.swift +++ b/GRDB/QueryInterface/SQL/SQLFunctions.swift @@ -82,8 +82,8 @@ public func cast(_ expression: some SQLSpecificExpressible, as storageClass: Dat /// /// Unlike the SQL function, `coalesce` accepts any number of arguments. /// When `values` is empty, the result is `NULL`. When `values` contains a -/// single value, the result is this value. `COALESCE` is used from -/// two values upwards. +/// single value, the result is this value. `COALESCE` is used for +/// two or more values. public func coalesce(_ values: some Collection) -> SQLExpression { // SQLite COALESCE wants at least two arguments. // There is no reason to apply the same limitation. diff --git a/GRDB/QueryInterface/SQL/SQLRelation.swift b/GRDB/QueryInterface/SQL/SQLRelation.swift index 6b2f1e511..f318795dc 100644 --- a/GRDB/QueryInterface/SQL/SQLRelation.swift +++ b/GRDB/QueryInterface/SQL/SQLRelation.swift @@ -41,7 +41,7 @@ /// /// - `.oneOptional`: /// -/// Such children are left joined. They may, or not, be included in +/// Such children are left joined. They may or may not be included in /// the selection. /// /// // SELECT book.* @@ -56,7 +56,7 @@ /// /// - `.oneRequired`: /// -/// Such children are inner joined. They may, or not, be included in +/// Such children are inner joined. They may or may not be included in /// the selection. /// /// // SELECT book.* @@ -85,9 +85,9 @@ /// below, the country relation has a `.bridge` child to passports, and the /// passport relation has an `.all` child to citizens. /// -/// // SELECT * FROM countries; -/// // SELECT citizens.* FROM citizens -/// // JOIN passport ON passport.citizenId = citizens.id +/// // SELECT * FROM country; +/// // SELECT citizen.* FROM citizen +/// // JOIN passport ON passport.citizenId = citizen.id /// // AND passport.countryCode IN ('BE', 'DE', 'FR', ...); /// Country.including(all: Country.citizens) struct SQLRelation: Sendable { @@ -388,7 +388,7 @@ extension SQLRelation { /// // JOIN destination ON destination.id = origin.destinationId /// let request = Origin.including(required: Origin.destination) /// - /// At low-level, this gives: + /// At a low level, this gives: /// /// let sqlAssociation = Origin.destination._sqlAssociation /// let origin = Origin.all().query.relation @@ -439,7 +439,7 @@ extension SQLRelation { // We want the child for the "captain" in the following request to be // registered under the singular "player" key, and not the plural // "players" key, so that it does not conflict with the other child - // named "players" (we can not have two distinct children with the + // named "players" (we cannot have two distinct children with the // same key): // // struct Team: TableRecord { diff --git a/GRDB/QueryInterface/SQLGeneration/SQLQueryGenerator.swift b/GRDB/QueryInterface/SQLGeneration/SQLQueryGenerator.swift index bb26178b1..b159c42ab 100644 --- a/GRDB/QueryInterface/SQLGeneration/SQLQueryGenerator.swift +++ b/GRDB/QueryInterface/SQLGeneration/SQLQueryGenerator.swift @@ -152,7 +152,7 @@ struct SQLQueryGenerator: Refinable { private func optimizedSelectedRegion(_ db: Database, _ selectedRegion: DatabaseRegion) throws -> DatabaseRegion { var optimizedRegion = selectedRegion - // Give up unless request feeds from a database table + // Give up unless request fetches from a database table let tableName = relation.source.tableName guard try db.tableExists(tableName) else { // skip views return optimizedRegion diff --git a/GRDB/QueryInterface/SQLGeneration/TableAlias.swift b/GRDB/QueryInterface/SQLGeneration/TableAlias.swift index 6e811794d..141925873 100644 --- a/GRDB/QueryInterface/SQLGeneration/TableAlias.swift +++ b/GRDB/QueryInterface/SQLGeneration/TableAlias.swift @@ -351,7 +351,7 @@ extension TableAlias { /// A boolean SQL expression indicating whether this alias refers to some /// rows, or not. /// - /// In the example below, we only fetch books that are not associated to + /// In the example below, we only fetch books that are not associated with /// any author: /// /// ```swift diff --git a/GRDB/QueryInterface/Schema/Database+SchemaDefinition.swift b/GRDB/QueryInterface/Schema/Database+SchemaDefinition.swift index 0682cb3f3..b6b6a4a26 100644 --- a/GRDB/QueryInterface/Schema/Database+SchemaDefinition.swift +++ b/GRDB/QueryInterface/Schema/Database+SchemaDefinition.swift @@ -53,7 +53,7 @@ extension Database { /// /// ### Reference documentation /// - /// SQLite has many reference documents about table creation. They are a + /// SQLite has many reference documents about table creation. They are /// great learning material: /// /// - [CREATE TABLE](https://www.sqlite.org/lang_createtable.html) diff --git a/GRDB/QueryInterface/Schema/TableDefinition.swift b/GRDB/QueryInterface/Schema/TableDefinition.swift index a672dee07..fb7c6012c 100644 --- a/GRDB/QueryInterface/Schema/TableDefinition.swift +++ b/GRDB/QueryInterface/Schema/TableDefinition.swift @@ -12,7 +12,7 @@ public struct TableOptions: OptionSet, Sendable { /// Creates a [`WITHOUT ROWID`](https://www.sqlite.org/withoutrowid.html) table. /// - /// Such tables can not be tracked with tools. + /// Such tables cannot be tracked with tools. public static let withoutRowID = TableOptions(rawValue: 1 << 2) #if GRDBCUSTOMSQLITE || SQLITE_HAS_CODEC @@ -289,7 +289,7 @@ public final class TableDefinition { /// } /// ``` public func column(literal: SQL) { - GRDBPrecondition(!inPrimaryKeyBody, "Primary key columns can not be defined with raw SQL") + GRDBPrecondition(!inPrimaryKeyBody, "Primary key columns cannot be defined with raw SQL") columnComponents.append(.columnLiteral(literal)) } diff --git a/GRDB/QueryInterface/Schema/VirtualTableModule.swift b/GRDB/QueryInterface/Schema/VirtualTableModule.swift index 45ef4156d..b4f9ba83c 100644 --- a/GRDB/QueryInterface/Schema/VirtualTableModule.swift +++ b/GRDB/QueryInterface/Schema/VirtualTableModule.swift @@ -58,7 +58,7 @@ public protocol VirtualTableModule { // never able to be used by user-defined VirtualTableModule types, because // `ifNotExists` has never been public. public struct VirtualTableConfiguration { - /// If true, existing objects must not be replaced, or generate any error + /// If true, existing objects must neither be replaced nor generate any error /// (even if they do not match the objects that would be created otherwise.) var ifNotExists: Bool diff --git a/GRDB/Record/MutablePersistableRecord+DAO.swift b/GRDB/Record/MutablePersistableRecord+DAO.swift index 5ff8c377c..ddb6f39c6 100644 --- a/GRDB/Record/MutablePersistableRecord+DAO.swift +++ b/GRDB/Record/MutablePersistableRecord+DAO.swift @@ -4,7 +4,7 @@ final class DAO { let db: Database /// DAO keeps a copy of the record's persistenceContainer, so that this - /// dictionary is built once whatever the database operation. It is + /// dictionary is built once regardless of the database operation. It is /// guaranteed to have at least one (key, value) pair. let persistenceContainer: PersistenceContainer diff --git a/GRDB/Record/MutablePersistableRecord.swift b/GRDB/Record/MutablePersistableRecord.swift index 8ebf9802c..5d5b78e77 100644 --- a/GRDB/Record/MutablePersistableRecord.swift +++ b/GRDB/Record/MutablePersistableRecord.swift @@ -42,7 +42,7 @@ /// ready-made for `Encodable` types. /// /// You configure the database table where records are persisted with the -/// ``TableRecord`` inherited protocol. +/// inherited ``TableRecord`` protocol. /// /// ## Topics /// diff --git a/GRDB/Record/PersistableRecord.swift b/GRDB/Record/PersistableRecord.swift index 316a87e72..4397d91bd 100644 --- a/GRDB/Record/PersistableRecord.swift +++ b/GRDB/Record/PersistableRecord.swift @@ -10,7 +10,7 @@ /// ready-made for `Encodable` types. /// /// You configure the database table where records are persisted with the -/// ``TableRecord`` inherited protocol. +/// inherited ``TableRecord`` protocol. /// /// ## Topics /// diff --git a/GRDB/Record/Record.swift b/GRDB/Record/Record.swift index a66ef266f..7cbe1fb34 100644 --- a/GRDB/Record/Record.swift +++ b/GRDB/Record/Record.swift @@ -169,8 +169,8 @@ open class Record { /// A dictionary of changes that have not been saved. /// /// The keys of the dictionary are column names, and values are the old - /// values that have been changed since last fetching or saving of - /// the record. + /// values that have been changed since the record was last fetched + /// or saved. /// /// Unless the record has actually been fetched or saved, the old values /// are nil. diff --git a/GRDB/Record/TableRecord.swift b/GRDB/Record/TableRecord.swift index 17582a48f..a8de31f03 100644 --- a/GRDB/Record/TableRecord.swift +++ b/GRDB/Record/TableRecord.swift @@ -920,7 +920,7 @@ public enum RecordError: Error { /// /// It can also be thrown from methods that insert or update with a /// `RETURNING` clause, and the `IGNORE` conflict policy. In this case, - /// the error notifies that a conflict has prevented the change from + /// the error indicates that a conflict has prevented the change from /// being applied. /// /// - parameters: @@ -964,7 +964,7 @@ extension TableRecord { } extension TableRecord where Self: EncodableRecord { - /// Returns an error that tells that the record does not exist in + /// Returns an error indicating that the record does not exist in /// the database. /// /// - returns: ``RecordError/recordNotFound(databaseTableName:key:)``, or diff --git a/GRDB/Utils/OrderedDictionary.swift b/GRDB/Utils/OrderedDictionary.swift index 987e362a1..e9a41c3ea 100644 --- a/GRDB/Utils/OrderedDictionary.swift +++ b/GRDB/Utils/OrderedDictionary.swift @@ -1,4 +1,4 @@ -/// A dictionary with guaranteed keys ordering. +/// A dictionary with guaranteed key ordering. /// /// var dict = OrderedDictionary() /// dict.append(1, forKey: "foo") diff --git a/GRDB/Utils/Pool.swift b/GRDB/Utils/Pool.swift index d9050f1b1..5b3c2e5c5 100644 --- a/GRDB/Utils/Pool.swift +++ b/GRDB/Utils/Pool.swift @@ -21,7 +21,7 @@ import Dispatch /// /// If there is no available element, the pool builds a new element, unless the /// maximum number of elements is reached. In this case, the get() method -/// blocks the current thread, until an element eventually turns available again. +/// blocks the current thread, until an element eventually becomes available again. /// /// DispatchQueue.concurrentPerform(iterations: 6) { _ in /// pool.get { n in @@ -146,7 +146,7 @@ final class Pool: Sendable { } } - /// Performs a synchronous block with an element. The element turns + /// Performs a synchronous block with an element. The element becomes /// available after the block has executed. func get(block: (T) throws -> U) throws -> U { let (element, completion) = try get() @@ -154,7 +154,7 @@ final class Pool: Sendable { return try block(element) } - /// Performs an asynchronous block with an element. The element turns + /// Performs an asynchronous block with an element. The element becomes /// available after the block has executed. func get(block: (T) async throws -> U) async throws -> U { let (element, completion) = try await get() diff --git a/GRDB/ValueObservation/Reducers/ValueReducer.swift b/GRDB/ValueObservation/Reducers/ValueReducer.swift index d93a358e8..8aef7f076 100644 --- a/GRDB/ValueObservation/Reducers/ValueReducer.swift +++ b/GRDB/ValueObservation/Reducers/ValueReducer.swift @@ -19,8 +19,8 @@ public protocol _ValueReducer: GRDBSendableMetatype { associatedtype Value: Sendable /// Returns a value that fetches database values upon changes in an - /// observed database region. The returned value method must not depend - /// on the state of the reducer. + /// observed database region. The `fetch` method of the returned value + /// must not depend on the state of the reducer. func _makeFetcher() -> Fetcher /// Transforms a fetched value into an optional observed value. Returns nil diff --git a/GRDB/ValueObservation/SharedValueObservation.swift b/GRDB/ValueObservation/SharedValueObservation.swift index d16838a3e..6e66a428a 100644 --- a/GRDB/ValueObservation/SharedValueObservation.swift +++ b/GRDB/ValueObservation/SharedValueObservation.swift @@ -21,7 +21,7 @@ public enum SharedValueObservationExtent: Sendable { } extension ValueObservation { - /// Returns a shared value observation that spares database resources by + /// Returns a shared value observation that saves database resources by /// sharing a single underlying ``ValueObservation`` subscription. /// /// - note: [**🔥 EXPERIMENTAL**](https://github.com/groue/GRDB.swift/blob/master/README.md#what-are-experimental-features) @@ -129,7 +129,7 @@ extension ValueObservation { } } -/// A shared value observation spares database resources by sharing a single +/// A shared value observation saves database resources by sharing a single /// underlying ``ValueObservation`` subscription. /// /// - note: [**🔥 EXPERIMENTAL**](https://github.com/groue/GRDB.swift/blob/master/README.md#what-are-experimental-features) @@ -345,7 +345,7 @@ public final class SharedValueObservation: @unchecked Sendabl discardedCancellable?.cancel() } else if let lastResult { // Notify last result as an initial value. A fresher result may - // have been scheduled before, and already notified to the + // have been scheduled before, and already delivered to the // client: in this case, the last result is not notified. scheduler.scheduleInitial { client.notifyInitial(lastResult) diff --git a/GRDB/ValueObservation/ValueObservation.swift b/GRDB/ValueObservation/ValueObservation.swift index 9fed1a68c..b07ef90a4 100644 --- a/GRDB/ValueObservation/ValueObservation.swift +++ b/GRDB/ValueObservation/ValueObservation.swift @@ -11,7 +11,7 @@ public struct ValueObservation: Sendable { /// when it fetches fresh values. /// /// The `requiresWriteAccess` property is false by default. When true, a - /// `ValueObservation` has a write access to the database, and its fetches + /// `ValueObservation` has write access to the database, and its fetches /// are automatically wrapped in a savepoint: /// /// ```swift @@ -695,7 +695,7 @@ extension ValueObservation { /// ``` /// /// **Observations that do not track a constant database region must not - /// use this method, because some changes may not be notified to + /// use this method, because some changes may not be reported to /// the application.** /// /// For example, the observations below do not track a constant region. diff --git a/README.md b/README.md index 62f1d4f8a..1a8e41d86 100644 --- a/README.md +++ b/README.md @@ -372,7 +372,7 @@ GRDB can be installed as a framework, or a static library. Due to an [issue](https://github.com/CocoaPods/CocoaPods/issues/11839) in CocoaPods, it is currently not possible to deploy new versions of GRDB to CocoaPods. The last version available on CocoaPods is 6.24.1. To install later versions of GRDB using CocoaPods, use one of the following workarounds: -- Depend on the `GRDB7` branch. This is more or less equivalent to what `pod 'GRDB.swift', '~> 7.0'` would normally do, if CocoaPods would accept new GRDB versions to be published: +- Depend on the `GRDB7` branch. This is more or less equivalent to what `pod 'GRDB.swift', '~> 7.0'` would normally do, if CocoaPods allowed new GRDB versions to be published: ```ruby # Can't use semantic versioning due to https://github.com/CocoaPods/CocoaPods/issues/11839 @@ -457,7 +457,7 @@ Advanced topics: ## Executing Updates -Once granted with a [database connection], the [`execute(sql:arguments:)`](https://swiftpackageindex.com/groue/GRDB.swift/documentation/grdb/database/execute(sql:arguments:)) method executes the SQL statements that do not return any database row, such as `CREATE TABLE`, `INSERT`, `DELETE`, `ALTER`, etc. +Once you have a [database connection], the [`execute(sql:arguments:)`](https://swiftpackageindex.com/groue/GRDB.swift/documentation/grdb/database/execute(sql:arguments:)) method executes the SQL statements that do not return any database row, such as `CREATE TABLE`, `INSERT`, `DELETE`, `ALTER`, etc. For example: @@ -480,7 +480,7 @@ try dbQueue.write { db in } ``` -The `?` and colon-prefixed keys like `:score` in the SQL query are the **statement arguments**. You pass arguments with arrays or dictionaries, as in the example above. See [Values](#values) for more information on supported argument types (Bool, Int, String, Date, Swift enums, etc.), and [`StatementArguments`] for a detailed documentation of SQLite arguments. +The `?` and colon-prefixed keys like `:score` in the SQL query are the **statement arguments**. You pass arguments with arrays or dictionaries, as in the example above. See [Values](#values) for more information on supported argument types (Bool, Int, String, Date, Swift enums, etc.), and [`StatementArguments`] for detailed documentation of SQLite arguments. You can also embed query arguments right into your SQL queries, with [`execute(literal:)`](https://swiftpackageindex.com/groue/GRDB.swift/documentation/grdb/database/execute(literal:)), as in the example below. See [SQL Interpolation] for more details. @@ -650,7 +650,7 @@ try dbQueue.read { db in } ``` -Unlike arrays and sets, cursors returned by `fetchCursor()` load their results step after step: +Unlike arrays and sets, cursors returned by `fetchCursor()` load their results step by step: ```swift try dbQueue.read { db in @@ -662,7 +662,7 @@ try dbQueue.read { db in } ``` -- **Cursors can not be used on any thread**: you must consume a cursor on the dispatch queue it was created in. Particularly, don't extract a cursor out of a database access method: +- **Cursors cannot be used on just any thread**: you must consume a cursor on the dispatch queue it was created in. In particular, don't extract a cursor out of a database access method: ```swift // Wrong @@ -686,7 +686,7 @@ try dbQueue.read { db in - **Cursors iterate database results in a lazy fashion**, and don't consume much memory. Arrays and sets contain copies of database values, and may take a lot of memory when there are many fetched results. -- **Cursors are granted with direct access to SQLite,** unlike arrays and sets that have to take the time to copy database values. If you look for extra performance, you may prefer cursors. +- **Cursors have direct access to SQLite,** unlike arrays and sets that have to take the time to copy database values. If you look for extra performance, you may prefer cursors. - **Cursors can feed Swift collections.** @@ -737,7 +737,7 @@ try dbQueue.read { db in } ``` -- **Cursors are not Swift sequences.** That's because Swift sequences can't handle iteration errors, when reading SQLite results may fail at any time. +- **Cursors are not Swift sequences.** That's because Swift sequences can't handle iteration errors, whereas reading SQLite results may fail at any time. - **Cursors require a little care**: @@ -800,7 +800,7 @@ let rows = try Row.fetchAll(db, arguments: ["name": "Arthur"]) ``` -See [Values](#values) for more information on supported argument types (Bool, Int, String, Date, Swift enums, etc.), and [`StatementArguments`] for a detailed documentation of SQLite arguments. +See [Values](#values) for more information on supported argument types (Bool, Int, String, Date, Swift enums, etc.), and [`StatementArguments`] for detailed documentation of SQLite arguments. Unlike row arrays that contain copies of the database rows, row cursors are close to the SQLite metal, and require a little care: @@ -895,7 +895,7 @@ Generally speaking, you can extract the type you need, provided it can be conver row["missing"] as String // fatal error: no such column: missing ``` - You can explicitly check for a column presence with the `hasColumn` method. + You can explicitly check for the presence of a column with the `hasColumn` method. - **Invalid conversions throw a fatal error.** @@ -1265,8 +1265,8 @@ Some applications may prefer another date format: **You should think twice before choosing a different date format:** -- ISO-8601 is about *exchange and communication*, when SQLite is about *storage and data manipulation*. Sharing the same representation in your database and in JSON files only provides a superficial convenience, and should be the least of your priorities. Don't store dates as ISO-8601 without understanding what you lose. For example, ISO-8601 time zones forbid database-level date comparison. -- Sub-millisecond precision and exact `Date` roundtrip are not as obvious needs as it seems at first sight. Dates generally don't precisely roundtrip as soon as they leave your application anyway, because the other systems your app communicates with use their own date representation (the Android version of your app, the server your application is talking to, etc.) On top of that, `Date` comparison is at least as hard and nasty as [floating point comparison](https://www.google.com/search?q=floating+point+comparison+is+hard). +- ISO-8601 is about *exchange and communication*, whereas SQLite is about *storage and data manipulation*. Sharing the same representation in your database and in JSON files only provides a superficial convenience, and should be the least of your priorities. Don't store dates as ISO-8601 without understanding what you lose. For example, ISO-8601 time zones forbid database-level date comparison. +- Sub-millisecond precision and exact `Date` roundtrip are not as obvious needs as they seem at first sight. Dates generally don't precisely roundtrip as soon as they leave your application anyway, because the other systems your app communicates with use their own date representation (the Android version of your app, the server your application is talking to, etc.) On top of that, `Date` comparison is at least as hard and nasty as [floating point comparison](https://www.google.com/search?q=floating+point+comparison+is+hard). The customization of date format is explicit. For example: @@ -1344,7 +1344,7 @@ Here is how GRDB supports the various data types supported by SQLite: let number = try Decimal.fetchOne(db, sql: "SELECT '-100'") // Decimal ``` -- `NSNumber` and `NSDecimalNumber` send 64-bit signed integers and doubles in the database: +- `NSNumber` and `NSDecimalNumber` send 64-bit signed integers and doubles to the database: ```swift // INSERT INTO transfer VALUES (10) @@ -1367,7 +1367,7 @@ Here is how GRDB supports the various data types supported by SQLite: > - Send `Decimal` instead (those store decimal strings in the database). > - Send integers instead (for example, store amounts of cents instead of amounts of Euros). -- `Decimal` sends decimal strings in the database: +- `Decimal` sends decimal strings to the database: ```swift // INSERT INTO transfer VALUES ('10') @@ -1689,7 +1689,7 @@ extension Player: FetchableRecord, PersistableRecord { See more [examples of record definitions](#examples-of-record-definitions) below. -> Note: if you are familiar with Core Data's NSManagedObject or Realm's Object, you may experience a cultural shock: GRDB records are not uniqued, do not auto-update, and do not lazy-load. This is both a purpose, and a consequence of protocol-oriented programming. +> Note: if you are familiar with Core Data's NSManagedObject or Realm's Object, you may experience a culture shock: GRDB records are not uniqued, do not auto-update, and do not lazy-load. This is both a purpose, and a consequence of protocol-oriented programming. > > Tip: The [Recommended Practices for Designing Record Types](https://swiftpackageindex.com/groue/GRDB.swift/documentation/grdb/recordrecommendedpractices) guide provides general guidance. > @@ -2805,7 +2805,7 @@ let player = try Player.fetchOne(db, ...) ### Tip: Derive Columns from Coding Keys -Codable types are granted with a [CodingKeys](https://developer.apple.com/documentation/foundation/archives_and_serialization/encoding_and_decoding_custom_types) enum. You can use them to safely define database columns: +Codable types come with a [CodingKeys](https://developer.apple.com/documentation/foundation/archives_and_serialization/encoding_and_decoding_custom_types) enum. You can use them to safely define database columns: ```swift struct Player: Codable { @@ -3259,7 +3259,7 @@ try dbQueue.write { db in You need to open a [database connection] before you can query the database. -Please bear in mind that the query interface can not generate all possible SQL queries. You may also *prefer* writing SQL, and this is just OK. From little snippets to full queries, your SQL skills are welcome: +Please bear in mind that the query interface cannot generate all possible SQL queries. You may also *prefer* writing SQL, and this is just OK. From little snippets to full queries, your SQL skills are welcome: ```swift try dbQueue.write { db in @@ -3328,7 +3328,7 @@ let request = Player.all() let players = try request.fetchAll(db) // [Player] ``` -When you can not use a record type, use `Table`: +When you cannot use a record type, use `Table`: ```swift // The request for all rows from the player table: @@ -4033,7 +4033,7 @@ GRDB comes with a Swift version of many SQLite [built-in functions](https://sqli Player.select { $0.name.uppercased } ``` - > **Note**: When *comparing* strings, you'd rather use a [collation](#string-comparison): + > **Note**: When *comparing* strings, you should use a [collation](#string-comparison): > > ```swift > let name: String = ... @@ -4060,7 +4060,7 @@ GRDB comes with a Swift version of many SQLite [built-in functions](https://sqli You will sometimes want to extend your query interface requests with SQL snippets. This can happen because GRDB does not provide a Swift interface for some SQL function or operator, or because you want to use an SQLite construct that GRDB does not support. -Support for extensibility is large, but not unlimited. All the SQL queries built by the query interface request have the shape below. _If you need something else, you'll have to use [raw SQL requests](#sqlite-api)._ +Support for extensibility is broad, but not unlimited. All the SQL queries built by the query interface request have the shape below. _If you need something else, you'll have to use [raw SQL requests](#sqlite-api)._ ```sql WITH ... -- 1 @@ -4132,9 +4132,9 @@ LIMIT ... -- 9 See the [Query Interface Organization] for more information about `SQLSpecificExpressible` and `SQLExpression`. -3. `FROM ...`: only one table is supported here. You can not customize this SQL part. +3. `FROM ...`: only one table is supported here. You cannot customize this SQL part. -4. `JOIN ...`: joins are fully controlled by [Associations]. You can not customize this SQL part. +4. `JOIN ...`: joins are fully controlled by [Associations]. You cannot customize this SQL part. 5. `WHERE ...` @@ -4195,12 +4195,12 @@ LIMIT ... -- 9 .reversed() ``` -9. `LIMIT ...`: use the `limit(_:offset:)` method. You can not customize this SQL part. +9. `LIMIT ...`: use the `limit(_:offset:)` method. You cannot customize this SQL part. ## Fetching from Requests -Once you have a request, you can fetch the records at the origin of the request: +Once you have a request, you can fetch the records the request is based on: ```swift // Some request based on `Player` @@ -4523,7 +4523,7 @@ try request.fetchOne(db) // Player? try request.fetchCount(db) // Int ``` -**When the query interface can not generate the SQL you need**, you can still fall back to [raw SQL](#fetch-queries): +**When the query interface cannot generate the SQL you need**, you can still fall back to [raw SQL](#fetch-queries): ```swift // Custom SQL is always welcome @@ -4697,11 +4697,11 @@ try dbPool.barrierWriteWithoutTransaction { db in Providing a passphrase won't encrypt a clear-text database that already exists, though. SQLCipher can't do that, and you will get an error instead: `SQLite error 26: file is encrypted or is not a database`. -Instead, create a new encrypted database, at a distinct location, and export the content of the existing database. This can both encrypt a clear-text database, or change the passphrase of an encrypted database. +Instead, create a new encrypted database, at a distinct location, and export the content of the existing database. This can both encrypt a clear-text database, and change the passphrase of an encrypted database. The technique to do that is [documented](https://discuss.zetetic.net/t/how-to-encrypt-a-plaintext-sqlite-database-to-use-sqlcipher-and-avoid-file-is-encrypted-or-is-not-a-database-errors/868/1) by SQLCipher. -With GRDB, it gives: +With GRDB, it looks like this: ```swift // The existing database @@ -4771,7 +4771,7 @@ Some demanding users will want to go further, and manage the lifetime of the raw #### Managing the lifetime of the passphrase bytes -GRDB offers convenience methods for providing the database passphrases as Swift strings: `usePassphrase(_:)` and `changePassphrase(_:)`. Those methods don't keep the passphrase String in memory longer than necessary. But they are as secure as the standard String type: the lifetime of actual passphrase bytes in memory is not under control. +GRDB offers convenience methods for providing the database passphrases as Swift strings: `usePassphrase(_:)` and `changePassphrase(_:)`. Those methods don't keep the passphrase String in memory longer than necessary. But they are only as secure as the standard String type: the lifetime of actual passphrase bytes in memory is not under control. When you want to precisely manage the passphrase bytes, talk directly to SQLCipher, using its raw C functions. @@ -5008,7 +5008,7 @@ Considering that a local database is not some JSON loaded from a remote server, 📖 [`DatabaseError`](https://swiftpackageindex.com/groue/GRDB.swift/documentation/grdb/databaseerror) -**DatabaseError** are thrown on SQLite errors: +**DatabaseError** instances are thrown on SQLite errors: ```swift do { @@ -5107,7 +5107,7 @@ do { 📖 [`RowDecodingError`](https://swiftpackageindex.com/groue/GRDB.swift/documentation/grdb/rowdecodingerror) -**RowDecodingError** is thrown when the application can not decode a value from a database row. For example: +**RowDecodingError** is thrown when the application cannot decode a value from a database row. For example: ```swift let row = try Row.fetchOne(db, sql: "SELECT NULL AS name")! @@ -5117,7 +5117,7 @@ let name = try row.decode(String.self, forColumn: "name") ### Fatal Errors -**Fatal errors notify that the program, or the database, has to be changed.** +**Fatal errors signal that the program, or the database, has to be changed.** They uncover programmer errors, false assumptions, and prevent misuses. Here are a few examples: @@ -5203,7 +5203,7 @@ while let row = try rows.next() { It has two opportunities to throw fatal errors: -- **Untrusted arguments**: The dictionary may contain values that do not conform to the [DatabaseValueConvertible protocol](#values), or may miss keys required by the statement. +- **Untrusted arguments**: The dictionary may contain values that do not conform to the [DatabaseValueConvertible protocol](#values), or may lack keys required by the statement. - **Untrusted database content**: The row may contain a non-null value that can't be turned into a date. In such a situation, you can still avoid fatal errors by exposing and handling each failure point, one level down in the GRDB API: @@ -5282,7 +5282,7 @@ Player.select { $0.name.uppercased } ### String Comparison -SQLite compares strings in many occasions: when you sort rows according to a string column, or when you use a comparison operator such as `=` and `<=`. +SQLite compares strings on many occasions: when you sort rows according to a string column, or when you use a comparison operator such as `=` and `<=`. The comparison result comes from a *collating function*, or *collation*. SQLite comes with three built-in collations that do not support Unicode: [binary, nocase, and rtrim](https://www.sqlite.org/datatype3.html#collation). @@ -5460,12 +5460,12 @@ Open a read-only connection to your resource: // Get the path to the database resource. if let dbPath = Bundle.main.path(forResource: "db", ofType: "sqlite") { // If the resource exists, open a read-only connection. - // Writes are disallowed because resources can not be modified. + // Writes are disallowed because resources cannot be modified. var config = Configuration() config.readonly = true let dbQueue = try DatabaseQueue(path: dbPath, configuration: config) } else { - // The database resource can not be found. + // The database resource cannot be found. // Fix your setup, or report the problem to the user. } ``` @@ -5743,7 +5743,7 @@ For example: - `player(id,name)[1]`: The `id` and `name` columns of the row with id 1 in the `player` table - `player(*),team(*)`: Both the full `player` and `team` tables -If you happen to use the `ValueObservation.trackingConstantRegion(_:)` method and see a mismatch between the tracked region and your expectation, then change the definition of your observation by using `tracking(_:)`. You should witness that the logs which start with `tracked region` now evolve in order to include the expected changes, and that you get the expected notifications. +If you happen to use the `ValueObservation.trackingConstantRegion(_:)` method and see a mismatch between the tracked region and your expectation, then change the definition of your observation by using `tracking(_:)`. You should see that the logs which start with `tracked region` now evolve in order to include the expected changes, and that you get the expected notifications. If after all those steps (thank you!), your observation is still failing you, please [open an issue](https://github.com/groue/GRDB.swift/issues/new) and provide a [minimal reproducible example](https://stackoverflow.com/help/minimal-reproducible-example)! @@ -5828,7 +5828,7 @@ When this is the case, there are two possible explanations: To find it, check the SQL statement that comes with the [DatabaseError](#databaseerror). -2. Maybe the application is using the character `"` instead of the single quote `'` as the delimiter for string literals in raw SQL queries. Recent versions of SQLite have learned to tell about this deviation from the SQL standard, and this is why you are seeing this error. +2. Maybe the application is using the character `"` instead of the single quote `'` as the delimiter for string literals in raw SQL queries. Recent versions of SQLite have learned to warn about this deviation from the SQL standard, and this is why you are seeing this error. For example: this is not standard SQL: `UPDATE player SET name = "Arthur"`. @@ -5921,7 +5921,7 @@ Sample Code - [Pierlis](http://pierlis.com), where we write great software. - [@alextrob](https://github.com/alextrob), [@alexwlchan](https://github.com/alexwlchan), [@bellebethcooper](https://github.com/bellebethcooper), [@bfad](https://github.com/bfad), [@cfilipov](https://github.com/cfilipov), [@charlesmchen-signal](https://github.com/charlesmchen-signal), [@Chiliec](https://github.com/Chiliec), [@chrisballinger](https://github.com/chrisballinger), [@darrenclark](https://github.com/darrenclark), [@davidkraus](https://github.com/davidkraus), [@eburns-vmware](https://github.com/eburns-vmware), [@felixscheinost](https://github.com/felixscheinost), [@fpillet](https://github.com/fpillet), [@gcox](https://github.com/gcox), [@GetToSet](https://github.com/GetToSet), [@gjeck](https://github.com/gjeck), [@guidedways](https://github.com/guidedways), [@gusrota](https://github.com/gusrota), [@haikusw](https://github.com/haikusw), [@hartbit](https://github.com/hartbit), [@holsety](https://github.com/holsety), [@jroselightricks](https://github.com/jroselightricks), [@kdubb](https://github.com/kdubb), [@kluufger](https://github.com/kluufger), [@KyleLeneau](https://github.com/KyleLeneau), [@layoutSubviews](https://github.com/layoutSubviews), [@mallman](https://github.com/mallman), [@MartinP7r](https://github.com/MartinP7r), [@Marus](https://github.com/Marus), [@mattgallagher](https://github.com/mattgallagher), [@MaxDesiatov](https://github.com/MaxDesiatov), [@michaelkirk-signal](https://github.com/michaelkirk-signal), [@mtancock](https://github.com/mtancock), [@pakko972](https://github.com/pakko972), [@peter-ss](https://github.com/peter-ss), [@pierlo](https://github.com/pierlo), [@pocketpixels](https://github.com/pocketpixels), [@pp5x](https://github.com/pp5x), [@professordeng](https://github.com/professordeng), [@robcas3](https://github.com/robcas3), [@runhum](https://github.com/runhum), [@sberrevoets](https://github.com/sberrevoets), [@schveiguy](https://github.com/schveiguy), [@SD10](https://github.com/SD10), [@sobri909](https://github.com/sobri909), [@sroddy](https://github.com/sroddy), [@steipete](https://github.com/steipete), [@swiftlyfalling](https://github.com/swiftlyfalling), [@Timac](https://github.com/Timac), [@tternes](https://github.com/tternes), [@valexa](https://github.com/valexa), [@wuyuehyang](https://github.com/wuyuehyang), [@ZevEisenberg](https://github.com/ZevEisenberg), and [@zmeyc](https://github.com/zmeyc) for their contributions, help, and feedback on GRDB. - [@aymerick](https://github.com/aymerick) and [@kali](https://github.com/kali) because SQL. -- [ccgus/fmdb](https://github.com/ccgus/fmdb) for its excellency. +- [ccgus/fmdb](https://github.com/ccgus/fmdb) for its excellence. ---