diff --git a/draft/tutorial/copy-database.txt b/draft/tutorial/copy-database.txt new file mode 100644 index 00000000000..e7288250bcf --- /dev/null +++ b/draft/tutorial/copy-database.txt @@ -0,0 +1,146 @@ +=========================================== +Copy Databases Between ``mongod`` Instances +=========================================== + +.. default-domain:: mongodb + +Sypnosis +-------- + +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 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 or destination database during the copy process may + result in databases with different contents. + +Considerations +-------------- + +- You must run :dbcommand:`copydb` or :dbcommand:`clone` on the + destination server. + +- 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. + +- 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. 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 +------- + +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. 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. + +To copy the database named ``test`` on server ``db0.example.net`` to +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``. + +- Log onto the destination server, ``db1.example.net``. + +- Run the following operation from the :program:`mongo` shell on the + destination server, ``db1.example.net``: + + .. code-block:: javascript + + db.copyDatabase( "test", "records", db0.example.net ) + +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. 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``. + +- Log onto the destination server, ``db1.example.net``. + +- Run the following command from the :program:`mongo` shell on the + destination server, ``db1.example.net``: + + .. code-block:: javascript + + db.copyDatabase( "test", "records" ) + +Copy a Database with Authentication +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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. 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`` +authentication, to ``db1.example.net`` use the following procedure. + +- Log onto the destination server, ``db1.example.net``. + +- Run the following command from the :program:`mongo` shell on the + destination server, ``db1.example.net``. + + .. code-block:: javascript + + 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 on the destination server. For many operations, +:dbcommand:`clone` has identical functionality and a simpler syntax +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. + +- Log onto the destination server, ``db1.example.net``. + +- Run the following command from the :program:`mongo` shell on the + destination server, ``db1.example.net``: + + .. code-block:: javascript + + db.cloneDatabase( "db0.example.net" )