Service Changes and Deprecations for IBM Cloudant

Details

Notice that the following Cloudant features are deprecated:

• show functions - used to modify the format of the response when requesting a single document from the database.
• list functions - similar to show functions, but applied to the output of MapReduce views.
• rewrite functions - used to embody routing logic in CouchApps.
• update functions - used to carry out business logic within the database e.g. adding a timestamp to all document writes.

These four features are already deprecated in Apache CouchDB and scheduled to be removed from the code in Apache CouchDB 4.0. None of these features are modelled in our Cloudant SDKs.

Although these features are deprecated, they will not be removed from the service yet.

We may completely remove the features in the future, but will leave them operable for the time being to give customers time to modify their applications. As deprecated features, they will not appear in our documentation, their use is not recommended and they will not be supported by our Support team.

Alternatives to these functions can be found on the Cloudant blog here.

Details

Replicator endpoint proxy support is removed. Replication jobs with proxy, source_proxy or target_proxy fields set will fail with an error.

Details

Due to the end of the Cloud Foundry service, IBM Cloudant instances that are created as Cloud Foundry service instances are being deprecated and must be migrated to an IBM Cloud resource group.

Migration to a resource group provides the added capability to use IBM Cloud IAM to control access. When migrating the Cloudant instance, you can choose which of your IBM Cloud resource groups to migrate it to. For example, you might have one resource group for production and a different one for Dev/Test.

Standard Plan instances that are not migrated before 1 September 2023 will be migrated by IBM.

Should IBM be required to migrate a Cloudant instance to a resource group, it will be migrated to the default resource group for the IBM Cloud account. The assignment of the Cloudant instance to the default resource group cannot be changed later.

Deadline for Lite plan instances has been extended from 1 August 2023 to 18 September 2023: Lite plan instances that are not migrated before 18 September 2023 will be disabled for 30 days and deleted on 18 October 2023.

How do I know if my instances use Cloud Foundry?

• Display the list of Cloudant instances in the IBM Cloud GUI
• The presence of the migrate icon after the instance name identifies instances that need to be migrated

How do I migrate the instance to an IBM Cloud resource group?

• To complete the migration, follow these IBM Cloudant instructions.

1. Open the More actions menu.
2. Select Migrate to a resource group to get started.
3. Select a resource group.
4. Click Migrate and the instance is migrated for you.
5. Since you can migrate only one instance at a time, you can continue migrating eligible instances after you migrate the first one.

The data in the Cloudant instance is not involved in this migration. There is no Cloudant service downtime as a result of this migration.

What is IBM Cloudant Geospatial?

Data is stored as GeoJSON in the IBM Cloudant database to describe point, line, polygon, multi-point, multi-line, and multi-polygon objects. Each object, as well as the geographic information, can have optional properties: Metadata about the object, which is returned in the search results.

Again, an index is defined as a JavaScript function, and then, queries can be used to ask questions of your collection of geographic features. For example, find me the nearest object to this point; find objects within this polygon; find objects along this path; or find objects that intersect with this object.

To summarize, IBM Cloudant Geo is something unique to the IBM Cloudant service and is used to perform advanced geospatial queries against your databases of GeoJSON objects. It cannot be combined with other index types. It is only of use to Geographic Information Systems or use-cases that have a purely geographic purpose.

What is changing?

As of 1 February 2023, the following conditions apply:

• Users cannot query /$DATABASE/_design/$DDOCS/_geo endpoints. Requests to those endpoints return a 404 Not Found response.
• Users can define indexes by using the st_indexes keyword in design documents, but those indexes are ignored by the service. This practice ensures that existing design documents can be updated, and replications that contain geospatial indexes do not fail. Existing Geo indexes are deleted, and customers are no longer billed for the space they consume.
• IBM Cloud® support no longer answers questions or assists with issues that are related to the Geospatial feature of the IBM Cloudant service.

Alternatives to geospatial

Many simple geospatial queries can be done without using the Geospatial capability that was removed from the IBM Cloudant service. These alternatives are described in this IBM Cloudant blog post.

What is dbcopy?

IBM Cloudant allows materialized MapReduce views to be created on a database - a secondary index structure that contains user-defined keys and values. MapReduce views exist and are queried in the same path as the primary database.

With the "dbcopy" feature configured, the MapReduce data is instead written to a second database. The second database then contains the key/value pairs that would usually be found in the materialized view of a normal MapReduce view. The dbcopy feature was used to allow view data to be "chained" (for example, the creation of views of views) or to provide a primitive join functionality between documents.

What happens after the feature is removed?

The primary database continues to function as normal, but any MapReduce indexes with dbcopy configured no longer write data to the secondary database. The secondary database still exists, but it cannot be updated when the primary data changes.

How do I know whether my MapReduce views use dbcopy?

MapReduce index definitions are stored in a database's design documents. These MapReduce index definitions contain JavaScript that programmatically decides what data from the document makes it into the view, as shown in the following example:

{
  "_id": "_design/myview",
  "views": {
    "view": {
      "map": "function(doc) { emit(doc.date, doc.price) }",
      "dbcopy": "another_database"
    }
  }
}

If a view definition contains an attribute that is called dbcopy, as is the case with the previous example design document, then the dbcopy feature is in use and is affected by the feature's removal.

Alternatives to dbcopy

No alternative to the dbcopy feature exists. Simply removing the "dbcopy" attribute from a design document instructs IBM Cloudant to build a normal MapReduce view. This view contains the same data that was being copied to the secondary database, for example:

{
  "_id": "_design/myview",
  "views": {
    "view": {
      "map": "function(doc) { emit(doc.date, doc.price) }"
    }
  }
}

The dbcopy key was removed, so this view becomes a normal MapReduce view that you can query by using the IBM Cloudant API.

If you are concerned about the removal of the dbcopy feature, you can open a support ticket and ask to consult with our Client Architecture team.

What is replication?

IBM Cloudant replications allow you to copy one database's changes to another IBM Cloudant database. This database is in the same IBM Cloudant instance or in another IBM Cloudant instance on the other side of the world. IBM Cloudant also replicates to and from Apache CouchDB and PouchDB databases on the public internet.

What happens after HTTP support is removed?

Following this change, a replication that is configured with the http:// protocol fails permanently. The replication job is not retried. Any replications using the https:// protocol are unaffected.

How do I know whether my replications use HTTP?

Replication job definitions are stored in documents in an IBM Cloudant account's _replicator database, for example:

{
  "_id": "myreplicationjob",
  "source": "https://mycloudantservice.cloudant.com/products",
  "target": "http://myselfhostedcouchdb.mydomain.com/products"
}

If either the source or target URLs contain an http:// prefix, then the replication job is affected and action must be taken to ensure the replication runs.

How do I avoid being affected?

If a self-hosted CouchDB service supports HTTPS, then change the replication definition to contain an https:// prefix, as shown in the following example:

{
  "_id": "myreplicationjob",
  "source": "https://mycloudantservice.cloudant.com/products",
  "target": "https://myselfhostedcouchdb.mydomain.com/products"
}

IBM Cloudant restarts the replication from where the old replication job stopped.

If a self-hosted CouchDB service does _not* support HTTPS, CouchDB can mediate replication jobs instead of IBM Cloudant. For example, stop the replication job that runs on the IBM Cloudant side and set up a replication job on a self-hosted Apache CouchDB service to "pull" the data from IBM Cloudant.

IBM Cloudant supports only https:// traffic, so if IBM Cloudant is to be the source or target in a self-hosted replication definition, it must be configured with an https:// prefix.