RECENT POSTS

Upcoming Kivik changes for CouchDB 3.x

Feb 29, 2020 • Jonathan Hall

Earlier this week CouchDB 3.0.0 was released! This represents a big step forward, with several exciting new features.

Good news and bad news

The good news for Kivik users is that the Kivik 3.0.0 integration test suite passes with flying colors against CouchDB 3.0.0, with no changes at all. This means that if you’re using Kivik 3.x (or 2.x) and choose to upgrade your CouchDB installation to 3.0.0, you won’t need to make any changes to your client code.

The bad news, though, is that none of the new API endpoints of CouchDB 3.0.0 are yet supported by Kivik. But I aim to remedy that quickly with a release of Kivik 3.1.0. Any features of CouchDB 3.0.0 that do not require API endpoint changes should work automatically with Kivik, though they have not been explicitly tested. If you discover something is not working, please report a bug.

Upcoming changes to Kivik

Here is a high-level outline of the new features in CouchDB, and plans for inclusion in Kivik. Your feedback is welcome, to help shape these new features of Kivik (please comment freely on the linked GitHub issues).

  • Multiple query requests – Kivik issue #447.

    Kivik currently has four view methods: Query(), AllDocs(), LocalDocs() and DesignDocs(). Duplicating all of these to include multi-query variants seems like a heavy API change, for what is likely to be a rarely-used feature. For this reason, the two options I’m most seriously considering at the moment are:

    • Deprecate AllDocs(), LocalDocs(), and DesignDocs(), making it possible to query these views via Query() (possibly by specifying an empty ddoc argument, and passing _all_docs, _local, or _design, respectively, as the view name). Then adding a single Queries() method will seem natural.
    • Adding the same functionality as above, but keeping at least AllDocs(), and possibly LocalDocs(), and DesignDocs() as simple convenience functions. This seems attractive, given that AllDocs() is one of the most commonly used methods in Kivik code I have seen.

    Please leave your opinion, or alternate suggestions, on the Kivik issue.

  • Partitioned queries – Kivik issue #448

    The semantics of new partitioned queries are identical to the existing view queries, they just require one additional URL component: _partition/{partition}. Three possible approaches come to mind:

    1. Create new Partition variants of each query metho. e.g. AllDocsPartition, QueryPartition, etc.
    2. Accept the partition as part of the view ID. e.g. Query(ctx, "ddoc", "_partition/123/view") This will only work with Query(), but in conjunction with the proposed changes to support multiple query requests, this could work.
    3. Accepting a partition option. e.g. AllDocs(kivik.Options{"_partition":"123})

    I am leaning toward the third option. I believe it has two compelling advantages:

    • It doesn’t clutter the Kivik API with any new methods.
    • It would be 100% backward compatible with the current API.

    And one minor disadvantage:

    • Using an option to change the fundamental behavior of a query seems a bit icky. But it’s not entirely without precedent.

    I believe the most natural way to implement this would be by adding a new constant to the couchdb driver package:

      // Partition specifies the name of a partition, and causes a partition-bound query.
  Partition = "kivik:partition"

  • Full Text Search - Kivik issue #450

    I believe this will be pretty straight forward. I intend to add three new methods:

    • Search(), the analog to Query() and Find(), will be used to perform search queries.
    • SearchInfo() will be used for the _search_info endpoint
    • SearchAnalyze will be the analog to Explain for mango queries.

And finally, a couple of new features I probably won’t be implementing in Kivik, because they are primarily used for maintenance, and thus the value of a Go SDK seems dubious. But if you feel otherwise, please let me know by commenting on the appropriate issue in GitHub, and I will be happy to re-consider.

That sums up the upcoming changes for Kivik 3.1.0. Depending on time, and the complexity of implementing the multi-query requests, I anticipate having a release ready by mid-April.

Opinions, comments, and of course, pull requests, are welcome from all!