Tutorial copy db

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 </reference/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" )