Merge pull request #6 from Outdooractive/3_postgres_connection

#3: Use PostgresConnection.Configuration for the PostgreSQL connection configuration

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

@@ -9,6 +9,7 @@ import PostgresNIO
 public struct PoolConfiguration {
 
     /// PostgreSQL connection parameters.
+    @available(*, deprecated, message: "Use `PostgresConnection.Configuration` etc. instead.")
     public struct Connection {
         let username: String
         let password: String
@@ -35,12 +36,13 @@ public struct PoolConfiguration {
     public let applicationName: String
 
     /// Connection parameters to the database.
-    public let connection: Connection
+    public let postgresConfiguration: PostgresConnection.Configuration
 
     /// Timeout for opening new connections to the PostgreSQL database, in seconds (default: 5 seconds).
     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).
@@ -62,16 +64,25 @@ 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,
-        connection: Connection,
+        postgresConfiguration: PostgresConnection.Configuration,
         connectTimeout: TimeInterval = 5.0,
         queryTimeout: TimeInterval? = nil,
         poolSize: Int = 10,
         maxIdleConnections: Int? = nil)
     {
         self.applicationName = applicationName
-        self.connection = connection
+        self.postgresConfiguration = postgresConfiguration
         self.connectTimeout = connectTimeout.atLeast(1.0)
         self.queryTimeout = queryTimeout?.atLeast(1.0)
         self.poolSize = poolSize.atLeast(1)
@@ -82,4 +93,28 @@ public struct PoolConfiguration {
         }
     }
 
+    @available(*, deprecated, message: "Use `init(applicationName:postgresConfiguration:connectTimeout:queryTimeout:poolSize:maxIdleConnections:)` instead.")
+    public init(
+        applicationName: String,
+        connection: Connection,
+        connectTimeout: TimeInterval = 5.0,
+        queryTimeout: TimeInterval? = nil,
+        poolSize: Int = 10,
+        maxIdleConnections: Int? = nil)
+    {
+        let postgresConfiguration = PostgresConnection.Configuration(
+            host: connection.host,
+            port: connection.port,
+            username: connection.username,
+            password: connection.password,
+            database: connection.database,
+            tls: .disable)
+        self.init(applicationName: applicationName,
+                  postgresConfiguration: postgresConfiguration,
+                  connectTimeout: connectTimeout,
+                  queryTimeout: queryTimeout,
+                  poolSize: poolSize,
+                  maxIdleConnections: maxIdleConnections)
+    }
+
 }

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/PostgresConnectionPool.swift

@@ -48,22 +48,32 @@ public actor PostgresConnectionPool {
         self.eventLoopGroup = MultiThreadedEventLoopGroup(numberOfThreads: configuration.poolSize * 2)
 
         self.connectionName = String(configuration.applicationName.replacingPattern("[^-\\w\\d\\s()]", with: "").prefix(PostgresConnectionPool.postgresMaxNameLength))
-        self.poolName = "\(configuration.connection.username)@\(configuration.connection.host):\(configuration.connection.port)/\(configuration.connection.database)"
         self.poolSize = configuration.poolSize
         self.maxIdleConnections = configuration.maxIdleConnections
         self.queryTimeout = configuration.queryTimeout
 
+        let dbUsername = configuration.postgresConfiguration.username
+        let dbDatabase = configuration.postgresConfiguration.database ?? dbUsername
+        if let host = configuration.postgresConfiguration.host,
+           let port = configuration.postgresConfiguration.port
+        {
+            self.poolName = "\(dbUsername)@\(host):\(port)/\(dbDatabase)"
+        }
+        else if let unixSocketPath = configuration.postgresConfiguration.unixSocketPath {
+            self.poolName = "postgresql:///\(dbDatabase)?user=\(dbUsername)&host=\(unixSocketPath)"
+        }
+        else if let channel = configuration.postgresConfiguration.establishedChannel {
+            self.poolName = "\(dbUsername)@EstablishedChannel<\(channel)>/\(dbDatabase)"
+        }
+        else {
+            self.poolName = "<Unknown connection>"
+        }
+
         self.onOpenConnection = configuration.onOpenConnection
         self.onReturnConnection = configuration.onReturnConnection
         self.onCloseConnection = configuration.onCloseConnection
 
-        var postgresConfiguration = PostgresConnection.Configuration(
-            host: configuration.connection.host,
-            port: configuration.connection.port,
-            username: configuration.connection.username,
-            password: configuration.connection.password,
-            database: configuration.connection.database,
-            tls: .disable)
+        var postgresConfiguration = configuration.postgresConfiguration
         postgresConfiguration.options.connectTimeout = .seconds(Int64(configuration.connectTimeout))
         self.postgresConfiguration = postgresConfiguration
     }

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)
     }
 
 }