Documentation update

Author: trasch

README.md

@@ -13,7 +13,7 @@ This package requires Swift 5.7 or higher (at least Xcode 13), and compiles on m
 
 ```swift
 dependencies: [
-    .package(url: "https://github.com/Outdooractive/PostgresConnectionPool.git", from: "0.5.4"),
+    .package(url: "https://github.com/Outdooractive/PostgresConnectionPool.git", from: "0.5.5"),
 ],
 targets: [
     .target(name: "MyTarget", dependencies: [
@@ -29,19 +29,21 @@ Please see also the [API documentation](https://swiftpackageindex.com/Outdooract
 ``` swift
 import PostgresConnectionPool
 import PostgresKit
+import PostgresNIO
 
 var logger = Logger(label: "TestApp")
 logger.logLevel = .debug
 
-let connection = PoolConfiguration.Connection(
-    username: "testuser",
-    password: "testpassword",
+let postgresConfiguration = PostgresConnection.Configuration(
     host: "postgres",
     port: 5432,
-    database: "test")
+    username: "testuser",
+    password: "testpassword",
+    database: "test",
+    tls: .disable)
 let configuration = PoolConfiguration(
     applicationName: "TestApp",
-    connection: connection,
+    postgresConfiguration: postgresConfiguration,
     connectTimeout: 10.0,
     queryTimeout: 60.0,
     poolSize: 5,

Sources/PostgresConnectionPool/PoolConfiguration.swift

@@ -42,6 +42,7 @@ public struct PoolConfiguration {
     public let connectTimeout: TimeInterval
 
     /// TImeout for individual database queries, in seconds (default: none).
+    /// - warning: This includes the time the server needs to send the data to the client, so be careful over slow connections.
     public let queryTimeout: TimeInterval?
 
     /// The maximum number of open connections to the database (default: 10).
@@ -63,6 +64,15 @@ public struct PoolConfiguration {
     /// Called just before a connection is being closed.
     public var onCloseConnection: ((PostgresConnection, Logger) async throws -> Void)?
 
+    /// Pool configuation.
+    ///
+    /// - Parameters:
+    ///   - applicationName: The name used for database connections
+    ///   - postgresConfiguration: Connection parameters to the database
+    ///   - connectTimeout: Timeout for opening new connections
+    ///   - queryTimeout: TImeout for individual database queries
+    ///   - poolSize: The maximum number of open connections
+    ///   - maxIdleConnections: The maximum number of idle connections
     public init(
         applicationName: String,
         postgresConfiguration: PostgresConnection.Configuration,

Sources/PostgresConnectionPool/PoolConnectionState.swift

@@ -4,6 +4,7 @@
 
 import Foundation
 
+/// The possible states of a database connection.
 public enum PoolConnectionState: Equatable {
 
     /// The connection is in use.

Sources/PostgresConnectionPool/PoolError.swift

@@ -14,7 +14,7 @@ public enum PoolError: Error {
     case connectionFailed
     /// The pool was already shut down.
     case poolDestroyed
-    /// Some PostgreSQL error
+    /// Some PostgreSQL error.
     case postgresError(PSQLError)
     /// The query was cancelled by the server.
     case queryCancelled(query: String, runtime: Double)

Sources/PostgresConnectionPool/PoolInfo.swift

@@ -9,20 +9,32 @@ public struct PoolInfo {
 
     /// Information about an open connection.
     public struct ConnectionInfo {
+        /// The unique connection id.
         public let id: Int
+        /// The connection name on the server.
         public let name: String
+        /// Total number of queries that were sent over this connection.
         public let usageCounter: Int
+        /// The current query, if available.
         public let query: String?
+        /// The current time for the query, if available.
         public let queryRuntime: TimeInterval?
+        /// The state of the connection, see ``PoolConnectionState``.
         public let state: PoolConnectionState
     }
 
+    /// The name of the pool which is usually something like the Postgres connection string.
     public let name: String
+    /// The total number of open connections to the server.
     public let openConnections: Int
+    /// The number of connections that are currently in use.
     public let activeConnections: Int
+    /// The number of connections that are currently available.
     public let availableConnections: Int
+    /// The total number of queries that were sent to the server.
     public let usageCounter: Int
 
+    /// Information about individual open connections to the server.
     public let connections: [ConnectionInfo]
 
 }

Sources/PostgresConnectionPool/PostgresConnectionWrapper.swift

@@ -6,6 +6,7 @@ import Foundation
 import PostgresKit
 import PostgresNIO
 
+/// A wrapper around a postgres connection.
 public final class PostgresConnectionWrapper {
 
     private let poolConnection: PoolConnection
@@ -35,7 +36,9 @@ public final class PostgresConnectionWrapper {
 
             switch PostgresError.Code(raw: code) {
             case .queryCanceled:
-                throw PoolError.queryCancelled(query: connectionWrapper.poolConnection.query ?? "<unknown>", runtime: connectionWrapper.poolConnection.queryRuntime ?? 0.0)
+                throw PoolError.queryCancelled(
+                    query: connectionWrapper.poolConnection.query ?? "<unknown>",
+                    runtime: connectionWrapper.poolConnection.queryRuntime ?? 0.0)
             default:
                 throw PoolError.postgresError(error)
             }
@@ -54,11 +57,12 @@ public final class PostgresConnectionWrapper {
 
     // MARK: - Public interface, from PostgresConnection
 
-    /// A logger to use in case
+    /// The database logger.
     public var logger: Logger {
         postgresConnection.logger
     }
 
+    /// if the connection is closed (which would be an error).
     public var isClosed: Bool {
         postgresConnection.isClosed
     }
@@ -93,14 +97,19 @@ public final class PostgresConnectionWrapper {
         postgresConnection.sql(encoder: encoder, decoder: decoder)
     }
 
-    /// Add a handler for NotificationResponse messages on a certain channel. This is used in conjunction with PostgreSQL's `LISTEN`/`NOTIFY` support: to listen on a channel, you add a listener using this method to handle the NotificationResponse messages, then issue a `LISTEN` query to instruct PostgreSQL to begin sending NotificationResponse messages.
+    /// Add a handler for NotificationResponse messages on a certain channel.
+    ///
+    /// This is used in conjunction with PostgreSQL's `LISTEN`/`NOTIFY` support:
+    /// to listen on a channel, you add a listener using this method to handle the NotificationResponse messages,
+    /// then issue a `LISTEN` query to instruct PostgreSQL to begin sending NotificationResponse messages.
     @discardableResult
     public func addListener(
         channel: String,
         handler notificationHandler: @escaping (PostgresListenContext, PostgresMessage.NotificationResponse) -> Void)
         -> PostgresListenContext
     {
-        postgresConnection.addListener(channel: channel, handler: notificationHandler)
+        poolConnection.query = "LISTEN \(channel)"
+        return postgresConnection.addListener(channel: channel, handler: notificationHandler)
     }
 
 }