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/Kitura/Kitura-CouchDB.git", from: "x.x.x")
Add CouchDB
to your target's dependencies:
.target(name: "example", dependencies: ["CouchDB"]),
import CouchDB
To 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/Kitura/Kitura-CouchDB.git
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
)
Open a Terminal window, change into the Kitura-CouchDB
folder and run swift 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_db
database.
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.
_id
field is the unique identifier for the document. If it is not set, a random UUID will be assigned for the document. _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: "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)
couchDBClient.createDB("NewDB") { (database, error) in
if let database = database {
// Use database
}
}
couchDBClient.retrieveDB("ExistingDB") { (database, error) in
if let database = database {
// Use 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:
Document
DesignDocument
Document
attachmentThe following code demonstrates the CRUD operations for a single Document
:
var myDocument = MyDocument(_id: "Kitura", _rev: nil, value: "Hello World")
database.create(myDocument) { (response, error) in
if let response = response {
print("Document: \(response.id), created with rev: \(response.rev)")
}
}
database.retrieve("Kitura") { (document: MyDocument?, error: CouchDBError?) in
if let document = document {
print("Retrieved document with value: \(document.value)")
}
}
myDocument.value = "New Value"
database.update("Kitura", rev: "<latest_rev>", document: myDocument) { (response, error) in
if let response = response {
print("Document: \(response.id), updated")
}
}
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.