Expose query metadata

[MahdiBM]

Currently the functions that return PostgresRowSequence have no way of reporting back the metadata of the query.
This PR exposes the metadata.

Checklist

• Add PostgresConnection tests for the new query and execute funcs
• Add PostgresClient funcs + tests

[codecov]

Codecov Report

Attention: Patch coverage is 0% with 101 lines in your changes missing coverage. Please review.

Project coverage is 60.80%. Comparing base (5d817be) to head (61da70d).

Files with missing lines	Patch %	Lines
...es/PostgresNIO/Connection/PostgresConnection.swift	0.00%	55 Missing ⚠️
Sources/PostgresNIO/New/PSQLRowStream.swift	0.00%	46 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #504      +/-   ##
==========================================
- Coverage   61.39%   60.80%   -0.60%     
==========================================
  Files         125      125              
  Lines       10149    10250     +101     
==========================================
+ Hits         6231     6232       +1     
- Misses       3918     4018     +100     

Files with missing lines	Coverage Δ
Sources/PostgresNIO/New/PostgresRowSequence.swift	90.38% <ø> (ø)
Sources/PostgresNIO/New/PSQLRowStream.swift	75.14% <0.00%> (-11.23%)	⬇️
...es/PostgresNIO/Connection/PostgresConnection.swift	34.46% <0.00%> (-3.99%)	⬇️

... and 4 files with indirect coverage changes

[MahdiBM]

@fabianfett I've thought a bit more about this and possibly we might want to have another type that wraps PostgresRowSequence in the next major version at least? so we can expose more stuff in the response. Not only the metadata, but maybe even the connection properties? Or who knows what.
I don't have an immediate use-case for connection properties but it looks like some lost info. Maybe someone finds a value in them although they can also be individually queried.

[bridger]

I'd love this addition! I have queries that should update exactly 1 row. I'd like to check that the update was successful, but I can't check without the metadata. (These queries currently don't return the row itself.)

[fabianfett]

I'm not a fan of the proposed API changes: They either get everything into memory, or they force users to consume the rows synchronously. I consider both bad options.

However I do have an alternative in mind:

extension PostgresConnection {
    // use this for queries where you don't expect any rows back.
    @discardableResult
    func execute(_ query: PostgresQuery) async throws -> PostgresQueryMetadata

    // use this for queries where you want to consume the rows.
    // we can use the `consume` scope to better ensure structured concurrency when consuming the rows.
    func query<Result>(
        _ query: PostgresQuery, 
        _ consume: (PostgresRowSequence) async throws -> Result
    ) async throws -> (Result, PostgresQueryMetadata)
}

@MahdiBM Wdyt?

[MahdiBM]

I'm not a fan of the proposed API changes: They either get everything into memory, or they force users to consume the rows synchronously. I consider both bad options.

I honestly don't think this is a problem. We're not really taking any options away.

However I do have an alternative in mind:

To be honest this looks better, at least at the first glance. So I'd be happy to move this way.