Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/vapor/postgres-kit
🐘 Non-blocking, event-driven Swift client for PostgreSQL.
https://github.com/vapor/postgres-kit
async postgresql server-side-swift sql swift vapor vapor-service
Last synced: about 2 months ago
JSON representation
🐘 Non-blocking, event-driven Swift client for PostgreSQL.
- Host: GitHub
- URL: https://github.com/vapor/postgres-kit
- Owner: vapor
- License: mit
- Created: 2018-01-14T06:33:00.000Z (almost 7 years ago)
- Default Branch: main
- Last Pushed: 2024-05-16T20:03:32.000Z (7 months ago)
- Last Synced: 2024-05-21T06:06:53.719Z (7 months ago)
- Topics: async, postgresql, server-side-swift, sql, swift, vapor, vapor-service
- Language: Swift
- Homepage:
- Size: 796 KB
- Stars: 182
- Watchers: 22
- Forks: 68
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
🐘 Non-blocking, event-driven Swift client for PostgreSQL.
### Usage
Use the SPM string to easily include the dependendency in your `Package.swift` file.
```swift
.package(url: "https://github.com/vapor/postgres-kit.git", from: "2.0.0")
```
### Supported Platforms
PostgresKit supports the following platforms:
- Ubuntu 20.04+
- macOS 10.15+
## Overview
PostgresKit is an [SQLKit] driver for PostgreSQL cliets. 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.
> [!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.
[SQLKit]: https://github.com/vapor/sql-kit
[PostgresNIO]: https://github.com/vapor/postgres-nio
[AsyncKit]: https://github.com/vapor/async-kit
[PostgresClient]: https://api.vapor.codes/postgresnio/documentation/postgresnio/postgresclient
### Configuration
Database connection options and credentials are specified using a `PostgresConfiguration` struct.
```swift
import PostgresKit
let configuration = PostgresConfiguration(
hostname: "localhost",
username: "vapor_username",
password: "vapor_password",
database: "vapor_database"
)
```
URL string based configuration is also supported.
```swift
guard let configuration = PostgresConfiguration(url: "postgres://...") else {
...
}
```
To connect via unix-domain sockets, use `unixDomainSocketPath` instead of `hostname` and `port`.
```swift
let configuration = PostgresConfiguration(
unixDomainSocketPath: "/path/to/socket",
username: "vapor_username",
password: "vapor_password",
database: "vapor_database"
)
```
### Connection Pool
Once you have a `PostgresConfiguration`, you can use it to create a connection source and pool.
```swift
let eventLoopGroup: EventLoopGroup = ...
defer { try! eventLoopGroup.syncShutdown() }
let pools = EventLoopGroupConnectionPool(
source: PostgresConnectionSource(configuration: configuration),
on: eventLoopGroup
)
defer { pools.shutdown() }
```
First create a `PostgresConnectionSource` using the configuration struct. This type is responsible for creating new connections to your database server as needed.
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.
`EventLoopGroupConnectionPool` is a collection of pools for each event loop. When using `EventLoopGroupConnectionPool` directly, random event loops will be chosen as needed.
```swift
pools.withConnection { conn
print(conn) // PostgresConnection on randomly chosen event loop
}
```
To get a pool for a specific event loop, use `pool(for:)`. This returns an `EventLoopConnectionPool`.
```swift
let eventLoop: EventLoop = ...
let pool = pools.pool(for: eventLoop)
pool.withConnection { conn
print(conn) // PostgresConnection on eventLoop
}
```
### PostgresDatabase
Both `EventLoopGroupConnectionPool` and `EventLoopConnectionPool` can be used to create instances of `PostgresDatabase`.
```swift
let postgres = pool.database(logger: ...) // PostgresDatabase
let rows = try postgres.simpleQuery("SELECT version();").wait()
```
Visit [PostgresNIO's docs](https://github.com/vapor/postgres-nio) for more information on using `PostgresDatabase`.
### SQLDatabase
A `PostgresDatabase` can be used to create an instance of `SQLDatabase`.
```swift
let sql = postgres.sql() // SQLDatabase
let planets = try sql.select().column("*").from("planets").all().wait()
```
Visit [SQLKit's docs](https://github.com/vapor/sql-kit) for more information on using `SQLDatabase`.