Kitura-CouchDB is a pure Swift client which allows Kitura applications to interact with a CouchDB or Cloudant database.
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 CouchDBTo run the CouchDB Sample, you must set up and connect to a local CouchDB database by following the steps below:
-
Set up an admin username and password in CouchDB.
-
Create a database with the name
kitura_test_db. -
Clone this repository:
git clone https://github.com/IBM-Swift/Kitura-CouchDB.git
-
Update the following code in
Sources\CouchDBSample\main.swiftwith 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 )
-
Open a Terminal window, change into the
Kitura-CouchDBfolder and runswift build:swift build
-
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_dbdatabase.
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
_idfield is the unique identifier for the document. If it is not set, a random UUID will be assigned for the document. - The
_revfield 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: "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
}
}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
Documentattachment
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.