Refactor doc #116

jannyHou · 2017-05-02T20:36:58Z

connect to strongloop-internal/scrum-apex#196

For easier reading, I would suggest ignore the git compare, just click the updated README.md file.
I grap everything from old doc and fit them into new doc.
Generate TOC(table of contents)
This might not be a perfect document that explains everything in this connector, at this moment I mainly changed the layout so user can quickly search and find the part they are interested in, and pay attention to design their model that fits cloudant nature. Any opinion or suggestions would be helpful :) And specificlly I appreciate reviewers could verify this story by:
- When you have question on how to use the connector or how it works, the new layout(table of content) can quickly take you to the right place. Or with the keyword you can think of, a quick search on this page can take you to relevant doc.
- It gives you a better understanding of how a loopback concepts fit cloudant concepts.
- It explains most questions asked in PMRs or by customers, and includes features TBD so users know what's our refactor direction.

ssh24 · 2017-05-04T17:51:53Z

README.md

@@ -8,16 +8,165 @@ Local.
 For more information, see [Getting started with Cloudant NoSQL DB](https://www.ng.bluemix.net/docs/services/Cloudant/index.html)

 The `loopback-connector-cloudant` module is the Cloudant connector for the Loopback framework.
+<!-- TOC -->
+
+- [loopback-connector-cloudant](#loopback-connector-cloudant)


Can we add this hyperlink to https://github.com/strongloop/loopback-connector-cloudant/pull/116/files#diff-04c6e90faac2675aa89e2176d2eec7d8L1 instead?

@ssh Sorry I am confused what do we put a PR hyperlink here? This is auto generated by TOC.

I mean we should not have that there at all. This already points me to the loopback-connector-cloudant. Small thing, if you want to leave as it is I am okay :)

@ssh24 oh ok I see, true, I have auto TOC generator on when saving my file, not sure how to tell the generator skip it lol. I will disable the generator and delete it in the final commit.

dhmlau · 2017-05-04T17:43:09Z

README.md

+
+<!-- /TOC -->
+
+# Design


It seems to me that they are limitations. If so, it's better to put this section towards the end of the document. When users want to use this connector, they probably want to know about the basic first rather than the limitations. :)

@dhmlau True I have to say it's not an exciting thing to mention the "limitation" at the beginning, while it depends on how do you think of the design, IMO, if a user decides to choose cloudant, they may want to be aware of the nature of this database,.
I also feel that my words is not polite enough to describe them as design principles, it gives users a waring impression.
Thinking of how to improve and rephrase it :(

@jannyHou per our discussion, I'm thinking of putting the Design and Model sections under Getting Started. So the structure could be

Getting Started

Things to consider (the old Design section - we could think of a better name)

Best Practices (the old Model section)

@dhmlau Updated the layout, and also rephrased the titles a little bit in a more friendly way.

dhmlau · 2017-05-04T17:45:50Z

README.md

+
+Workaround: Do not pass partial values for the data object to be updated. If there are properties that are not being updated, please include the old value to keep data persistent.
+
+We plan to support partial update in the future by retrieving the original data and merging it with the updated one, but user should be aware of the risk when merging happens.


not sure if our plan to support is necessary to be included in the README.

@dhmlau If eventually we decide to support it, then I feel it's necessary to be included in README. Now the tricky thing is we may not want to do the messy "data merging" in our connector, it's probably better to ask the user provide their own merging solution.
Let's discuss in issue #35
cc @kjdelisle

Maybe it's different in open source community. Normally I'd rather not to share the plan in official documentation. If #35 is the one to track the progress, perhaps we could say the discussion related to this topic can be found in #35 (or whatever issue # we use).

@dhmlau The git issues column is actually a big features/plan pool :p So I assume it's ok to include plans in doc, anyway community can see them, and might be interested to share more opinions and join the discussion.

I reworded this part to not explicitly describe the plan details.

dhmlau · 2017-05-04T17:47:21Z

README.md

+Cloudant is not designed to change same document frequently and multiple times. It stores status change by creating different documents and including the same unique id to tell that they are attached to the same item, not updating the same document.
+
+By modeling the data in separate documents that are only written once, we can ensure that documents never become conflicted, such as during concurrent access to the same document by separate processes.
+


A generic comment: what's the implication if i do have frequent modification? What's our recommendation?

It implicates user need to properly handle doc conflicts by dealing with its revision. I will add that part.

Suggestion:
By modelling the data in separate documents that are only written once, we can reduce the chance of concurrent access to the same document by separate processes.

dhmlau · 2017-05-04T17:48:50Z

README.md

+
+## Map between model and document
+
+Unlike relational db or mongodb, cloudant doesn't have a concept as 'table' or 'collection', data in a cloudant database are all stored as documents.


Minor changes (might occur in the rest of the document too):
cloudant --> Cloudant
loopback --> LoopBack

I will update other places as well.

dhmlau · 2017-05-04T17:49:25Z

README.md

@@ -27,7 +176,9 @@ $ npm install loopback-connector-cloudant --save

 The `--save` option adds the dependency to the application’s `package.json` file.

-## Configuration
+# Config


Config --> Configuration

dhmlau · 2017-05-04T17:49:42Z

README.md

-## Configuration
+# Config
+
+## generate datasource


generate datasource --> Generate DataSource

In general, the title should have the proper capitalization of the first character of the word.

ok I kept all subtitle lower cases, will change them.

0candy · 2017-05-04T18:06:01Z

README.md

+
+TBD. 
+
+The basic idea is when modifying a document, user needs to control conflict by handling the revision of a document, currently the connector controls this process, after retriving the latest revision, connector uses it to update/delete doc, and returns 409 conflict error if doc changes during that time slot. In the middle user could not interfere and provide their own conflict solution.


There should be a comma after In the middle

0candy · 2017-05-04T18:08:16Z

README.md

+
+Unlike relational db or mongodb, cloudant doesn't have a concept as 'table' or 'collection', data in a cloudant database are all stored as documents.
+
+The connector uses a design document to represent a loopback model, and other non-design(non-design might not be the best word here, appreciate more ideas about how to describe it) documents to represent model instances.


Not sure what you mean by other non-design documents but you just leave it at other documents.

@0candy Let me elaborate more on the document type, there are two types of documents in cloudant database:

Design document

common document that is not a design document

I am not sure what is the brief and accurate word to describe the second one...

0candy · 2017-05-04T18:09:50Z

README.md

-* Query and filtering is performed on the database for optimal efficiency.
-* Use different DB instances per model definition.
-* Supports basic model discovery.
+For model properties, we plan to create index for property that has config `index: true` in the future, it will be the same way as what mongodb connector does.


Start in the future as a new sentence.

0candy · 2017-05-04T18:11:48Z

README.md

+
+## _rev property
+
+In a document, property `_rev` is the latest doc revision and must be provided when modifing the doc. Currently when updating/deleting a doc, the connector first retrieves that doc, then gets its `_rev`, then calls a modify api with `_rev` included. It makes three calls to database and this would easily result in race condition.


typo modifying
make three calls to the database

0candy · 2017-05-04T18:16:58Z

README.md


+I believe there are more stuff TBD in this part, appreciate more ideas.


Create doesn't require _rev right?

Good catch lol

0candy · 2017-05-04T18:17:59Z

README.md

-ds.updateOrCreate('User', {
-  prop1: 'updated1',
-}, function (err, res) {});
+The following migration functions take either an array of multiple models' name, or a string of a single model's name. The example code will show how to do it.


0candy · 2017-05-04T18:24:12Z

README.md


-There is no free version of local Cloudant to download, so to develop or test with Cloudant connector, you must set up either a Cloudant DBaas instance or a Bluemix Cloudant instance.
+For development use, a docker container of cloudant local is easy to setup and there is no request limit per second.
+Bluemix cloudant will be more stable for product.


Did you mean for production?

@0candy I thought they mean the same thing when use "product" as an noun..? I will change it to "production" :)

0candy · 2017-05-04T18:24:37Z

README.md


-After creating a Cloudant instance, you will need three configuration properties to run the tests: `username`, `password`, `database`
+- Cloduant local(docker image)


typo Cloudant

jannyHou · 2017-05-04T19:22:12Z

Regarding the first title loopback-connector-cloudant, I have auto TOC generator turning on when saving my file, not sure how to tell the generator skip it lol. I will disable the generator and delete it in the final commit.

jannyHou · 2017-05-04T19:57:42Z

there are two types of documents in cloudant database:

Design document
common document that is not a design document

I am not sure what is the brief and accurate word to describe the second one, so ATM I use "common document" to represent it.

jannyHou · 2017-05-04T20:00:21Z

@0candy @dhmlau @ssh24 Comments applied, thanks a lot, PTAL again.

ssh24

Some small changes.

Also @jannyHou I have noticed in some places the docs are not well written because we do not have the full picture for the upcoming features and their behaviour.

In those places could we leave a more generic message likeTo Be Updated once the bug/feature has been fixed?

ssh24 · 2017-05-04T21:26:02Z

README.md

-## Installation
+### Careful Frequent Modification
+
+Cloudant is not designed to change same document frequently and multiple times. It stores status change by creating different documents and including the same unique id to tell that they are attached to the same item, not updating the same document.


Change this to: Cloudant is not designed to change the same document multiple times.

I think "frequent" and "multiple" emphasize different things.
"frequent": easy run into race condition, considering simultaneous modifications to same doc
"multiple": considering everytime you need to do a full update(replace), one modification requires large amount of work.

ssh24 · 2017-05-04T21:27:46Z

README.md

+
+By modeling the data in separate documents that are only written once, we can ensure that documents never become conflicted, such as during concurrent access to the same document by separate processes.
+
+While it doesn't mean modification will cause trouble, by properly conflict controllation, developer can still do a safe modify. For details, refer to [Conflict Control](https://github.com/strongloop/loopback-connector-cloudant##conflict-control)


by properly conflict controllation

Change to:

by properly controlling the conflict

The link for Conflict Control is wrong. Please update to: https://github.com/strongloop/loopback-connector-cloudant#conflict-control

ssh24 · 2017-05-04T21:38:13Z

README.md

+
+### Model-specific configuration
+
+You can also specify per-model configuration for database selection and to


You can also specify per-model configuration for database selection

Change to:

You can specify configurations per model for database selection

jannyHou · 2017-05-05T15:06:47Z

@ssh24

In those places could we leave a more generic message likeTo Be Updated once the bug/feature has been fixed?

sounds good to me, I will update those fields once I gather opinions from everyone and PR ready to land.

ssh24

LGTM.

Please also update places in the readme with a generic To be updated statement in places where the doc will need to be updated with the upcoming refactoring and new feature/bug fixes.

dhmlau · 2017-05-05T15:14:29Z

README.md

+## Design
+Loopback tries best to fit its model to a specific database's design, while limited by the nature of database, it's not always possible to support all Loopback features perfectly, and user would like to be aware of some key features about Cloudant before they start to design a Cloudant model.
+
+### Careful partial update


I'm thinking simply Partial Update is enough?

@dhmlau I feel 'careful partial update' would be more clear :p
well tbh it's just a personal feeling and maybe it's good to have feedback from more people @strongloop/sq-lb-apex

Two header options here:

option1: 'Careful partial update'

option2: 'Partial update'

from a user's perspective, which one would you prefer to see?

👍 for Partial Update

OK, I removed two careful

dhmlau · 2017-05-05T15:16:12Z

README.md

+
+### Careful partial update
+
+*Cloudant does not support the idea of updating a document. All "updates" on a document are _destructive_ replacements.*



Suggestion: move the "workaround" to here.

dhmlau · 2017-05-05T15:22:28Z

README.md

+
+*Please note how property `prop2` was completely dropped upon update.*
+
+Workaround: Do not pass partial values for the data object to be updated. If there are properties that are not being updated, please include the old value to keep data persistent.


Perhaps we could omit the "workaround". If we move this section up, we could say something like...

It implies that unchanged values need to be included in the update object.

I move this part up and change it to

It implies that if you do want to partially update a document, please make sure unchanged values are included in the update object.

dhmlau · 2017-05-05T15:24:05Z

README.md

+
+### Careful Frequent Modification
+
+Cloudant is not designed to change same document frequently and multiple times. It stores status change by creating different documents and including the same unique id to tell that they are attached to the same item, not updating the same document.


status change --> status changes?

dhmlau · 2017-05-05T15:29:06Z

README.md

+Cloudant is not designed to change same document frequently and multiple times. It stores status change by creating different documents and including the same unique id to tell that they are attached to the same item, not updating the same document.
+
+By modeling the data in separate documents that are only written once, we can ensure that documents never become conflicted, such as during concurrent access to the same document by separate processes.
+


Suggestion:
By modelling the data in separate documents that are only written once, we can reduce the chance of concurrent access to the same document by separate processes.

dhmlau · 2017-05-05T15:30:58Z

README.md

+
+By modeling the data in separate documents that are only written once, we can ensure that documents never become conflicted, such as during concurrent access to the same document by separate processes.
+
+While it doesn't mean modification will cause trouble, by properly controlling the conflict, developer can still do a safe modify. For details, refer to [Conflict Control](https://github.com/strongloop/loopback-connector-cloudant#conflict-control)


maybe we don't need While it doesn't mean modification will cause trouble? :)

