Add DatabaseValueConvertible tip for JSON columns

[bok-]

This PR adds a tip to the JSON page of the DocC docs about conforming your JSON column's Codable property to DatabaseValueConvertible for filtering. Adding my first JSON column and this would have saved me a couple of hours of digging.

Please feel free to rewrite if it doesn't match the tone or intent of existing documentation.

Pull Request Checklist

• CONTRIBUTING: You have read https://github.com/groue/GRDB.swift/blob/master/CONTRIBUTING.md
• BRANCH: This pull request is submitted against the development branch.
• DOCUMENTATION: Inline documentation has been updated.
• DOCUMENTATION: README.md or another dedicated guide has been updated.
• TESTS: Changes are tested.
• TESTS: The make smokeTest terminal command runs without failure.

[groue]

Hello @bok-,

Thank you for sharing your experience and suggesting this tip in the documentation!

I'm happy if your application can profit from this technique, because it is handy.

Now, the sample code has SQLite perform string comparison, which is sensitive to white space and key ordering, etc. It only works reliably if all database values in the address column have the exact same format as a serialized Address instance.

If this precondition is not fulfilled, the test will fail to match some addresses. There are plenty of reasons:

• Some database addresses are produced by something else than a serialized Address.
• The Address type has evolved over time, but the json columns were not migrated.
• The JSONEncoder used by Address was customized and misses the .sortedKeys output formatting option.
• etc.

In summary:

• Not all apps can use this technique.
• All developers that want to use this technique must understand the precondition and its consequences.
• The precondition can not be tested. One can assert that one particular database works as expected, but it can't be asserted that all databases comply.
• Failure may never happen on the developer's machine, or in the test suite, but it may happen on a user's device (immensely difficult to notice and debug).
• Implementing the precondition as a CHECK constraint looks overwhelmingly hard and inefficient at runtime.

In summary, this technique is a clever hack. I love clever hacks, but documentation must not drive users into writing code that may fail them at some point. They would be upset, and rightly so.

Primum non nocere.

[groue]

Maybe it is possible to find a short and clear way to express the precondition.

What about:

Tip: Conform your Codable property to DatabaseValueConvertible if you want to be able to filter on specific values of it:

extension Address: DatabaseValueConvertible {}

// SELECT * FROM player
// WHERE "address" = '{"street": "...", "city": "...",  "country": "..."}'
let players = try Player
    .filter(JSONColumn("address") == Address(...))
    .fetchAll(db)

Take care that SQLite will compare strings, not JSON objects: make sure that the database contains values that are formatted exactly like a serialized Address (white-space, key ordering, etc.)

[groue]

I made up my mind :-) I hope you'll agree with this little amendment.

[groue]

Merged :-) Thank you @bok- 👍

[groue]

⛵ Shipped in 7.0.0-beta.3

[bok-]

Forgot to come back to this one! Yep totally agree with the improved wording and the warning about consequences! Thanks very much 🙏