diff --git a/source/applications/drivers.txt b/source/applications/drivers.txt index 48ad8e6c82b..fd378aa2594 100644 --- a/source/applications/drivers.txt +++ b/source/applications/drivers.txt @@ -5,10 +5,15 @@ MongoDB Drivers and Client Libraries ==================================== -Applications communicate with MongoDB by way of a client library or -driver that handles all interaction with the database in a language -appropriate and sensible manner. See the following pages for more -information about the MongoDB :ecosystem:`drivers `: +An application communicates with MongoDB by way of a client library, +called a :ecosystem:`driver`, that handles all interaction with the +database in a language appropriate to the application. + +Drivers +------- + +See the following pages for more information about the MongoDB +:ecosystem:`drivers `: - JavaScript (:ecosystem:`Language Center `, :api:`docs `) - Python (:ecosystem:`Language Center `, :api:`docs `) @@ -22,3 +27,24 @@ information about the MongoDB :ecosystem:`drivers `: - C++ (:ecosystem:`Language Center `, :api:`docs `) - Haskell (`Language Center `_, :api:`docs `) - Erlang (:ecosystem:`Language Center `, :api:`docs `) + +.. _drivers-version-numbers: + +Driver Version Numbers +---------------------- + +Driver version numbers use the **major.minor.patch** semantic. In a +driver version number, the first number is the major version, the second +the minor version, and the third indicates a patch. + +.. example:: Driver version numbers. + + If your driver has a version number of ``2.9.1``, ``2`` is the major + version, ``9`` is minor, and ``1`` is the patch. + +The numbering scheme for drivers differs from the scheme for the MongoDB +server, which uses the first two numbers together to designate the major +version, with the second digit denoting the branch of the release: an odd +second digit (i.e. 3 in 2.3.0) is a development branch, and an even second digit +(i.e. the 4 in 2.4.0) is the stable, production-ready branch. For more information +on server versioning, see :ref:`release-version-numbers`. diff --git a/source/installation.txt b/source/installation.txt index d9570aeca49..521716e8b02 100644 --- a/source/installation.txt +++ b/source/installation.txt @@ -10,9 +10,10 @@ Install MongoDB Installation Guides ------------------- -MongoDB runs on most platforms, and supports 32-bit and 64-bit architectures. +MongoDB runs on most platforms and supports 32-bit and 64-bit architectures. `10gen `_, the MongoDB makers, provides both binaries -and packages. Choose your platform below: +and packages. In production environments, use 64-bit MongoDB binaries. +Choose your platform below: .. _tutorials-installation: .. _tutorial-installation: @@ -28,27 +29,23 @@ and packages. Choose your platform below: tutorial/install-mongodb-on-windows tutorial/install-mongodb-enterprise -After you have installed MongoDB, consider the following documents as -you begin to learn about MongoDB: +Upgrade MongoDB +--------------- .. toctree:: :hidden: - tutorial/getting-started + tutorial/upgrade-revision -- :doc:`/tutorial/getting-started` -- :doc:`/core/create` -- :doc:`/core/read` -- :doc:`/core/update` -- :doc:`/core/delete` +To upgrade to a new revision of a MongoDB major release, see the +following document: :doc:`/tutorial/upgrade-revision` Release Notes ------------- -You should always install the latest, stable version of MongoDB. -Stable versions have an even-numbered minor version number. For -example: v2.4 is stable, v2.2, and v2.0 were previously the stable, -while v2.1 and v2.3 are a development versions. +You should always install the latest, *stable* version of MongoDB. Stable +versions have an even number for the second number in the :ref:`version number +`. The following release notes are for stable versions: - Current Stable Release: @@ -59,3 +56,22 @@ while v2.1 and v2.3 are a development versions. - :doc:`/release-notes/2.2` - :doc:`/release-notes/2.0` - :doc:`/release-notes/1.8` + +First Steps with MongoDB +------------------------ + +After you have installed MongoDB, consider the following documents as +you begin to learn about MongoDB: + +.. toctree:: + :hidden: + + tutorial/getting-started + +- :doc:`/tutorial/getting-started` +- :doc:`/core/create` +- :doc:`/core/read` +- :doc:`/core/update` +- :doc:`/core/delete` +- :doc:`/data-modeling` +- :doc:`/applications/drivers` diff --git a/source/release-notes.txt b/source/release-notes.txt index 48685eded04..66e2f050759 100644 --- a/source/release-notes.txt +++ b/source/release-notes.txt @@ -57,40 +57,35 @@ Other MongoDB Release Notes .. _release-version-numbers: -Version Numbers -~~~~~~~~~~~~~~~ +MongoDB Version Numbers +~~~~~~~~~~~~~~~~~~~~~~~ -There are three numbers in a MongoDB version: +For MongoDB ``2.4.1``, ``2.4`` refers to the release series and ``.1`` refers +to the revision. The second component of the release series (e.g. ``4`` +in ``2.4.1``) describes the type of release series. Release series ending +with even numbers (e.g. ``4`` above) are *stable* and ready for +production, while odd numbers are for *development* and testing only. -``..`` +Generally, changes in the release series (e.g. ``2.4``) mark the +introduction of new features that may break backwards +compatibility. Changes to the revision number mark the release +bug fixes and backwards-compatible changes. -The second number, the release number, indicates release stability. An -odd release number indicates a release in a development series. Even -numbered releases indicate a stable, general availability, release. +Always upgrade to the latest stable revision of your release series. -Additionally, the three numbers indicate the following: +The version numbering system for MongoDB differs from the system +used for the MongoDB drivers. Drivers use only the first number to indicate +a major version. For details, see :ref:`drivers-version-numbers`. -- ````: This rarely changes. A change to this number - indicates very large changes to MongoDB. +.. example:: Version numbers -- ````: A release can include many changes, including - new features and updates. Some changes may break backwards - compatibility. See release notes for every version for compatibility - notes. Even-numbered release numbers are stable - branches. Odd-numbered release numbers are development branches. + - 2.0.0 : Stable release. -- ````: This digit increments for every - release. Changes each revision address bugs and security issues, + - 2.0.1 : Revision. -.. example:: Version numbers: + - 2.1.0 : Development release *for testing only*. Includes new features and changes for + testing. Interfaces and stability may not be compatible in + development releases. - - 1.0.0 : First stable release - - - 1.0.x : Bug fixes to 1.0.x. These releases carry low risk. Always - upgrade to the latest revision in your release series. - - - 1.1.x : Development release. Includes new features not fully finished - and other works-in-progress. Some things may be different than 1.0 - - - 1.2.x : Second stable release. This is a culmination of the 1.1.x + - 2.2.0 : Stable release. This is a culmination of the 2.1.x development series. diff --git a/source/tutorial/manage-sharded-cluster-balancer.txt b/source/tutorial/manage-sharded-cluster-balancer.txt index b37a70200f0..59668dd0f28 100644 --- a/source/tutorial/manage-sharded-cluster-balancer.txt +++ b/source/tutorial/manage-sharded-cluster-balancer.txt @@ -158,24 +158,26 @@ all migration, use the following procedure: sh.startBalancer() -.. note:: + .. note:: - If a migration is in progress, the system will complete - the in-progress migration. After disabling, you can use the - following operation in the :program:`mongo` shell to determine if - there are no migrations in progress: + If a migration is in progress, the system will complete the + in-progress migration before stopping. After disabling, you can use the following + operation in the :program:`mongo` shell to determine if there are + no migrations in progress: - .. code-block:: javascript + .. code-block:: javascript - use config - while( db.locks.findOne({_id: "balancer"}).state ) { - print("waiting..."); sleep(1000); - } + use config + while( sh.isBalancerRunning() ) { + print("waiting..."); + sleep(1000); + } -The above process and the :method:`sh.setBalancerState()`, -:method:`sh.startBalancer()`, and :method:`sh.stopBalancer()` helpers provide -wrappers on the following process, which may be useful if you need to -run this operation from a driver that does not have helper functions: + The above process and the :method:`sh.setBalancerState()`, + :method:`sh.startBalancer()`, and :method:`sh.stopBalancer()` helpers + provide wrappers on the following process, which may be useful if you + need to run this operation from a driver that does not have helper + functions: #. Connect to any :program:`mongos` in the cluster using the :program:`mongo` shell. @@ -214,7 +216,42 @@ operation: - :ref:`manually disable the balancer ` for the duration of the backup procedure. -Confirm that the balancer is not active using the -:method:`sh.getBalancerState()` method before starting a backup -operation. When the backup procedure is complete you can reactivate +If you turn the balancer off while it is in the middle of a balancing round, +the shut down is not instantaneous. The balancer completes the chunk +move in-progress and then ceases all further balancing rounds. + +Before starting a backup operation, confirm that the balancer is not +active. You can use the following command to determine if the balancer +is active: + +.. code-block:: javascript + + !sh.getBalancerState() && !sh.isBalancerRunning() + +When the backup procedure is complete you can reactivate the balancer process. + +.. _sharding-balancing-re-enable: + +Re-enable the Balancer after Temporarily Disabling It +----------------------------------------------------- + +Use this procedure if you have temporarily disabled the balancer and are +ready to re-enable it: + +#. Connect to any :program:`mongos` in the cluster using the + :program:`mongo` shell. + +#. Issue one of the following operations to enable the balancer: + + - From the :program:`mongo` shell, issue: + + .. code-block:: javascript + + sh.startBalancer() + + - From a driver that does not have the :method:`sh.startBalancer()` helper: + + .. code-block:: javascript + + db.settings.update( { _id: "balancer" }, { $set : { stopped: false } } , true ); diff --git a/source/tutorial/upgrade-revision.txt b/source/tutorial/upgrade-revision.txt new file mode 100644 index 00000000000..852f092f340 --- /dev/null +++ b/source/tutorial/upgrade-revision.txt @@ -0,0 +1,202 @@ +========================================= +Upgrade to the Latest Revision of MongoDB +========================================= + +.. default-domain:: mongodb + +Revisions provide security patches, bug fixes, and new or changed +features that do not contain any backward breaking changes. Always +upgrade to the latest revision in your release series. The third number +in the :ref:`MongoDB version number ` indicates +the revision. + +.. _upgrade-options: + +Before Upgrading +---------------- + +- Ensure you have an up-to-date backup of your data set. See + :doc:`/core/backups`. + +- Consult the following documents for any special considerations or + compatibility issues specific to your MongoDB release: + + - The release notes, located at :doc:`/release-notes`. + + - The documentation for your driver. See :doc:`/applications/drivers`. + +- If your installation includes :term:`replica sets `, plan + the upgrade during a predefined maintenance window. + + .. TODO check: Upgrading a replica set typically involves 10-20 seconds of downtime. + +- Before you upgrade a production environment, use the procedures in + this document to upgrade a *staging* environment that reproduces your + production environment, to ensure that your production configuration + is compatible with all changes. + +.. _upgrade-procedure: + +Upgrade Procedure +----------------- + +.. important:: Always backup all of your data before upgrading MongoDB. + +Upgrade each :program:`mongod` and :program:`mongos` instance +separately, using the procedure described here. When upgrading an instance, +use the procedure :ref:`upgrade-mongodb-instance`. + +Follow this upgrade procedure: + +1. For deployments that use authentication, first upgrade all of your + MongoDB :doc:`drivers `. To upgrade, see the + documentation for your driver, which is located at + :doc:`/applications/drivers`. + +#. Upgrade sharded clusters, as described in + :ref:`upgrade-sharded-cluster`. + +#. Upgrade any standalone instances. See :ref:`upgrade-mongodb-instance`. + +#. Upgrade any replica sets that are not part of a sharded cluster, as + described in :ref:`upgrade-replica-set`. + +.. _upgrade-mongodb-instance: + +Upgrade a MongoDB Instance +-------------------------- + +To upgrade a :program:`mongod` or :program:`mongos` instance, use one of +the following approaches. The preferred approach is the first: + +- Upgrade the instance using the operating system's package management + tool and the packages provided by 10gen. This is the preferred + approach. See :doc:`/installation`. + +- Upgrade the instance by replacing the existing binaries. See + :ref:`upgrade-replace-binaries`. + +.. _upgrade-replace-binaries: + +Replace the Existing Binaries +----------------------------- + +.. important:: Always backup all of your data before upgrading MongoDB. + +This section describes how to upgrade MongoDB by replacing the existing +binaries. The preferred approach to an upgrade is to use the operating +system's package management tool and the packages provided by 10gen, as +described in :doc:`/installation`. + +To upgrade a :program:`mongod` or :program:`mongos` instance by +replacing the existing binaries: + +1. Download the binaries for the latest MongoDB revision from the + `MongoDB Download Page`_ and store the binaries in a temporary + location. The binaries download as compressed files that uncompress + to the directory structure used by the MongoDB installation. + +#. Shutdown the instance. + +#. Replace the existing MongoDB binaries with the downloaded binaries. + +#. Restart the instance. + +.. _`MongoDB Download Page`: http://downloads.mongodb.org/ + +.. _upgrade-sharded-cluster: + +Upgrade Sharded Clusters +------------------------ + +To upgrade a sharded cluster: + +1. Disable the cluster's balancer, as described in + :ref:`sharding-balancing-disable-temporally`. + +#. Upgrade each :program:`mongos` instance by following the instructions + below in :ref:`upgrade-mongodb-instance`. You can upgrade the + :program:`mongos` instances in any order. + +#. Upgrade each :program:`mongod` :ref:`config server + ` individually starting with the last config + server listed in your :option:`mongos --configdb` string and working + backward. To keep the cluster online, make sure at least one config + server is always running. For each config server upgrade, follow the + instructions below in :ref:`upgrade-mongodb-instance` + + ..example:: Given the following config string: + + .. code-block:: cfg + + mongos --configdb cfg0.example.net:27019,cfg1.example.net:27019,cfg2.example.net:27019 + + You would upgrade the config servers in the following order: + + 1. cfg2.example.net + 2. cfg1.example.net + 3. cfg0.example.net + +#. Upgrade each shard. + + - If a shard is a replica set, upgrade the shard using the + procedure below titled :ref:`upgrade-replica-set`. + + - If a shard is a standalone instance, upgrade the shard using the + procedure below titled + :ref:`upgrade-mongodb-instance`. + +#. Re-enable the balancer, as described in :ref:`sharding-balancing-re-enable`. + +.. _upgrade-replica-set: + +Upgrade Replica Sets +-------------------- + +To upgrade a replica set, upgrade each member individually, starting with +the :term:`secondaries ` and finishing with the +:term:`primary`. Plan the upgrade during a predefined maintenance window. + +.. TODO check: Upgrading a replica set typically involves 10-20 seconds of downtime. + +Upgrade Secondaries +~~~~~~~~~~~~~~~~~~~ + +Upgrade each secondary separately as follows: + +1. Upgrade the secondary's :program:`mongod` instance by following the + instructions below in :ref:`upgrade-mongodb-instance`. + +#. After upgrading a secondary, wait for the secondary to recover to + the ``SECONDARY`` state before upgrading the next instance. To + check the member's state, issue :method:`rs.status()` in the + :program:`mongo` shell. + + The secondary may briefly go into ``STARTUP2`` or ``RECOVERING``. + This is normal. Make sure to wait for the secondary to fully recover + to ``SECONDARY`` before you continue the upgrade. + +Upgrade the Primary +~~~~~~~~~~~~~~~~~~~ + +1. Step down the primary to initiate the normal :ref:`failover + ` procedure. Either: + + - Issue :method:`rs.stepDown()` in the :program:`mongo` shell. + + - Use the :dbcommand:`replSetStepDown` database command. + + During failover, the set cannot accept writes. Typically this takes + 10-20 seconds. Plan the upgrade during a predefined maintenance + window. + + .. note:: Stepping down the primary is preferable to directly + *shutting down* the primary. Stepping down expedites the + failover procedure. + +#. Once the primary has stepped down, regularly issue + :method:`rs.status()` from the :program:`mongo` shell until you + see that another member has assumed the ``PRIMARY`` state. + +#. Shut down the original primary and upgrade its instance by + following the instructions below in :ref:`upgrade-mongodb-instance`.