jannyHou · 2017-05-05T16:30:09Z

Suggestion:
By modelling the data in separate documents that are only written once, we can reduce the chance of concurrent access to the same document by separate processes.

@dhmlau I copied that part from couchdb document lol, but yours looks better. Changed.

b-admike · 2017-05-05T16:20:11Z

README.md

@@ -8,16 +8,207 @@ Local.
 For more information, see [Getting started with Cloudant NoSQL DB](https://www.ng.bluemix.net/docs/services/Cloudant/index.html)

 The `loopback-connector-cloudant` module is the Cloudant connector for the Loopback framework.


nitpick LoopBack

b-admike · 2017-05-05T16:27:00Z

README.md

+
+We have some discussion on update methods, the issue link can be found in [Feature Backlog](https://github.com/strongloop/loopback-connector-cloudant##feature-backlog) section
+
+### Careful Frequent Modification


I think having just Frequent Modification here is enough, but am okay with this as well.

b-admike · 2017-05-05T16:28:30Z

README.md

+|---------------|------------------------------|---------------------------------------|------------------------|
+| Relational DB | table                        | column in table                       | row in table           |
+| Mongodb       | collection                   | createIndex if property.index is true | document in collection |
+| Cloudant      | Design documents in database | NOT stored in document                     | common documents in database  |


If you know where model property is stored for cloudant, can you put that information here?

hmm, sorry I don't quite understand "If you know where model property is stored for cloudant", for example, where is it stored? could you give me a concrete example?

b-admike · 2017-05-05T16:29:27Z

README.md

+|               | Model                        | Model Property                        | Model Instance         |
+|---------------|------------------------------|---------------------------------------|------------------------|
+| Relational DB | table                        | column in table                       | row in table           |
+| Mongodb       | collection                   | createIndex if property.index is true | document in collection |


what if property.index is false for mongodb?

I didn't confirm with a real mongodb db collection, just read the logic from code: https://github.com/strongloop/loopback-connector-mongodb/blob/master/lib/mongodb.js#L1381

if index === false, connector does nothing to the property.

b-admike · 2017-05-05T16:30:14Z

README.md

-* Query and filtering is performed on the database for optimal efficiency.
-* Use different DB instances per model definition.
-* Supports basic model discovery.
+For model properties, we plan to create index for property that has config `index: true`. In the future, it will be the same way as what mongodb connector does.


can you also add a statement to say what happens when index: false or not specified?

b-admike · 2017-05-05T16:37:20Z

README.md

+  - No request limit.
+  - Please follow https://hub.docker.com/r/ibmcom/cloudant-developer/ to create your Cloudant local instance
+
+- Setup Cloudant on Bluemix


Cloudant on Bluemix to keep it consistent

b-admike · 2017-05-05T16:39:21Z

README.md

+  - Limited free trial.
+  - Sign up with https://cloudant.com/sign-up/ then you will see your Cloudant dashboard.
+
+To view the Cloudant dashboard on both DBaaS and Bluemix, [sign in](https://cloudant.com/sign-in/) with your Cloudant username and password.


are we sure that the link will log you in to your instances in Bluemix? thought you had to log into Bluemix for that.

I remember I can login with bluemix account, IIRC after you login bluemix and go to the cloudant instance dashboard, it just directs you to same domain as DBaaS

b-admike · 2017-05-05T16:40:42Z

README.md

+    return User.destroyAll();
+  }).then(function(user) {
+    console.log('destroy user!');
+  })catch(err);


}).catch(err);

