[CDRIVER-3755] Provide an index creation helper Created: 16/Jul/20  Updated: 28/Oct/23  Resolved: 14/Jun/23

Status: Closed
Project: C Driver
Component/s: None
Affects Version/s: None
Fix Version/s: 1.24.0

Type: Improvement Priority: Major - P3
Reporter: Kevin Albertson Assignee: Kevin Albertson
Resolution: Fixed Votes: 0
Labels: GnG, neweng, rp-track
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Depends
is depended on by CDRIVER-3646 Hidden Indexes Closed
Epic Link: Improve Developer Experience
Quarter: FY24Q2

 Description   

CDRIVER-2096 deprecated index creation helpers in favor of sending createIndexes commands directly through generic command helpers. This is documented in the Creating Indexes guide.

This adds some difficulty for users and wrapping drivers in terms of constructing the command and passing supported options.

The commitQuorum option is particularly problematic. This option is only supported on 4.4+ servers, and has adverse side-effects on older servers. This is documented by CDRIVER-3748 and the Q&A of the index management spec:

Starting in 3.4, the server validates all options passed to the createIndexes command, but due to a bug in versions 4.2.0-4.2.5 of the server (SERVER-47193), specifying commitQuorum does not result in an error. The option is used internally by the server on those versions, and its value could have adverse effects on index builds. To prevent users from mistakenly specifying this option, drivers manually verify it is only sent to 4.4+ servers.

Since libmongoc does not provide an index creation helper, and generic command helpers should not be validating command specific options, this forces the user / wrapping driver to do this validation. In particular, this required additional server selection and wire version checking in the C++ driver's support of commitQuorum (CXX-1998).

This PR discussion has additional context and motivation: https://github.com/mongodb/mongo-c-driver/pull/662#discussion_r454365303.



 Comments   
Comment by Githook User [ 14/Jun/23 ]

Author:

{'name': 'Kevin Albertson', 'email': 'kevin.albertson@mongodb.com', 'username': 'kevinAlbs'}

Message: CDRIVER-3755 Provide an index creation helper (#1303)

  • format mongoc-collection.c
  • add `mongoc_collection_create_indexes_with_opts`
  • make `assert_match_bson` a macro

Includes the caller's file and line number on error.

  • fixup `hex_to_bin` helper
  • return NULL if `hex` is NULL
  • set `len` to 0 on error

This fixes a possible crash if LOCAL_MASTERKEY is not set in the example.

  • update legacy test runner to use `mongoc_collection_create_indexes_with_opts`
  • use `mongoc_collection_create_indexes_with_opts` in `create_collection_with_encryptedFields`
  • use `mongoc_collection_create_indexes_with_opts` in `operation_create_index`
  • fix placement of `strlen`

`strlen` was called was before `to_encrypt.value.v_utf8.str` was assigned. This resulted in a `strlen` call with `NULL` argument.

  • use `mongoc_collection_create_indexes_with_opts` in examples
  • add documentation page for `mongoc_collection_create_indexes_with_opts`
  • update "Creating Indexes" guide
  • add file name to example error message

Co-authored-by: vector-of-bool <vectorofbool@gmail.com>

  • fix documented type of `models` to include `*`

Co-authored-by: Ezra Chung <88335979+eramongodb@users.noreply.github.com>

  • simplify error handling

Co-authored-by: Ezra Chung <88335979+eramongodb@users.noreply.github.com>

  • revise assert message

Co-authored-by: Ezra Chung <88335979+eramongodb@users.noreply.github.com>

  • use `mongoc_collection_create_indexes_with_opts` in more tests
  • rename FAIL to HANDLE_ERROR
  • document "success" and "failure" paths in example
  • rename guide page to "Manage Collection Indexes"
  • rename guide file to `manage-collection-indexes.rst`
  • rename `example-create-indexes.c` to `example-manage-collection-indexes.c`
  • add "See Also" sections
  • link to `createIndexes` documentation for form of `keys`
  • document `mongoc_index_model_t`
  • change `BSON_ASSERT` to `return NULL;`
  • make pointer argument const

---------

Co-authored-by: vector-of-bool <vectorofbool@gmail.com>
Co-authored-by: Ezra Chung <88335979+eramongodb@users.noreply.github.com>
Branch: master
https://github.com/mongodb/mongo-c-driver/commit/ca45383fcf3843b0f360c72e5296e7bc5335efd9

Comment by Rachelle Palmer [ 14/Feb/22 ]

Flagging for re-triage as I think maybe this can be closed?

Generated at Wed Feb 07 21:18:56 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.