Skip to content

Commit 1bafa94

Browse files
kevinAlbskevinAlbs
authored
CDRIVER-5708 deprecate mongoc_<obj>_command (#1778)
* deprecate `mongoc_(client|database|collection)_command` * recommend `mongoc_<obj>_command_simple` as a simpler alternative * add migrating example code
1 parent ff0c9fb commit 1bafa94

File tree

10 files changed

+321
-31
lines changed

10 files changed

+321
-31
lines changed

‎NEWS‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,12 @@ Platform Support:
66

77
* Support for Visual Studio 2013 is dropped.
88

9+
Deprecated:
10+
11+
* `mongoc_client_command` is deprecated and planned for removal in a future release. Use `mongoc_client_command_simple` instead.
12+
* `mongoc_database_command` is deprecated and planned for removal in a future release. Use `mongoc_database_command_simple` instead.
13+
* `mongoc_collection_command` is deprecated and planned for removal in a future release. Use `mongoc_collection_command_simple` instead.
14+
915
libmongoc 1.28.1
1016
================
1117

‎src/libmongoc/CMakeLists.txt‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1338,6 +1338,11 @@ if (ENABLE_EXAMPLES AND ENABLE_SHARED)
13381338
# examples/tutorial
13391339
mongoc_add_example (executing ${PROJECT_SOURCE_DIR}/examples/tutorial/executing.c)
13401340
mongoc_add_example (appending ${PROJECT_SOURCE_DIR}/examples/tutorial/appending.c)
1341+
mongoc_add_example (migrating ${PROJECT_SOURCE_DIR}/examples/migrating.c)
1342+
# Ignore deprecation warnings in migrating examples. Migrating examples deliberately call deprecated API to show how to migrate.
1343+
target_compile_options (migrating
1344+
PRIVATE $<$<NOT:$<C_COMPILER_ID:MSVC>>:-Wno-deprecated-declarations>
1345+
)
13411346
endif ()
13421347

13431348
if (ENABLE_TESTS AND ENABLE_SHARED AND MONGOC_ENABLE_SSL AND NOT WIN32)

‎src/libmongoc/doc/mongoc_client_command.rst‎

Lines changed: 29 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,12 @@
33
mongoc_client_command()
44
=======================
55

6+
.. warning::
7+
.. deprecated:: 1.29.0
8+
9+
This function is deprecated and should not be used in new code.
10+
Use :symbol:`mongoc_client_command_simple()` instead.
11+
612
Synopsis
713
--------
814

@@ -19,8 +25,6 @@ Synopsis
1925
const bson_t *fields,
2026
const mongoc_read_prefs_t *read_prefs);
2127
22-
This function is superseded by :symbol:`mongoc_client_command_with_opts()`, :symbol:`mongoc_client_read_command_with_opts()`, :symbol:`mongoc_client_write_command_with_opts()`, and :symbol:`mongoc_client_read_write_command_with_opts()`.
23-
2428
.. include:: includes/not-retryable-read.txt
2529

2630
Description
@@ -43,6 +47,29 @@ Parameters
4347
* ``fields``: Unused.
4448
* ``read_prefs``: An optional :symbol:`mongoc_read_prefs_t`. Otherwise, the command uses mode ``MONGOC_READ_PRIMARY``.
4549

50+
Migrating
51+
---------
52+
53+
:symbol:`mongoc_client_command` is deprecated.
54+
55+
The following example uses :symbol:`mongoc_client_command`:
56+
57+
.. literalinclude:: ../examples/migrating.c
58+
:language: c
59+
:dedent: 6
60+
:start-after: // mongoc_client_command ... before ... begin
61+
:end-before: // mongoc_client_command ... before ... end
62+
:caption: Before
63+
64+
The above code block may be rewritten to use :symbol:`mongoc_client_command_simple` instead, as shown below:
65+
66+
.. literalinclude:: ../examples/migrating.c
67+
:language: c
68+
:dedent: 6
69+
:start-after: // mongoc_client_command ... after ... begin
70+
:end-before: // mongoc_client_command ... after ... end
71+
:caption: After
72+
4673
Returns
4774
-------
4875

‎src/libmongoc/doc/mongoc_collection_command.rst‎

Lines changed: 34 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,12 @@
33
mongoc_collection_command()
44
===========================
55

6+
.. warning::
7+
.. deprecated:: 1.29.0
8+
9+
This function is deprecated and should not be used in new code.
10+
Use :symbol:`mongoc_collection_command_simple()` instead.
11+
612
Synopsis
713
--------
814

@@ -18,22 +24,43 @@ Synopsis
1824
const bson_t *fields,
1925
const mongoc_read_prefs_t *read_prefs);
2026
21-
This function is superseded by :symbol:`mongoc_collection_command_with_opts()`, :symbol:`mongoc_collection_read_command_with_opts()`, :symbol:`mongoc_collection_write_command_with_opts()`, and :symbol:`mongoc_collection_read_write_command_with_opts()`.
22-
2327
.. include:: includes/not-retryable-read.txt
2428

2529
Parameters
2630
----------
2731

2832
* ``collection``: A :symbol:`mongoc_collection_t`.
29-
* ``flags``: A :symbol:`mongoc_query_flags_t`.
30-
* ``skip``: A uint32_t with the number of documents to skip or zero.
31-
* ``limit``: A uint32_t with the max number of documents to return or zero.
32-
* ``batch_size``: A uint32_t with the number of documents in each batch or zero. Default is 100.
33+
* ``flags``: Unused.
34+
* ``skip``: Unused.
35+
* ``limit``: Unused.
36+
* ``batch_size``: Unused.
3337
* ``command``: A :symbol:`bson:bson_t` containing the command to execute.
34-
* ``fields``: A :symbol:`bson:bson_t` containing the fields to return or ``NULL``. Not all commands support this option.
38+
* ``fields``: Unused.
3539
* ``read_prefs``: An optional :symbol:`mongoc_read_prefs_t`. Otherwise, the command uses mode ``MONGOC_READ_PRIMARY``.
3640

