Swiftpack.co - Package - IBM-Swift/Kitura-CouchDB


APIDoc Build Status - Master macOS Linux Apache 2 Slack Status


Kitura-CouchDB is a pure Swift client which allows Kitura applications to interact with a CouchDB or Cloudant database.


Add dependencies

Add the Kitura-CouchDB package to the dependencies within your application’s Package.swift file. Substitute "x.x.x" with the latest Kitura-CouchDB release.

.package(url: "https://github.com/IBM-Swift/Kitura-CouchDB.git", from: "x.x.x")

Add CouchDB to your target's dependencies:

.target(name: "example", dependencies: ["CouchDB"]),

Import package

import CouchDB

Run Kitura-CouchDB Sample

To run the CouchDB Sample, you must set up and connect to a local CouchDB database by following the steps below:

  1. Download and install CouchDB.

  2. Set up an admin username and password in CouchDB.

  3. Create a database with the name kitura_test_db.

  4. Clone this repository:

    git clone https://github.com/IBM-Swift/Kitura-CouchDB.git
  5. Update the following code in Sources\CouchDBSample\main.swift with your admin username and password (the host will default to and the port will default to 5984):

    let connProperties = ConnectionProperties(
        host: host,         // http address
        port: port,         // http port
        secured: secured,   // https or http
        username: nil,      // admin username
        password: nil       // admin password
  6. Open a Terminal window, change into the Kitura-CouchDB folder and run swift build:

    swift build
  7. Run the CouchDBSample executable:


    You should see informational messages such as "Successfully created the following JSON document in CouchDB:" for each of the operations (create, read, update and delete) performed on the kitura_test_db database.

API Documentation


CouchDB is a NoSQL database for storing documents. A Document is any structure that can be represented as JSON and contains _id and _rev fields.

  • The _id field is the unique identifier for the document. If it is not set, a random UUID will be assigned for the document.
  • The _rev field is the revision of the document. It is returned when you make requests and is used to prevent conflicts from multiple users updating the same document.

To define a CouchDB document, create a Swift object and make it conform to the Document protocol:

struct MyDocument: Document {
   let _id: String?
   var _rev: String?
   var value: String


The CouchDBClient represents a connection to a CouchDB server. It is initialized with your ConnectionProperties and handles the creation, retrieval and deletion of CouchDB databases.

// Define ConnectionProperties
let conProperties = ConnectionProperties(
    host: "",              // http address
    port: 5984,                     // http port
    secured: false,                 // https or http
    username: "<CouchDB-username>", // admin username
    password: "<CouchDB-password>"  // admin password
// Initialize CouchDBClient
let couchDBClient = CouchDBClient(connectionProperties: conProperties)
  • Create a new database
couchDBClient.createDB("NewDB") { (database, error) in
    if let database = database {
        // Use database
  • Get an existing database
couchDBClient.retrieveDB("ExistingDB") { (database, error) in
    if let database = database {
        // Use database
  • Delete a database
couchDBClient.deleteDB("ExistingDB") { (error) in
    if let error = error {
        // Handle the error


The Database class is used to make HTTP requests to the corresponding CouchDB database. This class can make CRUD (Create, Retrieve, Update, Delete) requests for:

  • A single CouchDB Document
  • An array of CouchDB documents
  • A CouchDB DesignDocument
  • A Document attachment

The following code demonstrates the CRUD operations for a single Document:

var myDocument = MyDocument(_id: "Kitura", _rev: nil, value: "Hello World")
  • Create a Document:
database.create(myDocument) { (response, error) in
    if let response = response {
        print("Document: \(response.id), created with rev: \(response.rev)")
  • Retrieve a Document:
database.retrieve("Kitura") { (document: MyDocument?, error: CouchDBError?) in
    if let document = document {
        print("Retrieved document with value: \(document.value)")
  • Update a Document:
myDocument.value = "New Value"
database.update("Kitura", rev: "<latest_rev>", document: myDocument) { (response, error) in
    if let response = response {
        print("Document: \(response.id), updated")
  • Delete a Document:
database.delete("Kitura", rev: "<latest_rev>") { (error) in
    if error == nil {
        print("Document successfully deleted")

For more information visit our API reference.


We love to talk server-side Swift, and Kitura. Join our Slack to meet the team!


This library is licensed under Apache 2.0. Full license text is available in LICENSE.


Stars: 45

Used By

Total: 0


3.2.0 - 2019-09-04 10:11:12

  • Update to Kitura-NIO 2.2.0 when building in KITURA_NIO mode
  • fix: Apply percent-encoding to + character in CouchDB request paths (#108)

3.1.1 - 2019-04-11 12:50:15

  • Build in Swift 5 mode (#101)

3.1.0 - 2019-02-05 16:05:42

  • Add decodeDocuments() to AllDatabaseDocuments (#97)

3.0.0 - 2019-01-28 11:58:30

This is a major rework of KituraCouchDB API (#86). Instead of using SwiftyJSON objects to represent documents, you now define your document as a Document type which uses Codable. Database operations are then performed by passing instances of this type.

2.1.1 - 2018-10-16 14:36:34

  • SwiftNIO support (#83): enable by setting the KITURA_NIO environment variable while building
    • for example: env KITURA_NIO=1 swift build

2.1.0 - 2018-04-23 13:04:43

  • Update dependencies for Kitura 2.3, and support Swift 4.1 (#75)

2.0.0 - 2017-12-15 15:10:59


  • Updates to latest Swift 4.0.2 dependencies

1.7.2 - 2017-09-15 16:31:29

What's New

  • Add support for Swift 4

1.7.0 - 2017-03-29 18:25:10

Tag for swift-3.1 release

1.6.1 - 2017-03-28 19:54:51

Fix to compile on Swift-3.1. Still needs regression testing before 1.7 tag.

v0.10.0 - 2016-04-25 14:36:47

v0.6.0 - 2016-03-23 20:11:19

v0.4.0 - 2016-03-08 23:46:47

v0.2.1 - 2016-02-23 19:45:14

  • CRUD operations for JSON documents.
  • CRUD operations on databases.
  • Support for CouchDB and Cloudant databases.
  • Updated Package.swift file.

v0.2.0 - 2016-02-22 15:21:23

  • CRUD operations for JSON documents.
  • CRUD operations on databases.
  • Support for CouchDB and Cloudant databases.