codewinsdotcom/PostgresClientKit

README

PostgresClientKit

Caution

This repository has been archived, and will no longer be updated or supported.

SwiftPostgresClient and PostgresNIO offer alternative Swift APIs for operating against a PostgreSQL database.

PostgresClientKit provides a friendly Swift API for operating against a PostgreSQL database.

Features

Doesn't require libpq. PostgresClientKit implements the Postgres network protocol in Swift, so it does not require libpq.
Developer-friendly API using modern Swift. For example, errors are represented by instances of enum PostgresError: Error and are raised by a throw or by returning a Result<Success, Error>.
Safe conversion between Postgres and Swift types. Type conversion is explicit and robust. Conversion errors are signaled, not masked. PostgresClientKit provides additional Swift types for dates and times to address the impedance mismatch between Postgres types and Foundation Date.
Memory efficient. The rows in a result are exposed through an iterator, not an array. Rows are lazily retrieved from the Postgres server.
SSL/TLS support. Encrypts the connection between PostgresClientKit and the Postgres server.
Well-engineered. Complete API documentation, an extensive test suite, actively supported.

Sounds good? Let's look at an example.

Example

This is a basic, but complete, example of how to connect to Postgres, perform a SQL SELECT command, and process the resulting rows. It uses the weather table in the Postgres tutorial.

import PostgresClientKit

do {
    var configuration = PostgresClientKit.ConnectionConfiguration()
    configuration.host = "127.0.0.1"
    configuration.database = "example"
    configuration.user = "bob"
    configuration.credential = .scramSHA256(password: "welcome1")

    let connection = try PostgresClientKit.Connection(configuration: configuration)
    defer { connection.close() }

    let text = "SELECT city, temp_lo, temp_hi, prcp, date FROM weather WHERE city = $1;"
    let statement = try connection.prepareStatement(text: text)
    defer { statement.close() }

    let cursor = try statement.execute(parameterValues: [ "San Francisco" ])
    defer { cursor.close() }

    for row in cursor {
        let columns = try row.get().columns
        let city = try columns[0].string()
        let tempLo = try columns[1].int()
        let tempHi = try columns[2].int()
        let prcp = try columns[3].optionalDouble()
        let date = try columns[4].date()
    
        print("""
            \(city) on \(date): low: \(tempLo), high: \(tempHi), \
            precipitation: \(String(describing: prcp))
            """)
    }
} catch {
    print(error) // better error handling goes here
}

Output:

San Francisco on 1994-11-27: low: 46, high: 50, precipitation: Optional(0.25)
San Francisco on 1994-11-29: low: 43, high: 57, precipitation: Optional(0.0)

Prerequisites

Swift 5 or later (PostgresClientKit uses Swift 5 language features)
libssl-dev (only required on Linux)

PostgresClientKit is compatible with Linux, macOS, and iOS. It has been tested on:

Ubuntu 18.04 LTS, 20.04 LTS
macOS 10.14, 10.15, 11, 12
iOS 12, 13, 14, 15
Postgres 10, 11, 12, 13, 14

Building

cd <path-to-clone>
swift package clean
swift build

Testing

Set up a Postgres database for testing. This is a one-time process.

Then:

cd <path-to-clone>
swift package clean
swift build
swift test

Using

From an Xcode project (as a package dependency)

In Xcode:

Select File > Add Packages...
Enter the package URL: https://github.com/codewinsdotcom/PostgresClientKit
Set the package version requirements (see Decide on Package Requirements). For example, choose Up To Next Major Version and 1.0.0 to select the latest 1.x.x release of PostgresClientKit.
Click Add Package.

Import to your source code file:

import PostgresClientKit

From a standalone Swift package (`Package.swift`)

In your Package.swift file:

Add PostgresClientKit to the dependencies. For example:

dependencies: [
    .package(url: "https://github.com/codewinsdotcom/PostgresClientKit", from: "1.0.0"),
],

Reference the PostgresClientKit product in the targets. For example:

targets: [
    .target(
        name: "MyProject",
        dependencies: ["PostgresClientKit"]),
]

Import to your source code file:

import PostgresClientKit

Using CocoaPods

Add PostgresClientKit to your Podfile. For example:

target 'MyApp' do
  pod 'PostgresClientKit', '~> 1.0'
end

Then run pod install.

Import to your source code file:

import PostgresClientKit

Documentation

Additional examples

PostgresClientKit-CommandLine-Example: an example command-line application
PostgresClientKit-iOS-Example: an example iOS app

Contributing

Thank you for your interest in contributing to PostgresClientKit.

This project has a code of conduct. See CODE_OF_CONDUCT.md for details.

Please use issues to:

ask questions
report problems (bugs)
request enhancements

Pull requests against the develop branch are welcomed. For a non-trivial contribution (for example, more than correcting spelling, typos, or whitespace) please first discuss the proposed change by opening an issue.

License

PostgresClientKit is licensed under the Apache 2.0 license. See LICENSE for details.

Versioning

PostgresClientKit uses Semantic Versioning 2.0.0. For the versions available, see the tags on this repository.

Built with

Kitura BlueSocket - socket library
Kitura BlueSSLService - SSL/TLS support
Jazzy - generation of API documentation pages

