Skip to content

Commit 80bd77f

Browse files
gwynnegwynne
committed
Add some docs notes about use with PostgresClient. Also bump CI.
1 parent cd2ff69 commit 80bd77f

File tree

3 files changed

+118
-6
lines changed

3 files changed

+118
-6
lines changed

‎.github/workflows/test.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -156,6 +156,6 @@ jobs:
156156
- name: Check out code
157157
uses: actions/checkout@v6
158158
- name: Install SDK
159-
run: swift sdk install https://download.swift.org/swift-6.2-release/static-sdk/swift-6.2-RELEASE/swift-6.2-RELEASE_static-linux-0.0.1.artifactbundle.tar.gz --checksum d2225840e592389ca517bbf71652f7003dbf45ac35d1e57d98b9250368769378
159+
run: swift sdk install https://download.swift.org/swift-6.2.3-release/static-sdk/swift-6.2.3-RELEASE/swift-6.2.3-RELEASE_static-linux-0.0.1.artifactbundle.tar.gz --checksum f30ec724d824ef43b5546e02ca06a8682dafab4b26a99fbb0e858c347e507a2c
160160
- name: Build
161161
run: swift build --swift-sdk x86_64-swift-linux-musl

‎README.md‎

Lines changed: 59 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -61,15 +61,72 @@ guard let configuration = SQLPostgresConfiguration(url: "postgres://...") else {
6161
To connect via unix-domain sockets, use ``SQLPostgresConfiguration/init(unixDomainSocketPath:username:password:database:)`` instead of ``SQLPostgresConfiguration/init(hostname:port:username:password:database:tls:)``.
6262

6363
```swift
64-
let configuration = PostgresConfiguration(
64+
let configuration = SQLPostgresConfiguration(
6565
unixDomainSocketPath: "/path/to/socket",
6666
username: "vapor_username",
6767
password: "vapor_password",
6868
database: "vapor_database"
6969
)
7070
```
7171

72-
### Connection Pool
72+
### Connection Pool (Modern PostgresNIO)
73+
74+
You don't need a ``SQLPostgresConfiguration`` to create a `PostgresClient`, an instance of PostgresNIO's modern connection pool. Instead, use `PostgresClient`'s native configuration type:
75+
76+
```swift
77+
let configuration = PostgresClient.Configuration(
78+
host: "localhost",
79+
username: "vapor_username",
80+
password: "vapor_password",
81+
database: "vapor_database",
82+
tls: .prefer(.makeClientConfiguration())
83+
)
84+
let psqlClient = PostgresClient(configuration: configuration)
85+
86+
// Start a Task to run the client:
87+
let clientTask = Task { await client.run() }
88+
// Or, if you're using ServiceLifecycle, add the client to a ServiceGroup:
89+
await serviceGroup.addServiceUnlessShutdown(client)
90+
```
91+
92+
You can then lease a `PostgresConnection` from the client:
93+
94+
```swift
95+
try await client.withConnection { conn in
96+
print(conn) // PostgresConnection managed by PostgresClient's connection pool
97+
}
98+
```
99+
100+
> [!NOTE]
101+
> `PostgresClient.Configuration` does not support URL-based configuration. If you want to handle URLs, you can create an instance of `SQLPostgresConfiguration` and translate it into a `PostgresClient.Configuration`:
102+
>
103+
> ```swift
104+
> extension PostgresClient.Configuration {
105+
> init(from configuration: PostgresConnection.Configuration) {
106+
> let tls: PostgresClient.Configuration.TLS = switch (configuration.tls.isEnforced, configuration.tls.isAllowed) {
107+
> case (true, _): .require(configuration.tls.sslContext!.configuration)
108+
> case (_, true): .prefer(configuration.tls.sslContext!.configuration)
109+
> default: .disable
110+
> }
111+
>
112+
> if let host = configuration.host, let port = configuration.port {
113+
> self.init(host: host, port: port, username: configuration.username, password: configuration.password, database: configuration.database, tls: tls)
114+
> } else if let socket = configuration.unixSocketPath {
115+
> self.init(unixSocketPath: socket, username: configuration.username, password: configuration.password, database: configuration.database)
116+
> } else {
117+
> fatalError("Preconfigured channels not supported")
118+
> }
119+
> }
120+
> }
121+
>
122+
> guard let sqlConfiguration = SQLPostgresConfiguration(url: "...") else { ... }
123+
> let clientConfiguration = PostgresClient.Configuration(configuration: sqlConfiguration.coreConfiguration)
124+
> ```
125+
126+
### Connection Pool (Legacy AsyncKit)
127+
128+
> [!WARNING]
129+
> AsyncKit is deprecated; using it is strongly discouraged. You should not use this setup unless you are also working with FluentKit, which at the time of this writing is not compatible with `PostgresClient`.
73130
74131
Once you have a ``SQLPostgresConfiguration``, you can use it to create a connection source and pool.
75132

‎Sources/PostgresKit/Docs.docc/PostgresKit.md‎

Lines changed: 58 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -53,15 +53,70 @@ guard let configuration = SQLPostgresConfiguration(url: "postgres://...") else {
5353
To connect via unix-domain sockets, use ``SQLPostgresConfiguration/init(unixDomainSocketPath:username:password:database:)`` instead of ``SQLPostgresConfiguration/init(hostname:port:username:password:database:tls:)``.
5454

5555
```swift
56-
let configuration = PostgresConfiguration(
56+
let configuration = SQLPostgresConfiguration(
5757
unixDomainSocketPath: "/path/to/socket",
5858
username: "vapor_username",
5959
password: "vapor_password",
6060
database: "vapor_database"
6161
)
6262
```
6363

64-
### Connection Pool
64+
### Connection Pool (Modern PostgresNIO)
65+
66+
You don't need a ``SQLPostgresConfiguration`` to create a `PostgresClient`, an instance of PostgresNIO's modern connection pool. Instead, use `PostgresClient`'s native configuration type:
67+
68+
```swift
69+
let configuration = PostgresClient.Configuration(
70+
host: "localhost",
71+
username: "vapor_username",
72+
password: "vapor_password",
73+
database: "vapor_database",
74+
tls: .prefer(.makeClientConfiguration())
75+
)
76+
let psqlClient = PostgresClient(configuration: configuration)
77+
78+
// Start a Task to run the client; be sure you cancel this task before exiting:
79+
let clientTask = Task { await psqlClient.run() }
80+
// Or, if you're using ServiceLifecycle, add the client to a ServiceGroup:
81+
await serviceGroup.addServiceUnlessShutdown(psqlClient)
82+
```
83+
84+
You can then lease a `PostgresConnection` from the client:
85+
86+
```swift
87+
try await client.withConnection { conn in
88+
print(conn) // PostgresConnection managed by PostgresClient's connection pool
89+
}
90+
```
91+
92+
> Note: `PostgresClient.Configuration` does not support URL-based configuration. If you want to handle URLs, you can create an instance of `SQLPostgresConfiguration` and translate it into a `PostgresClient.Configuration`:
93+
>
94+
> ```swift
95+
> extension PostgresClient.Configuration {
96+
> init(from configuration: PostgresConnection.Configuration) {
97+
> let tls: PostgresClient.Configuration.TLS = switch (configuration.tls.isEnforced, configuration.tls.isAllowed) {
98+
> case (true, _): .require(configuration.tls.sslContext!.configuration)
99+
> case (_, true): .prefer(configuration.tls.sslContext!.configuration)
100+
> default: .disable
101+
> }
102+
>
103+
> if let host = configuration.host, let port = configuration.port {
104+
> self.init(host: host, port: port, username: configuration.username, password: configuration.password, database: configuration.database, tls: tls)
105+
> } else if let socket = configuration.unixSocketPath {
106+
> self.init(unixSocketPath: socket, username: configuration.username, password: configuration.password, database: configuration.database)
107+
> } else {
108+
> fatalError("Preconfigured channels not supported")
109+
> }
110+
> }
111+
> }
112+
>
113+
> guard let sqlConfiguration = SQLPostgresConfiguration(url: "...") else { ... }
114+
> let clientConfiguration = PostgresClient.Configuration(configuration: sqlConfiguration.coreConfiguration)
115+
> ```
116+
117+
### Connection Pool (Legacy AsyncKit)
118+
119+
> Warning: AsyncKit is deprecated; using it is strongly discouraged. You should not use this setup unless you are also working with FluentKit, which at the time of this writing is not compatible with `PostgresClient`.
65120
66121
Once you have a ``SQLPostgresConfiguration``, you can use it to create a connection source and pool.
67122
@@ -83,7 +138,7 @@ Next, use the connection source to create an `EventLoopGroupConnectionPool`. You
83138
`EventLoopGroupConnectionPool` is a collection of pools for each event loop. When using `EventLoopGroupConnectionPool` directly, random event loops will be chosen as needed.
84139

85140
```swift
86-
pools.withConnection { conn
141+
pools.withConnection { conn in
87142
print(conn) // PostgresConnection on randomly chosen event loop
88143
}
89144
```

0 commit comments

Comments
 (0)