Database
public class 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
-
Indicates when to update.
See moreDeclaration
Swift
public enum StaleOptions
-
Query parameters for view functions from design documents.
See moreDeclaration
Swift
public enum QueryParameters
-
Name for the Database.
Declaration
Swift
public let name: String
-
Escaped name for the Database.
Declaration
Swift
public let escapedName: String
-
ConnectionProperties
the Database will use for its actions.Declaration
Swift
public let connProperties: ConnectionProperties
-
Create a new document.
Usage Example:
struct MyDocument: Document { let _id: String? var _rev: String? var value: String } 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)") } }
Declaration
Swift
public func create<D: Document>(_ document: D, callback: @escaping (DocumentResponse?, CouchDBError?) -> ())
-
Retrieve a document from the database.
Usage Example:
struct MyDocument: Document { let _id: String? var _rev: String? var value: String } database.retrieve("Kitura") { (document: MyDocument?, error: CouchDBError?) in if var document = document { print("Retrieved document with value: \(document.value)") } }
Declaration
Swift
public func retrieve<D: Document>(_ id: String, callback: @escaping (D?, CouchDBError?) -> ())
-
Update a document in the database. If no document exists for the provided id, a new document is created.
Usage Example:
struct MyDocument: Document { let _id: String? var _rev: String? var value: String } var myDocument = MyDocument(_id: "Kitura", _rev: nil, value: "New Value") database.update("<document_id>", rev: "<latest_rev>", document: myDocument) { (response, error) in if let response = response { print("Document: \(response.id), updated") } }
Declaration
Swift
public func update<D: Document>(_ id: String, rev: String, document: D, callback: @escaping (DocumentResponse?, CouchDBError?) -> ())
-
Delete a document.
Usage Example:
database.delete("<document_id>", rev: "<latest_rev>") { (error) in if let response = response { print("Document: \(response.id), deleted") } }
Declaration
Swift
public func delete(_ id: String, rev: String, callback: @escaping (CouchDBError?) -> ())
-
Bulk update or insert documents into the database.
Note
Note:
- CouchDB will return the results in the same order as supplied in the array. The
id
and revision will be added for every document passed as content to a bulk insert, even for those that were just deleted. - If you omit the per-document
_id
specification, CouchDB will generate unique IDs for you, as it does for regularcreate(_:callback:)
function. - Updating existing documents requires setting the
_rev
member to the revision being updated. To delete a document set the_deleted
member totrue
.[ {"_id": "0", "_rev": "1-62657917", "_deleted": true}, {"_id": "1", "_rev": "1-2089673485", "integer": 2, "string": "2"}, {"_id": "2", "_rev": "1-2063452834", "integer": 3, "string": "3"} ]
- If the
_rev
does not match the current version of the document, then that particular document will not be saved and will be reported as a conflict, but this does not prevent other documents in the batch from being saved.[ {"id": "0", "error": "conflict", "reason": "Document update conflict."}, {"id": "1", "rev": "2-1579510027"}, {"id": "2", "rev": "2-3978456339"} ]
Declaration
Swift
public func bulk(documents: BulkDocuments, callback: @escaping ([BulkResponse]?, CouchDBError?) -> ())
Parameters
documents
An
BulkDocuments
struct containing an array of JSON documents to be updated or inserted.callback
callback containing either a
BulkResponse
array or an error. - CouchDB will return the results in the same order as supplied in the array. The
-
Executes the specified view function from the specified design document.
Declaration
Swift
public func queryByView(_ view: String, ofDesign design: String, usingParameters params: [Database.QueryParameters], callback: @escaping (AllDatabaseDocuments?, CouchDBError?) -> ())
Parameters
view
View function name String.
design
Design document name.
params
Query parameters for the function.
callback
Callback containing either the
AllDatabaseDocuments
or aCouchDBError
. -
Retrieve all documents in the database using the CouchDB
_all_docs
view. IfincludeDocuments
is false, each returnedAllDatabaseDocuments
row will be structured as follows:[ "id": "<_id>", "key": "<_id>", "value": [ "rev": "<_rev>" ] ]
If
includeDocuments
is true, each row will have an additionaldoc
field containing the JSON document. These documents can then be decoded to a given swift type usingdecodeDocuments(ofType:)
. https://docs.couchdb.org/en/stable/api/database/bulk-api.htmlUsage Example:
struct MyDocument: Document { let _id: String? var _rev: String? var value: String } database.retrieveAll(includeDocuments: true) { (allDocs, error) in if let allDocs = allDocs, let decodedDocs = allDocs.decodeDocuments(ofType: MyDocument) { for doc in decodedDocs { print("Retrieved MyDocument with value: \(doc.value)") } } }
Declaration
Swift
public func retrieveAll(includeDocuments: Bool = false, callback: @escaping (AllDatabaseDocuments?, CouchDBError?) -> ())
-
Create a design document. If a design document already exists with the same name it will be replaced.
Declaration
Swift
public func createDesign(_ designName: String, document: DesignDocument, callback: @escaping (DocumentResponse?, CouchDBError?) -> ())
Parameters
designName
Name String for the design document.
document
The JSON data of the new design document.
callback
Callback containing the
DocumentResponse
or aCouchDBError
. -
Delete a design document.
Declaration
Swift
public func deleteDesign(_ designName: String, revision: String, failOnNotFound: Bool = false, callback: @escaping (CouchDBError?) -> ())
Parameters
designName
Name String of the design document to delete.
revision
The latest revision String of the design document to delete.
failOnNotFound
Bool indicating whether to return an error if the design document was not found.
callback
Callback containing the
DocumentResponse
or aCouchDBError
.
-
Attach the provided
Data
theDocument
with the provided ID with the given attachmentName. If an attachment exists with the same name it will be replaced with the new attachment.Declaration
Swift
public func createAttachment(_ docId: String, docRevison: String, attachmentName: String, attachmentData: Data, contentType: String, callback: @escaping (DocumentResponse?, CouchDBError?) -> ())
Parameters
docId
Document ID String that the attachment is associated with.
docRevision
Document revision String.
attachmentName
Attachment name String.
attachmentData
The attachment Data.
contentType
Attachment MIME type String.
callback
Callback containing the
DocumentResponse
or aCouchDBError
. -
Get an attachment associated with a specified document.
Declaration
Swift
public func retrieveAttachment(_ docId: String, attachmentName: String, callback: @escaping (Data?, String?, CouchDBError?) -> ())
Parameters
docId
Document ID String that the attachment is associated with.
attachmentName
Name String for the desired attachment.
callback
Callback containing either the retrieved attachment data and the content type of the attachment or a
CouchDBError
. -
Delete an attachment associated with a specified document.
Declaration
Swift
public func deleteAttachment(_ docId: String, docRevison: String, attachmentName: String, callback: @escaping (CouchDBError?) -> ())
Parameters
docId
Document ID String that the attachment is associated with.
docRevision
Latest revision String of the document.
attachmentName
Name String of the attachment to be deleted.
callback
Callback containing either the
DocumentResponse
or aCouchDBError
.