MIGRATION.md

Migrating to the cloudant-node-sdk library

This document is to assist in migrating from the nodejs-cloudant (package: @cloudant/cloudant) to the newly supported cloudant-node-sdk (package: @ibm-cloud/cloudant) that compatible with JavaScript and TypeScript.

Initializing the client connection

There are several ways to create a client connection in cloudant-node-sdk:

1. Environment variables
2. External configuration file
3. Programmatically

See the README for code examples on using environment variables.

Other differences

1. Using the dotenv package to store credentials in a file is not recommended. See the external file configuration section in our API docs for handling this feature in our new library.
2. In cloudant-node-sdk all operations are performed from the scope of the client instance and not associated with any sub-scope like the database. There is no need to instantiate a database object to interact with documents - the database name is included as part of document operations. For example, in the case of updating a document you would first call getDocument({ db: dbName, docId: docId}) to fetch and then putDocument({ db: dbName, docId: docId}) to update. As a result of which the use operation also became obsoleted.
3. Plugins are not supported, but several of the plugin features exist in the new library e.g. IAM, automatic retries for failed requests.
4. Error handling is not transferable from @cloudant/cloudant to @ibm-cloud/cloudant. For more information go to the Error handling section in our API docs.
5. Custom HTTP client configurations in @cloudant/cloudant can be set differently in @ibm-cloud/cloudant. For more information go to the Configuring the HTTP client section in the IBM Cloud SDK Common README.

Troubleshooting

1. Authentication errors occur during service instantiation. For example, the code const service = CloudantV1.newInstance({ serviceName: 'EXAMPLE' }); will fail with At least one of `iamProfileName` or `iamProfileId` must be specified. if required environment variables prefixed with EXAMPLE are not set.
2. Server errors occur when running a request against the service. We suggest to check server errors with getServerInformation which is the new alternative of ping.

Request mapping

Here's a list of the top 5 most frequently used nodejs-cloudant operations and the cloudant-node-sdk equivalent API operation documentation link:

nodejs-cloudant operation	cloudant-node-sdk API operation documentation link
db.get()	getDocument
db.view()	postView
db.find()	postFind
db.head()	headDocument
db.insert()	putDocument

A table with the whole list of operations is provided at the end of this guide.

The cloudant-node-sdk library is generated from a more complete API spec and provides a significant number of operations that do not exist in nodejs-cloudant. See the IBM Cloud API Documentation to review request parameter and body options, code examples, and additional details for every endpoint.

Known Issues

There's an outline of known issues in the cloudant-node-sdk repository.

Reference table

The table below contains a list of nodejs-cloudant functions and the cloudant-node-sdk equivalent API operation documentation link. The cloudant-node-sdk operation documentation link will contain the new function in a code sample e.g. getServerInformation link will contain a code example with getServerInformation().

Note: There are many API operations included in the new cloudant-node-sdk that are not available in the nodejs-cloudant library. The API documentation contains the full list of operations.

nodejs-cloudant function	cloudant-node-sdk function reference
ping()	getServerInformation
listDbs()/listDbsAsStream()	getAllDbs
updates()/followUpdates()	getDbUpdates
replicate()/replicateDb()/enableReplication()/replication.enable()	putReplicationDocument
queryReplication()/replication.query()	getSchedulerDocument
disableReplication()/replication.delete()	deleteReplicationDocument
session()	getSessionInformation
uuids()	getUuids
db.destroy()	deleteDatabase
db.info()	getDatabaseInformation
db.insert()	postDocument
db.create(db_name)	putDatabase
db.fetch()/db.list()/db.listAsStream()	postAllDocs, postAllDocsAsStream
db.bulk()	postBulkDocs
db.bulk_get()	postBulkGet
db.changes()	postChanges
db.destroy() with _design path	deleteDesignDocument
db.get() with _design path	getDesignDocument
db.insert() with _design path	putDesignDocument
db.search()/db.searchAsStream()	postSearch, postSearchAsStream
db.view()	postView
db.list() (only design documents)	postDesignDocs
db.find()	postFind
db.createIndex()	postIndex
db.index.del()	deleteIndex
db.destroy() with _local path	deleteLocalDocument
db.get() with _local path	getLocalDocument
db.insert() with _local path	putLocalDocument
db.partitionInfo()	getPartitionInformation
db.partitionedList()/partitionedListAsStream()	postPartitionAllDocs, postPartitionAllDocsAsStream
db.partitionedSearch()/partitionedSearchAsStream()	postPartitionSearch, postPartitionSearchAsStream
db.partitionedView()/partitionedViewAsStream()	postPartitionView, postPartitionViewAsStream
db.partitionedFind()/partitionedFindAsStream()	postPartitionFind, postPartitionFindAsStream
db.get_security()	getSecurity
db.set_security()	putSecurity
db.destroy()	deleteDocument
db.get()	getDocument
db.head()	headDocument
db.insert()	putDocument
db.attachment.destroy()	deleteAttachment
db.attachment.get/getAsStream	getAttachment
db.attachment.insert/insertAsStream	putAttachment
generate_api_key()	postApiKeys
db.set_security()	putCloudantSecurityConfiguration
get_cors()	getCorsInformation
set_cors()	putCorsConfiguration
db.geo()	getGeo