DatabasePool won't close read-only connections if requested, and ValueObservation no longer opens a new database connection when it starts

[groue]

This PR completes #1248, and aims at solving #1256:

• Enhances performances of ValueObservation on DatabasePool, because it no longer opens a new database connection when it starts.

• Allows applications to keep read-only connections open.

  Configuration has gained a persistentReadOnlyConnections property. The default is false: DatabasePool manages read-only connections in order to spare memory. When true, DatabasePool keeps read-only connections open.

  // Keep read-only connections open
  var config = Configuration()
  config.persistentReadOnlyConnections = true
  let dbPool = try DatabasePool(path: "...", configuration: config)

  When profiling your application reveals that a lot of time is spent opening a new SQLite connection at the wrong place:

  • Set persistentReadOnlyConnections to true.
  • Make sure the needed read-only connection was opened beforehand. A plain try dbPool.read { _ in }, for example, creates a read-only connection if no one is available yet. There's no built-in api for creating multiple read-only connections (open a feature request if you need this).
  • Check your eventual use of invalidateReadOnlyConnections(), because this method closes read-only connections regardless of the persistentReadOnlyConnections configuration.

---

Since #1248, ValueObservation on DatabasePool creates a new database connection when it starts, on the thread that starts the observation. #1256 has revealed that opening a connection can take a long time, with unfortunate consequences for the main thread :-/

In this PR, ValueObservation on DatabasePool just uses one of the available read-only connections:

• Starting a synchronous .immediate observation still blocks the main thread until the initial value is fetched, but no time is spent opening a new connection if there is an available read-only connection. If there is no available read-only connection, the main thread is blocked until one is opened, or becomes available. That's where persistentReadOnlyConnections is useful: it helps finding an available read-only connection, as long as the app has already performed reads before the observation starts.
• Starting an asynchronous observation schedules the fetch of the initial value and returns immediately. Again, persistentReadOnlyConnections is useful, because starting an observation asynchronously also needs an available read-only connection.

When WAL snapshots are available, a long-running transaction is kept opened on the read-only connection, until we can acquire a write access, compare database versions, perform a fetch+notification if and only if the database was modified, and start observing the write transactions. The ability to keep a long-running transaction (that spans several database accesses) on an existing reader is a new (internal) feature of this PR.

When WAL snapshots are not available (Xcode 14.0 and macOS, and some SQLCipher/SQLite builds), a double notification of the initial value is always performed, because we can't prove that the database was not changed between the initial fetch and the write access (we need WAL snapshots for that).

[groue]

Note to self: it could be useful for users to pre-heat reader connections, and also to prevent connections from being closed when the app reclaims memory (automatic on iOS apps when they enter background or receive a memory warning). TBD in another PR.

EDIT: addressed with the new persistentReadOnlyConnections mentioned in the PR summary above.

[rpassis]

Tested this with SQL_ENABLE_SNAPSHOT turned on and off.

In both scenarios the changes here drastically reduced the thread blocking we were experiencing with ValueObservation and SQLCipher when opening a database connection.

Turning the persistentReadOnlyConnections flag to true didn't seem to have a noticeable effect however it seems like it would be an effective solution to minimise opening of database connections for cases like ours where this operation can be process intensive.

I've left one minor comment on the documentation where you seem to be using a reentrant method but the documentation says otherwise.

Thanks for working on this fix so quickly, our team truly appreciates your efforts 👊👍💙

[groue]

Thank you for being so supportive, @rpassis and your team!! Without you, nothing would have happened 😃🎉

Now, on to v6.10.0!

[groue]

v6.10.0 has shipped