Skip to content

Commit 27e0d70

Browse files
rustagirrustagir
authored
DOCSP-13871: FAQ page (mongodb#226)
* DOCSP-13871: FAQ go driver * first pass fixes * CC PR fixes 1 * CC PR fixes 2 * CC suggestions
1 parent d8adc35 commit 27e0d70

File tree

2 files changed

+120
-3
lines changed

2 files changed

+120
-3
lines changed

‎source/faq.txt

+119-3
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,128 @@ FAQ
66

77
.. default-domain:: mongodb
88

9-
Frequently Asked Questions
10-
119
.. contents:: On this page
1210
:local:
1311
:backlinks: none
1412
:depth: 1
1513
:class: singlecol
1614

17-
Lorem ipsum.
15+
This page contains frequently asked questions and their corresponding answers.
16+
17+
.. tip::
18+
19+
If you can't find an answer to your problem on this page,
20+
see the :ref:`golang-issues-and-help` page for next steps and more
21+
resources.
22+
23+
How Can I Fix the "WriteNull can only write while positioned on a Element or Value but is positioned on a TopLevel" Error?
24+
--------------------------------------------------------------------------------------------------------------------------
25+
26+
The ``bson.Marshal()`` method requires a parameter that can be decoded
27+
into a BSON document, such as the ``bson.D`` type. This error occurs
28+
when you pass something *other* than a BSON document to
29+
``bson.Marshal()``.
30+
31+
The ``WriteNull`` error occurs when you pass a ``null`` to
32+
``bson.Marshal()``. Situations in which a similar error can occur
33+
include the following:
34+
35+
- You pass a string to ``bson.Marshal()``, causing a ``WriteString`` error.
36+
- You pass a boolean to ``bson.Marshal()``, causing a ``WriteBoolean`` error.
37+
- You pass an integer to ``bson.Marshal()``, causing a ``WriteInt32`` error.
38+
39+
You may encounter this error when you perform a CRUD operation that
40+
internally uses the ``bson.Marshal()`` method or when you call
41+
``bson.Marshal()`` directly to encode data.
42+
43+
The following code produces a ``WriteNull`` error because the driver
44+
cannot encode the ``null`` valued ``sortOrder`` variable to BSON during
45+
the ``FindOneAndUpdate()`` operation:
46+
47+
.. code-block:: go
48+
49+
var sortOrder bson.D
50+
opts := options.FindOneAndUpdate().SetSort(sortOrder)
51+
52+
updateDocument := bson.D{{"$inc", bson.D{{"counter", 1}}}}
53+
result := coll.FindOneAndUpdate(context.TODO(), bson.D{}, updateDocument, opts)
54+
if err := result.Err(); err != nil {
55+
panic(err)
56+
}
57+
58+
The following code shows how to correctly initialize the ``sortOrder``
59+
variable as a ``bson.D`` type so that the driver can convert it to BSON:
60+
61+
.. code-block:: go
62+
63+
sortOrder := bson.D{}
64+
65+
How Do I Convert a BSON Document to JSON?
66+
-----------------------------------------
67+
68+
The driver provides a variety of marshaller methods that can be used to
69+
convert a BSON document to JSON, such as the ``MarshalExtJSON()``
70+
method. To view a readable form of the JSON encoding, you must use
71+
an unmarshaller method or string type-casting to parse the JSON byte
72+
format.
73+
74+
The following code converts a BSON document to JSON using the
75+
``MarshalExtJSON()`` method, then parses and prints the JSON byte array
76+
using string type-casting:
77+
78+
.. io-code-block::
79+
:copyable: true
80+
81+
.. input::
82+
:language: go
83+
:emphasize-lines: 3
84+
85+
bsonDocument := bson.D{{"hello", "world"}}
86+
87+
jsonBytes, err := bson.MarshalExtJSON(bsonDocument, true, false)
88+
if err != nil {
89+
panic(err)
90+
}
91+
92+
fmt.Println(string(jsonBytes))
93+
94+
.. output::
95+
:language: none
96+
:visible: false
97+
98+
{"hello":"world"}
99+
100+
To learn more about conversions between BSON and Go types, see the
101+
:ref:`golang-bson` guide.
102+
103+
Why Did the Driver Throw an "Authentication failed" Error?
104+
----------------------------------------------------------
105+
106+
If you attempt to connect to a MongoDB deployment using incorrect
107+
username and password credentials or specifying the wrong authentication
108+
mechanism, you receive an "Authentication failed" error message. For
109+
example, the following error message is returned when you pass invalid
110+
credentials when authenticating with ``SCRAM-SHA-256``:
111+
112+
.. code-block:: none
113+
:copyable: false
114+
115+
connection() error occurred during connection handshake: auth error:
116+
sasl conversation error: unable to authenticate using mechanism
117+
"SCRAM-SHA-256": (AuthenticationFailed) Authentication failed.
118+
119+
This error message does not contain the detailed authentication failure
120+
reason for security reasons. Common causes for authentication failure include the
121+
following:
122+
123+
- Incorrect password
124+
- Incorrect username
125+
- Incorrect authentication mechanism specified in your connection string
126+
or ``Credential`` struct
127+
128+
To avoid this error, ensure that your credentials and authentication
129+
mechanism are correct. You can store your authentication credentials in
130+
environment variables or you can pass them to the ``SetAuth()`` method.
131+
132+
To learn more about authentication, see the
133+
:ref:`golang-authentication-mechanisms` guide.

‎source/index.txt

+1
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
/usage-examples
1414
/fundamentals
1515
API Documentation <{+api+}/mongo>
16+
/faq
1617
/issues-and-help
1718
/compatibility
1819
/whats-new

0 commit comments

Comments
 (0)