Repository files navigation

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

• Doesn't require libpq. PostgresClientKit implements the Postgres network protocol in Swift, so it does not requirelibpq.

• Developer-friendly API using modern Swift. For example, errors are represented by instances ofenum PostgresError: Error and are raised by athrow or by returning aResult<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 FoundationDate.

• 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.

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

import PostgresClientKitdo{varconfiguration=PostgresClientKit.ConnectionConfiguration()    configuration.host="127.0.0.1"    configuration.database="example"    configuration.user="bob"    configuration.credential=.scramSHA256(password:"welcome1")letconnection=tryPostgresClientKit.Connection(configuration: configuration)defer{ connection.close()}lettext="SELECT city, temp_lo, temp_hi, prcp, date FROM weather WHERE city = $1;"letstatement=try connection.prepareStatement(text: text)defer{ statement.close()}letcursor=try statement.execute(parameterValues:["San Francisco"])defer{ cursor.close()}forrowin cursor{letcolumns=try row.get().columnsletcity=trycolumns[0].string()lettempLo=trycolumns[1].int()lettempHi=trycolumns[2].int()letprcp=trycolumns[3].optionalDouble()letdate=trycolumns[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)

• 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

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

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

Then:

cd <path-to-clone>swift package cleanswift buildswift test

In Xcode:

• Select File > Add Packages...

• Enter the package URL:https://github.com/codewinsdotcom/PostgresClientKit

• Set the package version requirements (seeDecide on Package Requirements). For example, chooseUp To Next Major Version and1.0.0 to select the latest 1.x.x release of PostgresClientKit.

• Click Add Package.

Import to your source code file:

import PostgresClientKit

In yourPackage.swift file:

• Add PostgresClientKit to thedependencies. For example:

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

• Reference thePostgresClientKit product in thetargets. For example:

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

Import to your source code file:

import PostgresClientKit

AddPostgresClientKit to yourPodfile. For example:

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

Then runpod install.

Import to your source code file:

import PostgresClientKit

• API
• Troubleshooting
• FAQ

• PostgresClientKit-CommandLine-Example: an example command-line application

• PostgresClientKit-iOS-Example: an example iOS app

Thank you for your interest in contributing to PostgresClientKit.

This project has a code of conduct. SeeCODE_OF_CONDUCT.md for details.

Please useissues to:

• ask questions
• report problems (bugs)
• request enhancements

Pull requests against thedevelop 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.

PostgresClientKit is licensed under the Apache 2.0 license. SeeLICENSE for details.

PostgresClientKit usesSemantic Versioning 2.0.0. For the versions available, see thetags on this repository.

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

• David Pitfield(@pitfield)