41+
Migrating
42+
---------
43+
44+
:symbol:`mongoc_collection_command` is deprecated.
45+
46+
The following example uses :symbol:`mongoc_collection_command`:
47+
48+
.. literalinclude:: ../examples/migrating.c
49+
:language: c
50+
:dedent: 6
51+
:start-after: // mongoc_collection_command ... before ... begin
52+
:end-before: // mongoc_collection_command ... before ... end
53+
:caption: Before
54+
55+
The above code block may be rewritten to use :symbol:`mongoc_collection_command_simple` instead, as shown below:
56+
57+
.. literalinclude:: ../examples/migrating.c
58+
:language: c
59+
:dedent: 6
60+
:start-after: // mongoc_collection_command ... after ... begin
61+
:end-before: // mongoc_collection_command ... after ... end
62+
:caption: After
63+
3764
Returns
3865
-------
3966

‎src/libmongoc/doc/mongoc_database_command.rst‎

Lines changed: 34 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,12 @@
33
mongoc_database_command()
44
=========================
55

6+
.. warning::
7+
.. deprecated:: 1.29.0
8+
9+
This function is deprecated and should not be used in new code.
10+
Use :symbol:`mongoc_database_command_simple()` instead.
11+
612
Synopsis
713
--------
814

@@ -18,8 +24,6 @@ Synopsis
1824
const bson_t *fields,
1925
const mongoc_read_prefs_t *read_prefs);
2026
21-
This function is superseded by :symbol:`mongoc_database_command_with_opts()`, :symbol:`mongoc_database_read_command_with_opts()`, :symbol:`mongoc_database_write_command_with_opts()`, and :symbol:`mongoc_database_read_write_command_with_opts()`.
22-
2327
Description
2428
-----------
2529

@@ -31,14 +35,37 @@ Parameters
3135
----------
3236

3337
* ``database``: A :symbol:`mongoc_database_t`.
34-
* ``flags``: A :symbol:`mongoc_query_flags_t`.
35-
* ``skip``: The number of documents to skip on the server.
36-
* ``limit``: The maximum number of documents to return from the cursor.
37-
* ``batch_size``: Attempt to batch results from the server in groups of ``batch_size`` documents.
38+
* ``flags``: Unused.
39+
* ``skip``: Unused.
40+
* ``limit``: Unused.
41+
* ``batch_size``: Unused.
3842
* ``command``: A :symbol:`bson:bson_t` containing the command.
39-
* ``fields``: An optional :symbol:`bson:bson_t` containing the fields to return. ``NULL`` for all fields.
43+
* ``fields``: Unused.
4044
* ``read_prefs``: An optional :symbol:`mongoc_read_prefs_t`. Otherwise, the command uses mode ``MONGOC_READ_PRIMARY``.
4145

46+
Migrating
47+
---------
48+
49+
:symbol:`mongoc_database_command` is deprecated.
50+
51+
The following example uses :symbol:`mongoc_database_command`:
52+
53+
.. literalinclude:: ../examples/migrating.c
54+
:language: c
55+
:dedent: 6
56+
:start-after: // mongoc_database_command ... before ... begin
57+
:end-before: // mongoc_database_command ... before ... end
58+
:caption: Before
59+
60+
The above code block may be rewritten to use :symbol:`mongoc_database_command_simple` instead, as shown below:
61+
62+
.. literalinclude:: ../examples/migrating.c
63+
:language: c
64+
:dedent: 6
65+
:start-after: // mongoc_database_command ... after ... begin
66+
:end-before: // mongoc_database_command ... after ... end
67+
:caption: After
68+
4269
Returns
4370
-------
4471

‎src/libmongoc/examples/basic_aggregation/map-reduce-advanced.c‎

Lines changed: 6 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,8 @@ map_reduce_advanced (mongoc_database_t *database)
44
bson_t *command;
55
bson_error_t error;
66
bool res = true;
7-
mongoc_cursor_t *cursor;
87
mongoc_read_prefs_t *read_pref;
9-
const bson_t *doc;
8+
bson_t doc;
109

1110
/* Construct the mapReduce command */
1211
/* Other arguments can also be specified here, like "query" or "limit"
@@ -22,25 +21,20 @@ map_reduce_advanced (mongoc_database_t *database)
2221
"out",
2322
"{",
2423
"inline",
25-
"1",
24+
BCON_INT32 (1),
2625
"}");
2726

2827
read_pref = mongoc_read_prefs_new (MONGOC_READ_SECONDARY);
29-
cursor = mongoc_database_command (database, MONGOC_QUERY_NONE, 0, 0, 0, command, NULL, read_pref);
30-
31-
/* Do something with the results */
32-
while (mongoc_cursor_next (cursor, &doc)) {
33-
print_res (doc);
34-
}
35-
36-
if (mongoc_cursor_error (cursor, &error)) {
28+
if (mongoc_database_command_simple (database, command, read_pref, &doc, &error)) {
29+
print_res (&doc);
30+
} else {
3731
fprintf (stderr, "ERROR: %s\n", error.message);
3832
res = false;
3933
}
4034

41-
mongoc_cursor_destroy (cursor);
4235
mongoc_read_prefs_destroy (read_pref);
4336
bson_destroy (command);
37+
bson_destroy (&doc);
4438

4539
return res;
4640
}

0 commit comments

Comments
 (0)