From 2e8f15dbfbb2dc421c2732105086fd50a05b70ca Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Fri, 13 Jul 2012 10:22:34 -0400 Subject: [PATCH 1/9] initial outline --- draft/tutorial/copy-database.txt | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 draft/tutorial/copy-database.txt diff --git a/draft/tutorial/copy-database.txt b/draft/tutorial/copy-database.txt new file mode 100644 index 00000000000..a4b48cab40a --- /dev/null +++ b/draft/tutorial/copy-database.txt @@ -0,0 +1,30 @@ + +=============== + Copy Database +=============== + +Sypnosis +-------- + +This document oulines the procedure to copy MongoDB databases from one +server to another. + +There are special commands to copy a MongoDB database from one server to +another. This is faster than using :program:`mongodump` and +:program:`mongorestore` programs as there is no intermediate files to +be created. + +Concerns +-------- + +- does not lock + + +Process +------- + +copydb + +cloneDatabase + + From c2638f3720f3bd4ff3d4542e5cacd4e6cafba27d Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Mon, 16 Jul 2012 20:21:00 -0400 Subject: [PATCH 2/9] draft of tutorial-copyDatabase --- draft/tutorial/copy-database.txt | 118 +++++++++++++++++++++++++++---- 1 file changed, 103 insertions(+), 15 deletions(-) diff --git a/draft/tutorial/copy-database.txt b/draft/tutorial/copy-database.txt index a4b48cab40a..9ab395d62f3 100644 --- a/draft/tutorial/copy-database.txt +++ b/draft/tutorial/copy-database.txt @@ -1,30 +1,118 @@ +============= +Copy Database +============= -=============== - Copy Database -=============== +Copy Rename Move Databases + +Database transfer without intermediate file + +.. default-domain:: mongodb Sypnosis -------- This document oulines the procedure to copy MongoDB databases from one -server to another. +server to another using the :program:`copydb` command. The copy +database function in MongoDB can help you in several situations such +as: renaming a database, migrating databases between servers, and seeding +development from an existing data set for test environments. -There are special commands to copy a MongoDB database from one server to -another. This is faster than using :program:`mongodump` and -:program:`mongorestore` programs as there is no intermediate files to -be created. +While :program:`mongodump` and :program:`mongorestore` tools are +available, the copy database commands are faster as there is no +intermediate files to be created. -Concerns --------- +.. warning:: + + These copy procedures do not lock the database so writes may still + occur during the copy process at the source. This will produce a + destination database which is inconsistent with the source + database. + +.. TODO find alternatives to this? +.. mongodump / mongorestore +.. disconnect the DB from the network? +.. perform lock by hand? +.. Other references? -> mongodump / mongorestore tutorials +.. mongolock function + +Limitations +----------- + +- These commands must be run on the destination server. + +- These commands do not work with the total data set of a :term:`shard + cluster`. + +- These commands may be run on a :term:`secondary` member. + +- There must be enough disk storage on the destination server for the database. + + +Copy a Database from a Server +----------------------------- + +To copy database named ``databaseA`` on server ``db1.example.net`` to +another server ``db2.example.net`` naming it to ``databaseB``. + +- verify name of database, ``databaseA``, you want to copy on source + server, ``db1.example.net`` + +- log onto the destination server, ``db2.example.net`` + +- Run the following command from :program:`mongo shell` on the + destination server, ``db2.example.net`` + +.. code-block:: javascript + + db.copyDatabase( "databaseA", "databaseB", "db1.example.net") + +Copy a Database within a Server +------------------------------- + +If you would like rename a database from ``databaseA`` to + ``databaseB`` within the same server, ``db2.example.net``: + +- log onto the destination server, ``db2.example.net`` + +- Run the following command from :program:`mongo shell` on the + destination server, ``db2.example.net`` + +.. code-block:: javascript + + db.copyDatabase( "databaseA", "databaseB") + +Copy a Database with Authentication +----------------------------------- + +If authentication is required to logon to the source server using +``username`` and ``password`` authentication on ``db1.example.net``, +use the following procedure to copy ``databaseA`` to ``databaseB``: + +- log onto the destination server, ``db2.example.net`` + +- Run the following command from :program:`mongo shell` on the + destination server, ``db2.example.net`` + +.. code-block:: javascript -- does not lock + db.copyDatabase( "databaseA", "databaseB", "db1.example.net", + ``username``, ``password``) + +Copy a Database Without Name Change +----------------------------------- +:program:`cloneDatabase` is similar to :program:`copyDatabase` but has +a simplified syntax to copy a database from another server while +preserving the database name. -Process -------- +To copy a database from ``db1.example.net`` to ``db2.example.net``, +on ``db2.example.net`` run command: -copydb +- log onto the destination server, ``db2.example.net`` -cloneDatabase +- Run the following command from :program:`mongo shell` on the + destination server, ``db2.example.net`` +.. code-block:: javascript + db.cloneDatabase( "``db1.example.net``" ) From 515cdb9b7851f5ca3155caaf0c9e36023df8febb Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Wed, 18 Jul 2012 18:02:59 -0400 Subject: [PATCH 3/9] updated draft... still have a few TODOs --- draft/tutorial/copy-database.txt | 74 ++++++++++++++++++-------------- 1 file changed, 41 insertions(+), 33 deletions(-) diff --git a/draft/tutorial/copy-database.txt b/draft/tutorial/copy-database.txt index 9ab395d62f3..a8b6979f79b 100644 --- a/draft/tutorial/copy-database.txt +++ b/draft/tutorial/copy-database.txt @@ -14,8 +14,10 @@ Sypnosis This document oulines the procedure to copy MongoDB databases from one server to another using the :program:`copydb` command. The copy database function in MongoDB can help you in several situations such -as: renaming a database, migrating databases between servers, and seeding -development from an existing data set for test environments. +as: renaming a database, migrating databases between servers, and +seeding development from an existing data set for test +environments. The :program:`copydb` commands may be run on a +:term:`secondary` member. While :program:`mongodump` and :program:`mongorestore` tools are available, the copy database commands are faster as there is no @@ -35,6 +37,12 @@ intermediate files to be created. .. Other references? -> mongodump / mongorestore tutorials .. mongolock function +.. TODO link to collections/databases terminology page - so people +.. don't get confused with 'mongo database' vs. traditional database terms. + +.. TODO literals, should they stay literals throughout the doc? even +.. in the code examples too? + Limitations ----------- @@ -43,10 +51,8 @@ Limitations - These commands do not work with the total data set of a :term:`shard cluster`. -- These commands may be run on a :term:`secondary` member. - -- There must be enough disk storage on the destination server for the database. - +- There must be enough free disk storage on the destination server for the + database from the source server. Copy a Database from a Server ----------------------------- @@ -54,65 +60,67 @@ Copy a Database from a Server To copy database named ``databaseA`` on server ``db1.example.net`` to another server ``db2.example.net`` naming it to ``databaseB``. -- verify name of database, ``databaseA``, you want to copy on source - server, ``db1.example.net`` +- Verify name of database, ``databaseA``, you want to copy on the source + server, ``db1.example.net``. -- log onto the destination server, ``db2.example.net`` +- Log onto the destination server, ``db2.example.net``. - Run the following command from :program:`mongo shell` on the - destination server, ``db2.example.net`` + destination server, ``db2.example.net``. -.. code-block:: javascript + .. code-block:: javascript - db.copyDatabase( "databaseA", "databaseB", "db1.example.net") + db.copyDatabase( "databaseA", "databaseB", "db1.example.net") Copy a Database within a Server ------------------------------- -If you would like rename a database from ``databaseA`` to - ``databaseB`` within the same server, ``db2.example.net``: +To rename a database from ``databaseA`` to ``databaseB`` within the +same server, ``db2.example.net``. -- log onto the destination server, ``db2.example.net`` +- Log onto the destination server, ``db2.example.net``. - Run the following command from :program:`mongo shell` on the - destination server, ``db2.example.net`` + destination server, ``db2.example.net``. -.. code-block:: javascript + .. code-block:: javascript - db.copyDatabase( "databaseA", "databaseB") + db.copyDatabase( "databaseA", "databaseB") Copy a Database with Authentication ----------------------------------- -If authentication is required to logon to the source server using -``username`` and ``password`` authentication on ``db1.example.net``, -use the following procedure to copy ``databaseA`` to ``databaseB``: +To copy ``databaseA`` to ``databaseB`` using ``username`` and +``password`` authentication from the source server, ``db1.example.net`` +to ``db2.example.net`` use the following procedure. + +.. TODO reword this so it's not so LONG and contrived. -- log onto the destination server, ``db2.example.net`` +- Log onto the destination server, ``db2.example.net``. - Run the following command from :program:`mongo shell` on the - destination server, ``db2.example.net`` + destination server, ``db2.example.net``. -.. code-block:: javascript + .. code-block:: javascript - db.copyDatabase( "databaseA", "databaseB", "db1.example.net", - ``username``, ``password``) + db.copyDatabase( "databaseA", "databaseB", "db1.example.net", + ``username``, ``password``) -Copy a Database Without Name Change ------------------------------------ +Copy a Database Using CloneDatabase Command +------------------------------------------- :program:`cloneDatabase` is similar to :program:`copyDatabase` but has a simplified syntax to copy a database from another server while preserving the database name. To copy a database from ``db1.example.net`` to ``db2.example.net``, -on ``db2.example.net`` run command: +on ``db2.example.net`` follow these procedures. -- log onto the destination server, ``db2.example.net`` +- Log onto the destination server, ``db2.example.net``. - Run the following command from :program:`mongo shell` on the - destination server, ``db2.example.net`` + destination server, ``db2.example.net``. -.. code-block:: javascript + .. code-block:: javascript - db.cloneDatabase( "``db1.example.net``" ) + db.cloneDatabase( "``db1.example.net``" ) From c67ffd4e334a603268388a194e2250db1d6928f8 Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Fri, 20 Jul 2012 11:21:34 -0400 Subject: [PATCH 4/9] updating copyDB tutorial - tightened everything --- draft/tutorial/copy-database.txt | 136 +++++++++++++++---------------- 1 file changed, 68 insertions(+), 68 deletions(-) diff --git a/draft/tutorial/copy-database.txt b/draft/tutorial/copy-database.txt index a8b6979f79b..558d64bb319 100644 --- a/draft/tutorial/copy-database.txt +++ b/draft/tutorial/copy-database.txt @@ -1,50 +1,42 @@ -============= -Copy Database -============= - -Copy Rename Move Databases - -Database transfer without intermediate file +================================================= +Copy or Clone Database without Intermediate Files +================================================= .. default-domain:: mongodb Sypnosis -------- -This document oulines the procedure to copy MongoDB databases from one -server to another using the :program:`copydb` command. The copy -database function in MongoDB can help you in several situations such -as: renaming a database, migrating databases between servers, and -seeding development from an existing data set for test -environments. The :program:`copydb` commands may be run on a -:term:`secondary` member. +One may need to copy a :term:`database` from one server to another, +rename a :term:`database`, or move a :term:`database` within the same +server, seed a development server from a production server, or create +a test environment with production data. The :program:`copyDatabase` +and :program:`cloneDatabase` function in MongoDB can help one in these +situations. + +This document oulines the procedure to copy MongoDB :term:`databases` +using the :program:`copyDatabase` and :program:`cloneDatabase` +command. While :program:`mongodump` and :program:`mongorestore` tools are -available, the copy database commands are faster as there is no +available, the copy database commands are faster as there are no intermediate files to be created. .. warning:: - These copy procedures do not lock the database so writes may still - occur during the copy process at the source. This will produce a - destination database which is inconsistent with the source + Copy procedures with :program:`copyDatabase` and + :program:`cloneDatabase` do not lock the database, so writes may + still occur during the copy process at the source. This will + produce a destination database that is inconsistent with the source database. -.. TODO find alternatives to this? -.. mongodump / mongorestore -.. disconnect the DB from the network? -.. perform lock by hand? -.. Other references? -> mongodump / mongorestore tutorials -.. mongolock function - -.. TODO link to collections/databases terminology page - so people -.. don't get confused with 'mongo database' vs. traditional database terms. + If your needs are for consistent database copies, consider using + :program:`mongodump` and :program:`mongorestore` instead. More + details on these programs can be found in :ref:`database dump + ` and :ref:`database restore Date: Fri, 20 Jul 2012 17:21:28 -0400 Subject: [PATCH 5/9] adding more use cases to procedures --- draft/tutorial/copy-database.txt | 123 +++++++++++++++++-------------- 1 file changed, 66 insertions(+), 57 deletions(-) diff --git a/draft/tutorial/copy-database.txt b/draft/tutorial/copy-database.txt index 558d64bb319..4f4f6d26be7 100644 --- a/draft/tutorial/copy-database.txt +++ b/draft/tutorial/copy-database.txt @@ -1,6 +1,6 @@ -================================================= -Copy or Clone Database without Intermediate Files -================================================= +============================= +How to Copy or Clone Database +============================= .. default-domain:: mongodb @@ -8,71 +8,73 @@ Sypnosis -------- One may need to copy a :term:`database` from one server to another, -rename a :term:`database`, or move a :term:`database` within the same -server, seed a development server from a production server, or create -a test environment with production data. The :program:`copyDatabase` -and :program:`cloneDatabase` function in MongoDB can help one in these +rename a database, or move a database within the same server, seed a +development server from a production server, or create a test +environment with production data. The :dbcommand:`copydb` and +:dbcommand:`clone` function in MongoDB can help one in these situations. -This document oulines the procedure to copy MongoDB :term:`databases` -using the :program:`copyDatabase` and :program:`cloneDatabase` -command. +This document oulines the procedure to copy MongoDB databases using +the :dbcommand:`copydb` and :dbcommand:`clone` command. While :program:`mongodump` and :program:`mongorestore` tools are available, the copy database commands are faster as there are no intermediate files to be created. -.. warning:: - - Copy procedures with :program:`copyDatabase` and - :program:`cloneDatabase` do not lock the database, so writes may - still occur during the copy process at the source. This will - produce a destination database that is inconsistent with the source - database. - - If your needs are for consistent database copies, consider using - :program:`mongodump` and :program:`mongorestore` instead. More - details on these programs can be found in :ref:`database dump - ` and :ref:`database restore Date: Tue, 24 Jul 2012 13:48:37 -0400 Subject: [PATCH 6/9] updates to copyDB draft --- draft/tutorial/copy-database.txt | 40 +++++++++++++++++++------------- 1 file changed, 24 insertions(+), 16 deletions(-) diff --git a/draft/tutorial/copy-database.txt b/draft/tutorial/copy-database.txt index 4f4f6d26be7..129954e76b5 100644 --- a/draft/tutorial/copy-database.txt +++ b/draft/tutorial/copy-database.txt @@ -8,7 +8,7 @@ Sypnosis -------- One may need to copy a :term:`database` from one server to another, -rename a database, or move a database within the same server, seed a +rename a database, move a database within the same server, seed a development server from a production server, or create a test environment with production data. The :dbcommand:`copydb` and :dbcommand:`clone` function in MongoDB can help one in these @@ -17,9 +17,9 @@ situations. This document oulines the procedure to copy MongoDB databases using the :dbcommand:`copydb` and :dbcommand:`clone` command. -While :program:`mongodump` and :program:`mongorestore` tools are -available, the copy database commands are faster as there are no -intermediate files to be created. +The :dbcommand:`copydb` and :dbcommand:`clone` are faster than +:program:`mongodump` and :program:`mongorestore` because there are no +intermediate files to be created when using the former. .. note:: @@ -49,9 +49,13 @@ Process Copy a Database to Another Server ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Use the :dbcommand:`copydb` when you need to transfer a database from -one server, such as a development server, to another, such as a -production server. +Use the :dbcommand:`copydb` command when you need to transfer a database from +one server to another, such as from a development server a production +server, changing the database name in the process. + +This is useful when you want to move a database from the development +environment to the production environment, or create a remote-branch of the database +to archive the current database on a different server. To copy the database named ``test`` on server ``db0.example.net`` to another server ``db1.example.net`` renaming it ``records``. @@ -71,17 +75,17 @@ another server ``db1.example.net`` renaming it ``records``. Rename a Database ~~~~~~~~~~~~~~~~~ -Use the :dbcommand:`copydb` to rename a database within the same +Use the :dbcommand:`copydb` command to rename a database within the same server. This is useful when the contents of the database has changed from the initial naming of the database and a new name would be more -fitting for the +appropriate. To rename a database from ``test`` to ``records`` within the same server, ``db1.example.net``. - Log onto the destination server, ``db1.example.net``. -- Run the following command from :program:`mongo shell` on the +- Run the following command from :program:`mongo` shell on the destination server, ``db1.example.net``: .. code-block:: javascript @@ -94,7 +98,8 @@ Copy a Database with Authentication If the source server requires ``username`` and ``password`` authentication, you can include these parameters in the :dbcommand:`copydb` command. This is useful where you need to create -offsite backups. +offsite backups, a local development system which has data from the +production system, or create a system to produce reports. To copy ``test`` to ``records`` from the source server ``db0.example.net``, which requires ``username`` and ``password`` @@ -114,13 +119,16 @@ authentication, to ``db1.example.net`` use the following procedure. Clone a Database ~~~~~~~~~~~~~~~~ -.. ?? use to create a secondary server very quickly? - - -:dbcommand:`clone` copies a database between :program:`mongod` +The :dbcommand:`clone` command copies a database between :program:`mongod` instances; however, :dbcommand:`clone` preserves the database name. For many operations :dbcommand:`clone` has a more -straightforward syntax than :dbcommand:`copydb`. +straightforward syntax than :dbcommand:`copydb` but are functionally +the same. + +You can use :dbcommand:`clone` to quickly create a :term:`secondary` +member from the :term:`primary` dataset, to seed a development system +with production data, or to create a system to run reports on instead +of the main production system. To clone a database from ``db0.example.net`` to ``db1.example.net``, on ``db1.example.net`` follow these procedures. From 8450a6900afae16fb74f1fe1087731c148a753ee Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Tue, 24 Jul 2012 17:01:27 -0400 Subject: [PATCH 7/9] adding *the* to mongo shell in examples --- draft/tutorial/copy-database.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/draft/tutorial/copy-database.txt b/draft/tutorial/copy-database.txt index 129954e76b5..fbf0f5a8689 100644 --- a/draft/tutorial/copy-database.txt +++ b/draft/tutorial/copy-database.txt @@ -19,7 +19,7 @@ the :dbcommand:`copydb` and :dbcommand:`clone` command. The :dbcommand:`copydb` and :dbcommand:`clone` are faster than :program:`mongodump` and :program:`mongorestore` because there are no -intermediate files to be created when using the former. +intermediate files to be created in the :dbcommand:`copydb` process. .. note:: @@ -65,7 +65,7 @@ another server ``db1.example.net`` renaming it ``records``. - Log onto the destination server, ``db1.example.net``. -- Run the following operation from :program:`mongo` shell on the +- Run the following operation from the :program:`mongo` shell on the destination server, ``db1.example.net``: .. code-block:: javascript @@ -85,7 +85,7 @@ same server, ``db1.example.net``. - Log onto the destination server, ``db1.example.net``. -- Run the following command from :program:`mongo` shell on the +- Run the following command from the :program:`mongo` shell on the destination server, ``db1.example.net``: .. code-block:: javascript @@ -107,7 +107,7 @@ authentication, to ``db1.example.net`` use the following procedure. - Log onto the destination server, ``db1.example.net``. -- Run the following command from :program:`mongo` shell on the +- Run the following command from the :program:`mongo` shell on the destination server, ``db1.example.net``. .. code-block:: javascript @@ -135,7 +135,7 @@ To clone a database from ``db0.example.net`` to ``db1.example.net``, on - Log onto the destination server, ``db1.example.net``. -- Run the following command from :program:`mongo` shell on the +- Run the following command from the :program:`mongo` shell on the destination server, ``db1.example.net``: .. code-block:: javascript From 6f2ee44fde5e3c71565a365ee202d016e9128ef7 Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Wed, 25 Jul 2012 13:00:18 -0400 Subject: [PATCH 8/9] updating copyDB tutorial --- draft/tutorial/copy-database.txt | 84 ++++++++++++++++---------------- 1 file changed, 41 insertions(+), 43 deletions(-) diff --git a/draft/tutorial/copy-database.txt b/draft/tutorial/copy-database.txt index fbf0f5a8689..3dee7ca08ca 100644 --- a/draft/tutorial/copy-database.txt +++ b/draft/tutorial/copy-database.txt @@ -1,47 +1,52 @@ -============================= -How to Copy or Clone Database -============================= +=========================================== +Copy Databases Between ``mongod`` Instances +=========================================== .. default-domain:: mongodb Sypnosis -------- -One may need to copy a :term:`database` from one server to another, -rename a database, move a database within the same server, seed a -development server from a production server, or create a test -environment with production data. The :dbcommand:`copydb` and -:dbcommand:`clone` function in MongoDB can help one in these -situations. +In some situations, you may need to copy a :term:`database` from one +MongoDB instance to another. For example, you may use these commands +to support migrations and data warehousing, seeding test environments, +or to help perform backups. The :dbcommand:`copydb` and +:dbcommand:`clone` function in MongoDB can help in these situations. This document oulines the procedure to copy MongoDB databases using the :dbcommand:`copydb` and :dbcommand:`clone` command. The :dbcommand:`copydb` and :dbcommand:`clone` are faster than -:program:`mongodump` and :program:`mongorestore` because there are no -intermediate files to be created in the :dbcommand:`copydb` process. +:program:`mongodump` and :program:`mongorestore` because the commands +do not require intermediate files. .. note:: :dbcommand:`copydb` and :dbcommand:`clone` do not produce point-in-time snapshots of the source database. Write traffic to - the source database during the copy process may result in databases - with different contents. + the source or destination database during the copy process may + result in databases with different contents. Considerations -------------- -- :dbcommand:`copydb` or :dbcommand:`clone` must be run on the +- You must run :dbcommand:`copydb` or :dbcommand:`clone` on the destination server. -- :dbcommand:`copydb` or :dbcommand:`clone` do not work with a sharded - database, such as a database a from :term:`shard cluster`. +- You can use :dbcommand:`copydb` or :dbcommand:`clone` with unsharded + databases in a :term:`shard cluster` when you're connected directly + to the :program:`mongod` instance. -- :dbcommand:`copydb` or :dbcommand:`clone` commands may be run - on a :term:`secondary` member. +- You can run :dbcommand:`copydb` or :dbcommand:`clone` commands on a + :term:`secondary` member. - There must be enough free disk storage on the destination server for the - database from the source server. + database from the source server. You can check for the size of the + database on the source server by issuing command: + + .. code-block:: + + db.runCommand() Process ------- @@ -49,16 +54,16 @@ Process Copy a Database to Another Server ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Use the :dbcommand:`copydb` command when you need to transfer a database from -one server to another, such as from a development server a production -server, changing the database name in the process. +Use the :dbcommand:`copydb` command to transfer a database from +one MongoDB instance to another, such as from a development instance +to a production instance. This is useful when you want to move a database from the development environment to the production environment, or create a remote-branch of the database to archive the current database on a different server. To copy the database named ``test`` on server ``db0.example.net`` to -another server ``db1.example.net`` renaming it ``records``. +another server ``db1.example.net`` renaming it ``records`` in the process. - Verify name of database, ``test``, you want to copy on the source server, ``db0.example.net``. @@ -75,10 +80,10 @@ another server ``db1.example.net`` renaming it ``records``. Rename a Database ~~~~~~~~~~~~~~~~~ -Use the :dbcommand:`copydb` command to rename a database within the same -server. This is useful when the contents of the database has changed -from the initial naming of the database and a new name would be more -appropriate. +Use the :dbcommand:`copydb` command to copy a database within the same +server also renaming the database. This is useful when the contents of +the database has changed from the initial naming of the database and a +new name would be more appropriate. To rename a database from ``test`` to ``records`` within the same server, ``db1.example.net``. @@ -95,11 +100,11 @@ same server, ``db1.example.net``. Copy a Database with Authentication ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If the source server requires ``username`` and ``password`` -authentication, you can include these parameters in the -:dbcommand:`copydb` command. This is useful where you need to create -offsite backups, a local development system which has data from the -production system, or create a system to produce reports. +If the source server requires ``username`` and ``password``, you can +include these parameters in the :dbcommand:`copydb` command. This is +useful where you need to create offsite backups, a local development +system which has data from the production system, or create a system +to produce reports. To copy ``test`` to ``records`` from the source server ``db0.example.net``, which requires ``username`` and ``password`` @@ -112,23 +117,16 @@ authentication, to ``db1.example.net`` use the following procedure. .. code-block:: javascript - db.copyDatabase( "test", "records", db0.example.net, username, password) - -.. TODO verify that username & password do not have to be in quotes...? + db.copyDatabase( "test", "records", db0.example.net, "username", "password") Clone a Database ~~~~~~~~~~~~~~~~ The :dbcommand:`clone` command copies a database between :program:`mongod` instances; however, :dbcommand:`clone` preserves the database -name. For many operations :dbcommand:`clone` has a more -straightforward syntax than :dbcommand:`copydb` but are functionally -the same. - -You can use :dbcommand:`clone` to quickly create a :term:`secondary` -member from the :term:`primary` dataset, to seed a development system -with production data, or to create a system to run reports on instead -of the main production system. +name on the destination server. For many operations, +:dbcommand:`clone` has identical functionality and a simpler syntax +than :dbcommand:`copydb`. To clone a database from ``db0.example.net`` to ``db1.example.net``, on ``db1.example.net`` follow these procedures. From 414738f408588f4a2565ad58de901d30a45faf41 Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Thu, 26 Jul 2012 11:54:15 -0400 Subject: [PATCH 9/9] adding in links for shell helpers --- draft/tutorial/copy-database.txt | 41 ++++++++++++++++++-------------- 1 file changed, 23 insertions(+), 18 deletions(-) diff --git a/draft/tutorial/copy-database.txt b/draft/tutorial/copy-database.txt index 3dee7ca08ca..e7288250bcf 100644 --- a/draft/tutorial/copy-database.txt +++ b/draft/tutorial/copy-database.txt @@ -40,13 +40,11 @@ Considerations - You can run :dbcommand:`copydb` or :dbcommand:`clone` commands on a :term:`secondary` member. -- There must be enough free disk storage on the destination server for the - database from the source server. You can check for the size of the - database on the source server by issuing command: - - .. code-block:: - - db.runCommand() +- There must be enough free disk storage on the destination server for + the database from the source server. Use the ``db.stats()`` function + to check the size of the database on the source :program:`mongod` + instance. For more information on ``db.stats()`` see the + :doc:`database statistics ` section. Process ------- @@ -54,13 +52,15 @@ Process Copy a Database to Another Server ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Use the :dbcommand:`copydb` command to transfer a database from -one MongoDB instance to another, such as from a development instance -to a production instance. +Use the :dbcommand:`copydb` command to transfer a database from one +MongoDB instance to another, such as from a development instance to a +production instance. The :func:`db.copyDatabase()` helper in the +:program:`mongo` shell provides a wrapper around the +:dbcommand:`copydb`. This is useful when you want to move a database from the development -environment to the production environment, or create a remote-branch of the database -to archive the current database on a different server. +environment to the production environment, or create a remote-branch +of the database to archive the current database on a different server. To copy the database named ``test`` on server ``db0.example.net`` to another server ``db1.example.net`` renaming it ``records`` in the process. @@ -83,7 +83,9 @@ Rename a Database Use the :dbcommand:`copydb` command to copy a database within the same server also renaming the database. This is useful when the contents of the database has changed from the initial naming of the database and a -new name would be more appropriate. +new name would be more appropriate. The :func:`db.copyDatabase()` +helper in the :program:`mongo` shell provides a wrapper around the +:dbcommand:`copydb`. To rename a database from ``test`` to ``records`` within the same server, ``db1.example.net``. @@ -104,7 +106,9 @@ If the source server requires ``username`` and ``password``, you can include these parameters in the :dbcommand:`copydb` command. This is useful where you need to create offsite backups, a local development system which has data from the production system, or create a system -to produce reports. +to produce reports. The :func:`db.copyDatabase()` helper in the +:program:`mongo` shell provides a wrapper around the +:dbcommand:`copydb`. To copy ``test`` to ``records`` from the source server ``db0.example.net``, which requires ``username`` and ``password`` @@ -122,11 +126,12 @@ authentication, to ``db1.example.net`` use the following procedure. Clone a Database ~~~~~~~~~~~~~~~~ -The :dbcommand:`clone` command copies a database between :program:`mongod` -instances; however, :dbcommand:`clone` preserves the database -name on the destination server. For many operations, +The :dbcommand:`clone` command copies a database between +:program:`mongod` instances; however, :dbcommand:`clone` preserves the +database name on the destination server. For many operations, :dbcommand:`clone` has identical functionality and a simpler syntax -than :dbcommand:`copydb`. +than :dbcommand:`copydb`. The :func:`db.cloneDatabase()` helper in the +:program:`mongo` shell provides a wrapper around :dbcommand:`clone`. To clone a database from ``db0.example.net`` to ``db1.example.net``, on ``db1.example.net`` follow these procedures.