Swiftpack.co - Package - vapor/postgres-kit
PostgresKit
Documentation Team Chat MIT License Continuous Integration Swift 5.2

🐘 Non-blocking, event-driven Swift client for PostgreSQL.

Major Releases

The table below shows a list of PostgresKit major releases alongside their compatible NIO and Swift versions.

|Version|NIO|Swift|SPM| |-|-|-|-| |2.0|2.0|5.2+|from: "2.0.0"| |1.0|1.0|4.0+|from: "1.0.0"|

Use the SPM string to easily include the dependendency in your Package.swift file.

.package(url: "https://github.com/vapor/postgres-kit.git", from: ...)

Supported Platforms

PostgresKit supports the following platforms:

  • Ubuntu 16.04+
  • macOS 10.15+

Overview

PostgresKit is a PostgreSQL client library built on SQLKit. 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.

Configuration

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

Connection Pool

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
}

PostgresDatabase

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.

SQLDatabase

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.

Github

link
Stars: 76

Releases

Fix force unwrap in PostgresDataDecoder - 2020-05-01 19:30:48

This patch was authored by @SusanDoggie and released by @tanner0101.

Replaces a force unwrap with a DecodingError in PostgresDataDecoder (#184).

PostgresKit 2.0.0 - 2020-04-29 13:54:19

Docs: https://github.com/vapor/postgres-kit/blob/master/README.md

More information on Vapor 4 official release: https://forums.swift.org/t/vapor-4-official-release-begins/34802

Use default port for URLs - 2020-04-23 15:23:38

This patch was authored by @vknabel and released by @tanner0101.

Adds support for database urls not containing an explicit port: postgres://user:password@localhost/database (#183).

Fix not-regexp operator, add case insensitive regexp operators - 2020-03-31 16:40:47

Fixes the notRegexp operator and adds the two case-insensitive variants (#139, #90).

See the pgsql docs for reference.

Fix assertion while decoding JSON (non-JSONB) - 2020-03-30 17:45:58

Fixes JSON / JSONB decoding for text and binary serializations (#177).

Add EventLoopGroupConnectionPool database convenience - 2020-03-06 02:54:23

This patch was authored and released by @tanner0101.

Adds a method for creating a PostgresDatabase from an EventLoopGroupConnectionPool.

let db = pool.database(logger: .init(label: "test"))

Release Candidate 1 - 2020-02-28 21:20:34

Updates to Swift 5.2 and macOS 10.15.

Release candidates represent the final shift toward focusing on bug fixes and documentation. Breaking changes will only be accepted for critical issues. We expect a final release of this package shortly after Swift 5.2's release date.

Alter table syntax - 2020-02-21 00:08:34

Implement Postgres alter table syntax in SQLDialect.

Support encoding non-JSON arrays - 2020-02-20 06:21:26

Adds support for encoding arrays that contain values besides nested structs (JSON and JSONB).

Added create/drop trigger dialect conditions - 2020-02-13 21:13:26

Updates the package to specify syntax that PostgreSQL supports for triggers.

Add support for configuring connections via UNIX domain socket - 2020-02-12 23:33:38

Add support for configuring connections via UNIX domain socket (#170).

PostgresConfiguration(
    unixDomainSocketPath: "/tmp/.s.PGSQL.5432",
    username: "postgres",
    password: "postgres",
    database: "postgres"
)

Support JSON or JSONB for decoding structs - 2020-01-22 22:01:42

Adds support for both JSON and JSONB data types when decoding nested structs. Error messages in PostgresDataDecoder have also been improved.

Enum Support - 2020-01-22 03:00:08

https://github.com/vapor/sql-kit/pull/85

Improved PostgresConfiguration(url:) support - 2020-01-15 22:35:39

  • Adds support for URLs with scheme postgres:// and postgresql://
  • Adds support for sslmode=require query string
  • TLS certificate verification is now enabled by default

PostgresKit 2.0.0 Beta 3.1 - 2019-12-13 23:52:16

  • Fix a bug decoding nil values (#162)

PostgresKit 2.0.0 Beta 3 - 2019-12-13 22:05:57

Refactors PostgresDataEncoder to be more flexible. There are now three distinct paths for encoding:

  • Single value: Cast to PostgresDataConvertible, if fail, unwrap and try again
  • Unkeyed value: Convert to JSONB[]
  • Keyed value: Convert to JSONB

Refactors PostgresDataDecoder to operate similarly.

Also updates PostgresRow's SQLRow conformance to latest changes.

PostgresKit 2.0.0 Beta 2.2 - 2019-12-11 17:25:23

  • Support custom JSON coders in PostgresDataEncoder and PostgresDataDecoder (#159)

PostgresKit 2.0.0 Beta 2.1 - 2019-12-11 00:38:41

  • PostgresDataEncoder/Decoder now support arrays (#160)

PostgresKit 2.0.0 Beta 2 - 2019-12-09 19:16:43

  • Added support for custom Logger passing. (#156)

  • Fixed a bug encoding JSONB data.

  • Added a test for leaking promises (#155)

  • Enabled test discovery on Linux. (#158)

PostgresKit 2.0.0 Beta 1 - 2019-10-24 23:26:06

Update to AsyncKit 1.0.0 Beta 1.

PostgreSQL 1.5.0 - 2019-10-14 23:34:37

  • Fixed PostgresError.stackTrace conformance to Debuggable. (#146, #147)

⚠️ This is technically a breaking change if you use PostgresError.stackTrace directly. However, this is normally accessed via Debuggable conformance so most users should not be affected.

PostgresKit 2.0.0 Alpha 2.1 - 2019-09-23 21:55:30

  • Connections from PostgresConnectionSource are now closed properly if authentication fails. (#144)

PostgreSQL 1.4.2 - 2019-09-08 09:07:01

Fixed:

  • Decoding an array with a NULL value in it no longer crashes (#141 - #142).

PostgresKit 2.0.0 Alpha 2 - 2019-08-02 18:38:31

  • Implemented missing methods in PostgresDataDecoder and PostgresDataEncoder.

PostgresKit 2.0.0 Alpha 1 - 2019-06-06 20:20:59

More information on Vapor 4 alpha releases:

https://medium.com/@codevapor/vapor-4-alpha-1-releases-begin-94a4bc79dd9a

API Docs:

https://api.vapor.codes/postgres-kit/master/PostgresKit/index.html

PostgreSQL 1.4.1 - 2019-03-14 18:19:43

Fixed:

  • Improved row decoding performance. (#134)

PostgreSQL 1.4.0 - 2019-03-01 02:46:45

New:

  • Added a new PostgreSQLPolygon type for interacting with POLYGON columns. (#129)

PostgreSQL 1.3.0 - 2019-02-26 19:54:58

Fixed:

  • PostgreSQLPoint now encodes and decodes endianness correctly. (#125, #126)

⚠️ If you were using PostgreSQLPoint prior to this patch, your database may be storing point columns with flipped endianness. After this patch, points will be fetched and saved using the correct format, meaning old values may now be flipped. Use the following helper method to flip PostgreSQLPoint endianness.

let x = PostgreSQLPoint(x: 3.14, y: -42).endiannessflipped()
print(x)

PostgreSQL 1.2.2 - 2019-02-19 15:58:22

Fixed:

  • Fixed keyed PostgreSQLData encoding for empty containers. (#123)
  • Fixed a reference cycle in PostgreSQLConnection. (#116)

PostgreSQL 1.2.1 - 2019-02-12 20:52:06

Fixed:

  • Added swift-nio-ssl as an explicit dependency. (#121)