b-admike · 2017-05-05T16:41:05Z

README.md


-```
+Loopback api assumes user include the `_rev` when modifying data, so please make sure you handle document's revision properly before you call a POST/PATCH/DELETE api. For details, refer to https://github.com/strongloop/loopback-connector-cloudant#_rev-property


nitpick LoopBack API

b-admike · 2017-05-05T16:43:20Z

README.md


-#### Note on using `updateOrCreate` functionality:
-**Cloudant does not support the idea of updating a document. All "updates" on a document are _destructive_ replacements.**
+I believe there are more stuff TBD in this part, appreciate more ideas.


https://loopback.io/doc/en/lb2/Built-in-models-REST-API

jannyHou · 2017-05-05T17:52:26Z

@b-admike @dhmlau @0candy PTAL again. Thanks.

0candy · 2017-05-05T19:23:57Z

README.md

+# Getting Started
+
+## Design
+LoopBack tries best to fit its model to a specific database's design, while limited by the nature of database, it's not always possible to support all LoopBack features perfectly, and user would like to be aware of some key features about Cloudant before they start to design a Cloudant model.


I think it should be users should be aware of some key features

0candy · 2017-05-05T20:04:43Z

README.md

+
+# Setup Cloudant Instance
+
+For user that don't have a cloudant server to develop or test, here is some suggestions can help you quickly setup one.


here are some suggestions that can help you

0candy · 2017-05-05T20:56:31Z

doc/multiple-db-instances.md

+
+For example, in function `Cloudant.prototype.destroy`, we call driver function by [`mo.db.destroy`](https://github.com/strongloop/loopback-connector-cloudant/blob/a62f72f291ed6fd7a5c318ceea3220cf19a2f2fe/lib/cloudant.js#L612), `mo` is the model.
+
+I am going to add some code example & test case to demo/verify this feature. That's why I keep it in a separate doc page.


Should we remove this line before check in?

@0candy this is on purpose, I pick the url of code from a specific commit, so the line number wouldn't change when master keeps getting new PR checked in.

jannyHou · 2017-05-05T21:06:13Z

doc/multiple-db-instances.md

+
+For example, in function `Cloudant.prototype.destroy`, we call driver function by [`mo.db.destroy`](https://github.com/strongloop/loopback-connector-cloudant/blob/a62f72f291ed6fd7a5c318ceea3220cf19a2f2fe/lib/cloudant.js#L612), `mo` is the model.
+
+I am going to add some code example & test case to demo/verify this feature. That's why I keep it in a separate doc page.


Removed "That's why I keep it in a separate doc page.", that is not public facing word.

* Inherit couchdb functionalities (#163) (Sakib Hasan) * Add stalebot configuration (Kevin Delisle) * Recover & reuse couchdb2 tests (jannyHou) * Fix readme (ssh24) * Create Issue and PR Templates (#171) (Sakib Hasan) * Add CODEOWNER file (Diana Lau) * Recover manipulation.test.js (#159) (Janny) * Recover juggler tests (#158) (Janny) * Require init on mocha args (ssh24) * Do not strip _rev value on create (ssh24) * Fix docs on bulk replace op hooks (ssh24) * Fix update/updateAll function (ssh24) * Add cloudant specific bulkReplace function (ssh24) * Check error and result (#149) (Janny) * Fix updateAttributes function (ssh24) * Fix doc (#148) (Janny) * viewDocs (#133) (Janny) * Return back result count in updateAll (ssh24) * Fix database name typo on README (ssh24) * Add regexp doc (#143) (Janny) * Add proxy config test (#142) (Janny) * Allow users to spawn docker and run tests (ssh24) * test: use Cloudant 2.x based image for testing (Ryan Graham) * test: replace setup.sh with test.js (Ryan Graham) * Refactor functions in cloudant (ssh24) * Allow handling of ._rev on models (#123) (Kevin Delisle) * Allow travis to run against the latest code base (#138) (Sakib Hasan) * Add docker setup (#132) (Sakib Hasan) * Fix updateOrCreate (#136) (Sakib Hasan) * Fix typo (#135) (Janny) * cloudant.test: cleanup after test runs (Kevin Delisle) * Setup Travis with Docker Compose (Kevin Delisle) * Refactor doc (#116) (Janny) * reinstate bulk update (biniam) * add array prop update tests (biniam) * update docs with current revision (biniam) * Allow id property to be a number (#115) (Sakib Hasan) * autoupdate and automigrate fix (#109) (Janny) * update readme to doc async connect (biniam) * check cloudant db in config (biniam) * call driver asynchronously (biniam) * Fix sort query builder (#107) (Janny) * Recover maxrows.test.js (#91) (Janny) * Fix regexp.test.js (#103) (Janny) * Use define function in loopback-connector (jannyHou) * add url config example (biniam) * Update connector to 4.0.0 (ssh24) * Add doc for fitler and order (jannyHou) * Add advisory note regarding update (ssh24) * Add $elemMatch for array (jannyHou) * Revert "Build selector with array type data" (jannyHou)

jannyHou added needs-priority #review labels May 2, 2017

jannyHou force-pushed the refactor/doc branch 5 times, most recently from e617860 to 203c82c Compare May 3, 2017 21:08

jannyHou changed the title ~~Add model doc~~ Refactor doc May 4, 2017

ssh24 reviewed May 4, 2017

View reviewed changes

dhmlau requested changes May 4, 2017

View reviewed changes

0candy suggested changes May 4, 2017

View reviewed changes

jannyHou self-assigned this May 4, 2017

jannyHou force-pushed the refactor/doc branch from 462bf30 to 1079305 Compare May 4, 2017 19:35

jannyHou force-pushed the refactor/doc branch from 24ed247 to e44dfda Compare May 4, 2017 19:58

ssh24 suggested changes May 4, 2017

View reviewed changes

ssh24 approved these changes May 5, 2017

View reviewed changes

dhmlau reviewed May 5, 2017

View reviewed changes

jannyHou force-pushed the refactor/doc branch from 55e11b6 to 2316233 Compare May 5, 2017 16:29

b-admike reviewed May 5, 2017

View reviewed changes

0candy reviewed May 5, 2017

View reviewed changes

b-admike approved these changes May 5, 2017

View reviewed changes

jannyHou added 4 commits May 5, 2017 16:42

Add model doc

4f97d5e

Apply change

2b9e04b

Add more stuff

9242403

Apply feedback

81cfb65

jannyHou force-pushed the refactor/doc branch from 80e7bf1 to 81cfb65 Compare May 5, 2017 20:42

jannyHou added 3 commits May 5, 2017 16:44

Apply feedback

aae05b0

fix typo

9f32b96

Change title case

534965a

0candy approved these changes May 5, 2017

View reviewed changes

Fix

7ce2e94

b-admike approved these changes May 5, 2017

View reviewed changes

Improve multiple db instances

cce6759

jannyHou commented May 5, 2017

View reviewed changes

jannyHou merged commit ca262d3 into master May 5, 2017

jannyHou added needs-priority and removed needs-priority #review labels May 5, 2017

jannyHou deleted the refactor/doc branch May 15, 2017 14:34


		Workaround: Do not pass partial values for the data object to be updated. If there are properties that are not being updated, please include the old value to keep data persistent.

		We plan to support partial update in the future by retrieving the original data and merging it with the updated one, but user should be aware of the risk when merging happens.

		Cloudant is not designed to change same document frequently and multiple times. It stores status change by creating different documents and including the same unique id to tell that they are attached to the same item, not updating the same document.

		By modeling the data in separate documents that are only written once, we can ensure that documents never become conflicted, such as during concurrent access to the same document by separate processes.


		## Map between model and document

		Unlike relational db or mongodb, cloudant doesn't have a concept as 'table' or 'collection', data in a cloudant database are all stored as documents.


		TBD.

		The basic idea is when modifying a document, user needs to control conflict by handling the revision of a document, currently the connector controls this process, after retriving the latest revision, connector uses it to update/delete doc, and returns 409 conflict error if doc changes during that time slot. In the middle user could not interfere and provide their own conflict solution.


		Unlike relational db or mongodb, cloudant doesn't have a concept as 'table' or 'collection', data in a cloudant database are all stored as documents.

		The connector uses a design document to represent a loopback model, and other non-design(non-design might not be the best word here, appreciate more ideas about how to describe it) documents to represent model instances.


		## _rev property

		In a document, property `_rev` is the latest doc revision and must be provided when modifing the doc. Currently when updating/deleting a doc, the connector first retrieves that doc, then gets its `_rev`, then calls a modify api with `_rev` included. It makes three calls to database and this would easily result in race condition.


		I believe there are more stuff TBD in this part, appreciate more ideas.


		After creating a Cloudant instance, you will need three configuration properties to run the tests: `username`, `password`, `database`
		- Cloduant local(docker image)


		By modeling the data in separate documents that are only written once, we can ensure that documents never become conflicted, such as during concurrent access to the same document by separate processes.

		While it doesn't mean modification will cause trouble, by properly conflict controllation, developer can still do a safe modify. For details, refer to [Conflict Control](https://github.com/strongloop/loopback-connector-cloudant##conflict-control)


		### Model-specific configuration

		You can also specify per-model configuration for database selection and to


		### Careful partial update

		Cloudant does not support the idea of updating a document. All "updates" on a document are _destructive_ replacements.


		Please note how property `prop2` was completely dropped upon update.

		Workaround: Do not pass partial values for the data object to be updated. If there are properties that are not being updated, please include the old value to keep data persistent.


		### Careful Frequent Modification

		Cloudant is not designed to change same document frequently and multiple times. It stores status change by creating different documents and including the same unique id to tell that they are attached to the same item, not updating the same document.

		@@ -8,16 +8,207 @@ Local.
		For more information, see [Getting started with Cloudant NoSQL DB](https://www.ng.bluemix.net/docs/services/Cloudant/index.html)

		The `loopback-connector-cloudant` module is the Cloudant connector for the Loopback framework.


		We have some discussion on update methods, the issue link can be found in [Feature Backlog](https://github.com/strongloop/loopback-connector-cloudant##feature-backlog) section

		### Careful Frequent Modification


		```
		Loopback api assumes user include the `_rev` when modifying data, so please make sure you handle document's revision properly before you call a POST/PATCH/DELETE api. For details, refer to https://github.com/strongloop/loopback-connector-cloudant#_rev-property


		# Setup Cloudant Instance

		For user that don't have a cloudant server to develop or test, here is some suggestions can help you quickly setup one.


		For example, in function `Cloudant.prototype.destroy`, we call driver function by [`mo.db.destroy`](https://github.com/strongloop/loopback-connector-cloudant/blob/a62f72f291ed6fd7a5c318ceea3220cf19a2f2fe/lib/cloudant.js#L612), `mo` is the model.

		I am going to add some code example & test case to demo/verify this feature. That's why I keep it in a separate doc page.

Refactor doc #116

Refactor doc #116

Conversation

jannyHou commented May 2, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jannyHou May 4, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jannyHou May 4, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jannyHou May 4, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jannyHou commented May 4, 2017 • edited Loading

jannyHou commented May 4, 2017

jannyHou commented May 4, 2017

ssh24 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jannyHou May 5, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jannyHou commented May 5, 2017

ssh24 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jannyHou May 5, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jannyHou May 5, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jannyHou commented May 5, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

b-admike May 5, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jannyHou commented May 5, 2017

jannyHou commented May 2, 2017 •

edited

Loading

jannyHou May 4, 2017 •

edited

Loading

jannyHou May 4, 2017 •

edited

Loading

jannyHou May 4, 2017 •

edited

Loading

jannyHou commented May 4, 2017 •

edited

Loading

jannyHou May 5, 2017 •

edited

Loading

jannyHou May 5, 2017 •

edited

Loading

jannyHou May 5, 2017 •

edited

Loading

b-admike May 5, 2017 •

edited

Loading

0candy May 5, 2017 •

edited

Loading