Skip to content

Commit bda1aa8

Browse files
committed
wiki Gotchas page migration and fix build error
1 parent 6582a63 commit bda1aa8

File tree

2 files changed

+235
-6
lines changed

2 files changed

+235
-6
lines changed

source/administration/production-notes.txt

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -252,3 +252,225 @@ bwm-ng
252252
command-line tool for monitoring network use. If you suspect a
253253
network-based bottleneck, you may use ``bwm-ng`` to begin your
254254
diagnostic process.
255+
256+
.. _gotchas:
257+
258+
Production Checklist
259+
--------------------
260+
261+
64-bit Builds for Production
262+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
263+
264+
Always use 64-bit Builds for Production. MongoDB uses memory mapped
265+
files. See the :ref:`32-bit limitations <faq-32-bit-limitations>` for
266+
more information.
267+
268+
32-bit builds exist to support use on development machines and also for
269+
other miscellaneous things such as replica set arbiters.
270+
271+
BSON Document Size Limit
272+
~~~~~~~~~~~~~~~~~~~~~~~~
273+
274+
There is a :limit:`BSON Document Size` -- at the time of this writing
275+
16MB per document. If you have large objects, use :doc:`GridFS
276+
</applications/gridfs/>` instead.
277+
278+
Set Appropriate Write Concern for Write Operations
279+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
280+
281+
See :ref:`write concern <write-concern>` for more information.
282+
283+
.. MongoDB requires an explicit request for acknowledgement of the
284+
results of a write. This is the getLastError command. If you don't call
285+
it at all, that is likely bad -- unless you are doing so with intent.
286+
The intent is to provide a way to do batch operations without
287+
continuous client/server turnarounds on every write of a batch of say,
288+
a million. The drivers support automatically calling this if you
289+
indicate a "write concern" for your connection to the database.
290+
291+
.. For example, if you try to insert a document above the BSON size limit
292+
indicated in the above section, [getLastError|DOCS:getLastError
293+
Command]/[writeconcern|http://docs.mongodb.org/manual/applications/repli
294+
cation/#replica-set-write-concern] would return an error -- *if* you
295+
ask for those.
296+
297+
.. While this can be very useful when used appropriately, it is
298+
acknowledged this can be confusing at first as this is an untraditional
299+
pattern.
300+
301+
.. See also the getLastError/WriteConcern parameters -- particularly 'j'
302+
and 'w' parameters.
303+
304+
Dynamic Schema
305+
~~~~~~~~~~~~~~
306+
307+
Data in MongoDB has a *flexible schema*. :term:`Collections
308+
<collection>` do not enforce :term:`document` structure. This makes
309+
iterative development and polymorphism much easier. However, it is not
310+
unusual for collections to have highly homogenous document structures
311+
within them. See :doc:`/core/data-modeling` for more information.
312+
313+
Some operational considerations include:
314+
315+
- the exact set of collections to be used
316+
317+
- the indexes to be used, which are created explicitly except for the
318+
``_id`` index
319+
320+
- shard key declarations, which are explicit and quite important as it
321+
is hard to change shard keys later
322+
323+
One very simple rule-of-thumb is to not verbatim import data from a
324+
relational database unmodified: you will generally want to "roll up"
325+
certain data into richer documents that use some embedding of nested
326+
documents and arrays (and/or arrays of subdocuments).
327+
328+
Updates by Default Affect Only **one** Document
329+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
330+
331+
Set the ``multi`` parameter to ``true`` to :method:`update
332+
<db.collection.update>` multiple documents that meet the query
333+
criteria. The :program:`mongo` shell syntax is:
334+
335+
.. code-block:: javascript
336+
337+
db.my_collection_name.update(my_query, my_update_expression, bool_upsert, bool_multi)
338+
339+
Set ``bool_multi`` to ``true`` when updating many documents. Otherwise
340+
only the first matched will update!
341+
342+
Case Sensitive Strings
343+
~~~~~~~~~~~~~~~~~~~~~~
344+
345+
MongoDB strings are case sensitive. So a search for ``"joe"`` will not
346+
find ``"Joe"``.
347+
348+
Consider:
349+
350+
- storing data in a normalized case format, or
351+
352+
- using regular expressions ending with ``/i``
353+
354+
- and/or using :doc:`$toLower </reference/aggregation/toLower/>` or
355+
:doc:`$toUpper </reference/aggregation/toUpper/>` in the
356+
:doc:`aggregation framework </applications/aggregation/>`
357+
358+
Type Sensitive Fields
359+
~~~~~~~~~~~~~~~~~~~~~
360+
361+
MongoDB data -- which is JSON-style, specifically, :meta-driver:`BSON
362+
</legacy/bson/>` format -- have several data types.
363+
364+
Consider the following document which has a field ``x`` with the
365+
*string* value ``"123"``:
366+
367+
.. code-block:: javascript
368+
369+
{ x : "123" }
370+
371+
Then the following query which looks for a *number* value ``123`` will
372+
**not** return that document:
373+
374+
.. code-block:: javascript
375+
376+
db.mycollection.find( { x : 123 } )
377+
378+
Locking
379+
~~~~~~~
380+
381+
Older versions of MongoDB used a "global lock"; use MongoDB v2.2+ for
382+
better results. See the :doc:`Concurrency </faq/concurrency/>` page for
383+
more information.
384+
385+
Packages
386+
~~~~~~~~
387+
388+
Be sure you have the latest stable release if you are using a package
389+
manager. You can see what is current on the Downloads page, even if you
390+
then choose to install via a package manager.
391+
392+
Use Odd Number of Replica Set Members
393+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
394+
395+
:doc:`Replica sets </replication/>` perform consensus elections. Use
396+
either an odd number of members (e.g., three) or else use an arbiter to
397+
get up to an odd number of votes.
398+
399+
Don't disable journaling
400+
~~~~~~~~~~~~~~~~~~~~~~~~
401+
402+
See :doc:`Journaling </administration/journaling/>` for more information.
403+
404+
Keep Replica Set Members Up-to-Date
405+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
406+
407+
This is important as MongoDB replica sets support automatic failover.
408+
Thus you want your secondaries to be up-to-date. You have a few options
409+
here:
410+
411+
1. Monitoring and alerts for any lagging can be done via various means.
412+
MMS shows a graph of replica set lag
413+
414+
#. Using :ref:`getLastError <replica-set-write-concern>` with
415+
``w:'majority'``, you will get a timeout or no return if a majority of
416+
the set is lagging. This is thus another way to guard against lag and
417+
get some reporting back of its occurrence.
418+
419+
#. Or, if you want to fail over manually, you can set your secondaries
420+
to ``priority:0`` in their configuration. Then manual action would be
421+
required for a failover. This is practical for a small cluster; for a
422+
large cluster you will want automation.
423+
424+
Additionally, see information on :ref:`replica set rollbacks
425+
<replica-set-rollback>`.
426+
427+
Additional Deployment Checklist
428+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
429+
430+
- Pick your shard keys carefully! They cannot be changed except
431+
manually by making a new collection.
432+
433+
- You cannot shard an existing collection over 256G. This will
434+
eventually be removed but is a limit in the system today. You could
435+
as a workaround create a new sharded collection and copy over the
436+
data via some script -- albeit that will likely take a while at this
437+
size.
438+
439+
- Unique indexes are not enforced across shards except for the shard
440+
key itself.
441+
442+
- Consider :doc:`pre-splitting </administration/sharded-clusters>` a
443+
sharded collection before a massive bulk import. Usually this isn't
444+
necessary but on a bulk import of size it is helpful.
445+
446+
- Use :doc:`security/auth </administration/security/>` mode if you
447+
need it. It is not on by default; rather a trusted environment is
448+
assumed.
449+
450+
- You do not have :doc:`fully generalized transactions
451+
</tutorial/isolate-sequence-of-operations/>`. Create rich documents
452+
and read the preceding link and consider the use case -- often there
453+
is a good fit.
454+
455+
- Disable NUMA - we find that works better. This will be printed as an
456+
informational warning at :program:`mongod` startup on a NUMA box
457+
usually.
458+
459+
- Avoid excessive prefetch/readahead on the filesystem. Check your
460+
prefetch settings. Note on linux the parameter is in *sectors*, not
461+
bytes. 32KBytes (a setting of 64 sectors) is pretty reasonable.
462+
463+
- Check :doc:`ulimits </administration/ulimit/>` settings.
464+
465+
- Use SSD if available and economical. Spinning disks can work well but
466+
SSDs and MongoDB are a nice combo. See :ref:`production-nfs` for more
467+
info.
468+
469+
- Maintain a reasonable pool sizes on clients. If you have 100 client
470+
machines and each has a pool size of 1000 connections, that would be
471+
a worst case of 100,000 connections to MongoDB -- which would be too
472+
much if to a single :program:`mongod` or :program:`mongos` (if to a
473+
cluster with many :program:`mongos`, might be ok). Try to maintain a
474+
reasonable number: 1K is fine; 100K is too much; 10K is ok.
475+
476+
.. `rsmith`: http://rsmith.co/2012/11/05/mongodb-gotchas-and-how-to-avoid-them

source/tutorial/model-tree-structures-with-materialized-paths.txt

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -55,17 +55,24 @@ delimiter:
5555

5656
db.categories.find( { path: /,Programming,/ } )
5757

58-
- You can also look for descendants of ``Books`` where Books must be at the topmost level
59-
of the hierarchy as follows:
58+
- You can also retrieve the descendants of ``Books`` where the
59+
``Books`` is also at the topmost level of the hierarchy:
6060

6161
.. code-block:: javascript
6262

6363
db.categories.find( { path: /^,Books,/ } )
6464

65-
- Creating an index on field ``path`` would be somewhat useful. For the ^,Books, example
66-
it helps a lot. For the other case, where the node to be found might be in the middle of the indexed
67-
string, the entire index would be inspected; this might be somewhat helpful as the index might be
68-
significantly smaller than the entire collection.
65+
- An index on the field ``path`` may improve performance, depending on
66+
the query:
67+
68+
- For the ``/^,Books,/`` example, the index on the ``path`` improves
69+
the query performance significantly.
70+
71+
- For the ``/,Programming,/`` example, or similar queries where the
72+
node might be in the middle of the indexed string, the query
73+
inspects the entire index. In this case, the index *may* provide
74+
some performance improvement *if* the index is significantly
75+
smaller than the entire collection.
6976

7077
.. code-block:: javascript
7178

0 commit comments

Comments
 (0)