You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Bump Swift min to 5.10, update README and API docs, clean up some doc comments, run swift-format, fix warning about retroactive conformance in 6.2.
* Apply PR feedback
* Fixup those darn docs
🐘 Non-blocking, event-driven Swift client for PostgreSQL.
15
+
PostgresKit is an [SQLKit] driver for PostgreSQL clients.
16
+
17
+
## Overview
18
+
19
+
PostgresKit supports building and serializing Postgres-dialect SQL queries using [SQLKit]'s API. PostgresKit uses [PostgresNIO] to connect and communicate with the database server asynchronously. [AsyncKit] is used to provide connection pooling.
20
+
21
+
> Important: It is strongly recommended that users who leverage PostgresKit directly (e.g. absent the Fluent ORM layer) take advantage of PostgresNIO's [PostgresClient] API for connection management rather than relying upon the legacy AsyncKit API.
20
22
21
23
### Usage
22
24
23
-
Use the SPM string to easily include the dependendency in your `Package.swift`file.
25
+
Reference this package in your `Package.swift`to include it in your project.
@@ -33,42 +35,30 @@ PostgresKit supports the following platforms:
33
35
- Ubuntu 20.04+
34
36
- macOS 10.15+
35
37
36
-
## Overview
37
-
38
-
PostgresKit is an [SQLKit] driver for PostgreSQL clients. It supports building and serializing Postgres-dialect SQL queries. PostgresKit uses [PostgresNIO] to connect and communicate with the database server asynchronously. [AsyncKit](https://github.com/vapor/async-kit) is used to provide connection pooling.
39
-
40
-
> [!IMPORTANT]
41
-
> It is strongly recommended that users who leverage PostgresKit directly (e.g. absent the Fluent ORM layer) take advantage of PostgresNIO's [PostgresClient] API for connection management rather than relying upon the legacy AsyncKit API.
To connect via unix-domain sockets, use `unixDomainSocketPath` instead of `hostname` and `port`.
61
+
To connect via unix-domain sockets, use ``SQLPostgresConfiguration/init(unixDomainSocketPath:username:password:database:)`` instead of ``SQLPostgresConfiguration/init(hostname:port:username:password:database:tls:)``.
72
62
73
63
```swift
74
64
let configuration =PostgresConfiguration(
@@ -81,22 +71,22 @@ let configuration = PostgresConfiguration(
81
71
82
72
### Connection Pool
83
73
84
-
Once you have a `PostgresConfiguration`, you can use it to create a connection source and pool.
74
+
Once you have a ``SQLPostgresConfiguration``, you can use it to create a connection source and pool.
85
75
86
76
```swift
87
-
let eventLoopGroup: EventLoopGroup =...
88
-
defer { try! eventLoopGroup.syncShutdown() }
89
-
77
+
let eventLoopGroup: EventLoopGroup = NIOSingletons.posixEventLoopGroup
First create a `PostgresConnectionSource` using the configuration struct. This type is responsible for creating new connections to your database server as needed.
87
+
First create a ``PostgresConnectionSource`` using the configuration struct. This type is responsible for creating new connections to your database server as needed.
98
88
99
-
Next, use the connection source to create an `EventLoopGroupConnectionPool`. You will also need to pass an `EventLoopGroup`. For more information on creating an `EventLoopGroup`, visit SwiftNIO's [documentation](https://apple.github.io/swift-nio/docs/current/NIO/index.html). Make sure to shutdown the connection pool before it deinitializes.
89
+
Next, use the connection source to create an `EventLoopGroupConnectionPool`. You will also need to pass an `EventLoopGroup`. For more information on creating an `EventLoopGroup`, visit [SwiftNIO's documentation]. Make sure to shutdown the connection pool before it deinitializes.
100
90
101
91
`EventLoopGroupConnectionPool` is a collection of pools for each event loop. When using `EventLoopGroupConnectionPool` directly, random event loops will be chosen as needed.
PostgresKit is a library providing an SQLKit driver for PostgresNIO.
7
+
PostgresKit is an [SQLKit] driver for PostgreSQL clients.
8
8
9
9
## Overview
10
10
11
-
This package provides the "foundational" level of support for using [Fluent] with PostgreSQL by implementing the requirements of an [SQLKit] driver. It is responsible for:
11
+
PostgresKit supports building and serializing Postgres-dialect SQL queries using [SQLKit]'s API. PostgresKit uses [PostgresNIO] to connect and communicate with the database server asynchronously. [AsyncKit] is used to provide connection pooling.
12
12
13
-
- Managing the underlying PostgreSQL library ([PostgresNIO]),
14
-
- Providing a two-way bridge between PostgresNIO and SQLKit's generic data and metadata formats, and
15
-
- Presenting an interface for establishing, managing, and interacting with database connections via [AsyncKit].
13
+
> Important: It is strongly recommended that users who leverage PostgresKit directly (e.g. absent the Fluent ORM layer) take advantage of PostgresNIO's [PostgresClient] API for connection management rather than relying upon the legacy AsyncKit API.
16
14
17
-
> Important: It is strongly recommended that users who leverage PostgresKit directly (e.g. absent the Fluent ORM layer) take advantage of PostgresNIO's [PostgresClient] API for connection management rather than relying upon the legacy AsyncKit-based support.
15
+
### Usage
18
16
19
-
> Tip: A FluentKit driver for PostgreSQL is provided by the [FluentPostgresDriver] package.
17
+
Reference this package in your `Package.swift` to include it in your project.
This package uses [PostgresNIO] for all underlying database interactions. It is compatible with all versions of PostgreSQL and all platforms supported by that package.
23
+
### Supported Platforms
24
24
25
-
> Caution: There is one exception to the above at the time of this writing: This package requires Swift 5.8 or newer, whereas PostgresNIO continues to support Swift 5.6.
To connect via unix-domain sockets, use ``SQLPostgresConfiguration/init(unixDomainSocketPath:username:password:database:)`` instead of ``SQLPostgresConfiguration/init(hostname:port:username:password:database:tls:)``.
54
+
55
+
```swift
56
+
let configuration =PostgresConfiguration(
57
+
unixDomainSocketPath: "/path/to/socket",
58
+
username: "vapor_username",
59
+
password: "vapor_password",
60
+
database: "vapor_database"
61
+
)
62
+
```
63
+
64
+
### Connection Pool
65
+
66
+
Once you have a ``SQLPostgresConfiguration``, you can use it to create a connection source and pool.
67
+
68
+
```swift
69
+
let eventLoopGroup: EventLoopGroup = NIOSingletons.posixEventLoopGroup
First create a ``PostgresConnectionSource`` using the configuration struct. This type is responsible for creating new connections to your database server as needed.
80
+
81
+
Next, use the connection source to create an `EventLoopGroupConnectionPool`. You will also need to pass an `EventLoopGroup`. For more information on creating an `EventLoopGroup`, visit [SwiftNIO's documentation]. Make sure to shutdown the connection pool before it deinitializes.
82
+
83
+
`EventLoopGroupConnectionPool` is a collection of pools for each event loop. When using `EventLoopGroupConnectionPool` directly, random event loops will be chosen as needed.
84
+
85
+
```swift
86
+
pools.withConnection { conn
87
+
print(conn) // PostgresConnection on randomly chosen event loop
88
+
}
89
+
```
90
+
91
+
To get a pool for a specific event loop, use `pool(for:)`. This returns an `EventLoopConnectionPool`.
92
+
93
+
```swift
94
+
let eventLoop: EventLoop =...
95
+
let pool = pools.pool(for: eventLoop)
96
+
97
+
pool.withConnection { conn
98
+
print(conn) // PostgresConnection on eventLoop
99
+
}
100
+
```
101
+
102
+
### PostgresDatabase
103
+
104
+
Both `EventLoopGroupConnectionPool` and `EventLoopConnectionPool` can be used to create instances of `PostgresDatabase`.
105
+
106
+
```swift
107
+
let postgres = pool.database(logger: ...) // PostgresDatabase
108
+
let rows =try postgres.simpleQuery("SELECT version();").wait()
109
+
```
110
+
111
+
Visit [PostgresNIO's docs] for more information on using `PostgresDatabase`.
112
+
113
+
### SQLDatabase
114
+
115
+
A `PostgresDatabase` can be used to create an instance of `SQLDatabase`.
116
+
117
+
```swift
118
+
let sql = postgres.sql() // SQLDatabase
119
+
let planets =try sql.select().column("*").from("planets").all().wait()
120
+
```
121
+
122
+
Visit [SQLKit's docs] for more information on using `SQLDatabase`.
0 commit comments