🐘 Non-blocking, event-driven Swift client for PostgreSQL.
Use the SPM string to easily include the dependendency in your Package.swift file.
.package(url: "https://github.com/vapor/postgres-kit.git", from: "2.0.0")PostgresKit supports the following platforms:
- Ubuntu 20.04+
- macOS 10.15+
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 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.
Database connection options and credentials are specified using a PostgresConfiguration struct.
import PostgresKit
let configuration = PostgresConfiguration(
hostname: "localhost",
username: "vapor_username",
password: "vapor_password",
database: "vapor_database"
)URL string based configuration is also supported.
guard let configuration = PostgresConfiguration(url: "postgres://...") else {
...
}To connect via unix-domain sockets, use unixDomainSocketPath instead of hostname and port.
let configuration = PostgresConfiguration(
unixDomainSocketPath: "/path/to/socket",
username: "vapor_username",
password: "vapor_password",
database: "vapor_database"
)Once you have a PostgresConfiguration, you can use it to create a connection source and pool.
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. 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.
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.
let eventLoop: EventLoop = ...
let pool = pools.pool(for: eventLoop)
pool.withConnection { conn
print(conn) // PostgresConnection on eventLoop
}Both EventLoopGroupConnectionPool and EventLoopConnectionPool can be used to create instances of PostgresDatabase.
let postgres = pool.database(logger: ...) // PostgresDatabase
let rows = try postgres.simpleQuery("SELECT version();").wait()Visit PostgresNIO's docs for more information on using PostgresDatabase.
A PostgresDatabase can be used to create an instance of SQLDatabase.
let sql = postgres.sql() // SQLDatabase
let planets = try sql.select().column("*").from("planets").all().wait()Visit SQLKit's docs for more information on using SQLDatabase.