From 5a313815af1a7d184f147d9050b33d15e5f7f29c Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 6 Aug 2024 14:54:51 -0400 Subject: [PATCH 1/6] DOCSP-37046: csot in v2 --- source/fundamentals/connections.txt | 4 +- source/fundamentals/connections/.tls.txt.swp | Bin 16384 -> 0 bytes .../connections/connection-guide.txt | 177 +--------------- .../connections/connection-options.txt | 198 ++++++++++++++++++ source/fundamentals/connections/tls.txt | 2 +- source/fundamentals/context.txt | 19 +- .../fundamentals/crud/compound-operations.txt | 12 -- .../crud/read-operations/count.txt | 10 +- .../crud/read-operations/distinct.txt | 4 +- .../crud/read-operations/retrieve.txt | 4 - source/fundamentals/crud/write-read-pref.txt | 17 +- source/whats-new.txt | 40 +++- 12 files changed, 266 insertions(+), 221 deletions(-) delete mode 100644 source/fundamentals/connections/.tls.txt.swp create mode 100644 source/fundamentals/connections/connection-options.txt diff --git a/source/fundamentals/connections.txt b/source/fundamentals/connections.txt index 172dd16b..11769ea5 100644 --- a/source/fundamentals/connections.txt +++ b/source/fundamentals/connections.txt @@ -7,6 +7,7 @@ Connections .. toctree:: /fundamentals/connections/connection-guide + /fundamentals/connections/connection-options /fundamentals/connections/network-compression /fundamentals/connections/tls Connect to MongoDB Atlas from AWS Lambda @@ -24,6 +25,7 @@ Learn how to use the {+driver-short+} to configure your application's connection to a MongoDB deployment in the following sections: - :ref:`golang-connection-guide` +- :ref:`golang-connection-options` - :ref:`golang-network-compression` - :ref:`golang-tls` - :atlas:`Connect to MongoDB Atlas from AWS Lambda ` @@ -31,4 +33,4 @@ connection to a MongoDB deployment in the following sections: To learn how to authenticate to MongoDB, see the following pages: - :ref:`golang-authentication-mechanisms` -- :ref:`golang-enterprise-authentication-mechanisms` \ No newline at end of file +- :ref:`golang-enterprise-authentication-mechanisms` diff --git a/source/fundamentals/connections/.tls.txt.swp b/source/fundamentals/connections/.tls.txt.swp deleted file mode 100644 index 289380895ea6c5b0d952ce25dd05a554ae280c1b..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 16384 zcmeI3Z;Tve9mgO3DE=u37(p@7$5!F4z1?ez6xm#h$F<;LOKY#R5Fp*Too8>yo12-= z%-(f@g0GasD4J-3FO*18(L#JBL=zyIC?;S6zA#Z^G?HkHR*VpRsh{8T%G` z#_T5FUT^35^Lu{(f4^sLe(T}cefqlkR>kLHrCxq*&iwK6)_IRTrBticiRJ4z`s}M6 zyy+8rZ`^V7%r!T^-q`zO!AajNPx^5yt1ZN#7cER?aW`$5$#ysLy(JUnUYJd`;wUn$ zJcy%gG7qzQemsA@g-6du92jxnEI4qXx_bLIYwDXeen7wT(p%4B&S=Pp10xQMI56VC zhyx=Ij5sjjz=#7Q4*b7xAWzO!_j8zYiv!(T{5)sX&-04kZ!3PDSoOU4b@XGzfe{Br z92jw6#DNh9MjRM%V8nqD2SywiabU!O5eNPUIpFz9oey0bqyfPFe_8+k?Hx+J0)7FW z29JW1;34n;NWn3%0P3IyE(I5WS1(fP58x&6B6tow1D*ywuob*=p;9k^=fT6^Yv3^0 z4Q9Z)Gxu0zz@Nb;1u`{h`<4` zA8Y_Wd#h4k0S|#Y!F#~F!A0Og@XA}1`U&_kcpN+kJ`aw7tH9|Cl==(!Id}qm6MPON zpbb6>UVF1rKLFnc-vy_@BDe~?7hC~edJ}vC-v*C?FM_*44{Qgg5zsflqu|TnOJEk9 z1D>TZ^9;Bb>;rqj6c`7WgUi4<;IGK{Gy?g)^pdw2L<`!}hxX3t!K)v2Sw#ri9~m8|dMQrL5J_G)@5E`42L_U28Ey9* zY^JA+5j{ONGdz%& zT1(+ULvK^{x(=d>%JF3> z?OV#`n>x&-?yoj1aoob6a+!j14v62?7wmqxd|NOv=lR@km( z!9pY?3>cJI9#_B63nnrt0{68S`MQ`g@5Gz&f=+e1E+x>j>j))D8v9-Q=8o(;p;wGf z4d;LwzjBCuakLQczJc@hNfk1ey)f``D0LkmiZu74T=+Ufpd4J!bEF)7fXYlC*t1W! zgV1V$c8s>FWRV+)I*Bi~x1H zDpQAIopoC+lV$C081{4!p@Cu{PJdH#tcx@XQBH4m~p z741j*8FcTyWlql>JZyC)^_c~GTVdB{h*+R#Mil4P*!b0boIyxb5>JGHu3EoPSr+og?EK_zD`KM${ zp*M}m$*E49#zHp;y?GNhnnPS{3Tv&u5Hs=+Rf^XqZitRr!D-xNLO@V+CPWE!JB^pDJ0JM^ z>f)=ZXo}+%PAnP1o9{woD>e8Z8zh^n=xJgi1e>U3R81f7vdj*PH2RhIuvn+77%SR{ zXBJQAOnFGH$D2*2^OfDj4L~kTa|$NYnoW@sUj=LJ+o`%zJR*c@ypF6fIPr?t%Nh!I zYC}@RN#iSoiG7=49~ zOlhw7dOZ@CInzQn;n38|WDxo0cs=PP*OR=2W@mrwQ9Jf%Irhpp^aFqAwrwBz@YWqy z@3?lyF8n0>5E4S;rDQUaqImOhHy7HRrxiXNDe1sP=4lTW$u#k1d60;@n$4hSDR1pl|Ud{9UJgfyg-PIK0Bs(e`O_d0e3v=8my9m4!uZWgd zRTaxvSM`u|5#B_~eVPuMwn+^-JQVfh_+FVrmh?H_5KWGC14$Ny zygmVRX-&j+ds~eiC~<$;fu8o48tCY*W+mMd`w;TnW5@7Fks_AD zhZhnEi_CCfSXuF&G)iQ%Cnrpo`V5?gV_IEFl4Uis*hiFeAY7|Lg^Cq{y2?g$MXfri zknHKwRtMQ!U2I~&>b0}fY*n*uwq!knv!g;S~n^6|NYc}|2)st|KuBr%fJiN@6UtB!717btKM9V4cY&9w*?$jCf;&K2$DgKN{}xyR0k{*~ z0j>b2sn7oeo&cW$JHh+G`@pZM%^v|@2PeS2AO|5>1Y_V;>hr&YC&BkX0``F2;1W>Q z?x(2HzW^Qtv)~eNF?f->{8{h}I0+sBp9ML{z;)nKa0z&p8a)C_;0`bgJ_a^`-<_}2 zZ-LbBcY!THc>NFI_vka?z<-AWHQhXZ&DQI5f*-`Q>8VbhCmGp!vba#EfRaDbanbdX%8n#ATe#6o!>EhLcP^b%Vh*!F?*uAbLslg> zEs}isE3z(1Y%68rW*Fpju!!z9Um}K+-@DXl^&gp0WM@&3Bqn!%W=5qgfjBc%Nyxn^ zLUMtXqNg30kk*DPY}OQEYE#`7Uqyaa$$iTLMiLjd>ab0)bW!Qi!<6lrTgkf0oio{C z)>eA9-6Y+T$}UB5Cn^g0q>`5YgK?bCOiLBVgJN-vv%WX>{M)eWkDJ~BFG$Cz{t6;w z7kTPdaGF-_logFO8Z%v6XtIx8S2m{EMVGIbS)@=U!)B)KOj&+L(o);)DZbQ6OkP)A zl9P$sso!E&gck>RUZqiO8?3VIVIj0uZT8&Hr|kJFoiV$4;?d8Q64jNjDg z(0{TLA+q*_ZN#I=yi&qzKc+M+%ju4+gW){dUv&A zD^z^AoO>NdjbJx9Z57v7KchQaqcwfgv<|*#Zb>QWB%8UmY}rOEndExM%iU1=#Rx!- zZH_0l&Z=YSWk<>#)OuoD*JG%acF1f& z)*L;B!}iXjv`smBzd7Ounbk)t-W9q6&`RDf`*TuTiR}1{>__H!Q&?@X&6_9G5!4z^*%=irC?z_m!h}G_SuZ5tE&O3hKWmwmeA!7V zh(fk*$&$2!fz4(mgMd{qK!^P`JEePmF;r zt=B_!9DOz_xn3x<+1M3`RAF5!G9AxF>t|7F>d%OSa$|t-Z=wno2Pk(r zvX^|fXiTEuvUM)|-L_R9!;tknIA521G?r|2WW6htHwscBW981HGYLFgA4yCouI=Pr zsAw115_^do6|qq}ru6!*jK$7x=S24QV&Gq`4pr=kOOt_O4IlYT0lyml)f+c}hTNqi zvDyT3$$(rJ9^#k@4FIXqMG(HRI$@8Nq`|V>)f7jhme)a>J0ERtFYGwuTichbMCqm` zoz%-*jKhRErA;Mh%Q{;Uo>tgkN`zhw)M+G4cUklMAdt8;>zVC9XglZ(fx`{4o?;<{fWBzH(=**` - when the specified host isn't the **primary**. - -.. _golang-connection-options: - ------------------- -Connection Options ------------------- - -This section explains several common MongoDB connection and authentication -options. You can pass the connection options as parameters of the connection -URI to specify the behavior of the client. - -.. list-table:: - :header-rows: 1 - :widths: 34 10 12 44 - - * - Option Name - - Type - - Default Value - - Description - - * - **timeoutMS** - - integer - - ``null`` - - Specifies the number of milliseconds that a single operation run on the - ``Client`` can take before returning a timeout error. Operations honor - this setting only if there is no deadline on the operation Context. - - * - **connectTimeoutMS** - - integer - - ``30000`` - - Specifies the number of milliseconds to wait before timeout on a TCP - connection. - - * - **maxPoolSize** - - integer - - ``100`` - - Specifies the maximum number of connections that a connection pool may - have at a given time. - - * - **replicaSet** - - string - - ``null`` - - Specifies the replica set name for the cluster. All nodes in the - replica set must have the same replica set name, or the Client will not - consider them as part of the set. - - * - **maxIdleTimeMS** - - integer - - ``0`` - - Specifies the maximum amount of time a connection can remain idle - in the connection pool before being removed and closed. The - default is ``0``, meaning a connection can remain unused - indefinitely. - - * - **minPoolSize** - - integer - - ``0`` - - Specifies the minimum number of connections that the driver maintains - in a single connection pool. - - * - **socketTimeoutMS** - - integer - - ``0`` - - Specifies the number of milliseconds to wait for a socket read or - write to return before returning a network error. The ``0`` - default value indicates that there is no timeout. - - * - **serverSelectionTimeoutMS** - - integer - - ``30000`` - - Specifies the number of milliseconds to wait to find an available, - suitable server to execute an operation. - - * - **heartbeatFrequencyMS** - - integer - - ``10000`` - - Specifies the number of milliseconds to wait between periodic - background server checks. - - * - **tls** - - boolean - - ``false`` - - Specifies whether to establish a Transport Layer Security (TLS) - connection with the instance. This is automatically set to ``true`` - when using a DNS seedlist (SRV) in the connection string. You can - override this behavior by setting the value to ``false``. - - * - **w** - - string or integer - - ``null`` - - Specifies the write concern. To learn more about values, see the - server documentation on - :manual:`Write Concern options `. - - * - **directConnection** - - boolean - - ``false`` - - Specifies whether to force dispatch **all** operations to the host - specified in the connection URI. - -For a full list of connection options, see the `ClientOptions API -documentation -<{+api+}/mongo/options#ClientOptions>`__. - -.. _golang-timeout-setting: - -Single Timeout Setting -~~~~~~~~~~~~~~~~~~~~~~ - -You can set a single ``Timeout`` option on your ``Client`` to govern the -amount of time that a single operation can take to execute using the -``SetTimeout()`` method or specifying the ``timeoutMS`` option in your -connection URI string. ``Database``, ``Collection``, -``Session``, ``ChangeStream``, and ``Bucket`` instances elsewhere in -your code inherit the ``Timeout`` option from ``Client`` if you do not set a -Context for operations against the same entity. - -If you pass a Context into an operation with a deadline, the driver uses -that Context deadline for the operation. If the context does not have a -deadline, the driver derives a new Context from the given Context using -the ``Timeout`` option set on the ``Client``. - -.. note:: Retries under Timeout Specification - - With default settings, if you set a ``Timeout`` option on your ``Client`` - and your operation requires a retry, the driver retries the operation - as many times as possible before the timeout expires. Once the timeout - expires, the driver returns a timeout error. Versions 1.1 and later - of the {+driver-short+} enable retryable reads and writes by default. - See the Server manual for more information about :ref:`retryable - reads ` and :manual:`retryable writes `. - -The following code shows how to set the ``Timeout`` option on a ``Client`` -with the ``SetTimeout`` option: - -.. code-block:: go - - opts := options.Client().SetTimeout(5 * time.Second) - -The following example shows how you can set a single timeout with the -URI option and execute an operation that inherits this setting: - -.. code-block:: go - - uri := "mongodb://user:pass@sample.host:27017/?timeoutMS=5000" - - client, err := mongo.Connect(options.Client().ApplyURI(uri)) - coll := client.Database("").Collection("") - - ... - coll.InsertOne(context.Background(), doc) - -.. important:: Legacy Timeout Options - - ``SocketTimeout``, ``wTimeout``, ``MaxTime``, and ``MaxCommitTime`` - will be deprecated in an upcoming release. The driver ignores ``MaxTime`` and - ``MaxCommitTime`` if you set ``Timeout``. The driver still honors - ``SocketTimeout`` and ``wTimeout``, but these settings may result in - undefined behavior. Consider using only the single timeout option instead. +To force operations on the host designated in the connection URI, +specify the ``directConnection`` option. Direct connections exhibit the +following behavior: + +- They don't support SRV strings. +- They fail on writes when the specified host is not the **primary**. +- They require you to specify a :manual:`secondary read preference + ` when the + specified host isn't the **primary** node. diff --git a/source/fundamentals/connections/connection-options.txt b/source/fundamentals/connections/connection-options.txt new file mode 100644 index 00000000..0d01ab34 --- /dev/null +++ b/source/fundamentals/connections/connection-options.txt @@ -0,0 +1,198 @@ +.. _golang-connection-options: + +================== +Connection Options +================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :description: Learn how to set connection options when using the MongoDB Go Driver. + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +This guide explains several common MongoDB connection and authentication +options. You can pass the connection options as parameters of the connection +URI to specify the behavior of the client. + +Options +------- + +The following table describes the connection options that you can set in +your connection URI. Each entry provides the option name, value type, +default value, and a description of the option. + +.. list-table:: + :header-rows: 1 + :widths: 34 10 12 44 + + * - Option Name + - Type + - Default Value + - Description + + * - **timeoutMS** + - integer + - ``null`` + - Specifies the number of milliseconds that a single operation run on the + ``Client`` can take before returning a timeout error. Operations honor + this setting only if there is no deadline on the operation Context. + + * - **connectTimeoutMS** + - integer + - ``30000`` + - Specifies the number of milliseconds to wait before timeout on a TCP + connection. + + * - **maxPoolSize** + - integer + - ``100`` + - Specifies the maximum number of connections that a connection pool may + have at a given time. + + * - **replicaSet** + - string + - ``null`` + - Specifies the replica set name for the cluster. All nodes in the + replica set must have the same replica set name, or the Client will not + consider them as part of the set. + + * - **maxIdleTimeMS** + - integer + - ``0`` + - Specifies the maximum amount of time a connection can remain idle + in the connection pool before being removed and closed. The + default is ``0``, meaning a connection can remain unused + indefinitely. + + * - **minPoolSize** + - integer + - ``0`` + - Specifies the minimum number of connections that the driver maintains + in a single connection pool. + + * - **serverSelectionTimeoutMS** + - integer + - ``30000`` + - Specifies the number of milliseconds to wait to find an available, + suitable server to execute an operation. + + * - **heartbeatFrequencyMS** + - integer + - ``10000`` + - Specifies the number of milliseconds to wait between periodic + background server checks. + + * - **tls** + - boolean + - ``false`` + - Specifies whether to establish a Transport Layer Security (TLS) + connection with the instance. This is automatically set to ``true`` + when using a DNS seedlist (SRV) in the connection string. You can + override this behavior by setting the value to ``false``. + + * - **w** + - string or integer + - ``null`` + - Specifies the write concern. To learn more about values, see the + server documentation on + :manual:`Write Concern options `. + + * - **directConnection** + - boolean + - ``false`` + - Specifies whether to force dispatch **all** operations to the host + specified in the connection URI. + +For a full list of connection options, see the `ClientOptions API +documentation +<{+api+}/mongo/options#ClientOptions>`__. + +.. _golang-timeout-setting: + +Single Timeout Setting +---------------------- + +You can set a single ``Timeout`` option on your ``Client`` instance to +specify the amount of time that a single operation can take to execute. +Set a timeout by using the ``SetTimeout()`` method or specifying the +``timeoutMS`` option in your connection URI string. ``Database``, ``Collection``, +``Session``, ``ChangeStream``, and ``Bucket`` instances elsewhere in +your code inherit the ``Timeout`` option from ``Client`` if you do not +set a different timeout in a Context for specific operations. + +If you pass a Context into an operation with a deadline, the driver uses +that Context deadline for the operation. If the context does not have a +deadline, the driver derives a new Context from the given Context by using +the ``Timeout`` option set on the ``Client``. + +.. note:: Retries under Timeout Specification + + When using default settings, if you set a ``Timeout`` option on your ``Client`` + and your operation requires a retry, the driver retries the operation + as many times as possible before the timeout expires. Once the timeout + expires, the driver returns a timeout error. Versions 1.1 and later + of the {+driver-short+} enable retryable reads and writes by default. + See the Server manual for more information about :ref:`retryable + reads ` and :manual:`retryable writes `. + +Timeout Examples +~~~~~~~~~~~~~~~~ + +This section provides examples that demonstrate different ways to set the +``Timeout`` setting in your application. + +Client Option +^^^^^^^^^^^^^ + +The following code shows how to set the ``Timeout`` option on a ``Client`` +by using the ``SetTimeout()`` method: + +.. code-block:: go + + opts := options.Client().SetTimeout(5 * time.Second) + client, err := mongo.Connect(opts) + +Connection String Option +^^^^^^^^^^^^^^^^^^^^^^^^ + +The following example shows how you can set a single timeout with the +URI option and execute an operation that inherits this setting: + +.. code-block:: go + + uri := "mongodb://user:pass@sample.host:27017/?timeoutMS=5000" + + client, err := mongo.Connect(options.Client().ApplyURI(uri)) + coll := client.Database("").Collection("") + + ... + coll.InsertOne(context.Background(), doc) + +Multiple Timeouts +^^^^^^^^^^^^^^^^^ + +The following example shows how you can set the ``Timeout`` option on a +``Client`` instance, then set a different timeout for an insert option +within the Context passed to the ``InsertOne()`` method: + +.. code-block:: go + :emphasize-lines: 1, 5 + + opts := options.Client().SetTimeout(5 * time.Second) + client, err := mongo.Connect(opts) + + ... + ctx, cancel := context.WithTimeout(context.TODO(), time.Second) + defer cancel() + + res, err := coll.InsertOne(ctx, bson.D{{"x", 2}}) diff --git a/source/fundamentals/connections/tls.txt b/source/fundamentals/connections/tls.txt index 1eabcb19..6e0163f1 100644 --- a/source/fundamentals/connections/tls.txt +++ b/source/fundamentals/connections/tls.txt @@ -89,7 +89,7 @@ Select from the following :guilabel:`Connection String` and the ``mongodb+srv`` prefix, TLS is enabled on your connection by default. -For a full list of client options, see :ref:`golang-connection-options`. +To view a full list of client options, see :ref:`golang-connection-options`. .. _golang-configure-tls-certificates: diff --git a/source/fundamentals/context.txt b/source/fundamentals/context.txt index 50d3e511..310c4cab 100644 --- a/source/fundamentals/context.txt +++ b/source/fundamentals/context.txt @@ -20,31 +20,30 @@ Context Overview -------- -The {+driver-long+} uses the `context package -`__ from Go's standard library to allow +The {+driver-short+} uses the `context package +`__ from the Go standard library to allow applications to signal timeouts and cancellations for any **blocking method** call. A blocking method relies on an external event, such as a network input or output, to proceed with its task. -An example of a blocking method in the Go Driver is the ``Insert()`` +An example of a blocking method is the ``InsertOne()`` method. If you want to perform an insert operation on a ``Collection`` within 10 seconds, you can use a Context with a timeout. If the operation doesn't complete within the timeout, the method returns an error. .. code-block:: go - :emphasize-lines: 3 - - client, err := mongo.Connect(options.Client().ApplyURI(uri)) ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) defer cancel() - client.Database("").Collection("").Insert(ctx, bson.D{{"x",1}}) + + client.Database("db").Collection("items").InsertOne(ctx, bson.D{{"x",1}}) If the Context passed into an operation does not have a deadline, you -can set a ``Timeout`` option on your ``Client`` and the operation will -derive the timeout specification from this setting. To learn more -about using the single timeout setting, see the :ref:`Connection Guide `. +can set a ``Timeout`` option on your ``Client`` and the operation +derives the timeout specification from this setting. To learn more +about using the single timeout setting, see the +:ref:`golang-timeout-setting` in the Connection Options guide. Expiration ---------- diff --git a/source/fundamentals/crud/compound-operations.txt b/source/fundamentals/crud/compound-operations.txt index 3d006081..26e5712c 100644 --- a/source/fundamentals/crud/compound-operations.txt +++ b/source/fundamentals/crud/compound-operations.txt @@ -104,10 +104,6 @@ with the following methods: - | The type of language collation to use when sorting results. | Default: ``nil`` - * - ``SetMaxTime()`` - - | The maximum amount of time that the query can run on the server. - | Default: ``nil`` - * - ``SetProjection()`` - | The fields to include in the document returned. | Default: ``nil`` @@ -200,10 +196,6 @@ with the following methods: * - ``SetCollation()`` - | The type of language collation to use when sorting results. | Default: ``nil`` - - * - ``SetMaxTime()`` - - | The maximum amount of time that the query can run on the server. - | Default: ``nil`` * - ``SetProjection()`` - | The fields to include in the document returned. @@ -302,10 +294,6 @@ with the following methods: * - ``SetCollation()`` - | The type of language collation to use when sorting results. | Default: ``nil`` - - * - ``SetMaxTime()`` - - | The maximum amount of time that the query can run on the server. - | Default: ``nil`` * - ``SetProjection()`` - | The fields to include in the document returned. diff --git a/source/fundamentals/crud/read-operations/count.txt b/source/fundamentals/crud/read-operations/count.txt index c03ca45f..7f43e7c1 100644 --- a/source/fundamentals/crud/read-operations/count.txt +++ b/source/fundamentals/crud/read-operations/count.txt @@ -100,10 +100,6 @@ following methods: - | The maximum number of documents to count. | Default: ``0`` - * - ``SetMaxTime()`` - - | The maximum amount of time that the query can run on the server. - | Default: ``nil`` - * - ``SetSkip()`` - | The number of documents to skip before counting. | Default: ``0`` @@ -201,7 +197,7 @@ in an ``EstimatedDocumentCountOptions`` type. If you don't specify any options, the driver uses its default values. The ``EstimatedDocumentCountOptions`` type allows you to configure -options with the following methods: +options by using the following methods: .. list-table:: :widths: 30 70 @@ -210,8 +206,8 @@ options with the following methods: * - Method - Description - * - ``SetMaxTime()`` - - | The maximum amount of time that the query can run on the server. + * - ``SetComment()`` + - | Sets a comment to attach to the count operation. | Default: ``nil`` Example diff --git a/source/fundamentals/crud/read-operations/distinct.txt b/source/fundamentals/crud/read-operations/distinct.txt index 60cbdc29..d0124762 100644 --- a/source/fundamentals/crud/read-operations/distinct.txt +++ b/source/fundamentals/crud/read-operations/distinct.txt @@ -89,8 +89,8 @@ with the following methods: - | The type of language collation to use when sorting results. | Default: ``nil`` - * - ``SetMaxTime()`` - - | The maximum amount of time that the query can run on the server. + * - ``SetComment()`` + - | Sets a comment to attach to the distinct operation. | Default: ``nil`` Example diff --git a/source/fundamentals/crud/read-operations/retrieve.txt b/source/fundamentals/crud/read-operations/retrieve.txt index 22fb0cf3..d18b3832 100644 --- a/source/fundamentals/crud/read-operations/retrieve.txt +++ b/source/fundamentals/crud/read-operations/retrieve.txt @@ -291,10 +291,6 @@ following methods: - | The type of language collation to use when sorting results. | Default: ``nil`` - * - ``SetMaxTime()`` - - | The maximum amount of time that the query can run on the server. - | Default: ``nil`` - * - ``SetMaxAwaitTime()`` - | The maximum amount of time for the server to wait on new documents to satisfy a tailable cursor query. | Default: ``nil`` diff --git a/source/fundamentals/crud/write-read-pref.txt b/source/fundamentals/crud/write-read-pref.txt index 79f0d74d..26c171e2 100644 --- a/source/fundamentals/crud/write-read-pref.txt +++ b/source/fundamentals/crud/write-read-pref.txt @@ -106,6 +106,13 @@ select common write concern specifications: | | **Parameter**: none +.. tip:: Write Concern Timeout + + You cannot set a timeout on a ``WriteConcern`` instance. Instead, set + the timeout at the operation level by using the ``WithTimeout()`` + method when creating a Context. To learn more, see + :ref:`golang-timeout-setting` in the Connection Options guide. + If you require a more specialized write concern, you can define a custom ``WriteConcern`` struct literal. You can set the following fields in a ``WriteConcern`` struct: @@ -130,16 +137,6 @@ If you require a more specialized write concern, you can define a custom | | **Type**: ``bool`` - * - ``WTimeout`` - - | Specifies a time limit for the write concern. This setting is - applicable only for ``W`` values greater than 1. Specifying this - setting and specifying a :ref:`Timeout - ` on the client at the same time - results in undefined behavior. To learn more, see the - :manual:`Write Concern specification for wtimeout `. - | - | **Type**: ``time.Duration`` - .. tip:: You can alternatively specify a write concern in your connection diff --git a/source/whats-new.txt b/source/whats-new.txt index 2cf5490c..26bbbaab 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -51,13 +51,39 @@ Learn what's new in: What's New in 2.0 ----------------- -.. important:: Breaking Change - - Starting in version 2.0, the ``mongo.Connect()`` method does not - accept a context parameter. This method accepts only an options - object. To view an example that uses this method, see the - :ref:`Connection Example Code ` in the - Connection Guide. +.. important:: Breaking Changes + + The {+driver-short+} v2.0 release introduces the following breaking + changes: + + - ``mongo.Connect()`` does not accept a Context parameter. This + method accepts only an options object. To view an example that uses + this method, see the :ref:`Connection Example Code + ` in the Connection Guide. + + - Removal of operation-specific timeout options. The following fields + and setter methods have been removed from the driver: + + - ``AggregateOptions.MaxTime``, ``AggregateOptions.SetMaxTime()`` + - ``ClientOptions.SocketTimeout``, ``ClientOptions.SetSocketTimeout()`` + - ``CountOptions.MaxTime``, ``CountOptions.SetMaxTime()`` + - ``DistinctOptions.MaxTime``, ``DistinctOptions.SetMaxTime()`` + - ``EstimatedDocumentCountOptions.MaxTime``, ``EstimatedDocumentCountOptions.SetMaxTime()`` + - ``FindOptions.MaxTime``, ``FindOptions.SetMaxTime()`` + - ``FindOneOptions.MaxTime``, ``FindOneOptions.SetMaxTime()`` + - ``FindOneAndReplaceOptions.MaxTime``, ``FindOneAndReplaceOptions.SetMaxTime()`` + - ``FindOneAndUpdateOptions.MaxTime``, ``FindOneAndUpdateOptions.SetMaxTime()`` + - ``GridFSFindOptions.MaxTime``, ``GridFSFindOptions.SetMaxTime()`` + - ``CreateIndexesOptions.MaxTime``, ``CreateIndexesOptions.SetMaxTime()`` + - ``DropIndexesOptions.MaxTime``, ``DropIndexesOptions.SetMaxTime()`` + - ``ListIndexesOptions.MaxTime``, ``ListIndexesOptions.SetMaxTime()`` + - ``SessionOptions.DefaultMaxCommitTime``, ``SessionOptions.SetDefaultMaxCommitTime()`` + - ``TransactionOptions.MaxCommitTime``, ``TransactionOptions.SetMaxCommitTime()`` + - ``WriteConcern.WTimeout`` + + Instead, you can set a timeout on your client or within a Context. + Learn more in the :ref:`golang-timeout-setting` section of the + Connection Options guide. The 2.0 {+driver-short+} release includes the following improvements and fixes: From dc81a850d7e00e4b0abce6b6127842806e6148c9 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 6 Aug 2024 15:01:56 -0400 Subject: [PATCH 2/6] wip --- source/fundamentals/connections/connection-options.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/fundamentals/connections/connection-options.txt b/source/fundamentals/connections/connection-options.txt index 0d01ab34..25db812c 100644 --- a/source/fundamentals/connections/connection-options.txt +++ b/source/fundamentals/connections/connection-options.txt @@ -9,7 +9,7 @@ Connection Options :values: reference .. meta:: - :description: Learn how to set connection options when using the MongoDB Go Driver. + :keywords: code example, timeout, customize connection .. contents:: On this page :local: From ba63674b63a896c53ed3b764f49a20ef7ecb19ce Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 6 Aug 2024 16:54:50 -0400 Subject: [PATCH 3/6] wip --- source/fundamentals/connections/connection-options.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/source/fundamentals/connections/connection-options.txt b/source/fundamentals/connections/connection-options.txt index 25db812c..eee7b9a5 100644 --- a/source/fundamentals/connections/connection-options.txt +++ b/source/fundamentals/connections/connection-options.txt @@ -173,7 +173,6 @@ URI option and execute an operation that inherits this setting: uri := "mongodb://user:pass@sample.host:27017/?timeoutMS=5000" client, err := mongo.Connect(options.Client().ApplyURI(uri)) - coll := client.Database("").Collection("") ... coll.InsertOne(context.Background(), doc) From d5f1d833f51c43c369465e39be37079021fa63d5 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 7 Aug 2024 10:13:15 -0400 Subject: [PATCH 4/6] JS PR fixes 1 --- .../connections/connection-options.txt | 44 ++++++++++--------- 1 file changed, 24 insertions(+), 20 deletions(-) diff --git a/source/fundamentals/connections/connection-options.txt b/source/fundamentals/connections/connection-options.txt index eee7b9a5..822a8701 100644 --- a/source/fundamentals/connections/connection-options.txt +++ b/source/fundamentals/connections/connection-options.txt @@ -21,7 +21,7 @@ Overview -------- This guide explains several common MongoDB connection and authentication -options. You can pass the connection options as parameters of the connection +options. You can pass the connection options as parameters in the connection URI to specify the behavior of the client. Options @@ -50,8 +50,8 @@ default value, and a description of the option. * - **connectTimeoutMS** - integer - ``30000`` - - Specifies the number of milliseconds to wait before timeout on a TCP - connection. + - Specifies the time in milliseconds to attempt a connection before + timing out. * - **maxPoolSize** - integer @@ -123,17 +123,20 @@ Single Timeout Setting ---------------------- You can set a single ``Timeout`` option on your ``Client`` instance to -specify the amount of time that a single operation can take to execute. -Set a timeout by using the ``SetTimeout()`` method or specifying the -``timeoutMS`` option in your connection URI string. ``Database``, ``Collection``, -``Session``, ``ChangeStream``, and ``Bucket`` instances elsewhere in -your code inherit the ``Timeout`` option from ``Client`` if you do not -set a different timeout in a Context for specific operations. - -If you pass a Context into an operation with a deadline, the driver uses -that Context deadline for the operation. If the context does not have a -deadline, the driver derives a new Context from the given Context by using -the ``Timeout`` option set on the ``Client``. +specify the maximum amount of time that a single operation can take to +execute. + +Set a timeout by calling the ``SetTimeout()`` method when specifying +options for your ``Client`` instance orby specifying the +``timeoutMS`` option in your connection URI. By default, all +``Database``, ``Collection``, ``Session``, ``ChangeStream``, and +``Bucket`` instances elsewhere in your application inherit the +``Timeout`` option from ``Client`` if you do not set a different timeout +on specific operations in the operation's Context. + +If you set a timeout on a Context passed into an operation, the driver uses +that value for the operation. If you do not specify a Context timeout, +the operation Context derives the timeout from the ``Client`` instance. .. note:: Retries under Timeout Specification @@ -165,13 +168,14 @@ by using the ``SetTimeout()`` method: Connection String Option ^^^^^^^^^^^^^^^^^^^^^^^^ -The following example shows how you can set a single timeout with the -URI option and execute an operation that inherits this setting: +The following example shows how to set a single timeout by using the +``timeoutMS`` URI option. Then, the code executes an insert operation +that inherits the timeout: .. code-block:: go + :emphasize-lines: 1, 5 uri := "mongodb://user:pass@sample.host:27017/?timeoutMS=5000" - client, err := mongo.Connect(options.Client().ApplyURI(uri)) ... @@ -180,9 +184,9 @@ URI option and execute an operation that inherits this setting: Multiple Timeouts ^^^^^^^^^^^^^^^^^ -The following example shows how you can set the ``Timeout`` option on a -``Client`` instance, then set a different timeout for an insert option -within the Context passed to the ``InsertOne()`` method: +The following example shows how to set the ``Timeout`` option on a +``Client`` instance. Then, the code sets a different timeout within the +Context passed to the ``InsertOne()`` method: .. code-block:: go :emphasize-lines: 1, 5 From ccef96b7380778a37385136480df513189f442a4 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 7 Aug 2024 11:06:41 -0400 Subject: [PATCH 5/6] JS PR fixes 2: typo --- source/fundamentals/connections/connection-options.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/fundamentals/connections/connection-options.txt b/source/fundamentals/connections/connection-options.txt index 822a8701..20024281 100644 --- a/source/fundamentals/connections/connection-options.txt +++ b/source/fundamentals/connections/connection-options.txt @@ -127,7 +127,7 @@ specify the maximum amount of time that a single operation can take to execute. Set a timeout by calling the ``SetTimeout()`` method when specifying -options for your ``Client`` instance orby specifying the +options for your ``Client`` instance or by specifying the ``timeoutMS`` option in your connection URI. By default, all ``Database``, ``Collection``, ``Session``, ``ChangeStream``, and ``Bucket`` instances elsewhere in your application inherit the From 9d6e9f9e648b11b95ecf4ddf2c75f72ea80545ee Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 9 Aug 2024 10:31:16 -0400 Subject: [PATCH 6/6] PV tech review 1 --- .../connections/connection-options.txt | 34 ++++++++----------- 1 file changed, 15 insertions(+), 19 deletions(-) diff --git a/source/fundamentals/connections/connection-options.txt b/source/fundamentals/connections/connection-options.txt index 20024281..af2537da 100644 --- a/source/fundamentals/connections/connection-options.txt +++ b/source/fundamentals/connections/connection-options.txt @@ -126,8 +126,8 @@ You can set a single ``Timeout`` option on your ``Client`` instance to specify the maximum amount of time that a single operation can take to execute. -Set a timeout by calling the ``SetTimeout()`` method when specifying -options for your ``Client`` instance or by specifying the +Set a client-level timeout by calling the ``SetTimeout()`` method when +specifying options for your ``Client`` instance or by specifying the ``timeoutMS`` option in your connection URI. By default, all ``Database``, ``Collection``, ``Session``, ``ChangeStream``, and ``Bucket`` instances elsewhere in your application inherit the @@ -140,19 +140,20 @@ the operation Context derives the timeout from the ``Client`` instance. .. note:: Retries under Timeout Specification - When using default settings, if you set a ``Timeout`` option on your ``Client`` - and your operation requires a retry, the driver retries the operation - as many times as possible before the timeout expires. Once the timeout - expires, the driver returns a timeout error. Versions 1.1 and later - of the {+driver-short+} enable retryable reads and writes by default. + If you set a timeout on your ``Client`` or in an operation-level + Context and the server returns a retryable error, the driver retries the + operation as many times as possible before the timeout expires. + + Once the timeout expires, the driver returns a timeout error. See the Server manual for more information about :ref:`retryable - reads ` and :manual:`retryable writes `. + reads ` and :manual:`retryable writes + `. Timeout Examples ~~~~~~~~~~~~~~~~ -This section provides examples that demonstrate different ways to set the -``Timeout`` setting in your application. +This section provides examples that demonstrate different ways to set a +timeout in your application. Client Option ^^^^^^^^^^^^^ @@ -181,20 +182,15 @@ that inherits the timeout: ... coll.InsertOne(context.Background(), doc) -Multiple Timeouts +Operation Timeout ^^^^^^^^^^^^^^^^^ -The following example shows how to set the ``Timeout`` option on a -``Client`` instance. Then, the code sets a different timeout within the -Context passed to the ``InsertOne()`` method: +The following example shows how to set an operation-level timeout in a +Context, which takes priority over a client-level timeout you might have +set: .. code-block:: go - :emphasize-lines: 1, 5 - - opts := options.Client().SetTimeout(5 * time.Second) - client, err := mongo.Connect(opts) - ... ctx, cancel := context.WithTimeout(context.TODO(), time.Second) defer cancel()