By Matteo Sist, Mobile Tech Lead, @MOLO17<\/a><\/em><\/em> One of the key ingredients in learning to make a great mobile app is to use a good database. So, in this article we will show how to easy it is to integrate Couchbase Lite in an iOS app.<\/span><\/p>\n What is Couchbase Lite? Couchbase Lite is the mobile SDK of the Couchbase Mobile<\/a> suite that allows developers to easily integrate a NoSQL database into mobile applications.<\/span><\/p>\n This blog will go through the CRUD operations (create, read, update, delete), \u00a0 providing details plus tips and tricks for each of the required steps, and highlight one of my favorite features, Sync Gateway.<\/span><\/p>\n The first step is to create a document with Couchbase. Couchbase has one method to create a document, saveDocument<\/strong><\/em>. That method accepts two parameters. The first is the document (CouchbaseLiteSwift.MutableDocument)<\/span>\u00a0 to be saved, and the second is an optional parameter (CouchbaseLiteSwift.ConcurrencyControl<\/span>\u00a0) that gives users the choice to resolve possible conflicts automatically or throw an exception to allow users to resolve the conflict manually. The default value is “LastWriteWins<\/strong><\/em>“.<\/span><\/p>\n \u00a0<\/span>How to use saveDocument<\/strong><\/em> method?<\/span><\/p>\n First, we need a database instance (CouchbaseLiteSwift.Database<\/span>\u00a0), so just initiate a new database:<\/span><\/p>\n \u00a0<\/span>Then we need to create the document we want to save. So, create a new document CouchbaseLiteSwift.MutableDocument<\/span>\u00a0 and add some fields:<\/span><\/p>\n \u00a0<\/span>Finally, just save it:<\/span><\/p>\n As you can see, creating and saving a document within Couchbase is really simple and intuitive.<\/span><\/p>\n \u00a0<\/span><\/p>\n – <\/span>Typing:<\/b> In the document I added a field named type<\/strong> doc.setString(“Contact”, forKey: “type”)<\/span>\u00a0. This is a trick that allows you to easily split a document into types and facilitates read operations. Later\u00a0 I will demonstrate how to use this field.<\/span><\/p>\n – <\/span>Id:<\/b> You don’t need to provide an id when you create a document. It’s an optional field, and if you don’t, Couchbase generates a UUID for you.<\/span><\/p>\n – <\/span>Document creation:<\/b> If you want, you can create a document from a dictionary (or a key-value map) by simply passing the dictionary as a parameter on the document\u2019s constructor.<\/span><\/p>\n \u00a0<\/span><\/p>\n Now that we have created our first document we also want to read it and display it in a list.\u00a0<\/span>There are two ways to retrieve a document:<\/span><\/p>\n \u00a0<\/span>To retrieve a document using its id we first need a database instance for a read operation.<\/span><\/p>\n Then we can use the method document<\/strong><\/em>\u00a0that needs the id of the document in order to retrieve it. The return type of this method is an optional document object (CouchbaseLiteSwift.Document?) that will be nil if the document doesn’t exist.<\/span><\/p>\n <\/p>\n As for the get by id operation, we need an instance of the database for the query as well.<\/span><\/p>\n <\/p>\n The next step is to create the query. To do this we need to use the metalanguage **N1QL**. N1QL, Couchbase\u2019s query language that extends SQL to JSON data, allows users to define a query with a SQL-like syntax on a NoSQL database. See the example below.<\/span><\/p>\n <\/p>\n In this way, we defined a simple query that searched all documents (with all fields, of course) from the database where the field “type” is equal to “Contact”.<\/span><\/p>\n Now, we just have to run the query and we will receive a result set containing all the documents that observe the query options.<\/span><\/p>\n <\/p>\n The object result conforms to the iterator protocol, so it can be iterated to get each document and do stuff. The result returned by the query is a snapshot of the data at the moment of the execution. The document changes made afterward will not be considered.<\/span><\/p>\n \u00a0<\/span><\/p>\n – <\/span>Query listener:<\/b> Couchbase also provides another method to execute queries that allow users to not only retrieve data from the built query but also listen for future changes. Doing this is as simple as the first method. Take a look!<\/span><\/p>\n The listener will be invoked every time the documents included in the query result change. The token returned from the “`addChangeListener“` methods can be used to stop listening as follows:<\/span><\/p>\n – <\/span>Document conversion:<\/b> As for the creation, you can easily convert a document to a dictionary (and vice versa) using toDictionary()<\/strong><\/em> method.<\/span><\/p>\n \u00a0<\/span><\/p>\n Now that we are able to create and read documents to Couchbase, lets update our document.<\/span><\/p>\n Updating a document is very similar to creating one. You only need to get a document to update, then update it, and save it again. Let see how.<\/span><\/p>\n Initiate the database:<\/span><\/p>\n Retrieve the document to update:<\/span><\/p>\n Edit it.<\/span><\/p>\n And of course, save it:<\/span><\/p>\n <\/p>\n <\/p>\n Last but not least, perhaps you want to delete some documents, here\u2019s how that can be done.<\/span><\/p>\n As always, we need the database.<\/span><\/p>\n Similar to the update operation, we should retrieve the document to delete. So, you will use the document by id method.<\/span><\/p>\n Now we can use the delete<\/strong><\/em> method to delete a document. As with saveDocument<\/strong><\/em>, we can choose to resolve conflicts manually or automatically.\u00a0<\/span><\/p>\n <\/p>\n Now we are able to integrate Couchbase Lite into our apps using CRUD:<\/span><\/p>\n But there\u2019s more. Couchbase provides another wonderful feature: Sync Gateway<\/span><\/p>\n \u00a0<\/span><\/p>\n Sync is one of my favorite functionalities of Couchbase because it is as simple as it is effective. Couchbase Lite provides this functionality in order to configure a remote database.<\/span><\/p>\n Let\u2019s go deep into the code.<\/span><\/p>\n In addition to our database, we need another object: the replicator.<\/span><\/p>\n \u00a0<\/span>What I need in order to initiate a replicator object (CouchbaseLiteSwift.Replicator) is a configuration object where the only mandatory field is the url of the Sync Gateway.<\/span><\/p>\n \u00a0<\/span>The other optional fields include replicatorType<\/strong><\/em>, where users can choose if the replication should work up, in, down, or both. Another field is continuous<\/strong><\/em>, a flag that allow users to configure whether or not replication should be run one time or continuously.<\/span>\u00a0<\/span><\/p>\n With the replicator<\/strong><\/em>\u00a0object we need to only start the replication.<\/span><\/p>\n Or stop the replication.<\/span><\/p>\n <\/p>\n – <\/span>Listen replication status:<\/b> For the query as well as for the replication we can add a listener to receive changes of replication status. Below is the code.<\/span>\u00a0<\/span><\/p>\n As for the queries, the token should be used to remove the listener from the replicator.<\/span><\/p>\n <\/p>\n \u00a0<\/span>Couchbase Lite, as a part of Couchbase Mobile suite, is a powerful arrow in the quiver of a mobile developer. It’s easy to learn, and in this article, we only showcased a small part of its potential, so my advice is to go deeper into Couchbase functionalities that will allow you to easily integrate and take full control of the database that supports your mobile apps.<\/span><\/p>\n About Matteo Sist, @MOLO17<\/em><\/strong><\/p>\n Matteo started collaborating with MOLO17<\/a> as an Android Developer when he was in high school (via an Information Technology course). Recruited in 2015, he joined the Mobile Development Team taking the role of key Developer for both iOS and Android platforms. Skilled in languages for native mobile app development<\/a>, ranging from Java and Objective-C to the most recents Kotlin and Swift, he designed and developed several successful solutions for mobile devices targeted at consumers and enterprises. In 2016, he became Tech Lead managing the mobile app development team, and in 2019, he co-founded MobileBridge (a MOLO17 sister company).<\/em><\/p>\n <\/p>\n","protected":false},"excerpt":{"rendered":" Learn Couchbase Lite in 5 Minutes and follow the CRUD By Matteo Sist, Mobile Tech Lead, @MOLO17 One of the key ingredients in learning to make a great mobile app is to use a good database. So, in this article […]<\/p>\n","protected":false},"author":31146,"featured_media":13873,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"inline_featured_image":false,"footnotes":""},"categories":[7667,1810,9410,2366],"tags":[1536],"ppma_author":[8921],"class_list":["post-8679","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-couchbase-lite","category-couchbase-mobile","category-objective-c","category-sync-gateway","tag-ios"],"acf":[],"yoast_head":"\n
\n<\/span><\/p>\nC as Create<\/span><\/h2>\n
do {\r\n database = try Database(name: \"DatabaseName\")\r\n} catch {\r\n fatalError(\"Error opening database\")\r\n}<\/pre>\nlet doc = MutableDocument(id: \"MyUniqueDocumentIdentifier\")\r\ndoc.setString(\"Mickey\", forKey: \"name\")\r\ndoc.setString(\"Mouse\", forKey: \"surname\")\r\ndoc.setInt(91, forKey: \"age\")\r\ndoc.setString(\"Contact\", forKey: \"type\")<\/pre>\n
do {\r\n try database.saveDocument(doc, concurrencyControl: .lastWriteWins)\r\n} catch {\r\n fatalError(\"Error saving document\")\r\n}<\/pre>\nTips and Tricks to Learn with Couchbase Lite<\/span><\/h3>\n
R as Read<\/span><\/h2>\n
\n
Get by id<\/span><\/h3>\n
do {\r\n database = try Database(name: \"DatabaseName\")\r\n} catch {\r\n fatalError(\"Error opening database\")\r\n}<\/pre>\nlet doc = database.document(withID: \"MyUniqueDocumentIdentifier\")<\/pre>\n
Query<\/span><\/h3>\n
do {\r\n database = try Database(name: \"DatabaseName\")\r\n} catch {\r\n fatalError(\"Error opening database\")\r\n}<\/pre>\nlet query = QueryBuilder\r\n .select(SelectResult.all())\r\n .from(DataSource.database(database))\r\n .where(Expression.property(\"type\").equalTo(Expression.string(\"Contact\")))<\/pre>\n
do {\r\n result = try query.execute()\r\n} catch {\r\n fatalError(\"Invalid query\")\r\n}<\/pre>\nTips and Tricks <\/span>to Learn with Couchbase Lite<\/h3>\n
let token = query.addChangeListener { queryChange in\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 result = queryChange.results?.allResults()\r\n}<\/pre>\nquery.removeChangeListener(withToken: token)<\/pre>\n
U as Update<\/span><\/h2>\n
do {\r\n database = try Database(name: \"DatabaseName\")\r\n} catch {\r\n fatalError(\"Error opening database\")\r\n}<\/pre>\nlet doc = database.document(withID: \"MyUniqueDocumentIdentifier\")<\/pre>\n
let docToUpdate = doc.toMutable()\r\ndocToUpdate.setString(\"Male\", forKey: \"gender\")<\/pre>\n
do {\r\n try database.saveDocument(docToUpdate, concurrencyControl: .lastWriteWins)\r\n} catch {\r\n fatalError(\"Error updating document\")\r\n}<\/pre>\nD as Delete<\/span><\/h2>\n
do {\r\n database = try Database(name: \"DatabaseName\")\r\n} catch {\r\n fatalError(\"Error opening database\")\r\n}<\/pre>\nlet doc = database.document(withID: \"MyUniqueDocumentIdentifier\")<\/pre>\n
do {\r\n try database.deleteDocument(doc, concurrencyControl: .lastWriteWins)\r\n} catch {\r\n fatalError(\"Error deleting document\")\r\n}<\/pre>\nCouchbase Sync Gateway is as easy to learn as Couchbase Lite<\/span><\/h2>\n
\n
Sync<\/span>\u00a0<\/span><\/h2>\n
do {\r\n database = try Database(name: DatabaseName)\r\n} catch {\r\n fatalError(\"Error opening database\")\r\n}<\/pre>\nlet targetEndpoint = URLEndpoint(url: \"ws:\/\/localhost:4984\/bucketname\/\")\r\nlet replConfig = ReplicatorConfiguration(database: database, target: targetEndpoint)\r\nreplConfig.replicatorType = .pushAndPull\r\nreplConfig.continuous = true\r\nreplConfig.authenticator = BasicAuthenticator(username: Username, password: Password)\r\nreplicator = Replicator(config: replConfig)<\/pre>\n
replicator.start()<\/pre>\n
replicator.stop()<\/pre>\n
Tips and Tricks to Learn with Sync<\/span><\/h3>\n
let token = replicator.addChangeListener { changes in\r\n status = changes.status\r\n}<\/pre>\nreplicator.removeChangeListener(withToken: token)<\/pre>\n
Conclusion, Couchbase Lite is Easy to Learn<\/span><\/h2>\n