Skip to content
master
Go to file
Code

README.md

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

You can’t perform that action at this time.