Skip to content

Kitura/Kitura-CouchDB

Repository files navigation

Kitura

APIDoc Build Status - Master macOS Linux Apache 2 Slack Status

Kitura-CouchDB

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

Usage

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/Kitura/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/Kitura/Kitura-CouchDB.git
  5. Update the following code in Sources\CouchDBSample\main.swift with your admin username and password (the host will default to 127.0.0.1 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:

    .build/debug/CouchDBSample

    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

Document

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
}

CouchDBClient

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: "127.0.0.1",              // 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
    }
}

Database

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.

Community

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

License

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