Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


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: "", 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
  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: \(, 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: \(, 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.