Authors

David Pitfield (@pitfield)

README

PostgresClientKit

Caution

This repository has been archived, and will no longer be updated or supported.

SwiftPostgresClient and PostgresNIO offer alternative Swift APIs for operating against a PostgreSQL database.

PostgresClientKit provides a friendly Swift API for operating against a PostgreSQL database.

Features

Doesn't require libpq. PostgresClientKit implements the Postgres network protocol in Swift, so it does not require libpq.
Developer-friendly API using modern Swift. For example, errors are represented by instances of enum PostgresError: Error and are raised by a throw or by returning a Result<Success, Error>.
Safe conversion between Postgres and Swift types. Type conversion is explicit and robust. Conversion errors are signaled, not masked. PostgresClientKit provides additional Swift types for dates and times to address the impedance mismatch between Postgres types and Foundation Date.
Memory efficient. The rows in a result are exposed through an iterator, not an array. Rows are lazily retrieved from the Postgres server.
SSL/TLS support. Encrypts the connection between PostgresClientKit and the Postgres server.
Well-engineered. Complete API documentation, an extensive test suite, actively supported.

Sounds good? Let's look at an example.

Example

This is a basic, but complete, example of how to connect to Postgres, perform a SQL SELECT command, and process the resulting rows. It uses the weather table in the Postgres tutorial.

import PostgresClientKit

do {
    var configuration = PostgresClientKit.ConnectionConfiguration()
    configuration.host = "127.0.0.1"
    configuration.database = "example"
    configuration.user = "bob"
    configuration.credential = .scramSHA256(password: "welcome1")

    let connection = try PostgresClientKit.Connection(configuration: configuration)
    defer { connection.close() }

    let text = "SELECT city, temp_lo, temp_hi, prcp, date FROM weather WHERE city = $1;"
    let statement = try connection.prepareStatement(text: text)
    defer { statement.close() }

    let cursor = try statement.execute(parameterValues: [ "San Francisco" ])
    defer { cursor.close() }

    for row in cursor {
        let columns = try row.get().columns
        let city = try columns[0].string()
        let tempLo = try columns[1].int()
        let tempHi = try columns[2].int()
        let prcp = try columns[3].optionalDouble()
        let date = try columns[4].date()
    
        print("""
            \(city) on \(date): low: \(tempLo), high: \(tempHi), \
            precipitation: \(String(describing: prcp))
            """)
    }
} catch {
    print(error) // better error handling goes here
}

Output:

San Francisco on 1994-11-27: low: 46, high: 50, precipitation: Optional(0.25)
San Francisco on 1994-11-29: low: 43, high: 57, precipitation: Optional(0.0)

Prerequisites

Swift 5 or later (PostgresClientKit uses Swift 5 language features)
libssl-dev (only required on Linux)

PostgresClientKit is compatible with Linux, macOS, and iOS. It has been tested on:

Ubuntu 18.04 LTS, 20.04 LTS
macOS 10.14, 10.15, 11, 12
iOS 12, 13, 14, 15
Postgres 10, 11, 12, 13, 14

Building

cd <path-to-clone>
swift package clean
swift build

Testing

Set up a Postgres database for testing. This is a one-time process.

Then:

cd <path-to-clone>
swift package clean
swift build
swift test

Using

From an Xcode project (as a package dependency)

In Xcode:

Select File > Add Packages...
Enter the package URL: https://github.com/codewinsdotcom/PostgresClientKit
Set the package version requirements (see Decide on Package Requirements). For example, choose Up To Next Major Version and 1.0.0 to select the latest 1.x.x release of PostgresClientKit.
Click Add Package.

Import to your source code file:

import PostgresClientKit

From a standalone Swift package (`Package.swift`)

In your Package.swift file:

Add PostgresClientKit to the dependencies. For example:

dependencies: [
    .package(url: "https://github.com/codewinsdotcom/PostgresClientKit", from: "1.0.0"),
],

Reference the PostgresClientKit product in the targets. For example:

targets: [
    .target(
        name: "MyProject",
        dependencies: ["PostgresClientKit"]),
]

Import to your source code file:

import PostgresClientKit

Using CocoaPods

Add PostgresClientKit to your Podfile. For example:

target 'MyApp' do
  pod 'PostgresClientKit', '~> 1.0'
end

Then run pod install.

Import to your source code file:

import PostgresClientKit

Documentation

Additional examples

PostgresClientKit-CommandLine-Example: an example command-line application
PostgresClientKit-iOS-Example: an example iOS app

Contributing

Thank you for your interest in contributing to PostgresClientKit.

This project has a code of conduct. See CODE_OF_CONDUCT.md for details.

Please use issues to:

ask questions
report problems (bugs)
request enhancements

License

PostgresClientKit is licensed under the Apache 2.0 license. See LICENSE for details.

Versioning

PostgresClientKit uses Semantic Versioning 2.0.0. For the versions available, see the tags on this repository.

Built with

Kitura BlueSocket - socket library
Kitura BlueSSLService - SSL/TLS support
Jazzy - generation of API documentation pages

Authors

David Pitfield (@pitfield)

gem-hunter